← Back to branch summary

~ubuntu-branches/debian/jessie/glib2.0/jessie

« back to all changes in this revision

Viewing changes to docs/reference/glib/xml/markup.xml

  • Committer: Bazaar Package Importer
  • Author(s): Gustavo Noronha Silva
  • Date: 2009-02-15 13:00:43 UTC
  • mfrom: (1.3.1 upstream) (69.1.10 intrepid)
  • Revision ID: james.westby@ubuntu.com-20090215130043-q47fbt3owmt42m2f
Tags: 2.18.4-2
* Release to unstable
* debian/rules:
- bump SHVER, since we are already forcing a 2.18.0 dependecy on the
  symbols introduced in the development versions
* debian/control.in:
- added Homepage and Vcs-* control fields

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/glib/xml/markup.xml
1
1
<refentry id="glib-Simple-XML-Subset-Parser">
2
2
<refmeta>
3
 
<refentrytitle role="top_of_page">Simple XML Subset Parser</refentrytitle>
 
3
<refentrytitle role="top_of_page" id="glib-Simple-XML-Subset-Parser.top_of_page">Simple XML Subset Parser</refentrytitle>
4
4
<manvolnum>3</manvolnum>
5
5
<refmiscinfo>GLIB Library</refmiscinfo>
6
6
</refmeta>
8
8
<refnamediv>
9
9
<refname>Simple XML Subset Parser</refname>
10
10
<refpurpose>parses a subset of XML</refpurpose>
11
 
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
12
11
</refnamediv>
13
12
 
14
 
<refsynopsisdiv role="synopsis">
 
13
<refsynopsisdiv id="glib-Simple-XML-Subset-Parser.synopsis" role="synopsis">
15
14
<title role="synopsis.title">Synopsis</title>
16
15
 
17
16
<synopsis>
18
17
 
19
18
#include &lt;glib.h&gt;
20
19
 
21
 
 
22
20
enum                <link linkend="GMarkupError">GMarkupError</link>;
23
 
#define             <link linkend="G-MARKUP-ERROR:CAPS">G_MARKUP_ERROR</link>
 
21
#define             <link linkend="G-MARKUP-ERROR--CAPS">G_MARKUP_ERROR</link>
24
22
enum                <link linkend="GMarkupParseFlags">GMarkupParseFlags</link>;
25
23
                    <link linkend="GMarkupParseContext">GMarkupParseContext</link>;
26
24
                    <link linkend="GMarkupParser">GMarkupParser</link>;
27
25
<link linkend="gchar">gchar</link>*              <link linkend="g-markup-escape-text">g_markup_escape_text</link>                (const <link linkend="gchar">gchar</link> *text,
28
26
                                                         <link linkend="gssize">gssize</link> length);
29
 
<link linkend="gchar">gchar</link>*              <link linkend="g-markup-printf-escaped">g_markup_printf_escaped</link>             (const <link linkend="char">char</link> *format,
 
27
<link linkend="gchar">gchar</link> *             <link linkend="g-markup-printf-escaped">g_markup_printf_escaped</link>             (const <link linkend="char">char</link> *format,
30
28
                                                         ...);
31
 
<link linkend="gchar">gchar</link>*              <link linkend="g-markup-vprintf-escaped">g_markup_vprintf_escaped</link>            (const <link linkend="char">char</link> *format,
 
29
<link linkend="gchar">gchar</link> *             <link linkend="g-markup-vprintf-escaped">g_markup_vprintf_escaped</link>            (const <link linkend="char">char</link> *format,
32
30
                                                         <link linkend="va-list">va_list</link> args);
33
31
<link linkend="gboolean">gboolean</link>            <link linkend="g-markup-parse-context-end-parse">g_markup_parse_context_end_parse</link>    (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context,
34
32
                                                         <link linkend="GError">GError</link> **error);
36
34
<link linkend="void">void</link>                <link linkend="g-markup-parse-context-get-position">g_markup_parse_context_get_position</link> (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context,
37
35
                                                         <link linkend="gint">gint</link> *line_number,
38
36
                                                         <link linkend="gint">gint</link> *char_number);
39
 
const <link linkend="gchar">gchar</link>*        <link linkend="g-markup-parse-context-get-element">g_markup_parse_context_get_element</link>  (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context);
40
 
const <link linkend="GSList">GSList</link>*       <link linkend="g-markup-parse-context-get-element-stack">g_markup_parse_context_get_element_stack</link>
41
 
                                                        (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context);
42
 
<link linkend="GMarkupParseContext">GMarkupParseContext</link>* <link linkend="g-markup-parse-context-new">g_markup_parse_context_new</link>         (const <link linkend="GMarkupParser">GMarkupParser</link> *parser,
 
37
const <link linkend="gchar">gchar</link> *       <link linkend="g-markup-parse-context-get-element">g_markup_parse_context_get_element</link>  (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context);
 
38
const <link linkend="GSList">GSList</link> *      <link linkend="g-markup-parse-context-get-element-stack">g_markup_parse_context_get_element_stack</link>
 
39
                                                        (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context);
 
40
<link linkend="gpointer">gpointer</link>            <link linkend="g-markup-parse-context-get-user-data">g_markup_parse_context_get_user_data</link>
 
41
                                                        (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context);
 
42
<link linkend="GMarkupParseContext">GMarkupParseContext</link> * <link linkend="g-markup-parse-context-new">g_markup_parse_context_new</link>        (const <link linkend="GMarkupParser">GMarkupParser</link> *parser,
43
43
                                                         <link linkend="GMarkupParseFlags">GMarkupParseFlags</link> flags,
44
44
                                                         <link linkend="gpointer">gpointer</link> user_data,
45
45
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> user_data_dnotify);
47
47
                                                         const <link linkend="gchar">gchar</link> *text,
48
48
                                                         <link linkend="gssize">gssize</link> text_len,
49
49
                                                         <link linkend="GError">GError</link> **error);
 
50
<link linkend="void">void</link>                <link linkend="g-markup-parse-context-push">g_markup_parse_context_push</link>         (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context,
 
51
                                                         <link linkend="GMarkupParser">GMarkupParser</link> *parser,
 
52
                                                         <link linkend="gpointer">gpointer</link> user_data);
 
53
<link linkend="gpointer">gpointer</link>            <link linkend="g-markup-parse-context-pop">g_markup_parse_context_pop</link>          (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context);
50
54
 
51
55
enum                <link linkend="GMarkupCollectType">GMarkupCollectType</link>;
52
56
<link linkend="gboolean">gboolean</link>            <link linkend="g-markup-collect-attributes">g_markup_collect_attributes</link>         (const <link linkend="gchar">gchar</link> *element_name,
56
60
                                                         <link linkend="GMarkupCollectType">GMarkupCollectType</link> first_type,
57
61
                                                         const <link linkend="gchar">gchar</link> *first_attr,
58
62
                                                         ...);
59
 
 
60
63
</synopsis>
61
64
</refsynopsisdiv>
62
65
 
68
71
 
69
72
 
70
73
 
71
 
<refsect1 role="desc">
 
74
<refsect1 id="glib-Simple-XML-Subset-Parser.description" role="desc">
72
75
<title role="desc.title">Description</title>
73
76
<para>
74
77
The "GMarkup" parser is intended to parse a simple markup format
75
78
that's a subset of XML. This is a small, efficient, easy-to-use
76
 
parser. It should not be used if you expect to interoperate with other 
 
79
parser. It should not be used if you expect to interoperate with other
77
80
applications generating full-scale XML. However, it's very useful for
78
81
application data files, config files, etc. where you know your
79
82
application will be the only one writing the file. Full-scale XML
80
83
parsers should be able to parse the subset used by GMarkup, so you can
81
84
easily migrate to full-scale XML at a later time if the need arises.
82
85
</para>
83
 
 
84
86
<para>
85
87
GMarkup is not guaranteed to signal an error on all invalid XML; the
86
 
parser may accept documents that an XML parser would not. However, XML 
 
88
parser may accept documents that an XML parser would not. However, XML
87
89
documents which are not well-formed<footnote id="wellformed">Being wellformed
88
 
is a weaker condition than being valid. See the 
89
 
<ulink url="http://www.w3.org/TR/REC-xml/">XML specification</ulink> for 
90
 
definitions of these terms.</footnote> are not considered valid GMarkup 
91
 
documents. 
 
90
is a weaker condition than being valid. See the
 
91
<ulink url="http://www.w3.org/TR/REC-xml/">XML specification</ulink> for
 
92
definitions of these terms.</footnote> are not considered valid GMarkup
 
93
documents.
92
94
</para>
93
 
 
94
95
<para>
95
96
Simplifications to XML include:
96
97
<itemizedlist>
106
107
</listitem>
107
108
<listitem>
108
109
<para>
109
 
Processing instructions, comments and the doctype declaration are "passed 
 
110
Processing instructions, comments and the doctype declaration are "passed
110
111
through" but are not interpreted in any way.
111
112
</para>
112
113
</listitem>
117
118
</listitem>
118
119
</itemizedlist>
119
120
</para>
120
 
 
121
121
<para>
122
122
The markup format does support:
123
123
<itemizedlist>
150
150
</para>
151
151
</refsect1>
152
152
 
153
 
<refsect1 role="details">
 
153
<refsect1 id="glib-Simple-XML-Subset-Parser.details" role="details">
154
154
<title role="details.title">Details</title>
155
 
<refsect2>
156
 
<title><anchor id="GMarkupError" role="enum"/>enum GMarkupError</title>
157
 
<indexterm><primary>GMarkupError</primary></indexterm><programlisting>typedef enum
 
155
<refsect2 id="GMarkupError" role="enum">
 
156
<title>enum GMarkupError</title>
 
157
<indexterm zone="GMarkupError"><primary sortas="GMarkupError">GMarkupError</primary></indexterm><programlisting>typedef enum
158
158
{
159
159
  G_MARKUP_ERROR_BAD_UTF8,
160
160
  G_MARKUP_ERROR_EMPTY,
171
171
<para>
172
172
Error codes returned by markup parsing.
173
173
</para><variablelist role="enum">
174
 
<varlistentry>
175
 
<term><anchor id="G-MARKUP-ERROR-BAD-UTF8:CAPS" role="constant"/><literal>G_MARKUP_ERROR_BAD_UTF8</literal></term>
 
174
<varlistentry id="G-MARKUP-ERROR-BAD-UTF8--CAPS" role="constant">
 
175
<term><literal>G_MARKUP_ERROR_BAD_UTF8</literal></term>
176
176
<listitem><simpara>text being parsed was not valid UTF-8
177
177
</simpara></listitem>
178
178
</varlistentry>
179
 
<varlistentry>
180
 
<term><anchor id="G-MARKUP-ERROR-EMPTY:CAPS" role="constant"/><literal>G_MARKUP_ERROR_EMPTY</literal></term>
 
179
<varlistentry id="G-MARKUP-ERROR-EMPTY--CAPS" role="constant">
 
180
<term><literal>G_MARKUP_ERROR_EMPTY</literal></term>
181
181
<listitem><simpara>document contained nothing, or only whitespace
182
182
</simpara></listitem>
183
183
</varlistentry>
184
 
<varlistentry>
185
 
<term><anchor id="G-MARKUP-ERROR-PARSE:CAPS" role="constant"/><literal>G_MARKUP_ERROR_PARSE</literal></term>
 
184
<varlistentry id="G-MARKUP-ERROR-PARSE--CAPS" role="constant">
 
185
<term><literal>G_MARKUP_ERROR_PARSE</literal></term>
186
186
<listitem><simpara>document was ill-formed
187
187
</simpara></listitem>
188
188
</varlistentry>
189
 
<varlistentry>
190
 
<term><anchor id="G-MARKUP-ERROR-UNKNOWN-ELEMENT:CAPS" role="constant"/><literal>G_MARKUP_ERROR_UNKNOWN_ELEMENT</literal></term>
 
189
<varlistentry id="G-MARKUP-ERROR-UNKNOWN-ELEMENT--CAPS" role="constant">
 
190
<term><literal>G_MARKUP_ERROR_UNKNOWN_ELEMENT</literal></term>
191
191
<listitem><simpara>error should be set by <link linkend="GMarkupParser"><type>GMarkupParser</type></link> functions; element wasn't known
192
192
</simpara></listitem>
193
193
</varlistentry>
194
 
<varlistentry>
195
 
<term><anchor id="G-MARKUP-ERROR-UNKNOWN-ATTRIBUTE:CAPS" role="constant"/><literal>G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE</literal></term>
 
194
<varlistentry id="G-MARKUP-ERROR-UNKNOWN-ATTRIBUTE--CAPS" role="constant">
 
195
<term><literal>G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE</literal></term>
196
196
<listitem><simpara>error should be set by <link linkend="GMarkupParser"><type>GMarkupParser</type></link> functions; attribute wasn't known
197
197
</simpara></listitem>
198
198
</varlistentry>
199
 
<varlistentry>
200
 
<term><anchor id="G-MARKUP-ERROR-INVALID-CONTENT:CAPS" role="constant"/><literal>G_MARKUP_ERROR_INVALID_CONTENT</literal></term>
 
199
<varlistentry id="G-MARKUP-ERROR-INVALID-CONTENT--CAPS" role="constant">
 
200
<term><literal>G_MARKUP_ERROR_INVALID_CONTENT</literal></term>
201
201
<listitem><simpara>error should be set by <link linkend="GMarkupParser"><type>GMarkupParser</type></link> functions; content was invalid
202
202
</simpara></listitem>
203
203
</varlistentry>
204
 
<varlistentry>
205
 
<term><anchor id="G-MARKUP-ERROR-MISSING-ATTRIBUTE:CAPS" role="constant"/><literal>G_MARKUP_ERROR_MISSING_ATTRIBUTE</literal></term>
 
204
<varlistentry id="G-MARKUP-ERROR-MISSING-ATTRIBUTE--CAPS" role="constant">
 
205
<term><literal>G_MARKUP_ERROR_MISSING_ATTRIBUTE</literal></term>
206
206
<listitem><simpara>error should be set by <link linkend="GMarkupParser"><type>GMarkupParser</type></link> functions; a required attribute was missing
207
 
 
208
207
</simpara></listitem>
209
208
</varlistentry>
210
209
</variablelist></refsect2>
211
 
<refsect2>
212
 
<title><anchor id="G-MARKUP-ERROR:CAPS" role="macro"/>G_MARKUP_ERROR</title>
213
 
<indexterm><primary>G_MARKUP_ERROR</primary></indexterm><programlisting>#define G_MARKUP_ERROR g_markup_error_quark ()
 
210
<refsect2 id="G-MARKUP-ERROR--CAPS" role="macro">
 
211
<title>G_MARKUP_ERROR</title>
 
212
<indexterm zone="G-MARKUP-ERROR--CAPS"><primary sortas="G_MARKUP_ERROR">G_MARKUP_ERROR</primary></indexterm><programlisting>#define G_MARKUP_ERROR g_markup_error_quark ()
214
213
</programlisting>
215
214
<para>
216
215
Error domain for markup parsing. Errors in this domain will
217
 
be from the <link linkend="GMarkupError"><type>GMarkupError</type></link> enumeration. See <link linkend="GError"><type>GError</type></link> for information on 
 
216
be from the <link linkend="GMarkupError"><type>GMarkupError</type></link> enumeration. See <link linkend="GError"><type>GError</type></link> for information on
218
217
error domains.
219
218
</para></refsect2>
220
 
<refsect2>
221
 
<title><anchor id="GMarkupParseFlags" role="enum"/>enum GMarkupParseFlags</title>
222
 
<indexterm><primary>GMarkupParseFlags</primary></indexterm><programlisting>typedef enum
 
219
<refsect2 id="GMarkupParseFlags" role="enum">
 
220
<title>enum GMarkupParseFlags</title>
 
221
<indexterm zone="GMarkupParseFlags"><primary sortas="GMarkupParseFlags">GMarkupParseFlags</primary></indexterm><programlisting>typedef enum
223
222
{
224
223
  G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG = 1 &lt;&lt; 0,
225
224
  G_MARKUP_TREAT_CDATA_AS_TEXT              = 1 &lt;&lt; 1,
227
226
} GMarkupParseFlags;
228
227
</programlisting>
229
228
<para>
230
 
Flags that affect the behaviour of the parser. 
 
229
Flags that affect the behaviour of the parser.
231
230
</para><variablelist role="enum">
232
 
<varlistentry>
233
 
<term><anchor id="G-MARKUP-DO-NOT-USE-THIS-UNSUPPORTED-FLAG:CAPS" role="constant"/><literal>G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG</literal></term>
 
231
<varlistentry id="G-MARKUP-DO-NOT-USE-THIS-UNSUPPORTED-FLAG--CAPS" role="constant">
 
232
<term><literal>G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG</literal></term>
234
233
<listitem><simpara>flag you should not use.
235
234
</simpara></listitem>
236
235
</varlistentry>
237
 
<varlistentry>
238
 
<term><anchor id="G-MARKUP-TREAT-CDATA-AS-TEXT:CAPS" role="constant"/><literal>G_MARKUP_TREAT_CDATA_AS_TEXT</literal></term>
 
236
<varlistentry id="G-MARKUP-TREAT-CDATA-AS-TEXT--CAPS" role="constant">
 
237
<term><literal>G_MARKUP_TREAT_CDATA_AS_TEXT</literal></term>
239
238
<listitem><simpara>When this flag is set, CDATA marked
240
239
  sections are not passed literally to the <parameter>passthrough</parameter> function of
241
 
  the parser. Instead, the content of the section (without the 
 
240
  the parser. Instead, the content of the section (without the
242
241
  <literal>&lt;![CDATA[</literal> and <literal>]]&gt;</literal>) is
243
242
  passed to the <parameter>text</parameter> function. This flag was added in GLib 2.12.
244
243
</simpara></listitem>
245
244
</varlistentry>
246
 
<varlistentry>
247
 
<term><anchor id="G-MARKUP-PREFIX-ERROR-POSITION:CAPS" role="constant"/><literal>G_MARKUP_PREFIX_ERROR_POSITION</literal></term>
 
245
<varlistentry id="G-MARKUP-PREFIX-ERROR-POSITION--CAPS" role="constant">
 
246
<term><literal>G_MARKUP_PREFIX_ERROR_POSITION</literal></term>
248
247
<listitem><simpara>Normally errors caught by GMarkup
249
248
  itself have line/column information prefixed to them to let the
250
249
  caller know the location of the error.  When this flag is set the
251
250
  location information is also prefixed to errors generated by the
252
251
  <link linkend="GMarkupParser"><type>GMarkupParser</type></link> implementation functions.
253
 
 
254
252
</simpara></listitem>
255
253
</varlistentry>
256
254
</variablelist></refsect2>
257
 
<refsect2>
258
 
<title><anchor id="GMarkupParseContext" role="struct"/>GMarkupParseContext</title>
259
 
<indexterm><primary>GMarkupParseContext</primary></indexterm><programlisting>typedef struct _GMarkupParseContext GMarkupParseContext;</programlisting>
 
255
<refsect2 id="GMarkupParseContext" role="struct">
 
256
<title>GMarkupParseContext</title>
 
257
<indexterm zone="GMarkupParseContext"><primary sortas="GMarkupParseContext">GMarkupParseContext</primary></indexterm><programlisting>typedef struct _GMarkupParseContext GMarkupParseContext;</programlisting>
260
258
<para>
261
259
A parse context is used to parse a stream of bytes that you expect to
262
260
contain marked-up text. See <link linkend="g-markup-parse-context-new"><function>g_markup_parse_context_new()</function></link>,
263
261
<link linkend="GMarkupParser"><type>GMarkupParser</type></link>, and so on for more details.
264
262
</para></refsect2>
265
 
<refsect2>
266
 
<title><anchor id="GMarkupParser" role="struct"/>GMarkupParser</title>
267
 
<indexterm><primary>GMarkupParser</primary></indexterm><programlisting>typedef struct {
 
263
<refsect2 id="GMarkupParser" role="struct">
 
264
<title>GMarkupParser</title>
 
265
<indexterm zone="GMarkupParser"><primary sortas="GMarkupParser">GMarkupParser</primary></indexterm><programlisting>typedef struct {
268
266
  /* Called for open tags &lt;foo bar="baz"&gt; */
269
267
  void (*start_element)  (GMarkupParseContext *context,
270
268
                          const gchar         *element_name,
307
305
} GMarkupParser;
308
306
</programlisting>
309
307
<para>
310
 
Any of the fields in <link linkend="GMarkupParser"><type>GMarkupParser</type></link> can be <link linkend="NULL:CAPS"><literal>NULL</literal></link>, in which case they
 
308
Any of the fields in <link linkend="GMarkupParser"><type>GMarkupParser</type></link> can be <link linkend="NULL--CAPS"><literal>NULL</literal></link>, in which case they
311
309
will be ignored. Except for the <parameter>error</parameter> function, any of these
312
310
callbacks can set an error; in particular the
313
 
<link linkend="G-MARKUP-ERROR-UNKNOWN-ELEMENT:CAPS"><literal>G_MARKUP_ERROR_UNKNOWN_ELEMENT</literal></link>, <link linkend="G-MARKUP-ERROR-UNKNOWN-ATTRIBUTE:CAPS"><literal>G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE</literal></link>,
314
 
and <link linkend="G-MARKUP-ERROR-INVALID-CONTENT:CAPS"><literal>G_MARKUP_ERROR_INVALID_CONTENT</literal></link> errors are intended to be set 
 
311
<link linkend="G-MARKUP-ERROR-UNKNOWN-ELEMENT--CAPS"><literal>G_MARKUP_ERROR_UNKNOWN_ELEMENT</literal></link>, <link linkend="G-MARKUP-ERROR-UNKNOWN-ATTRIBUTE--CAPS"><literal>G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE</literal></link>,
 
312
and <link linkend="G-MARKUP-ERROR-INVALID-CONTENT--CAPS"><literal>G_MARKUP_ERROR_INVALID_CONTENT</literal></link> errors are intended to be set
315
313
from these callbacks. If you set an error from a callback,
316
314
<link linkend="g-markup-parse-context-parse"><function>g_markup_parse_context_parse()</function></link> will report that error back to its caller.
317
315
</para><variablelist role="struct">
318
316
<varlistentry>
319
 
<term><structfield>start_element</structfield>&nbsp;()</term>
 
317
<term><structfield>start_element</structfield>&#160;()</term>
320
318
<listitem><simpara>Callback to invoke when the opening tag of an element
321
319
    is seen.
322
320
</simpara></listitem>
323
321
</varlistentry>
324
322
<varlistentry>
325
 
<term><structfield>end_element</structfield>&nbsp;()</term>
 
323
<term><structfield>end_element</structfield>&#160;()</term>
326
324
<listitem><simpara>Callback to invoke when the closing tag of an element is seen.
327
 
    Note that this is also called for empty tags like 
 
325
    Note that this is also called for empty tags like
328
326
    <literal>&lt;empty/&gt;</literal>.
329
327
</simpara></listitem>
330
328
</varlistentry>
331
329
<varlistentry>
332
 
<term><structfield>text</structfield>&nbsp;()</term>
 
330
<term><structfield>text</structfield>&#160;()</term>
333
331
<listitem><simpara>Callback to invoke when some text is seen (text is always
334
332
    inside an element). Note that the text of an element may be spread
335
 
    over multiple calls of this function. If the <link linkend="G-MARKUP-TREAT-CDATA-AS-TEXT:CAPS"><literal>G_MARKUP_TREAT_CDATA_AS_TEXT</literal></link>
336
 
    flag is set, this function is also called for the content of CDATA marked 
 
333
    over multiple calls of this function. If the <link linkend="G-MARKUP-TREAT-CDATA-AS-TEXT--CAPS"><literal>G_MARKUP_TREAT_CDATA_AS_TEXT</literal></link>
 
334
    flag is set, this function is also called for the content of CDATA marked
337
335
    sections.
338
336
</simpara></listitem>
339
337
</varlistentry>
340
338
<varlistentry>
341
 
<term><structfield>passthrough</structfield>&nbsp;()</term>
 
339
<term><structfield>passthrough</structfield>&#160;()</term>
342
340
<listitem><simpara>Callback to invoke for comments, processing instructions 
343
 
    and doctype declarations; if you're re-writing the parsed document, 
 
341
    and doctype declarations; if you're re-writing the parsed document,
344
342
    write the passthrough text back out in the same position. If the
345
 
    <link linkend="G-MARKUP-TREAT-CDATA-AS-TEXT:CAPS"><literal>G_MARKUP_TREAT_CDATA_AS_TEXT</literal></link> flag is not set, this function is also 
 
343
    <link linkend="G-MARKUP-TREAT-CDATA-AS-TEXT--CAPS"><literal>G_MARKUP_TREAT_CDATA_AS_TEXT</literal></link> flag is not set, this function is also
346
344
    called for CDATA marked sections.
347
345
</simpara></listitem>
348
346
</varlistentry>
349
347
<varlistentry>
350
 
<term><structfield>error</structfield>&nbsp;()</term>
 
348
<term><structfield>error</structfield>&#160;()</term>
351
349
<listitem><simpara>Callback to invoke when an error occurs.
352
 
 
353
350
</simpara></listitem>
354
351
</varlistentry>
355
352
</variablelist></refsect2>
356
 
<refsect2>
357
 
<title><anchor id="g-markup-escape-text" role="function"/>g_markup_escape_text ()</title>
358
 
<indexterm><primary>g_markup_escape_text</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_markup_escape_text                (const <link linkend="gchar">gchar</link> *text,
 
353
<refsect2 id="g-markup-escape-text" role="function">
 
354
<title>g_markup_escape_text ()</title>
 
355
<indexterm zone="g-markup-escape-text"><primary sortas="g_markup_escape_text">g_markup_escape_text</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_markup_escape_text                (const <link linkend="gchar">gchar</link> *text,
359
356
                                                         <link linkend="gssize">gssize</link> length);</programlisting>
360
357
<para>
361
358
Escapes text so that the markup parser will parse it verbatim.
366
363
<para>
367
364
Note that this function doesn't protect whitespace and line endings
368
365
from being processed according to the XML rules for normalization
369
 
of line endings and attribute values.</para>
370
 
<para>
371
 
 
 
366
of line endings and attribute values.
 
367
</para>
 
368
<para>
 
369
Note also that if given a string containing them, this function
 
370
will produce character references in the range of &amp;<link linkend="x1"><type>x1</type></link>; ..
 
371
&amp;<link linkend="x1f"><type>x1f</type></link>; for all control sequences except for tabstop, newline
 
372
and carriage return.  The character references in this range are
 
373
not valid XML 1.0, but they are valid XML 1.1 and will be accepted
 
374
by the GMarkup parser.</para>
 
375
<para>
372
376
</para><variablelist role="params">
373
 
<varlistentry><term><parameter>text</parameter>&nbsp;:</term>
 
377
<varlistentry><term><parameter>text</parameter>&#160;:</term>
374
378
<listitem><simpara> some valid UTF-8 text
375
379
</simpara></listitem></varlistentry>
376
 
<varlistentry><term><parameter>length</parameter>&nbsp;:</term>
 
380
<varlistentry><term><parameter>length</parameter>&#160;:</term>
377
381
<listitem><simpara> length of <parameter>text</parameter> in bytes, or -1 if the text is nul-terminated
378
382
</simpara></listitem></varlistentry>
379
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly allocated string with the escaped text
 
383
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly allocated string with the escaped text
380
384
</simpara></listitem></varlistentry>
381
385
</variablelist></refsect2>
382
 
<refsect2>
383
 
<title><anchor id="g-markup-printf-escaped" role="function" condition="since:2.4"/>g_markup_printf_escaped ()</title>
384
 
<indexterm role="2.4"><primary>g_markup_printf_escaped</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_markup_printf_escaped             (const <link linkend="char">char</link> *format,
 
386
<refsect2 id="g-markup-printf-escaped" role="function" condition="since:2.4">
 
387
<title>g_markup_printf_escaped ()</title>
 
388
<indexterm zone="g-markup-printf-escaped" role="2.4"><primary sortas="g_markup_printf_escaped">g_markup_printf_escaped</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             g_markup_printf_escaped             (const <link linkend="char">char</link> *format,
385
389
                                                         ...);</programlisting>
386
390
<para>
387
391
Formats arguments according to <parameter>format</parameter>, escaping
404
408
                                  store, item);
405
409
</programlisting></informalexample></para>
406
410
<para>
407
 
 
408
411
</para><variablelist role="params">
409
 
<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
 
412
<varlistentry><term><parameter>format</parameter>&#160;:</term>
410
413
<listitem><simpara> <link linkend="printf"><function>printf()</function></link> style format string
411
414
</simpara></listitem></varlistentry>
412
 
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
 
415
<varlistentry><term><parameter>...</parameter>&#160;:</term>
413
416
<listitem><simpara> the arguments to insert in the format string
414
417
</simpara></listitem></varlistentry>
415
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> newly allocated result from formatting
 
418
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> newly allocated result from formatting
416
419
 operation. Free with <link linkend="g-free"><function>g_free()</function></link>.
417
420
 
418
421
</simpara></listitem></varlistentry>
419
 
</variablelist><para role="since">Since  2.4
420
 
</para></refsect2>
421
 
<refsect2>
422
 
<title><anchor id="g-markup-vprintf-escaped" role="function" condition="since:2.4"/>g_markup_vprintf_escaped ()</title>
423
 
<indexterm role="2.4"><primary>g_markup_vprintf_escaped</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_markup_vprintf_escaped            (const <link linkend="char">char</link> *format,
 
422
</variablelist><para role="since">Since 2.4</para></refsect2>
 
423
<refsect2 id="g-markup-vprintf-escaped" role="function" condition="since:2.4">
 
424
<title>g_markup_vprintf_escaped ()</title>
 
425
<indexterm zone="g-markup-vprintf-escaped" role="2.4"><primary sortas="g_markup_vprintf_escaped">g_markup_vprintf_escaped</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             g_markup_vprintf_escaped            (const <link linkend="char">char</link> *format,
424
426
                                                         <link linkend="va-list">va_list</link> args);</programlisting>
425
427
<para>
426
428
Formats the data in <parameter>args</parameter> according to <parameter>format</parameter>, escaping
427
429
all string and character arguments in the fashion
428
430
of <link linkend="g-markup-escape-text"><function>g_markup_escape_text()</function></link>. See <link linkend="g-markup-printf-escaped"><function>g_markup_printf_escaped()</function></link>.</para>
429
431
<para>
430
 
 
431
432
</para><variablelist role="params">
432
 
<varlistentry><term><parameter>format</parameter>&nbsp;:</term>
 
433
<varlistentry><term><parameter>format</parameter>&#160;:</term>
433
434
<listitem><simpara> <link linkend="printf"><function>printf()</function></link> style format string
434
435
</simpara></listitem></varlistentry>
435
 
<varlistentry><term><parameter>args</parameter>&nbsp;:</term>
 
436
<varlistentry><term><parameter>args</parameter>&#160;:</term>
436
437
<listitem><simpara> variable argument list, similar to <link linkend="vprintf"><function>vprintf()</function></link>
437
438
</simpara></listitem></varlistentry>
438
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> newly allocated result from formatting
 
439
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> newly allocated result from formatting
439
440
 operation. Free with <link linkend="g-free"><function>g_free()</function></link>.
440
441
 
441
442
</simpara></listitem></varlistentry>
442
 
</variablelist><para role="since">Since  2.4
443
 
</para></refsect2>
444
 
<refsect2>
445
 
<title><anchor id="g-markup-parse-context-end-parse" role="function"/>g_markup_parse_context_end_parse ()</title>
446
 
<indexterm><primary>g_markup_parse_context_end_parse</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_markup_parse_context_end_parse    (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context,
 
443
</variablelist><para role="since">Since 2.4</para></refsect2>
 
444
<refsect2 id="g-markup-parse-context-end-parse" role="function">
 
445
<title>g_markup_parse_context_end_parse ()</title>
 
446
<indexterm zone="g-markup-parse-context-end-parse"><primary sortas="g_markup_parse_context_end_parse">g_markup_parse_context_end_parse</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_markup_parse_context_end_parse    (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context,
447
447
                                                         <link linkend="GError">GError</link> **error);</programlisting>
448
448
<para>
449
449
Signals to the <link linkend="GMarkupParseContext"><type>GMarkupParseContext</type></link> that all data has been
451
451
This function reports an error if the document isn't complete,
452
452
for example if elements are still open.</para>
453
453
<para>
454
 
 
455
454
</para><variablelist role="params">
456
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
455
<varlistentry><term><parameter>context</parameter>&#160;:</term>
457
456
<listitem><simpara> a <link linkend="GMarkupParseContext"><type>GMarkupParseContext</type></link>
458
457
</simpara></listitem></varlistentry>
459
 
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
458
<varlistentry><term><parameter>error</parameter>&#160;:</term>
460
459
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>
461
460
</simpara></listitem></varlistentry>
462
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if an error was set
 
461
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if an error was set
463
462
</simpara></listitem></varlistentry>
464
463
</variablelist></refsect2>
465
 
<refsect2>
466
 
<title><anchor id="g-markup-parse-context-free" role="function"/>g_markup_parse_context_free ()</title>
467
 
<indexterm><primary>g_markup_parse_context_free</primary></indexterm><programlisting><link linkend="void">void</link>                g_markup_parse_context_free         (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context);</programlisting>
 
464
<refsect2 id="g-markup-parse-context-free" role="function">
 
465
<title>g_markup_parse_context_free ()</title>
 
466
<indexterm zone="g-markup-parse-context-free"><primary sortas="g_markup_parse_context_free">g_markup_parse_context_free</primary></indexterm><programlisting><link linkend="void">void</link>                g_markup_parse_context_free         (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context);</programlisting>
468
467
<para>
469
468
Frees a <link linkend="GMarkupParseContext"><type>GMarkupParseContext</type></link>. Can't be called from inside
470
 
one of the <link linkend="GMarkupParser"><type>GMarkupParser</type></link> functions.</para>
 
469
one of the <link linkend="GMarkupParser"><type>GMarkupParser</type></link> functions. Can't be called while
 
470
a subparser is pushed.</para>
471
471
<para>
472
 
 
473
472
</para><variablelist role="params">
474
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
473
<varlistentry><term><parameter>context</parameter>&#160;:</term>
475
474
<listitem><simpara> a <link linkend="GMarkupParseContext"><type>GMarkupParseContext</type></link>
476
475
</simpara></listitem></varlistentry>
477
476
</variablelist></refsect2>
478
 
<refsect2>
479
 
<title><anchor id="g-markup-parse-context-get-position" role="function"/>g_markup_parse_context_get_position ()</title>
480
 
<indexterm><primary>g_markup_parse_context_get_position</primary></indexterm><programlisting><link linkend="void">void</link>                g_markup_parse_context_get_position (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context,
 
477
<refsect2 id="g-markup-parse-context-get-position" role="function">
 
478
<title>g_markup_parse_context_get_position ()</title>
 
479
<indexterm zone="g-markup-parse-context-get-position"><primary sortas="g_markup_parse_context_get_position">g_markup_parse_context_get_position</primary></indexterm><programlisting><link linkend="void">void</link>                g_markup_parse_context_get_position (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context,
481
480
                                                         <link linkend="gint">gint</link> *line_number,
482
481
                                                         <link linkend="gint">gint</link> *char_number);</programlisting>
483
482
<para>
486
485
semantics for what constitutes the "current" line number other than
487
486
"the best number we could come up with for error messages."</para>
488
487
<para>
489
 
 
490
488
</para><variablelist role="params">
491
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
489
<varlistentry><term><parameter>context</parameter>&#160;:</term>
492
490
<listitem><simpara> a <link linkend="GMarkupParseContext"><type>GMarkupParseContext</type></link>
493
491
</simpara></listitem></varlistentry>
494
 
<varlistentry><term><parameter>line_number</parameter>&nbsp;:</term>
495
 
<listitem><simpara> return location for a line number, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
492
<varlistentry><term><parameter>line_number</parameter>&#160;:</term>
 
493
<listitem><simpara> return location for a line number, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
496
494
</simpara></listitem></varlistentry>
497
 
<varlistentry><term><parameter>char_number</parameter>&nbsp;:</term>
498
 
<listitem><simpara> return location for a char-on-line number, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
495
<varlistentry><term><parameter>char_number</parameter>&#160;:</term>
 
496
<listitem><simpara> return location for a char-on-line number, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
499
497
</simpara></listitem></varlistentry>
500
498
</variablelist></refsect2>
501
 
<refsect2>
502
 
<title><anchor id="g-markup-parse-context-get-element" role="function" condition="since:2.2"/>g_markup_parse_context_get_element ()</title>
503
 
<indexterm role="2.2"><primary>g_markup_parse_context_get_element</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_markup_parse_context_get_element  (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context);</programlisting>
 
499
<refsect2 id="g-markup-parse-context-get-element" role="function" condition="since:2.2">
 
500
<title>g_markup_parse_context_get_element ()</title>
 
501
<indexterm zone="g-markup-parse-context-get-element" role="2.2"><primary sortas="g_markup_parse_context_get_element">g_markup_parse_context_get_element</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> *       g_markup_parse_context_get_element  (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context);</programlisting>
504
502
<para>
505
503
Retrieves the name of the currently open element.
506
504
</para>
509
507
give the element_name as passed to those functions. For the parent
510
508
elements, see <link linkend="g-markup-parse-context-get-element-stack"><function>g_markup_parse_context_get_element_stack()</function></link>.</para>
511
509
<para>
512
 
 
513
510
</para><variablelist role="params">
514
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
511
<varlistentry><term><parameter>context</parameter>&#160;:</term>
515
512
<listitem><simpara> a <link linkend="GMarkupParseContext"><type>GMarkupParseContext</type></link>
516
513
</simpara></listitem></varlistentry>
517
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the name of the currently open element, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
514
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the name of the currently open element, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
518
515
</simpara></listitem></varlistentry>
519
 
</variablelist><para role="since">Since  2.2
520
 
</para></refsect2>
521
 
<refsect2>
522
 
<title><anchor id="g-markup-parse-context-get-element-stack" role="function"/>g_markup_parse_context_get_element_stack ()</title>
523
 
<indexterm><primary>g_markup_parse_context_get_element_stack</primary></indexterm><programlisting>const <link linkend="GSList">GSList</link>*       g_markup_parse_context_get_element_stack
 
516
</variablelist><para role="since">Since 2.2</para></refsect2>
 
517
<refsect2 id="g-markup-parse-context-get-element-stack" role="function" condition="since:2.16">
 
518
<title>g_markup_parse_context_get_element_stack ()</title>
 
519
<indexterm zone="g-markup-parse-context-get-element-stack" role="2.16"><primary sortas="g_markup_parse_context_get_element_stack">g_markup_parse_context_get_element_stack</primary></indexterm><programlisting>const <link linkend="GSList">GSList</link> *      g_markup_parse_context_get_element_stack
524
520
                                                        (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context);</programlisting>
525
521
<para>
526
522
Retrieves the element stack from the internal state of the parser.
535
531
would merely return the name of the element that is being
536
532
processed.</para>
537
533
<para>
538
 
 
539
 
</para><variablelist role="params">
540
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
541
 
<listitem><simpara> a <link linkend="GMarkupParseContext"><type>GMarkupParseContext</type></link>
542
 
</simpara></listitem></varlistentry>
543
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the element stack, which must not be modified
544
 
 
545
 
Since 2.16
546
 
</simpara></listitem></varlistentry>
547
 
</variablelist></refsect2>
548
 
<refsect2>
549
 
<title><anchor id="g-markup-parse-context-new" role="function"/>g_markup_parse_context_new ()</title>
550
 
<indexterm><primary>g_markup_parse_context_new</primary></indexterm><programlisting><link linkend="GMarkupParseContext">GMarkupParseContext</link>* g_markup_parse_context_new         (const <link linkend="GMarkupParser">GMarkupParser</link> *parser,
 
534
</para><variablelist role="params">
 
535
<varlistentry><term><parameter>context</parameter>&#160;:</term>
 
536
<listitem><simpara> a <link linkend="GMarkupParseContext"><type>GMarkupParseContext</type></link>
 
537
</simpara></listitem></varlistentry>
 
538
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the element stack, which must not be modified
 
539
 
 
540
</simpara></listitem></varlistentry>
 
541
</variablelist><para role="since">Since 2.16</para></refsect2>
 
542
<refsect2 id="g-markup-parse-context-get-user-data" role="function" condition="since:2.18">
 
543
<title>g_markup_parse_context_get_user_data ()</title>
 
544
<indexterm zone="g-markup-parse-context-get-user-data" role="2.18"><primary sortas="g_markup_parse_context_get_user_data">g_markup_parse_context_get_user_data</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_markup_parse_context_get_user_data
 
545
                                                        (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context);</programlisting>
 
546
<para>
 
547
Returns the user_data associated with <parameter>context</parameter>.  This will either
 
548
be the user_data that was provided to <link linkend="g-markup-parse-context-new"><function>g_markup_parse_context_new()</function></link>
 
549
or to the most recent call of <link linkend="g-markup-parse-context-push"><function>g_markup_parse_context_push()</function></link>.</para>
 
550
<para>
 
551
</para><variablelist role="params">
 
552
<varlistentry><term><parameter>context</parameter>&#160;:</term>
 
553
<listitem><simpara> a <link linkend="GMarkupParseContext"><type>GMarkupParseContext</type></link>
 
554
</simpara></listitem></varlistentry>
 
555
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the provided user_data. The returned data belongs to
 
556
    the markup context and will be freed when <link linkend="g-markup-context-free"><function>g_markup_context_free()</function></link>
 
557
    is called.
 
558
 
 
559
</simpara></listitem></varlistentry>
 
560
</variablelist><para role="since">Since 2.18</para></refsect2>
 
561
<refsect2 id="g-markup-parse-context-new" role="function">
 
562
<title>g_markup_parse_context_new ()</title>
 
563
<indexterm zone="g-markup-parse-context-new"><primary sortas="g_markup_parse_context_new">g_markup_parse_context_new</primary></indexterm><programlisting><link linkend="GMarkupParseContext">GMarkupParseContext</link> * g_markup_parse_context_new        (const <link linkend="GMarkupParser">GMarkupParser</link> *parser,
551
564
                                                         <link linkend="GMarkupParseFlags">GMarkupParseFlags</link> flags,
552
565
                                                         <link linkend="gpointer">gpointer</link> user_data,
553
566
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> user_data_dnotify);</programlisting>
558
571
the parse context can't continue to parse text (you have to free it
559
572
and create a new parse context).</para>
560
573
<para>
561
 
 
562
574
</para><variablelist role="params">
563
 
<varlistentry><term><parameter>parser</parameter>&nbsp;:</term>
 
575
<varlistentry><term><parameter>parser</parameter>&#160;:</term>
564
576
<listitem><simpara> a <link linkend="GMarkupParser"><type>GMarkupParser</type></link>
565
577
</simpara></listitem></varlistentry>
566
 
<varlistentry><term><parameter>flags</parameter>&nbsp;:</term>
 
578
<varlistentry><term><parameter>flags</parameter>&#160;:</term>
567
579
<listitem><simpara> one or more <link linkend="GMarkupParseFlags"><type>GMarkupParseFlags</type></link>
568
580
</simpara></listitem></varlistentry>
569
 
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
581
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
570
582
<listitem><simpara> user data to pass to <link linkend="GMarkupParser"><type>GMarkupParser</type></link> functions
571
583
</simpara></listitem></varlistentry>
572
 
<varlistentry><term><parameter>user_data_dnotify</parameter>&nbsp;:</term>
 
584
<varlistentry><term><parameter>user_data_dnotify</parameter>&#160;:</term>
573
585
<listitem><simpara> user data destroy notifier called when the parse context is freed
574
586
</simpara></listitem></varlistentry>
575
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="GMarkupParseContext"><type>GMarkupParseContext</type></link>
 
587
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="GMarkupParseContext"><type>GMarkupParseContext</type></link>
576
588
</simpara></listitem></varlistentry>
577
589
</variablelist></refsect2>
578
 
<refsect2>
579
 
<title><anchor id="g-markup-parse-context-parse" role="function"/>g_markup_parse_context_parse ()</title>
580
 
<indexterm><primary>g_markup_parse_context_parse</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_markup_parse_context_parse        (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context,
 
590
<refsect2 id="g-markup-parse-context-parse" role="function">
 
591
<title>g_markup_parse_context_parse ()</title>
 
592
<indexterm zone="g-markup-parse-context-parse"><primary sortas="g_markup_parse_context_parse">g_markup_parse_context_parse</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_markup_parse_context_parse        (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context,
581
593
                                                         const <link linkend="gchar">gchar</link> *text,
582
594
                                                         <link linkend="gssize">gssize</link> text_len,
583
595
                                                         <link linkend="GError">GError</link> **error);</programlisting>
591
603
the process if an error occurs. Once an error is reported, no further
592
604
data may be fed to the <link linkend="GMarkupParseContext"><type>GMarkupParseContext</type></link>; all errors are fatal.</para>
593
605
<para>
594
 
 
595
606
</para><variablelist role="params">
596
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
607
<varlistentry><term><parameter>context</parameter>&#160;:</term>
597
608
<listitem><simpara> a <link linkend="GMarkupParseContext"><type>GMarkupParseContext</type></link>
598
609
</simpara></listitem></varlistentry>
599
 
<varlistentry><term><parameter>text</parameter>&nbsp;:</term>
 
610
<varlistentry><term><parameter>text</parameter>&#160;:</term>
600
611
<listitem><simpara> chunk of text to parse
601
612
</simpara></listitem></varlistentry>
602
 
<varlistentry><term><parameter>text_len</parameter>&nbsp;:</term>
 
613
<varlistentry><term><parameter>text_len</parameter>&#160;:</term>
603
614
<listitem><simpara> length of <parameter>text</parameter> in bytes
604
615
</simpara></listitem></varlistentry>
605
 
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
616
<varlistentry><term><parameter>error</parameter>&#160;:</term>
606
617
<listitem><simpara> return location for a <link linkend="GError"><type>GError</type></link>
607
618
</simpara></listitem></varlistentry>
608
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if an error occurred, <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success
 
619
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if an error occurred, <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> on success
609
620
</simpara></listitem></varlistentry>
610
621
</variablelist></refsect2>
611
 
<refsect2>
612
 
<title><anchor id="GMarkupCollectType" role="enum"/>enum GMarkupCollectType</title>
613
 
<indexterm><primary>GMarkupCollectType</primary></indexterm><programlisting>typedef enum
 
622
<refsect2 id="g-markup-parse-context-push" role="function" condition="since:2.18">
 
623
<title>g_markup_parse_context_push ()</title>
 
624
<indexterm zone="g-markup-parse-context-push" role="2.18"><primary sortas="g_markup_parse_context_push">g_markup_parse_context_push</primary></indexterm><programlisting><link linkend="void">void</link>                g_markup_parse_context_push         (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context,
 
625
                                                         <link linkend="GMarkupParser">GMarkupParser</link> *parser,
 
626
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
 
627
<para>
 
628
Temporarily redirects markup data to a sub-parser.
 
629
</para>
 
630
<para>
 
631
This function may only be called from the start_element handler of
 
632
a <link linkend="GMarkupParser"><type>GMarkupParser</type></link>.  It must be matched with a corresponding call to
 
633
<link linkend="g-markup-parse-context-pop"><function>g_markup_parse_context_pop()</function></link> in the matching end_element handler
 
634
(except in the case that the parser aborts due to an error).
 
635
</para>
 
636
<para>
 
637
All tags, text and other data between the matching tags is
 
638
redirected to the subparser given by <parameter>parser</parameter>.  <parameter>user_data</parameter> is used
 
639
as the user_data for that parser.  <parameter>user_data</parameter> is also passed to the
 
640
error callback in the event that an error occurs.  This includes
 
641
errors that occur in subparsers of the subparser.
 
642
</para>
 
643
<para>
 
644
The end tag matching the start tag for which this call was made is
 
645
handled by the previous parser (which is given its own user_data)
 
646
which is why <link linkend="g-markup-parse-context-pop"><function>g_markup_parse_context_pop()</function></link> is provided to allow "one
 
647
last access" to the <parameter>user_data</parameter> provided to this function.  In the
 
648
case of error, the <parameter>user_data</parameter> provided here is passed directly to
 
649
the error callback of the subparser and <link linkend="g-markup-parse-context"><function>g_markup_parse_context()</function></link>
 
650
should not be called.  In either case, if <parameter>user_data</parameter> was allocated
 
651
then it ought to be freed from both of these locations.
 
652
</para>
 
653
<para>
 
654
This function is not intended to be directly called by users
 
655
interested in invoking subparsers.  Instead, it is intended to be
 
656
used by the subparsers themselves to implement a higher-level
 
657
interface.
 
658
</para>
 
659
<para>
 
660
As an example, see the following implementation of a simple
 
661
parser that counts the number of tags encountered.
 
662
</para>
 
663
<para>
 
664
<informalexample><programlisting>
 
665
typedef struct
 
666
{
 
667
  gint tag_count;
 
668
} CounterData;
 
669
 
 
670
static void
 
671
counter_start_element (GMarkupParseContext  *context,
 
672
                       const gchar          *element_name,
 
673
                       const gchar         **attribute_names,
 
674
                       const gchar         **attribute_values,
 
675
                       gpointer              user_data,
 
676
                       GError              **error)
 
677
{
 
678
  CounterData *data = user_data;
 
679
 
 
680
  data->tag_count++;
 
681
}
 
682
 
 
683
static void
 
684
counter_error (GMarkupParseContext *context,
 
685
               GError              *error,
 
686
               gpointer             user_data)
 
687
{
 
688
  CounterData *data = user_data;
 
689
 
 
690
  g_slice_free (CounterData, data);
 
691
}
 
692
 
 
693
static GMarkupParser counter_subparser =
 
694
{
 
695
  counter_start_element,
 
696
  NULL,
 
697
  NULL,
 
698
  NULL,
 
699
  counter_error
 
700
};
 
701
</programlisting></informalexample>
 
702
</para>
 
703
<para>
 
704
In order to allow this parser to be easily used as a subparser, the
 
705
following interface is provided:
 
706
</para>
 
707
<para>
 
708
<informalexample><programlisting>
 
709
void
 
710
start_counting (GMarkupParseContext *context)
 
711
{
 
712
  CounterData *data = g_slice_new (CounterData);
 
713
 
 
714
  data->tag_count = 0;
 
715
  g_markup_parse_context_push (context, &amp;counter_subparser, data);
 
716
}
 
717
 
 
718
gint
 
719
end_counting (GMarkupParseContext *context)
 
720
{
 
721
  CounterData *data = g_markup_parse_context_pop (context);
 
722
  int result;
 
723
 
 
724
  result = data->tag_count;
 
725
  g_slice_free (CounterData, data);
 
726
 
 
727
  return result;
 
728
}
 
729
</programlisting></informalexample>
 
730
</para>
 
731
<para>
 
732
The subparser would then be used as follows:
 
733
</para>
 
734
<para>
 
735
<informalexample><programlisting>
 
736
static void start_element (context, element_name, ...)
 
737
{
 
738
  if (strcmp (element_name, "count-these") == 0)
 
739
    start_counting (context);
 
740
 
 
741
  /&ast; else, handle other tags... &ast;/
 
742
}
 
743
 
 
744
static void end_element (context, element_name, ...)
 
745
{
 
746
  if (strcmp (element_name, "count-these") == 0)
 
747
    g_print ("Counted %d tags\n", end_counting (context));
 
748
 
 
749
  /&ast; else, handle other tags... &ast;/
 
750
}
 
751
</programlisting></informalexample></para>
 
752
<para>
 
753
</para><variablelist role="params">
 
754
<varlistentry><term><parameter>context</parameter>&#160;:</term>
 
755
<listitem><simpara> a <link linkend="GMarkupParseContext"><type>GMarkupParseContext</type></link>
 
756
</simpara></listitem></varlistentry>
 
757
<varlistentry><term><parameter>parser</parameter>&#160;:</term>
 
758
<listitem><simpara> a <link linkend="GMarkupParser"><type>GMarkupParser</type></link>
 
759
</simpara></listitem></varlistentry>
 
760
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
 
761
<listitem><simpara> user data to pass to <link linkend="GMarkupParser"><type>GMarkupParser</type></link> functions
 
762
</simpara></listitem></varlistentry>
 
763
</variablelist><para role="since">Since 2.18</para></refsect2>
 
764
<refsect2 id="g-markup-parse-context-pop" role="function" condition="since:2.18">
 
765
<title>g_markup_parse_context_pop ()</title>
 
766
<indexterm zone="g-markup-parse-context-pop" role="2.18"><primary sortas="g_markup_parse_context_pop">g_markup_parse_context_pop</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_markup_parse_context_pop          (<link linkend="GMarkupParseContext">GMarkupParseContext</link> *context);</programlisting>
 
767
<para>
 
768
Completes the process of a temporary sub-parser redirection.
 
769
</para>
 
770
<para>
 
771
This function exists to collect the user_data allocated by a
 
772
matching call to <link linkend="g-markup-parse-context-push"><function>g_markup_parse_context_push()</function></link>.  It must be called
 
773
in the end_element handler corresponding to the start_element
 
774
handler during which <link linkend="g-markup-parse-context-push"><function>g_markup_parse_context_push()</function></link> was called.  You
 
775
must not call this function from the error callback -- the
 
776
<parameter>user_data</parameter> is provided directly to the callback in that case.
 
777
</para>
 
778
<para>
 
779
This function is not intended to be directly called by users
 
780
interested in invoking subparsers.  Instead, it is intended to be
 
781
used by the subparsers themselves to implement a higher-level
 
782
interface.</para>
 
783
<para>
 
784
</para><variablelist role="params">
 
785
<varlistentry><term><parameter>context</parameter>&#160;:</term>
 
786
<listitem><simpara> a <link linkend="GMarkupParseContext"><type>GMarkupParseContext</type></link>
 
787
</simpara></listitem></varlistentry>
 
788
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the user_data passed to <link linkend="g-markup-parse-context-push"><function>g_markup_parse_context_push()</function></link>.
 
789
 
 
790
</simpara></listitem></varlistentry>
 
791
</variablelist><para role="since">Since 2.18</para></refsect2>
 
792
<refsect2 id="GMarkupCollectType" role="enum">
 
793
<title>enum GMarkupCollectType</title>
 
794
<indexterm zone="GMarkupCollectType"><primary sortas="GMarkupCollectType">GMarkupCollectType</primary></indexterm><programlisting>typedef enum
614
795
{
615
796
  G_MARKUP_COLLECT_INVALID,
616
797
  G_MARKUP_COLLECT_STRING,
625
806
A mixed enumerated type and flags field.  You must specify one type
626
807
(string, strdup, boolean, tristate).  Additionally, you may
627
808
optionally bitwise OR the type with the flag
628
 
<link linkend="G-MARKUP-COLLECT-OPTIONAL:CAPS"><literal>G_MARKUP_COLLECT_OPTIONAL</literal></link>.
 
809
<link linkend="G-MARKUP-COLLECT-OPTIONAL--CAPS"><literal>G_MARKUP_COLLECT_OPTIONAL</literal></link>.
629
810
</para>
630
811
<para>
631
812
It is likely that this enum will be extended in the future to
632
813
support other types.</para>
633
814
<para>
634
 
 
635
815
</para><variablelist role="enum">
636
 
<varlistentry>
637
 
<term><anchor id="G-MARKUP-COLLECT-INVALID:CAPS" role="constant"/><literal>G_MARKUP_COLLECT_INVALID</literal></term>
 
816
<varlistentry id="G-MARKUP-COLLECT-INVALID--CAPS" role="constant">
 
817
<term><literal>G_MARKUP_COLLECT_INVALID</literal></term>
638
818
<listitem><simpara> used to terminate the list of attributes
639
819
                           to collect.
640
820
</simpara></listitem>
641
821
</varlistentry>
642
 
<varlistentry>
643
 
<term><anchor id="G-MARKUP-COLLECT-STRING:CAPS" role="constant"/><literal>G_MARKUP_COLLECT_STRING</literal></term>
 
822
<varlistentry id="G-MARKUP-COLLECT-STRING--CAPS" role="constant">
 
823
<term><literal>G_MARKUP_COLLECT_STRING</literal></term>
644
824
<listitem><simpara> collect the string pointer directly from
645
825
                          the attribute_values[] array.  Expects a
646
826
                          parameter of type (const char **).  If
647
 
                          <link linkend="G-MARKUP-COLLECT-OPTIONAL:CAPS"><literal>G_MARKUP_COLLECT_OPTIONAL</literal></link> is specified
 
827
                          <link linkend="G-MARKUP-COLLECT-OPTIONAL--CAPS"><literal>G_MARKUP_COLLECT_OPTIONAL</literal></link> is specified
648
828
                          and the attribute isn't present then the
649
 
                          pointer will be set to <link linkend="NULL:CAPS"><literal>NULL</literal></link>.
 
829
                          pointer will be set to <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
650
830
</simpara></listitem>
651
831
</varlistentry>
652
 
<varlistentry>
653
 
<term><anchor id="G-MARKUP-COLLECT-STRDUP:CAPS" role="constant"/><literal>G_MARKUP_COLLECT_STRDUP</literal></term>
654
 
<listitem><simpara> as with <link linkend="G-MARKUP-COLLECT-STRING:CAPS"><literal>G_MARKUP_COLLECT_STRING</literal></link>, but
 
832
<varlistentry id="G-MARKUP-COLLECT-STRDUP--CAPS" role="constant">
 
833
<term><literal>G_MARKUP_COLLECT_STRDUP</literal></term>
 
834
<listitem><simpara> as with <link linkend="G-MARKUP-COLLECT-STRING--CAPS"><literal>G_MARKUP_COLLECT_STRING</literal></link>, but
655
835
                          expects a paramter of type (char **) and
656
836
                          <link linkend="g-strdup"><function>g_strdup()</function></link>s the returned pointer.  The
657
837
                          pointer must be freed with <link linkend="g-free"><function>g_free()</function></link>.
658
838
</simpara></listitem>
659
839
</varlistentry>
660
 
<varlistentry>
661
 
<term><anchor id="G-MARKUP-COLLECT-BOOLEAN:CAPS" role="constant"/><literal>G_MARKUP_COLLECT_BOOLEAN</literal></term>
 
840
<varlistentry id="G-MARKUP-COLLECT-BOOLEAN--CAPS" role="constant">
 
841
<term><literal>G_MARKUP_COLLECT_BOOLEAN</literal></term>
662
842
<listitem><simpara> expects a parameter of type (gboolean *)
663
843
                           and parses the attribute value as a
664
 
                           boolean.  Sets <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if the attribute
 
844
                           boolean.  Sets <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if the attribute
665
845
                           isn't present.  Valid boolean values
666
846
                           consist of (case insensitive) "false",
667
847
                           "f", "no", "n", "0" and "true", "t",
668
848
                           "yes", "y", "1".
669
849
</simpara></listitem>
670
850
</varlistentry>
671
 
<varlistentry>
672
 
<term><anchor id="G-MARKUP-COLLECT-TRISTATE:CAPS" role="constant"/><literal>G_MARKUP_COLLECT_TRISTATE</literal></term>
673
 
<listitem><simpara> as with <link linkend="G-MARKUP-COLLECT-BOOLEAN:CAPS"><literal>G_MARKUP_COLLECT_BOOLEAN</literal></link>, but
 
851
<varlistentry id="G-MARKUP-COLLECT-TRISTATE--CAPS" role="constant">
 
852
<term><literal>G_MARKUP_COLLECT_TRISTATE</literal></term>
 
853
<listitem><simpara> as with <link linkend="G-MARKUP-COLLECT-BOOLEAN--CAPS"><literal>G_MARKUP_COLLECT_BOOLEAN</literal></link>, but
674
854
                            in the case of a missing attribute a
675
855
                            value is set that compares equal to
676
 
                            neither <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> nor <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>.
 
856
                            neither <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> nor <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>.
677
857
                            G_MARKUP_COLLECT_OPTIONAL is implied.
678
858
</simpara></listitem>
679
859
</varlistentry>
680
 
<varlistentry>
681
 
<term><anchor id="G-MARKUP-COLLECT-OPTIONAL:CAPS" role="constant"/><literal>G_MARKUP_COLLECT_OPTIONAL</literal></term>
 
860
<varlistentry id="G-MARKUP-COLLECT-OPTIONAL--CAPS" role="constant">
 
861
<term><literal>G_MARKUP_COLLECT_OPTIONAL</literal></term>
682
862
<listitem><simpara> can be bitwise ORed with the other
683
863
                            fields.  If present, allows the
684
864
                            attribute not to appear.  A default
687
867
</simpara></listitem>
688
868
</varlistentry>
689
869
</variablelist></refsect2>
690
 
<refsect2>
691
 
<title><anchor id="g-markup-collect-attributes" role="function" condition="since:2.16"/>g_markup_collect_attributes ()</title>
692
 
<indexterm role="2.16"><primary>g_markup_collect_attributes</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_markup_collect_attributes         (const <link linkend="gchar">gchar</link> *element_name,
 
870
<refsect2 id="g-markup-collect-attributes" role="function" condition="since:2.16">
 
871
<title>g_markup_collect_attributes ()</title>
 
872
<indexterm zone="g-markup-collect-attributes" role="2.16"><primary sortas="g_markup_collect_attributes">g_markup_collect_attributes</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_markup_collect_attributes         (const <link linkend="gchar">gchar</link> *element_name,
693
873
                                                         const <link linkend="gchar">gchar</link> **attribute_names,
694
874
                                                         const <link linkend="gchar">gchar</link> **attribute_values,
695
875
                                                         <link linkend="GError">GError</link> **error,
732
912
<para>
733
913
The pointer should be of the appropriate type
734
914
(see the descriptions under
735
 
<link linkend="GMarkupCollectType"><type>GMarkupCollectType</type></link>) and may be <link linkend="NULL:CAPS"><literal>NULL</literal></link> in case a
 
915
<link linkend="GMarkupCollectType"><type>GMarkupCollectType</type></link>) and may be <link linkend="NULL--CAPS"><literal>NULL</literal></link> in case a
736
916
particular attribute is to be allowed but
737
917
ignored.
738
918
</para>
739
919
<para>
740
920
This function deals with issuing errors for missing attributes 
741
 
(of type <link linkend="G-MARKUP-ERROR-MISSING-ATTRIBUTE:CAPS"><literal>G_MARKUP_ERROR_MISSING_ATTRIBUTE</literal></link>), unknown attributes 
742
 
(of type <link linkend="G-MARKUP-ERROR-UNKNOWN-ATTRIBUTE:CAPS"><literal>G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE</literal></link>) and duplicate 
743
 
attributes (of type <link linkend="G-MARKUP-ERROR-INVALID-CONTENT:CAPS"><literal>G_MARKUP_ERROR_INVALID_CONTENT</literal></link>) as well 
 
921
(of type <link linkend="G-MARKUP-ERROR-MISSING-ATTRIBUTE--CAPS"><literal>G_MARKUP_ERROR_MISSING_ATTRIBUTE</literal></link>), unknown attributes 
 
922
(of type <link linkend="G-MARKUP-ERROR-UNKNOWN-ATTRIBUTE--CAPS"><literal>G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE</literal></link>) and duplicate 
 
923
attributes (of type <link linkend="G-MARKUP-ERROR-INVALID-CONTENT--CAPS"><literal>G_MARKUP_ERROR_INVALID_CONTENT</literal></link>) as well 
744
924
as parse errors for boolean-valued attributes (again of type
745
 
<link linkend="G-MARKUP-ERROR-INVALID-CONTENT:CAPS"><literal>G_MARKUP_ERROR_INVALID_CONTENT</literal></link>). In all of these cases <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> 
 
925
<link linkend="G-MARKUP-ERROR-INVALID-CONTENT--CAPS"><literal>G_MARKUP_ERROR_INVALID_CONTENT</literal></link>). In all of these cases <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> 
746
926
will be returned and <parameter>error</parameter> will be set as appropriate.</para>
747
927
<para>
748
 
 
749
928
</para><variablelist role="params">
750
 
<varlistentry><term><parameter>element_name</parameter>&nbsp;:</term>
 
929
<varlistentry><term><parameter>element_name</parameter>&#160;:</term>
751
930
<listitem><simpara> the current tag name
752
931
</simpara></listitem></varlistentry>
753
 
<varlistentry><term><parameter>attribute_names</parameter>&nbsp;:</term>
 
932
<varlistentry><term><parameter>attribute_names</parameter>&#160;:</term>
754
933
<listitem><simpara> the attribute names
755
934
</simpara></listitem></varlistentry>
756
 
<varlistentry><term><parameter>attribute_values</parameter>&nbsp;:</term>
 
935
<varlistentry><term><parameter>attribute_values</parameter>&#160;:</term>
757
936
<listitem><simpara> the attribute values
758
937
</simpara></listitem></varlistentry>
759
 
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
760
 
<listitem><simpara> a pointer to a <link linkend="GError"><type>GError</type></link> or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
938
<varlistentry><term><parameter>error</parameter>&#160;:</term>
 
939
<listitem><simpara> a pointer to a <link linkend="GError"><type>GError</type></link> or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
761
940
</simpara></listitem></varlistentry>
762
 
<varlistentry><term><parameter>first_type</parameter>&nbsp;:</term>
 
941
<varlistentry><term><parameter>first_type</parameter>&#160;:</term>
763
942
<listitem><simpara> the <link linkend="GMarkupCollectType"><type>GMarkupCollectType</type></link> of the
764
943
             first attribute
765
944
</simpara></listitem></varlistentry>
766
 
<varlistentry><term><parameter>first_attr</parameter>&nbsp;:</term>
 
945
<varlistentry><term><parameter>first_attr</parameter>&#160;:</term>
767
946
<listitem><simpara> the name of the first attribute
768
947
</simpara></listitem></varlistentry>
769
 
<varlistentry><term><parameter>...</parameter>&nbsp;:</term>
 
948
<varlistentry><term><parameter>...</parameter>&#160;:</term>
770
949
<listitem><simpara> a pointer to the storage location of the
771
 
      first attribute (or <link linkend="NULL:CAPS"><literal>NULL</literal></link>), followed by
 
950
      first attribute (or <link linkend="NULL--CAPS"><literal>NULL</literal></link>), followed by
772
951
      more types names and pointers, ending
773
 
      with <link linkend="G-MARKUP-COLLECT-INVALID:CAPS"><literal>G_MARKUP_COLLECT_INVALID</literal></link>.
 
952
      with <link linkend="G-MARKUP-COLLECT-INVALID--CAPS"><literal>G_MARKUP_COLLECT_INVALID</literal></link>.
774
953
</simpara></listitem></varlistentry>
775
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if successful
 
954
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if successful
776
955
 
777
956
</simpara></listitem></varlistentry>
778
 
</variablelist><para role="since">Since  2.16
779
 
</para></refsect2>
 
957
</variablelist><para role="since">Since 2.16</para></refsect2>
780
958
 
781
959
</refsect1>
782
960
 
783
961
 
784
962
 
785
963
 
786
 
 
787
 
<refsect1><refsect2 /><refsect2 /></refsect1>
788
964
</refentry>