← Back to branch summary

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

« back to all changes in this revision

Viewing changes to docs/reference/glib/xml/option.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/option.xml
1
1
<refentry id="glib-Commandline-option-parser">
2
2
<refmeta>
3
 
<refentrytitle role="top_of_page">Commandline option parser</refentrytitle>
 
3
<refentrytitle role="top_of_page" id="glib-Commandline-option-parser.top_of_page">Commandline option parser</refentrytitle>
4
4
<manvolnum>3</manvolnum>
5
5
<refmiscinfo>GLIB Library</refmiscinfo>
6
6
</refmeta>
8
8
<refnamediv>
9
9
<refname>Commandline option parser</refname>
10
10
<refpurpose>parses commandline options</refpurpose>
11
 
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
12
11
</refnamediv>
13
12
 
14
 
<refsynopsisdiv role="synopsis">
 
13
<refsynopsisdiv id="glib-Commandline-option-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="GOptionError">GOptionError</link>;
23
 
#define             <link linkend="G-OPTION-ERROR:CAPS">G_OPTION_ERROR</link>
 
21
#define             <link linkend="G-OPTION-ERROR--CAPS">G_OPTION_ERROR</link>
24
22
<link linkend="gboolean">gboolean</link>            (<link linkend="GOptionArgFunc">*GOptionArgFunc</link>)                   (const <link linkend="gchar">gchar</link> *option_name,
25
23
                                                         const <link linkend="gchar">gchar</link> *value,
26
24
                                                         <link linkend="gpointer">gpointer</link> data,
27
25
                                                         <link linkend="GError">GError</link> **error);
28
26
                    <link linkend="GOptionContext">GOptionContext</link>;
29
 
<link linkend="GOptionContext">GOptionContext</link>*     <link linkend="g-option-context-new">g_option_context_new</link>                (const <link linkend="gchar">gchar</link> *parameter_string);
 
27
<link linkend="GOptionContext">GOptionContext</link> *    <link linkend="g-option-context-new">g_option_context_new</link>                (const <link linkend="gchar">gchar</link> *parameter_string);
30
28
<link linkend="void">void</link>                <link linkend="g-option-context-set-summary">g_option_context_set_summary</link>        (<link linkend="GOptionContext">GOptionContext</link> *context,
31
29
                                                         const <link linkend="gchar">gchar</link> *summary);
32
 
const <link linkend="gchar">gchar</link>*        <link linkend="g-option-context-get-summary">g_option_context_get_summary</link>        (<link linkend="GOptionContext">GOptionContext</link> *context);
 
30
const <link linkend="gchar">gchar</link> *       <link linkend="g-option-context-get-summary">g_option_context_get_summary</link>        (<link linkend="GOptionContext">GOptionContext</link> *context);
33
31
<link linkend="void">void</link>                <link linkend="g-option-context-set-description">g_option_context_set_description</link>    (<link linkend="GOptionContext">GOptionContext</link> *context,
34
32
                                                         const <link linkend="gchar">gchar</link> *description);
35
 
const <link linkend="gchar">gchar</link>*        <link linkend="g-option-context-get-description">g_option_context_get_description</link>    (<link linkend="GOptionContext">GOptionContext</link> *context);
36
 
const <link linkend="gchar">gchar</link>*        (<link linkend="GTranslateFunc">*GTranslateFunc</link>)                   (const <link linkend="gchar">gchar</link> *str,
 
33
const <link linkend="gchar">gchar</link> *       <link linkend="g-option-context-get-description">g_option_context_get_description</link>    (<link linkend="GOptionContext">GOptionContext</link> *context);
 
34
const <link linkend="gchar">gchar</link> *       (<link linkend="GTranslateFunc">*GTranslateFunc</link>)                   (const <link linkend="gchar">gchar</link> *str,
37
35
                                                         <link linkend="gpointer">gpointer</link> data);
38
36
<link linkend="void">void</link>                <link linkend="g-option-context-set-translate-func">g_option_context_set_translate_func</link> (<link linkend="GOptionContext">GOptionContext</link> *context,
39
37
                                                         <link linkend="GTranslateFunc">GTranslateFunc</link> func,
55
53
                                                         <link linkend="gboolean">gboolean</link> ignore_unknown);
56
54
<link linkend="gboolean">gboolean</link>            <link linkend="g-option-context-get-ignore-unknown-options">g_option_context_get_ignore_unknown_options</link>
57
55
                                                        (<link linkend="GOptionContext">GOptionContext</link> *context);
58
 
<link linkend="gchar">gchar</link>*              <link linkend="g-option-context-get-help">g_option_context_get_help</link>           (<link linkend="GOptionContext">GOptionContext</link> *context,
 
56
<link linkend="gchar">gchar</link> *             <link linkend="g-option-context-get-help">g_option_context_get_help</link>           (<link linkend="GOptionContext">GOptionContext</link> *context,
59
57
                                                         <link linkend="gboolean">gboolean</link> main_help,
60
58
                                                         <link linkend="GOptionGroup">GOptionGroup</link> *group);
61
59
enum                <link linkend="GOptionArg">GOptionArg</link>;
62
60
enum                <link linkend="GOptionFlags">GOptionFlags</link>;
63
 
#define             <link linkend="G-OPTION-REMAINING:CAPS">G_OPTION_REMAINING</link>
 
61
#define             <link linkend="G-OPTION-REMAINING--CAPS">G_OPTION_REMAINING</link>
64
62
                    <link linkend="GOptionEntry">GOptionEntry</link>;
65
63
<link linkend="void">void</link>                <link linkend="g-option-context-add-main-entries">g_option_context_add_main_entries</link>   (<link linkend="GOptionContext">GOptionContext</link> *context,
66
64
                                                         const <link linkend="GOptionEntry">GOptionEntry</link> *entries,
70
68
                                                         <link linkend="GOptionGroup">GOptionGroup</link> *group);
71
69
<link linkend="void">void</link>                <link linkend="g-option-context-set-main-group">g_option_context_set_main_group</link>     (<link linkend="GOptionContext">GOptionContext</link> *context,
72
70
                                                         <link linkend="GOptionGroup">GOptionGroup</link> *group);
73
 
<link linkend="GOptionGroup">GOptionGroup</link>*       <link linkend="g-option-context-get-main-group">g_option_context_get_main_group</link>     (<link linkend="GOptionContext">GOptionContext</link> *context);
74
 
<link linkend="GOptionGroup">GOptionGroup</link>*       <link linkend="g-option-group-new">g_option_group_new</link>                  (const <link linkend="gchar">gchar</link> *name,
 
71
<link linkend="GOptionGroup">GOptionGroup</link> *      <link linkend="g-option-context-get-main-group">g_option_context_get_main_group</link>     (<link linkend="GOptionContext">GOptionContext</link> *context);
 
72
<link linkend="GOptionGroup">GOptionGroup</link> *      <link linkend="g-option-group-new">g_option_group_new</link>                  (const <link linkend="gchar">gchar</link> *name,
75
73
                                                         const <link linkend="gchar">gchar</link> *description,
76
74
                                                         const <link linkend="gchar">gchar</link> *help_description,
77
75
                                                         <link linkend="gpointer">gpointer</link> user_data,
99
97
<link linkend="void">void</link>                <link linkend="g-option-group-set-translation-domain">g_option_group_set_translation_domain</link>
100
98
                                                        (<link linkend="GOptionGroup">GOptionGroup</link> *group,
101
99
                                                         const <link linkend="gchar">gchar</link> *domain);
102
 
 
103
100
</synopsis>
104
101
</refsynopsisdiv>
105
102
 
111
108
 
112
109
 
113
110
 
114
 
<refsect1 role="desc">
 
111
<refsect1 id="glib-Commandline-option-parser.description" role="desc">
115
112
<title role="desc.title">Description</title>
116
113
<para>
117
114
The GOption commandline parser is intended to be a simpler replacement for the
118
 
popt library. It supports short and long commandline options, as shown in the 
 
115
popt library. It supports short and long commandline options, as shown in the
119
116
following example:
120
117
</para>
121
 
 
122
118
<para>
123
119
<literal>testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2</literal>
124
120
</para>
125
 
 
126
121
<para>
127
122
The example demonstrates a number of features of the GOption commandline parser
128
123
<itemizedlist>
134
129
  Long options are prefixed by two consecutive dashes.
135
130
</para></listitem>
136
131
<listitem><para>
137
 
  Options can have an extra argument, which can be a number, a string or a 
138
 
  filename. For long options, the extra argument can be appended with an 
 
132
  Options can have an extra argument, which can be a number, a string or a
 
133
  filename. For long options, the extra argument can be appended with an
139
134
  equals sign after the option name.
140
135
</para></listitem>
141
136
<listitem><para>
142
137
  Non-option arguments are returned to the application as rest arguments.
143
138
</para></listitem>
144
139
<listitem><para>
145
 
  An argument consisting solely of two dashes turns off further parsing, 
146
 
  any remaining arguments (even those starting with a dash) are returned 
 
140
  An argument consisting solely of two dashes turns off further parsing,
 
141
  any remaining arguments (even those starting with a dash) are returned
147
142
  to the application as rest arguments.
148
143
</para></listitem>
149
144
</itemizedlist>
150
145
</para>
151
 
 
152
146
<para>
153
 
Another important feature of GOption is that it can automatically generate 
154
 
nicely formatted help output. Unless it is explicitly turned off with 
155
 
<link linkend="g-option-context-set-help-enabled"><function>g_option_context_set_help_enabled()</function></link>, GOption will recognize the 
 
147
Another important feature of GOption is that it can automatically generate
 
148
nicely formatted help output. Unless it is explicitly turned off with
 
149
<link linkend="g-option-context-set-help-enabled"><function>g_option_context_set_help_enabled()</function></link>, GOption will recognize the
156
150
<option>--help</option>, <option>-?</option>, <option>--help-all</option>
157
 
and <option>--help-</option><replaceable>groupname</replaceable> options 
158
 
(where <replaceable>groupname</replaceable> is the name of a <link linkend="GOptionGroup"><type>GOptionGroup</type></link>) 
 
151
and <option>--help-</option><replaceable>groupname</replaceable> options
 
152
(where <replaceable>groupname</replaceable> is the name of a <link linkend="GOptionGroup"><type>GOptionGroup</type></link>)
159
153
and write a text similar to the one shown in the following example to stdout.
160
154
</para>
161
 
 
162
155
<informalexample><screen>
163
156
Usage:
164
157
  testtreemodel [OPTION...] - test tree model performance
165
 
 
166
158
Help Options:
167
159
  -?, --help               Show help options
168
160
  --help-all               Show all help options
169
161
  --help-gtk               Show GTK+ Options
170
 
 
171
162
Application Options:
172
163
  -r, --repeats=N          Average over N repetitions
173
164
  -m, --max-size=M         Test up to 2^M items
174
165
  --display=DISPLAY        X display to use
175
166
  -v, --verbose            Be verbose
176
 
  -b, --beep               Beep when done   
 
167
  -b, --beep               Beep when done
177
168
  --rand                   Randomize the data
178
169
</screen></informalexample>
179
 
 
180
170
<para>
181
171
GOption groups options in <link linkend="GOptionGroup"><type>GOptionGroup</type></link><!-- -->s, which makes it easy to
182
172
incorporate options from multiple sources. The intended use for this is
184
174
add them to their <link linkend="GOptionContext"><type>GOptionContext</type></link>, and parse all options by a single call
185
175
to <link linkend="g-option-context-parse"><function>g_option_context_parse()</function></link>. See <link linkend="gtk-get-option-group"><function>gtk_get_option_group()</function></link> for an example.
186
176
</para>
187
 
 
188
177
<para>
189
178
If an option is declared to be of type string or filename, GOption takes
190
179
care of converting it to the right encoding; strings are returned in UTF-8,
191
180
filenames are returned in the GLib filename encoding. Note that this only
192
181
works if <link linkend="setlocale"><function>setlocale()</function></link> has been called before <link linkend="g-option-context-parse"><function>g_option_context_parse()</function></link>.
193
182
</para>
194
 
 
195
183
<para>
196
184
Here is a complete example of setting up GOption to parse the example
197
185
commandline above and produce the example help output.
202
190
static gboolean verbose = FALSE;
203
191
static gboolean beep = FALSE;
204
192
static gboolean rand = FALSE;
205
 
 
206
 
static GOptionEntry entries[] = 
 
193
static GOptionEntry entries[] =
207
194
{
208
195
  { "repeats", 'r', 0, G_OPTION_ARG_INT, &amp;repeats, "Average over N repetitions", "N" },
209
196
  { "max-size", 'm', 0, G_OPTION_ARG_INT, &amp;max_size, "Test up to 2^M items", "M" },
212
199
  { "rand", 0, 0, G_OPTION_ARG_NONE, &amp;rand, "Randomize the data", NULL },
213
200
  { NULL }
214
201
};
215
 
 
216
 
int 
 
202
int
217
203
main (int argc, char *argv[])
218
204
{
219
205
  GError *error = NULL;
220
206
  GOptionContext *context;
221
 
 
222
207
  context = g_option_context_new ("- test tree model performance");
223
208
  g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE);
224
209
  g_option_context_add_group (context, gtk_get_option_group (TRUE));
227
212
      g_print ("option parsing failed: %s\n", error->message);
228
213
      exit (1);
229
214
    }
230
 
 
231
215
  /* ... */
232
 
 
233
216
}
234
217
</programlisting></informalexample>
235
218
</refsect1>
236
219
 
237
 
<refsect1 role="details">
 
220
<refsect1 id="glib-Commandline-option-parser.details" role="details">
238
221
<title role="details.title">Details</title>
239
 
<refsect2>
240
 
<title><anchor id="GOptionError" role="enum"/>enum GOptionError</title>
241
 
<indexterm><primary>GOptionError</primary></indexterm><programlisting>typedef enum
 
222
<refsect2 id="GOptionError" role="enum">
 
223
<title>enum GOptionError</title>
 
224
<indexterm zone="GOptionError"><primary sortas="GOptionError">GOptionError</primary></indexterm><programlisting>typedef enum
242
225
{
243
226
  G_OPTION_ERROR_UNKNOWN_OPTION,
244
227
  G_OPTION_ERROR_BAD_VALUE,
248
231
<para>
249
232
Error codes returned by option parsing.
250
233
</para><variablelist role="enum">
251
 
<varlistentry>
252
 
<term><anchor id="G-OPTION-ERROR-UNKNOWN-OPTION:CAPS" role="constant"/><literal>G_OPTION_ERROR_UNKNOWN_OPTION</literal></term>
 
234
<varlistentry id="G-OPTION-ERROR-UNKNOWN-OPTION--CAPS" role="constant">
 
235
<term><literal>G_OPTION_ERROR_UNKNOWN_OPTION</literal></term>
253
236
<listitem><simpara>An option was not known to the parser.
254
237
  This error will only be reported, if the parser hasn't been instructed
255
238
  to ignore unknown options, see <link linkend="g-option-context-set-ignore-unknown-options"><function>g_option_context_set_ignore_unknown_options()</function></link>.
256
239
</simpara></listitem>
257
240
</varlistentry>
258
 
<varlistentry>
259
 
<term><anchor id="G-OPTION-ERROR-BAD-VALUE:CAPS" role="constant"/><literal>G_OPTION_ERROR_BAD_VALUE</literal></term>
 
241
<varlistentry id="G-OPTION-ERROR-BAD-VALUE--CAPS" role="constant">
 
242
<term><literal>G_OPTION_ERROR_BAD_VALUE</literal></term>
260
243
<listitem><simpara>A value couldn't be parsed.
261
244
</simpara></listitem>
262
245
</varlistentry>
263
 
<varlistentry>
264
 
<term><anchor id="G-OPTION-ERROR-FAILED:CAPS" role="constant"/><literal>G_OPTION_ERROR_FAILED</literal></term>
 
246
<varlistentry id="G-OPTION-ERROR-FAILED--CAPS" role="constant">
 
247
<term><literal>G_OPTION_ERROR_FAILED</literal></term>
265
248
<listitem><simpara>A <link linkend="GOptionArgFunc"><type>GOptionArgFunc</type></link> callback failed.
266
 
 
267
249
</simpara></listitem>
268
250
</varlistentry>
269
251
</variablelist></refsect2>
270
 
<refsect2>
271
 
<title><anchor id="G-OPTION-ERROR:CAPS" role="macro"/>G_OPTION_ERROR</title>
272
 
<indexterm><primary>G_OPTION_ERROR</primary></indexterm><programlisting>#define G_OPTION_ERROR (g_option_error_quark ())
 
252
<refsect2 id="G-OPTION-ERROR--CAPS" role="macro">
 
253
<title>G_OPTION_ERROR</title>
 
254
<indexterm zone="G-OPTION-ERROR--CAPS"><primary sortas="G_OPTION_ERROR">G_OPTION_ERROR</primary></indexterm><programlisting>#define G_OPTION_ERROR (g_option_error_quark ())
273
255
</programlisting>
274
256
<para>
275
257
Error domain for option parsing. Errors in this domain will
276
 
be from the <link linkend="GOptionError"><type>GOptionError</type></link> enumeration. See <link linkend="GError"><type>GError</type></link> for information on 
 
258
be from the <link linkend="GOptionError"><type>GOptionError</type></link> enumeration. See <link linkend="GError"><type>GError</type></link> for information on
277
259
error domains.
278
260
</para></refsect2>
279
 
<refsect2>
280
 
<title><anchor id="GOptionArgFunc" role="function"/>GOptionArgFunc ()</title>
281
 
<indexterm><primary>GOptionArgFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            (*GOptionArgFunc)                   (const <link linkend="gchar">gchar</link> *option_name,
 
261
<refsect2 id="GOptionArgFunc" role="function">
 
262
<title>GOptionArgFunc ()</title>
 
263
<indexterm zone="GOptionArgFunc"><primary sortas="GOptionArgFunc">GOptionArgFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            (*GOptionArgFunc)                   (const <link linkend="gchar">gchar</link> *option_name,
282
264
                                                         const <link linkend="gchar">gchar</link> *value,
283
265
                                                         <link linkend="gpointer">gpointer</link> data,
284
266
                                                         <link linkend="GError">GError</link> **error);</programlisting>
285
267
<para>
286
 
The type of function to be passed as callback for <link linkend="G-OPTION-ARG-CALLBACK:CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link>
 
268
The type of function to be passed as callback for <link linkend="G-OPTION-ARG-CALLBACK--CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link>
287
269
options.
288
270
</para><variablelist role="params">
289
 
<varlistentry><term><parameter>option_name</parameter>&nbsp;:</term>
 
271
<varlistentry><term><parameter>option_name</parameter>&#160;:</term>
290
272
<listitem><simpara>The name of the option being parsed. This will be either a 
291
273
  single dash followed by a single letter (for a short name) or two dashes
292
274
  followed by a long option name.
293
275
</simpara></listitem></varlistentry>
294
 
<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
 
276
<varlistentry><term><parameter>value</parameter>&#160;:</term>
295
277
<listitem><simpara>The value to be parsed.
296
278
</simpara></listitem></varlistentry>
297
 
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
 
279
<varlistentry><term><parameter>data</parameter>&#160;:</term>
298
280
<listitem><simpara>User data added to the <link linkend="GOptionGroup"><type>GOptionGroup</type></link> containing the option when it
299
281
  was created with <link linkend="g-option-group-new"><function>g_option_group_new()</function></link>
300
282
</simpara></listitem></varlistentry>
301
 
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
302
 
<listitem><simpara>A return location for errors. The error code <link linkend="G-OPTION-ERROR-FAILED:CAPS"><literal>G_OPTION_ERROR_FAILED</literal></link>
 
283
<varlistentry><term><parameter>error</parameter>&#160;:</term>
 
284
<listitem><simpara>A return location for errors. The error code <link linkend="G-OPTION-ERROR-FAILED--CAPS"><literal>G_OPTION_ERROR_FAILED</literal></link>
303
285
  is intended to be used for errors in <link linkend="GOptionArgFunc"><type>GOptionArgFunc</type></link> callbacks.
304
286
</simpara></listitem></varlistentry>
305
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the option was successfully parsed, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if an error 
 
287
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if the option was successfully parsed, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if an error 
306
288
  occurred, in which case <parameter>error</parameter> should be set with <link linkend="g-set-error"><function>g_set_error()</function></link>
307
 
 
308
 
 
309
289
</simpara></listitem></varlistentry>
310
290
</variablelist></refsect2>
311
 
<refsect2>
312
 
<title><anchor id="GOptionContext" role="struct"/>GOptionContext</title>
313
 
<indexterm><primary>GOptionContext</primary></indexterm><programlisting>typedef struct _GOptionContext GOptionContext;</programlisting>
 
291
<refsect2 id="GOptionContext" role="struct">
 
292
<title>GOptionContext</title>
 
293
<indexterm zone="GOptionContext"><primary sortas="GOptionContext">GOptionContext</primary></indexterm><programlisting>typedef struct _GOptionContext GOptionContext;</programlisting>
314
294
<para>
315
295
A <structname>GOptionContext</structname> struct defines which options
316
 
are accepted by the commandline option parser. The struct has only private 
 
296
are accepted by the commandline option parser. The struct has only private
317
297
fields and should not be directly accessed.
318
298
</para></refsect2>
319
 
<refsect2>
320
 
<title><anchor id="g-option-context-new" role="function" condition="since:2.6"/>g_option_context_new ()</title>
321
 
<indexterm role="2.6"><primary>g_option_context_new</primary></indexterm><programlisting><link linkend="GOptionContext">GOptionContext</link>*     g_option_context_new                (const <link linkend="gchar">gchar</link> *parameter_string);</programlisting>
 
299
<refsect2 id="g-option-context-new" role="function" condition="since:2.6">
 
300
<title>g_option_context_new ()</title>
 
301
<indexterm zone="g-option-context-new" role="2.6"><primary sortas="g_option_context_new">g_option_context_new</primary></indexterm><programlisting><link linkend="GOptionContext">GOptionContext</link> *    g_option_context_new                (const <link linkend="gchar">gchar</link> *parameter_string);</programlisting>
322
302
<para>
323
303
Creates a new option context. 
324
304
</para>
326
306
The <parameter>parameter_string</parameter> can serve multiple purposes. It can be used
327
307
to add descriptions for "rest" arguments, which are not parsed by
328
308
the <link linkend="GOptionContext"><type>GOptionContext</type></link>, typically something like "FILES" or
329
 
"FILE1 FILE2...". If you are using <link linkend="G-OPTION-REMAINING:CAPS"><type>G_OPTION_REMAINING</type></link> for
 
309
"FILE1 FILE2...". If you are using <link linkend="G-OPTION-REMAINING--CAPS"><type>G_OPTION_REMAINING</type></link> for
330
310
collecting "rest" arguments, GLib handles this automatically by
331
311
using the <parameter>arg_description</parameter> of the corresponding <link linkend="GOptionEntry"><type>GOptionEntry</type></link> in
332
312
the usage summary.
343
323
function set with <link linkend="g-option-context-set-translate-func"><function>g_option_context_set_translate_func()</function></link>, so
344
324
it should normally be passed untranslated.</para>
345
325
<para>
346
 
 
347
326
</para><variablelist role="params">
348
 
<varlistentry><term><parameter>parameter_string</parameter>&nbsp;:</term>
 
327
<varlistentry><term><parameter>parameter_string</parameter>&#160;:</term>
349
328
<listitem><simpara> a string which is displayed in
350
329
   the first line of <option>--help</option> output, after the
351
330
   usage summary 
352
331
   <literal><replaceable>programname</replaceable> [OPTION...]</literal>
353
332
</simpara></listitem></varlistentry>
354
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly created <link linkend="GOptionContext"><type>GOptionContext</type></link>, which must be
 
333
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly created <link linkend="GOptionContext"><type>GOptionContext</type></link>, which must be
355
334
   freed with <link linkend="g-option-context-free"><function>g_option_context_free()</function></link> after use.
356
335
 
357
336
</simpara></listitem></varlistentry>
358
 
</variablelist><para role="since">Since  2.6
359
 
</para></refsect2>
360
 
<refsect2>
361
 
<title><anchor id="g-option-context-set-summary" role="function" condition="since:2.12"/>g_option_context_set_summary ()</title>
362
 
<indexterm role="2.12"><primary>g_option_context_set_summary</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_set_summary        (<link linkend="GOptionContext">GOptionContext</link> *context,
 
337
</variablelist><para role="since">Since 2.6</para></refsect2>
 
338
<refsect2 id="g-option-context-set-summary" role="function" condition="since:2.12">
 
339
<title>g_option_context_set_summary ()</title>
 
340
<indexterm zone="g-option-context-set-summary" role="2.12"><primary sortas="g_option_context_set_summary">g_option_context_set_summary</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_set_summary        (<link linkend="GOptionContext">GOptionContext</link> *context,
363
341
                                                         const <link linkend="gchar">gchar</link> *summary);</programlisting>
364
342
<para>
365
343
Adds a string to be displayed in <option>--help</option> output
370
348
Note that the summary is translated (see 
371
349
<link linkend="g-option-context-set-translate-func"><function>g_option_context_set_translate_func()</function></link>, <link linkend="g-option-context-set-translation-domain"><function>g_option_context_set_translation_domain()</function></link>).</para>
372
350
<para>
373
 
 
374
351
</para><variablelist role="params">
375
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
352
<varlistentry><term><parameter>context</parameter>&#160;:</term>
376
353
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
377
354
</simpara></listitem></varlistentry>
378
 
<varlistentry><term><parameter>summary</parameter>&nbsp;:</term>
 
355
<varlistentry><term><parameter>summary</parameter>&#160;:</term>
379
356
<listitem><simpara> a string to be shown in <option>--help</option> output 
380
 
 before the list of options, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
357
 before the list of options, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
381
358
</simpara></listitem></varlistentry>
382
 
</variablelist><para role="since">Since  2.12
383
 
</para></refsect2>
384
 
<refsect2>
385
 
<title><anchor id="g-option-context-get-summary" role="function" condition="since:2.12"/>g_option_context_get_summary ()</title>
386
 
<indexterm role="2.12"><primary>g_option_context_get_summary</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_option_context_get_summary        (<link linkend="GOptionContext">GOptionContext</link> *context);</programlisting>
 
359
</variablelist><para role="since">Since 2.12</para></refsect2>
 
360
<refsect2 id="g-option-context-get-summary" role="function" condition="since:2.12">
 
361
<title>g_option_context_get_summary ()</title>
 
362
<indexterm zone="g-option-context-get-summary" role="2.12"><primary sortas="g_option_context_get_summary">g_option_context_get_summary</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> *       g_option_context_get_summary        (<link linkend="GOptionContext">GOptionContext</link> *context);</programlisting>
387
363
<para>
388
364
Returns the summary. See <link linkend="g-option-context-set-summary"><function>g_option_context_set_summary()</function></link>.</para>
389
365
<para>
390
 
 
391
366
</para><variablelist role="params">
392
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
367
<varlistentry><term><parameter>context</parameter>&#160;:</term>
393
368
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
394
369
</simpara></listitem></varlistentry>
395
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the summary
 
370
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the summary
396
371
 
397
372
</simpara></listitem></varlistentry>
398
 
</variablelist><para role="since">Since  2.12
399
 
</para></refsect2>
400
 
<refsect2>
401
 
<title><anchor id="g-option-context-set-description" role="function" condition="since:2.12"/>g_option_context_set_description ()</title>
402
 
<indexterm role="2.12"><primary>g_option_context_set_description</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_set_description    (<link linkend="GOptionContext">GOptionContext</link> *context,
 
373
</variablelist><para role="since">Since 2.12</para></refsect2>
 
374
<refsect2 id="g-option-context-set-description" role="function" condition="since:2.12">
 
375
<title>g_option_context_set_description ()</title>
 
376
<indexterm zone="g-option-context-set-description" role="2.12"><primary sortas="g_option_context_set_description">g_option_context_set_description</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_set_description    (<link linkend="GOptionContext">GOptionContext</link> *context,
403
377
                                                         const <link linkend="gchar">gchar</link> *description);</programlisting>
404
378
<para>
405
379
Adds a string to be displayed in <option>--help</option> output
410
384
Note that the summary is translated (see 
411
385
<link linkend="g-option-context-set-translate-func"><function>g_option_context_set_translate_func()</function></link>).</para>
412
386
<para>
413
 
 
414
387
</para><variablelist role="params">
415
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
388
<varlistentry><term><parameter>context</parameter>&#160;:</term>
416
389
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
417
390
</simpara></listitem></varlistentry>
418
 
<varlistentry><term><parameter>description</parameter>&nbsp;:</term>
 
391
<varlistentry><term><parameter>description</parameter>&#160;:</term>
419
392
<listitem><simpara> a string to be shown in <option>--help</option> output 
420
 
  after the list of options, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
393
  after the list of options, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
421
394
</simpara></listitem></varlistentry>
422
 
</variablelist><para role="since">Since  2.12
423
 
</para></refsect2>
424
 
<refsect2>
425
 
<title><anchor id="g-option-context-get-description" role="function" condition="since:2.12"/>g_option_context_get_description ()</title>
426
 
<indexterm role="2.12"><primary>g_option_context_get_description</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        g_option_context_get_description    (<link linkend="GOptionContext">GOptionContext</link> *context);</programlisting>
 
395
</variablelist><para role="since">Since 2.12</para></refsect2>
 
396
<refsect2 id="g-option-context-get-description" role="function" condition="since:2.12">
 
397
<title>g_option_context_get_description ()</title>
 
398
<indexterm zone="g-option-context-get-description" role="2.12"><primary sortas="g_option_context_get_description">g_option_context_get_description</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> *       g_option_context_get_description    (<link linkend="GOptionContext">GOptionContext</link> *context);</programlisting>
427
399
<para>
428
400
Returns the description. See <link linkend="g-option-context-set-description"><function>g_option_context_set_description()</function></link>.</para>
429
401
<para>
430
 
 
431
402
</para><variablelist role="params">
432
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
403
<varlistentry><term><parameter>context</parameter>&#160;:</term>
433
404
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
434
405
</simpara></listitem></varlistentry>
435
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the description
 
406
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the description
436
407
 
437
408
</simpara></listitem></varlistentry>
438
 
</variablelist><para role="since">Since  2.12
439
 
</para></refsect2>
440
 
<refsect2>
441
 
<title><anchor id="GTranslateFunc" role="function"/>GTranslateFunc ()</title>
442
 
<indexterm><primary>GTranslateFunc</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>*        (*GTranslateFunc)                   (const <link linkend="gchar">gchar</link> *str,
 
409
</variablelist><para role="since">Since 2.12</para></refsect2>
 
410
<refsect2 id="GTranslateFunc" role="function">
 
411
<title>GTranslateFunc ()</title>
 
412
<indexterm zone="GTranslateFunc"><primary sortas="GTranslateFunc">GTranslateFunc</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> *       (*GTranslateFunc)                   (const <link linkend="gchar">gchar</link> *str,
443
413
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
444
414
<para>
445
415
The type of functions which are used to translate user-visible
446
416
strings, for <option>--help</option> output.
447
417
</para><variablelist role="params">
448
 
<varlistentry><term><parameter>str</parameter>&nbsp;:</term>
 
418
<varlistentry><term><parameter>str</parameter>&#160;:</term>
449
419
<listitem><simpara>the untranslated string
450
420
</simpara></listitem></varlistentry>
451
 
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
 
421
<varlistentry><term><parameter>data</parameter>&#160;:</term>
452
422
<listitem><simpara>user data specified when installing the function, e.g.
453
423
  in <link linkend="g-option-group-set-translate-func"><function>g_option_group_set_translate_func()</function></link>
454
424
</simpara></listitem></varlistentry>
455
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>a translation of the string for the current locale.
 
425
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>a translation of the string for the current locale.
456
426
  The returned string is owned by GLib and must not be freed.
457
 
 
458
 
 
459
427
</simpara></listitem></varlistentry>
460
428
</variablelist></refsect2>
461
 
<refsect2>
462
 
<title><anchor id="g-option-context-set-translate-func" role="function" condition="since:2.12"/>g_option_context_set_translate_func ()</title>
463
 
<indexterm role="2.12"><primary>g_option_context_set_translate_func</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_set_translate_func (<link linkend="GOptionContext">GOptionContext</link> *context,
 
429
<refsect2 id="g-option-context-set-translate-func" role="function" condition="since:2.12">
 
430
<title>g_option_context_set_translate_func ()</title>
 
431
<indexterm zone="g-option-context-set-translate-func" role="2.12"><primary sortas="g_option_context_set_translate_func">g_option_context_set_translate_func</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_set_translate_func (<link linkend="GOptionContext">GOptionContext</link> *context,
464
432
                                                         <link linkend="GTranslateFunc">GTranslateFunc</link> func,
465
433
                                                         <link linkend="gpointer">gpointer</link> data,
466
434
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_notify);</programlisting>
467
435
<para>
468
436
Sets the function which is used to translate the contexts 
469
437
user-visible strings, for <option>--help</option> output. 
470
 
If <parameter>func</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, strings are not translated.
 
438
If <parameter>func</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, strings are not translated.
471
439
</para>
472
440
<para>
473
441
Note that option groups have their own translation functions, 
479
447
If you are using <link linkend="gettext"><function>gettext()</function></link>, you only need to set the translation
480
448
domain, see <link linkend="g-context-group-set-translation-domain"><function>g_context_group_set_translation_domain()</function></link>.</para>
481
449
<para>
482
 
 
483
450
</para><variablelist role="params">
484
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
451
<varlistentry><term><parameter>context</parameter>&#160;:</term>
485
452
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
486
453
</simpara></listitem></varlistentry>
487
 
<varlistentry><term><parameter>func</parameter>&nbsp;:</term>
488
 
<listitem><simpara> the <link linkend="GTranslateFunc"><type>GTranslateFunc</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> 
489
 
</simpara></listitem></varlistentry>
490
 
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
491
 
<listitem><simpara> user data to pass to <parameter>func</parameter>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
492
 
</simpara></listitem></varlistentry>
493
 
<varlistentry><term><parameter>destroy_notify</parameter>&nbsp;:</term>
494
 
<listitem><simpara> a function which gets called to free <parameter>data</parameter>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
495
 
</simpara></listitem></varlistentry>
496
 
</variablelist><para role="since">Since  2.12
497
 
</para></refsect2>
498
 
<refsect2>
499
 
<title><anchor id="g-option-context-set-translation-domain" role="function" condition="since:2.12"/>g_option_context_set_translation_domain ()</title>
500
 
<indexterm role="2.12"><primary>g_option_context_set_translation_domain</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_set_translation_domain
 
454
<varlistentry><term><parameter>func</parameter>&#160;:</term>
 
455
<listitem><simpara> the <link linkend="GTranslateFunc"><type>GTranslateFunc</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> 
 
456
</simpara></listitem></varlistentry>
 
457
<varlistentry><term><parameter>data</parameter>&#160;:</term>
 
458
<listitem><simpara> user data to pass to <parameter>func</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 
459
</simpara></listitem></varlistentry>
 
460
<varlistentry><term><parameter>destroy_notify</parameter>&#160;:</term>
 
461
<listitem><simpara> a function which gets called to free <parameter>data</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 
462
</simpara></listitem></varlistentry>
 
463
</variablelist><para role="since">Since 2.12</para></refsect2>
 
464
<refsect2 id="g-option-context-set-translation-domain" role="function" condition="since:2.12">
 
465
<title>g_option_context_set_translation_domain ()</title>
 
466
<indexterm zone="g-option-context-set-translation-domain" role="2.12"><primary sortas="g_option_context_set_translation_domain">g_option_context_set_translation_domain</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_set_translation_domain
501
467
                                                        (<link linkend="GOptionContext">GOptionContext</link> *context,
502
468
                                                         const <link linkend="gchar">gchar</link> *domain);</programlisting>
503
469
<para>
504
470
A convenience function to use <link linkend="gettext"><function>gettext()</function></link> for translating
505
471
user-visible strings.</para>
506
472
<para>
507
 
 
508
473
</para><variablelist role="params">
509
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
474
<varlistentry><term><parameter>context</parameter>&#160;:</term>
510
475
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
511
476
</simpara></listitem></varlistentry>
512
 
<varlistentry><term><parameter>domain</parameter>&nbsp;:</term>
 
477
<varlistentry><term><parameter>domain</parameter>&#160;:</term>
513
478
<listitem><simpara> the domain to use
514
479
</simpara></listitem></varlistentry>
515
 
</variablelist><para role="since">Since  2.12
516
 
</para></refsect2>
517
 
<refsect2>
518
 
<title><anchor id="g-option-context-free" role="function" condition="since:2.6"/>g_option_context_free ()</title>
519
 
<indexterm role="2.6"><primary>g_option_context_free</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_free               (<link linkend="GOptionContext">GOptionContext</link> *context);</programlisting>
 
480
</variablelist><para role="since">Since 2.12</para></refsect2>
 
481
<refsect2 id="g-option-context-free" role="function" condition="since:2.6">
 
482
<title>g_option_context_free ()</title>
 
483
<indexterm zone="g-option-context-free" role="2.6"><primary sortas="g_option_context_free">g_option_context_free</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_free               (<link linkend="GOptionContext">GOptionContext</link> *context);</programlisting>
520
484
<para>
521
485
Frees context and all the groups which have been 
522
486
added to it.</para>
523
487
<para>
524
 
 
525
488
</para><variablelist role="params">
526
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
489
<varlistentry><term><parameter>context</parameter>&#160;:</term>
527
490
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link> 
528
491
</simpara></listitem></varlistentry>
529
 
</variablelist><para role="since">Since  2.6
530
 
</para></refsect2>
531
 
<refsect2>
532
 
<title><anchor id="g-option-context-parse" role="function" condition="since:2.6"/>g_option_context_parse ()</title>
533
 
<indexterm role="2.6"><primary>g_option_context_parse</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_option_context_parse              (<link linkend="GOptionContext">GOptionContext</link> *context,
 
492
</variablelist><para role="since">Since 2.6</para></refsect2>
 
493
<refsect2 id="g-option-context-parse" role="function" condition="since:2.6">
 
494
<title>g_option_context_parse ()</title>
 
495
<indexterm zone="g-option-context-parse" role="2.6"><primary sortas="g_option_context_parse">g_option_context_parse</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_option_context_parse              (<link linkend="GOptionContext">GOptionContext</link> *context,
534
496
                                                         <link linkend="gint">gint</link> *argc,
535
497
                                                         <link linkend="gchar">gchar</link> ***argv,
536
498
                                                         <link linkend="GError">GError</link> **error);</programlisting>
561
523
automatic character set conversion of string and filename
562
524
arguments.</para>
563
525
<para>
564
 
 
565
526
</para><variablelist role="params">
566
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
527
<varlistentry><term><parameter>context</parameter>&#160;:</term>
567
528
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
568
529
</simpara></listitem></varlistentry>
569
 
<varlistentry><term><parameter>argc</parameter>&nbsp;:</term>
 
530
<varlistentry><term><parameter>argc</parameter>&#160;:</term>
570
531
<listitem><simpara> a pointer to the number of command line arguments
571
532
</simpara></listitem></varlistentry>
572
 
<varlistentry><term><parameter>argv</parameter>&nbsp;:</term>
 
533
<varlistentry><term><parameter>argv</parameter>&#160;:</term>
573
534
<listitem><simpara> a pointer to the array of command line arguments
574
535
</simpara></listitem></varlistentry>
575
 
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
536
<varlistentry><term><parameter>error</parameter>&#160;:</term>
576
537
<listitem><simpara> a return location for errors 
577
538
</simpara></listitem></varlistentry>
578
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the parsing was successful, 
579
 
              <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if an error occurred
 
539
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the parsing was successful, 
 
540
              <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if an error occurred
580
541
 
581
542
</simpara></listitem></varlistentry>
582
 
</variablelist><para role="since">Since  2.6
583
 
</para></refsect2>
584
 
<refsect2>
585
 
<title><anchor id="g-option-context-set-help-enabled" role="function" condition="since:2.6"/>g_option_context_set_help_enabled ()</title>
586
 
<indexterm role="2.6"><primary>g_option_context_set_help_enabled</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_set_help_enabled   (<link linkend="GOptionContext">GOptionContext</link> *context,
 
543
</variablelist><para role="since">Since 2.6</para></refsect2>
 
544
<refsect2 id="g-option-context-set-help-enabled" role="function" condition="since:2.6">
 
545
<title>g_option_context_set_help_enabled ()</title>
 
546
<indexterm zone="g-option-context-set-help-enabled" role="2.6"><primary sortas="g_option_context_set_help_enabled">g_option_context_set_help_enabled</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_set_help_enabled   (<link linkend="GOptionContext">GOptionContext</link> *context,
587
547
                                                         <link linkend="gboolean">gboolean</link> help_enabled);</programlisting>
588
548
<para>
589
549
Enables or disables automatic generation of <option>--help</option> 
592
552
and <option>--help-</option><replaceable>groupname</replaceable> and creates
593
553
suitable output to stdout.</para>
594
554
<para>
595
 
 
596
555
</para><variablelist role="params">
597
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
556
<varlistentry><term><parameter>context</parameter>&#160;:</term>
598
557
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
599
558
</simpara></listitem></varlistentry>
600
 
<varlistentry><term><parameter>help_enabled</parameter>&nbsp;:</term>
601
 
<listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> to enable <option>--help</option>, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> to disable it
 
559
<varlistentry><term><parameter>help_enabled</parameter>&#160;:</term>
 
560
<listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> to enable <option>--help</option>, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> to disable it
602
561
</simpara></listitem></varlistentry>
603
 
</variablelist><para role="since">Since  2.6
604
 
</para></refsect2>
605
 
<refsect2>
606
 
<title><anchor id="g-option-context-get-help-enabled" role="function" condition="since:2.6"/>g_option_context_get_help_enabled ()</title>
607
 
<indexterm role="2.6"><primary>g_option_context_get_help_enabled</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_option_context_get_help_enabled   (<link linkend="GOptionContext">GOptionContext</link> *context);</programlisting>
 
562
</variablelist><para role="since">Since 2.6</para></refsect2>
 
563
<refsect2 id="g-option-context-get-help-enabled" role="function" condition="since:2.6">
 
564
<title>g_option_context_get_help_enabled ()</title>
 
565
<indexterm zone="g-option-context-get-help-enabled" role="2.6"><primary sortas="g_option_context_get_help_enabled">g_option_context_get_help_enabled</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_option_context_get_help_enabled   (<link linkend="GOptionContext">GOptionContext</link> *context);</programlisting>
608
566
<para>
609
567
Returns whether automatic <option>--help</option> generation
610
568
is turned on for <parameter>context</parameter>. See <link linkend="g-option-context-set-help-enabled"><function>g_option_context_set_help_enabled()</function></link>.</para>
611
569
<para>
612
 
 
613
570
</para><variablelist role="params">
614
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
571
<varlistentry><term><parameter>context</parameter>&#160;:</term>
615
572
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
616
573
</simpara></listitem></varlistentry>
617
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if automatic help generation is turned on.
 
574
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if automatic help generation is turned on.
618
575
 
619
576
</simpara></listitem></varlistentry>
620
 
</variablelist><para role="since">Since  2.6
621
 
</para></refsect2>
622
 
<refsect2>
623
 
<title><anchor id="g-option-context-set-ignore-unknown-options" role="function" condition="since:2.6"/>g_option_context_set_ignore_unknown_options ()</title>
624
 
<indexterm role="2.6"><primary>g_option_context_set_ignore_unknown_options</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_set_ignore_unknown_options
 
577
</variablelist><para role="since">Since 2.6</para></refsect2>
 
578
<refsect2 id="g-option-context-set-ignore-unknown-options" role="function" condition="since:2.6">
 
579
<title>g_option_context_set_ignore_unknown_options ()</title>
 
580
<indexterm zone="g-option-context-set-ignore-unknown-options" role="2.6"><primary sortas="g_option_context_set_ignore_unknown_options">g_option_context_set_ignore_unknown_options</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_set_ignore_unknown_options
625
581
                                                        (<link linkend="GOptionContext">GOptionContext</link> *context,
626
582
                                                         <link linkend="gboolean">gboolean</link> ignore_unknown);</programlisting>
627
583
<para>
634
590
which don't start with a dash). But note that GOption cannot reliably
635
591
determine whether a non-option belongs to a preceding unknown option.</para>
636
592
<para>
637
 
 
638
593
</para><variablelist role="params">
639
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
594
<varlistentry><term><parameter>context</parameter>&#160;:</term>
640
595
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
641
596
</simpara></listitem></varlistentry>
642
 
<varlistentry><term><parameter>ignore_unknown</parameter>&nbsp;:</term>
643
 
<listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> to ignore unknown options, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> to produce
 
597
<varlistentry><term><parameter>ignore_unknown</parameter>&#160;:</term>
 
598
<listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> to ignore unknown options, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> to produce
644
599
   an error when unknown options are met
645
600
</simpara></listitem></varlistentry>
646
 
</variablelist><para role="since">Since  2.6
647
 
</para></refsect2>
648
 
<refsect2>
649
 
<title><anchor id="g-option-context-get-ignore-unknown-options" role="function" condition="since:2.6"/>g_option_context_get_ignore_unknown_options ()</title>
650
 
<indexterm role="2.6"><primary>g_option_context_get_ignore_unknown_options</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_option_context_get_ignore_unknown_options
 
601
</variablelist><para role="since">Since 2.6</para></refsect2>
 
602
<refsect2 id="g-option-context-get-ignore-unknown-options" role="function" condition="since:2.6">
 
603
<title>g_option_context_get_ignore_unknown_options ()</title>
 
604
<indexterm zone="g-option-context-get-ignore-unknown-options" role="2.6"><primary sortas="g_option_context_get_ignore_unknown_options">g_option_context_get_ignore_unknown_options</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_option_context_get_ignore_unknown_options
651
605
                                                        (<link linkend="GOptionContext">GOptionContext</link> *context);</programlisting>
652
606
<para>
653
607
Returns whether unknown options are ignored or not. See
654
608
<link linkend="g-option-context-set-ignore-unknown-options"><function>g_option_context_set_ignore_unknown_options()</function></link>.</para>
655
609
<para>
656
 
 
657
610
</para><variablelist role="params">
658
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
611
<varlistentry><term><parameter>context</parameter>&#160;:</term>
659
612
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
660
613
</simpara></listitem></varlistentry>
661
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if unknown options are ignored.
 
614
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if unknown options are ignored.
662
615
 
663
616
</simpara></listitem></varlistentry>
664
 
</variablelist><para role="since">Since  2.6
665
 
</para></refsect2>
666
 
<refsect2>
667
 
<title><anchor id="g-option-context-get-help" role="function" condition="since:2.14"/>g_option_context_get_help ()</title>
668
 
<indexterm role="2.14"><primary>g_option_context_get_help</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*              g_option_context_get_help           (<link linkend="GOptionContext">GOptionContext</link> *context,
 
617
</variablelist><para role="since">Since 2.6</para></refsect2>
 
618
<refsect2 id="g-option-context-get-help" role="function" condition="since:2.14">
 
619
<title>g_option_context_get_help ()</title>
 
620
<indexterm zone="g-option-context-get-help" role="2.14"><primary sortas="g_option_context_get_help">g_option_context_get_help</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             g_option_context_get_help           (<link linkend="GOptionContext">GOptionContext</link> *context,
669
621
                                                         <link linkend="gboolean">gboolean</link> main_help,
670
622
                                                         <link linkend="GOptionGroup">GOptionGroup</link> *group);</programlisting>
671
623
<para>
677
629
To obtain the help text for an option group, call
678
630
<literal>g_option_context_get_help (context, FALSE, group)</literal>.</para>
679
631
<para>
680
 
 
681
632
</para><variablelist role="params">
682
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
633
<varlistentry><term><parameter>context</parameter>&#160;:</term>
683
634
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
684
635
</simpara></listitem></varlistentry>
685
 
<varlistentry><term><parameter>main_help</parameter>&nbsp;:</term>
686
 
<listitem><simpara> if <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, only include the main group 
687
 
</simpara></listitem></varlistentry>
688
 
<varlistentry><term><parameter>group</parameter>&nbsp;:</term>
689
 
<listitem><simpara> the <link linkend="GOptionGroup"><type>GOptionGroup</type></link> to create help for, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
690
 
</simpara></listitem></varlistentry>
691
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A newly allocated string containing the help text
 
636
<varlistentry><term><parameter>main_help</parameter>&#160;:</term>
 
637
<listitem><simpara> if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, only include the main group 
 
638
</simpara></listitem></varlistentry>
 
639
<varlistentry><term><parameter>group</parameter>&#160;:</term>
 
640
<listitem><simpara> the <link linkend="GOptionGroup"><type>GOptionGroup</type></link> to create help for, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 
641
</simpara></listitem></varlistentry>
 
642
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> A newly allocated string containing the help text
692
643
 
693
644
</simpara></listitem></varlistentry>
694
 
</variablelist><para role="since">Since  2.14
695
 
</para></refsect2>
696
 
<refsect2>
697
 
<title><anchor id="GOptionArg" role="enum"/>enum GOptionArg</title>
698
 
<indexterm><primary>GOptionArg</primary></indexterm><programlisting>typedef enum
 
645
</variablelist><para role="since">Since 2.14</para></refsect2>
 
646
<refsect2 id="GOptionArg" role="enum">
 
647
<title>enum GOptionArg</title>
 
648
<indexterm zone="GOptionArg"><primary sortas="GOptionArg">GOptionArg</primary></indexterm><programlisting>typedef enum
699
649
{
700
650
  G_OPTION_ARG_NONE,
701
651
  G_OPTION_ARG_STRING,
715
665
<option>-x arg</option>, with a long option: <option>--name arg</option>
716
666
or combined in a single argument: <option>--name=arg</option>.
717
667
</para><variablelist role="enum">
718
 
<varlistentry>
719
 
<term><anchor id="G-OPTION-ARG-NONE:CAPS" role="constant"/><literal>G_OPTION_ARG_NONE</literal></term>
 
668
<varlistentry id="G-OPTION-ARG-NONE--CAPS" role="constant">
 
669
<term><literal>G_OPTION_ARG_NONE</literal></term>
720
670
<listitem><simpara>No extra argument. This is useful for simple flags.
721
671
</simpara></listitem>
722
672
</varlistentry>
723
 
<varlistentry>
724
 
<term><anchor id="G-OPTION-ARG-STRING:CAPS" role="constant"/><literal>G_OPTION_ARG_STRING</literal></term>
 
673
<varlistentry id="G-OPTION-ARG-STRING--CAPS" role="constant">
 
674
<term><literal>G_OPTION_ARG_STRING</literal></term>
725
675
<listitem><simpara>The option takes a string argument.
726
676
</simpara></listitem>
727
677
</varlistentry>
728
 
<varlistentry>
729
 
<term><anchor id="G-OPTION-ARG-INT:CAPS" role="constant"/><literal>G_OPTION_ARG_INT</literal></term>
 
678
<varlistentry id="G-OPTION-ARG-INT--CAPS" role="constant">
 
679
<term><literal>G_OPTION_ARG_INT</literal></term>
730
680
<listitem><simpara>The option takes an integer argument.
731
681
</simpara></listitem>
732
682
</varlistentry>
733
 
<varlistentry>
734
 
<term><anchor id="G-OPTION-ARG-CALLBACK:CAPS" role="constant"/><literal>G_OPTION_ARG_CALLBACK</literal></term>
 
683
<varlistentry id="G-OPTION-ARG-CALLBACK--CAPS" role="constant">
 
684
<term><literal>G_OPTION_ARG_CALLBACK</literal></term>
735
685
<listitem><simpara>The option provides a callback to parse the
736
686
  extra argument.
737
687
</simpara></listitem>
738
688
</varlistentry>
739
 
<varlistentry>
740
 
<term><anchor id="G-OPTION-ARG-FILENAME:CAPS" role="constant"/><literal>G_OPTION_ARG_FILENAME</literal></term>
 
689
<varlistentry id="G-OPTION-ARG-FILENAME--CAPS" role="constant">
 
690
<term><literal>G_OPTION_ARG_FILENAME</literal></term>
741
691
<listitem><simpara>The option takes a filename as argument.
742
692
</simpara></listitem>
743
693
</varlistentry>
744
 
<varlistentry>
745
 
<term><anchor id="G-OPTION-ARG-STRING-ARRAY:CAPS" role="constant"/><literal>G_OPTION_ARG_STRING_ARRAY</literal></term>
 
694
<varlistentry id="G-OPTION-ARG-STRING-ARRAY--CAPS" role="constant">
 
695
<term><literal>G_OPTION_ARG_STRING_ARRAY</literal></term>
746
696
<listitem><simpara>The option takes a string argument, multiple
747
697
  uses of the option are collected into an array of strings.
748
698
</simpara></listitem>
749
699
</varlistentry>
750
 
<varlistentry>
751
 
<term><anchor id="G-OPTION-ARG-FILENAME-ARRAY:CAPS" role="constant"/><literal>G_OPTION_ARG_FILENAME_ARRAY</literal></term>
 
700
<varlistentry id="G-OPTION-ARG-FILENAME-ARRAY--CAPS" role="constant">
 
701
<term><literal>G_OPTION_ARG_FILENAME_ARRAY</literal></term>
752
702
<listitem><simpara>The option takes a filename as argument, 
753
703
  multiple uses of the option are collected into an array of strings.
754
704
</simpara></listitem>
755
705
</varlistentry>
756
 
<varlistentry>
757
 
<term><anchor id="G-OPTION-ARG-DOUBLE:CAPS" role="constant"/><literal>G_OPTION_ARG_DOUBLE</literal></term>
 
706
<varlistentry id="G-OPTION-ARG-DOUBLE--CAPS" role="constant">
 
707
<term><literal>G_OPTION_ARG_DOUBLE</literal></term>
758
708
<listitem><simpara>The option takes a double argument. The argument
759
709
  can be formatted either for the user's locale or for the "C" locale. Since 2.12
760
710
</simpara></listitem>
761
711
</varlistentry>
762
 
<varlistentry>
763
 
<term><anchor id="G-OPTION-ARG-INT64:CAPS" role="constant"/><literal>G_OPTION_ARG_INT64</literal></term>
764
 
<listitem><simpara>The option takes a 64-bit integer. Like <link linkend="G-OPTION-ARG-INT:CAPS"><literal>G_OPTION_ARG_INT</literal></link>
 
712
<varlistentry id="G-OPTION-ARG-INT64--CAPS" role="constant">
 
713
<term><literal>G_OPTION_ARG_INT64</literal></term>
 
714
<listitem><simpara>The option takes a 64-bit integer. Like <link linkend="G-OPTION-ARG-INT--CAPS"><literal>G_OPTION_ARG_INT</literal></link>
765
715
  but for larger numbers. The number can be in decimal base, or in hexadecimal
766
716
  (when prefixed with <literal>0x</literal>, for example, <literal>0xffffffff</literal>).
767
717
  Since 2.12
768
 
 
769
718
</simpara></listitem>
770
719
</varlistentry>
771
720
</variablelist></refsect2>
772
 
<refsect2>
773
 
<title><anchor id="GOptionFlags" role="enum"/>enum GOptionFlags</title>
774
 
<indexterm><primary>GOptionFlags</primary></indexterm><programlisting>typedef enum
 
721
<refsect2 id="GOptionFlags" role="enum">
 
722
<title>enum GOptionFlags</title>
 
723
<indexterm zone="GOptionFlags"><primary sortas="GOptionFlags">GOptionFlags</primary></indexterm><programlisting>typedef enum
775
724
{
776
725
  G_OPTION_FLAG_HIDDEN          = 1 &lt;&lt; 0,
777
726
  G_OPTION_FLAG_IN_MAIN         = 1 &lt;&lt; 1,
785
734
<para>
786
735
Flags which modify individual options.
787
736
</para><variablelist role="enum">
788
 
<varlistentry>
789
 
<term><anchor id="G-OPTION-FLAG-HIDDEN:CAPS" role="constant"/><literal>G_OPTION_FLAG_HIDDEN</literal></term>
 
737
<varlistentry id="G-OPTION-FLAG-HIDDEN--CAPS" role="constant">
 
738
<term><literal>G_OPTION_FLAG_HIDDEN</literal></term>
790
739
<listitem><simpara>The option doesn't appear in <option>--help</option>
791
740
   output.
792
741
</simpara></listitem>
793
742
</varlistentry>
794
 
<varlistentry>
795
 
<term><anchor id="G-OPTION-FLAG-IN-MAIN:CAPS" role="constant"/><literal>G_OPTION_FLAG_IN_MAIN</literal></term>
 
743
<varlistentry id="G-OPTION-FLAG-IN-MAIN--CAPS" role="constant">
 
744
<term><literal>G_OPTION_FLAG_IN_MAIN</literal></term>
796
745
<listitem><simpara>The option appears in the main section of the
797
746
   <option>--help</option> output, even if it is defined in a group.
798
747
</simpara></listitem>
799
748
</varlistentry>
800
 
<varlistentry>
801
 
<term><anchor id="G-OPTION-FLAG-REVERSE:CAPS" role="constant"/><literal>G_OPTION_FLAG_REVERSE</literal></term>
802
 
<listitem><simpara>For options of the <link linkend="G-OPTION-ARG-NONE:CAPS"><literal>G_OPTION_ARG_NONE</literal></link> kind, this flag
 
749
<varlistentry id="G-OPTION-FLAG-REVERSE--CAPS" role="constant">
 
750
<term><literal>G_OPTION_FLAG_REVERSE</literal></term>
 
751
<listitem><simpara>For options of the <link linkend="G-OPTION-ARG-NONE--CAPS"><literal>G_OPTION_ARG_NONE</literal></link> kind, this flag
803
752
   indicates that the sense of the option is reversed.
804
753
</simpara></listitem>
805
754
</varlistentry>
806
 
<varlistentry>
807
 
<term><anchor id="G-OPTION-FLAG-NO-ARG:CAPS" role="constant"/><literal>G_OPTION_FLAG_NO_ARG</literal></term>
808
 
<listitem><simpara>For options of the <link linkend="G-OPTION-ARG-CALLBACK:CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link> kind,
 
755
<varlistentry id="G-OPTION-FLAG-NO-ARG--CAPS" role="constant">
 
756
<term><literal>G_OPTION_FLAG_NO_ARG</literal></term>
 
757
<listitem><simpara>For options of the <link linkend="G-OPTION-ARG-CALLBACK--CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link> kind,
809
758
   this flag indicates that the callback does not take any argument
810
 
   (like a <link linkend="G-OPTION-ARG-NONE:CAPS"><literal>G_OPTION_ARG_NONE</literal></link> option). Since 2.8
 
759
   (like a <link linkend="G-OPTION-ARG-NONE--CAPS"><literal>G_OPTION_ARG_NONE</literal></link> option). Since 2.8
811
760
</simpara></listitem>
812
761
</varlistentry>
813
 
<varlistentry>
814
 
<term><anchor id="G-OPTION-FLAG-FILENAME:CAPS" role="constant"/><literal>G_OPTION_FLAG_FILENAME</literal></term>
815
 
<listitem><simpara>For options of the <link linkend="G-OPTION-ARG-CALLBACK:CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link>
 
762
<varlistentry id="G-OPTION-FLAG-FILENAME--CAPS" role="constant">
 
763
<term><literal>G_OPTION_FLAG_FILENAME</literal></term>
 
764
<listitem><simpara>For options of the <link linkend="G-OPTION-ARG-CALLBACK--CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link>
816
765
   kind, this flag indicates that the argument should be passed to the
817
766
   callback in the GLib filename encoding rather than UTF-8. Since 2.8
818
767
</simpara></listitem>
819
768
</varlistentry>
820
 
<varlistentry>
821
 
<term><anchor id="G-OPTION-FLAG-OPTIONAL-ARG:CAPS" role="constant"/><literal>G_OPTION_FLAG_OPTIONAL_ARG</literal></term>
822
 
<listitem><simpara>For options of the <link linkend="G-OPTION-ARG-CALLBACK:CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link> 
 
769
<varlistentry id="G-OPTION-FLAG-OPTIONAL-ARG--CAPS" role="constant">
 
770
<term><literal>G_OPTION_FLAG_OPTIONAL_ARG</literal></term>
 
771
<listitem><simpara>For options of the <link linkend="G-OPTION-ARG-CALLBACK--CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link> 
823
772
   kind, this flag indicates that the argument supply is optional. If no argument
824
773
   is given then data of <link linkend="GOptionParseFunc"><literal>GOptionParseFunc</literal></link> will be set to NULL. Since 2.8
825
774
</simpara></listitem>
826
775
</varlistentry>
827
 
<varlistentry>
828
 
<term><anchor id="G-OPTION-FLAG-NOALIAS:CAPS" role="constant"/><literal>G_OPTION_FLAG_NOALIAS</literal></term>
 
776
<varlistentry id="G-OPTION-FLAG-NOALIAS--CAPS" role="constant">
 
777
<term><literal>G_OPTION_FLAG_NOALIAS</literal></term>
829
778
<listitem><simpara>This flag turns off the automatic conflict resolution
830
 
   which prefixes long option names with <literal>groupname-</literal> if 
 
779
   which prefixes long option names with <literal>groupname-</literal> if
831
780
   there is a conflict. This option should only be used in situations where
832
781
   aliasing is necessary to model some legacy commandline interface. It is
833
 
   not safe to use this option, unless all option groups are under your 
 
782
   not safe to use this option, unless all option groups are under your
834
783
   direct control. Since 2.8.
835
 
 
836
784
</simpara></listitem>
837
785
</varlistentry>
838
786
</variablelist></refsect2>
839
 
<refsect2>
840
 
<title><anchor id="G-OPTION-REMAINING:CAPS" role="macro" condition="since:2.6"/>G_OPTION_REMAINING</title>
841
 
<indexterm role="2.6"><primary>G_OPTION_REMAINING</primary></indexterm><programlisting>#define G_OPTION_REMAINING ""
 
787
<refsect2 id="G-OPTION-REMAINING--CAPS" role="macro" condition="since:2.6">
 
788
<title>G_OPTION_REMAINING</title>
 
789
<indexterm zone="G-OPTION-REMAINING--CAPS" role="2.6"><primary sortas="G_OPTION_REMAINING">G_OPTION_REMAINING</primary></indexterm><programlisting>#define G_OPTION_REMAINING ""
842
790
</programlisting>
843
791
<para>
844
 
If a long option in the main group has this name, it is not treated as a 
 
792
If a long option in the main group has this name, it is not treated as a
845
793
regular option. Instead it collects all non-option arguments which would
846
794
otherwise be left in <literal>argv</literal>. The option must be of type
847
 
<link linkend="G-OPTION-ARG-CALLBACK:CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link>, <link linkend="G-OPTION-ARG-STRING-ARRAY:CAPS"><literal>G_OPTION_ARG_STRING_ARRAY</literal></link>
848
 
or <link linkend="G-OPTION-ARG-FILENAME-ARRAY:CAPS"><literal>G_OPTION_ARG_FILENAME_ARRAY</literal></link>.
 
795
<link linkend="G-OPTION-ARG-CALLBACK--CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link>, <link linkend="G-OPTION-ARG-STRING-ARRAY--CAPS"><literal>G_OPTION_ARG_STRING_ARRAY</literal></link>
 
796
or <link linkend="G-OPTION-ARG-FILENAME-ARRAY--CAPS"><literal>G_OPTION_ARG_FILENAME_ARRAY</literal></link>.
849
797
</para>
850
 
 
851
798
<para>
852
 
Using <link linkend="G-OPTION-REMAINING:CAPS"><type>G_OPTION_REMAINING</type></link> instead of simply scanning <literal>argv</literal>
853
 
for leftover arguments has the advantage that GOption takes care of 
 
799
Using <link linkend="G-OPTION-REMAINING--CAPS"><type>G_OPTION_REMAINING</type></link> instead of simply scanning <literal>argv</literal>
 
800
for leftover arguments has the advantage that GOption takes care of
854
801
necessary encoding conversions for strings or filenames.
855
 
</para><para role="since">Since 2.6
856
 
 
857
 
 
858
 
</para></refsect2>
859
 
<refsect2>
860
 
<title><anchor id="GOptionEntry" role="struct"/>GOptionEntry</title>
861
 
<indexterm><primary>GOptionEntry</primary></indexterm><programlisting>typedef struct {
 
802
</para><para role="since">Since 2.6</para></refsect2>
 
803
<refsect2 id="GOptionEntry" role="struct">
 
804
<title>GOptionEntry</title>
 
805
<indexterm zone="GOptionEntry"><primary sortas="GOptionEntry">GOptionEntry</primary></indexterm><programlisting>typedef struct {
862
806
  const gchar *long_name;
863
807
  gchar        short_name;
864
808
  gint         flags;
876
820
<link linkend="g-option-context-add-main-entries"><function>g_option_context_add_main_entries()</function></link> or <link linkend="g-option-group-add-entries"><function>g_option_group_add_entries()</function></link>.
877
821
</para><variablelist role="struct">
878
822
<varlistentry>
879
 
<term>const&nbsp;<link linkend="gchar">gchar</link>&nbsp;*<structfield>long_name</structfield>;</term>
 
823
<term>const&#160;<link linkend="gchar">gchar</link>&#160;*<structfield>long_name</structfield>;</term>
880
824
<listitem><simpara>The long name of an option can be used to specify it
881
825
  in a commandline as --<replaceable>long_name</replaceable>. Every
882
826
  option must have a long name. To resolve conflicts if multiple
883
827
  option groups contain the same long name, it is also possible to
884
 
  specify the option as 
 
828
  specify the option as
885
829
  --<replaceable>groupname</replaceable>-<replaceable>long_name</replaceable>.
886
830
</simpara></listitem>
887
831
</varlistentry>
888
832
<varlistentry>
889
 
<term><link linkend="gchar">gchar</link>&nbsp;<structfield>short_name</structfield>;</term>
 
833
<term><link linkend="gchar">gchar</link>&#160;<structfield>short_name</structfield>;</term>
890
834
<listitem><simpara>If an option has a short name, it can be specified
891
 
  -<replaceable>short_name</replaceable> in a commandline. <parameter>short_name</parameter> must be 
 
835
  -<replaceable>short_name</replaceable> in a commandline. <parameter>short_name</parameter> must be
892
836
  a printable ASCII character different from '-', or zero if the option has no
893
837
  short name.
894
838
</simpara></listitem>
895
839
</varlistentry>
896
840
<varlistentry>
897
 
<term><link linkend="gint">gint</link>&nbsp;<structfield>flags</structfield>;</term>
 
841
<term><link linkend="gint">gint</link>&#160;<structfield>flags</structfield>;</term>
898
842
<listitem><simpara>Flags from <link linkend="GOptionFlags"><type>GOptionFlags</type></link>.
899
843
</simpara></listitem>
900
844
</varlistentry>
901
845
<varlistentry>
902
 
<term><link linkend="GOptionArg">GOptionArg</link>&nbsp;<structfield>arg</structfield>;</term>
 
846
<term><link linkend="GOptionArg">GOptionArg</link>&#160;<structfield>arg</structfield>;</term>
903
847
<listitem><simpara>The type of the option, as a <link linkend="GOptionArg"><type>GOptionArg</type></link>.
904
848
</simpara></listitem>
905
849
</varlistentry>
906
850
<varlistentry>
907
 
<term><link linkend="gpointer">gpointer</link>&nbsp;<structfield>arg_data</structfield>;</term>
908
 
<listitem><simpara> If the <parameter>arg</parameter> type is <link linkend="G-OPTION-ARG-CALLBACK:CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link>, then <parameter>arg_data</parameter> must 
909
 
 point to a <link linkend="GOptionArgFunc"><type>GOptionArgFunc</type></link> callback function, which will be called to handle 
910
 
 the extra argument. Otherwise, <parameter>arg_data</parameter> is a pointer to a location to store 
 
851
<term><link linkend="gpointer">gpointer</link>&#160;<structfield>arg_data</structfield>;</term>
 
852
<listitem><simpara> If the <parameter>arg</parameter> type is <link linkend="G-OPTION-ARG-CALLBACK--CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link>, then <parameter>arg_data</parameter> must 
 
853
 point to a <link linkend="GOptionArgFunc"><type>GOptionArgFunc</type></link> callback function, which will be called to handle
 
854
 the extra argument. Otherwise, <parameter>arg_data</parameter> is a pointer to a location to store
911
855
 the value, the required type of the location depends on the <parameter>arg</parameter> type:
912
856
  <variablelist>
913
857
    <varlistentry>
914
 
      <term><link linkend="G-OPTION-ARG-NONE:CAPS"><literal>G_OPTION_ARG_NONE</literal></link></term>
 
858
      <term><link linkend="G-OPTION-ARG-NONE--CAPS"><literal>G_OPTION_ARG_NONE</literal></link></term>
915
859
      <listitem><para><link linkend="gboolean"><literal>gboolean</literal></link></para></listitem>
916
860
    </varlistentry>
917
861
    <varlistentry>
918
 
      <term><link linkend="G-OPTION-ARG-STRING:CAPS"><literal>G_OPTION_ARG_STRING</literal></link></term>
 
862
      <term><link linkend="G-OPTION-ARG-STRING--CAPS"><literal>G_OPTION_ARG_STRING</literal></link></term>
919
863
      <listitem><para><link linkend="gchar"><literal>gchar</literal></link>*</para></listitem>
920
864
    </varlistentry>
921
865
    <varlistentry>
922
 
      <term><link linkend="G-OPTION-ARG-INT:CAPS"><literal>G_OPTION_ARG_INT</literal></link></term>
 
866
      <term><link linkend="G-OPTION-ARG-INT--CAPS"><literal>G_OPTION_ARG_INT</literal></link></term>
923
867
      <listitem><para><link linkend="gint"><literal>gint</literal></link></para></listitem>
924
868
    </varlistentry>
925
869
    <varlistentry>
926
 
      <term><link linkend="G-OPTION-ARG-FILENAME:CAPS"><literal>G_OPTION_ARG_FILENAME</literal></link></term>
 
870
      <term><link linkend="G-OPTION-ARG-FILENAME--CAPS"><literal>G_OPTION_ARG_FILENAME</literal></link></term>
927
871
      <listitem><para><link linkend="gchar"><literal>gchar</literal></link>*</para></listitem>
928
872
    </varlistentry>
929
873
    <varlistentry>
930
 
      <term><link linkend="G-OPTION-ARG-STRING-ARRAY:CAPS"><literal>G_OPTION_ARG_STRING_ARRAY</literal></link></term>
931
 
      <listitem><para><link linkend="gchar"><literal>gchar</literal></link>**</para></listitem>
932
 
    </varlistentry>
933
 
    <varlistentry>
934
 
      <term><link linkend="G-OPTION-ARG-FILENAME-ARRAY:CAPS"><literal>G_OPTION_ARG_FILENAME_ARRAY</literal></link></term>
935
 
      <listitem><para><link linkend="gchar"><literal>gchar</literal></link>**</para></listitem>
936
 
    </varlistentry>
937
 
    <varlistentry>
938
 
      <term><link linkend="G-OPTION-ARG-DOUBLE:CAPS"><literal>G_OPTION_ARG_DOUBLE</literal></link></term>
 
874
      <term><link linkend="G-OPTION-ARG-STRING-ARRAY--CAPS"><literal>G_OPTION_ARG_STRING_ARRAY</literal></link></term>
 
875
      <listitem><para><link linkend="gchar"><literal>gchar</literal></link>**</para></listitem>
 
876
    </varlistentry>
 
877
    <varlistentry>
 
878
      <term><link linkend="G-OPTION-ARG-FILENAME-ARRAY--CAPS"><literal>G_OPTION_ARG_FILENAME_ARRAY</literal></link></term>
 
879
      <listitem><para><link linkend="gchar"><literal>gchar</literal></link>**</para></listitem>
 
880
    </varlistentry>
 
881
    <varlistentry>
 
882
      <term><link linkend="G-OPTION-ARG-DOUBLE--CAPS"><literal>G_OPTION_ARG_DOUBLE</literal></link></term>
939
883
      <listitem><para><link linkend="gdouble"><literal>gdouble</literal></link></para></listitem>
940
884
    </varlistentry>
941
885
  </variablelist>
942
886
</simpara></listitem>
943
887
</varlistentry>
944
888
<varlistentry>
945
 
<term>const&nbsp;<link linkend="gchar">gchar</link>&nbsp;*<structfield>description</structfield>;</term>
 
889
<term>const&#160;<link linkend="gchar">gchar</link>&#160;*<structfield>description</structfield>;</term>
946
890
<listitem><simpara>the description for the option in <option>--help</option>
947
891
  output. The <parameter>description</parameter> is translated using the <parameter>translate_func</parameter> of the
948
892
  group, see <link linkend="g-option-group-set-translation-domain"><function>g_option_group_set_translation_domain()</function></link>.
949
893
</simpara></listitem>
950
894
</varlistentry>
951
895
<varlistentry>
952
 
<term>const&nbsp;<link linkend="gchar">gchar</link>&nbsp;*<structfield>arg_description</structfield>;</term>
 
896
<term>const&#160;<link linkend="gchar">gchar</link>&#160;*<structfield>arg_description</structfield>;</term>
953
897
<listitem><simpara>The placeholder to use for the extra argument parsed
954
898
  by the option in <option>--help</option>
955
899
  output. The <parameter>arg_description</parameter> is translated using the <parameter>translate_func</parameter> of the
956
900
  group, see <link linkend="g-option-group-set-translation-domain"><function>g_option_group_set_translation_domain()</function></link>.
957
 
 
958
901
</simpara></listitem>
959
902
</varlistentry>
960
903
</variablelist></refsect2>
961
 
<refsect2>
962
 
<title><anchor id="g-option-context-add-main-entries" role="function" condition="since:2.6"/>g_option_context_add_main_entries ()</title>
963
 
<indexterm role="2.6"><primary>g_option_context_add_main_entries</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_add_main_entries   (<link linkend="GOptionContext">GOptionContext</link> *context,
 
904
<refsect2 id="g-option-context-add-main-entries" role="function" condition="since:2.6">
 
905
<title>g_option_context_add_main_entries ()</title>
 
906
<indexterm zone="g-option-context-add-main-entries" role="2.6"><primary sortas="g_option_context_add_main_entries">g_option_context_add_main_entries</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_add_main_entries   (<link linkend="GOptionContext">GOptionContext</link> *context,
964
907
                                                         const <link linkend="GOptionEntry">GOptionEntry</link> *entries,
965
908
                                                         const <link linkend="gchar">gchar</link> *translation_domain);</programlisting>
966
909
<para>
967
910
A convenience function which creates a main group if it doesn't 
968
911
exist, adds the <parameter>entries</parameter> to it and sets the translation domain.</para>
969
912
<para>
970
 
 
971
913
</para><variablelist role="params">
972
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
914
<varlistentry><term><parameter>context</parameter>&#160;:</term>
973
915
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
974
916
</simpara></listitem></varlistentry>
975
 
<varlistentry><term><parameter>entries</parameter>&nbsp;:</term>
976
 
<listitem><simpara> a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of <link linkend="GOptionEntry"><type>GOptionEntry</type></link><!-- -->s
 
917
<varlistentry><term><parameter>entries</parameter>&#160;:</term>
 
918
<listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of <link linkend="GOptionEntry"><type>GOptionEntry</type></link><!-- -->s
977
919
</simpara></listitem></varlistentry>
978
 
<varlistentry><term><parameter>translation_domain</parameter>&nbsp;:</term>
 
920
<varlistentry><term><parameter>translation_domain</parameter>&#160;:</term>
979
921
<listitem><simpara> a translation domain to use for translating
980
922
   the <option>--help</option> output for the options in <parameter>entries</parameter>
981
 
   with <link linkend="gettext"><function>gettext()</function></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
 
923
   with <link linkend="gettext"><function>gettext()</function></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
982
924
</simpara></listitem></varlistentry>
983
 
</variablelist><para role="since">Since  2.6
984
 
</para></refsect2>
985
 
<refsect2>
986
 
<title><anchor id="GOptionGroup" role="struct"/>GOptionGroup</title>
987
 
<indexterm><primary>GOptionGroup</primary></indexterm><programlisting>typedef struct _GOptionGroup GOptionGroup;</programlisting>
 
925
</variablelist><para role="since">Since 2.6</para></refsect2>
 
926
<refsect2 id="GOptionGroup" role="struct">
 
927
<title>GOptionGroup</title>
 
928
<indexterm zone="GOptionGroup"><primary sortas="GOptionGroup">GOptionGroup</primary></indexterm><programlisting>typedef struct _GOptionGroup GOptionGroup;</programlisting>
988
929
<para>
989
930
A <structname>GOptionGroup</structname> struct defines the options in a single
990
 
group. The struct has only private fields and should not be directly accessed. 
 
931
group. The struct has only private fields and should not be directly accessed.
991
932
</para>
992
933
<para>
993
934
All options in a group share the same translation function. Libaries which
994
935
need to parse commandline options are expected to provide a function for
995
 
getting a <structname>GOptionGroup</structname> holding their options, which 
 
936
getting a <structname>GOptionGroup</structname> holding their options, which
996
937
the application can then add to its <link linkend="GOptionContext"><type>GOptionContext</type></link>.
997
938
</para></refsect2>
998
 
<refsect2>
999
 
<title><anchor id="g-option-context-add-group" role="function" condition="since:2.6"/>g_option_context_add_group ()</title>
1000
 
<indexterm role="2.6"><primary>g_option_context_add_group</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_add_group          (<link linkend="GOptionContext">GOptionContext</link> *context,
 
939
<refsect2 id="g-option-context-add-group" role="function" condition="since:2.6">
 
940
<title>g_option_context_add_group ()</title>
 
941
<indexterm zone="g-option-context-add-group" role="2.6"><primary sortas="g_option_context_add_group">g_option_context_add_group</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_add_group          (<link linkend="GOptionContext">GOptionContext</link> *context,
1001
942
                                                         <link linkend="GOptionGroup">GOptionGroup</link> *group);</programlisting>
1002
943
<para>
1003
944
Adds a <link linkend="GOptionGroup"><type>GOptionGroup</type></link> to the <parameter>context</parameter>, so that parsing with <parameter>context</parameter>
1006
947
called, so you must not free the group yourself after adding it
1007
948
to a context.</para>
1008
949
<para>
1009
 
 
1010
950
</para><variablelist role="params">
1011
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
951
<varlistentry><term><parameter>context</parameter>&#160;:</term>
1012
952
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
1013
953
</simpara></listitem></varlistentry>
1014
 
<varlistentry><term><parameter>group</parameter>&nbsp;:</term>
 
954
<varlistentry><term><parameter>group</parameter>&#160;:</term>
1015
955
<listitem><simpara> the group to add
1016
956
</simpara></listitem></varlistentry>
1017
 
</variablelist><para role="since">Since  2.6
1018
 
</para></refsect2>
1019
 
<refsect2>
1020
 
<title><anchor id="g-option-context-set-main-group" role="function" condition="since:2.6"/>g_option_context_set_main_group ()</title>
1021
 
<indexterm role="2.6"><primary>g_option_context_set_main_group</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_set_main_group     (<link linkend="GOptionContext">GOptionContext</link> *context,
 
957
</variablelist><para role="since">Since 2.6</para></refsect2>
 
958
<refsect2 id="g-option-context-set-main-group" role="function" condition="since:2.6">
 
959
<title>g_option_context_set_main_group ()</title>
 
960
<indexterm zone="g-option-context-set-main-group" role="2.6"><primary sortas="g_option_context_set_main_group">g_option_context_set_main_group</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_context_set_main_group     (<link linkend="GOptionContext">GOptionContext</link> *context,
1022
961
                                                         <link linkend="GOptionGroup">GOptionGroup</link> *group);</programlisting>
1023
962
<para>
1024
963
Sets a <link linkend="GOptionGroup"><type>GOptionGroup</type></link> as main group of the <parameter>context</parameter>. 
1026
965
the only difference is that the options in the main group are 
1027
966
treated differently when generating <option>--help</option> output.</para>
1028
967
<para>
1029
 
 
1030
968
</para><variablelist role="params">
1031
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
969
<varlistentry><term><parameter>context</parameter>&#160;:</term>
1032
970
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
1033
971
</simpara></listitem></varlistentry>
1034
 
<varlistentry><term><parameter>group</parameter>&nbsp;:</term>
 
972
<varlistentry><term><parameter>group</parameter>&#160;:</term>
1035
973
<listitem><simpara> the group to set as main group
1036
974
</simpara></listitem></varlistentry>
1037
 
</variablelist><para role="since">Since  2.6
1038
 
</para></refsect2>
1039
 
<refsect2>
1040
 
<title><anchor id="g-option-context-get-main-group" role="function" condition="since:2.6"/>g_option_context_get_main_group ()</title>
1041
 
<indexterm role="2.6"><primary>g_option_context_get_main_group</primary></indexterm><programlisting><link linkend="GOptionGroup">GOptionGroup</link>*       g_option_context_get_main_group     (<link linkend="GOptionContext">GOptionContext</link> *context);</programlisting>
 
975
</variablelist><para role="since">Since 2.6</para></refsect2>
 
976
<refsect2 id="g-option-context-get-main-group" role="function" condition="since:2.6">
 
977
<title>g_option_context_get_main_group ()</title>
 
978
<indexterm zone="g-option-context-get-main-group" role="2.6"><primary sortas="g_option_context_get_main_group">g_option_context_get_main_group</primary></indexterm><programlisting><link linkend="GOptionGroup">GOptionGroup</link> *      g_option_context_get_main_group     (<link linkend="GOptionContext">GOptionContext</link> *context);</programlisting>
1042
979
<para>
1043
980
Returns a pointer to the main group of <parameter>context</parameter>.</para>
1044
981
<para>
1045
 
 
1046
982
</para><variablelist role="params">
1047
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
983
<varlistentry><term><parameter>context</parameter>&#160;:</term>
1048
984
<listitem><simpara> a <link linkend="GOptionContext"><type>GOptionContext</type></link>
1049
985
</simpara></listitem></varlistentry>
1050
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the main group of <parameter>context</parameter>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if <parameter>context</parameter> doesn't
 
986
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the main group of <parameter>context</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if <parameter>context</parameter> doesn't
1051
987
 have a main group. Note that group belongs to <parameter>context</parameter> and should
1052
988
 not be modified or freed.
1053
989
 
1054
990
</simpara></listitem></varlistentry>
1055
 
</variablelist><para role="since">Since  2.6
1056
 
</para></refsect2>
1057
 
<refsect2>
1058
 
<title><anchor id="g-option-group-new" role="function" condition="since:2.6"/>g_option_group_new ()</title>
1059
 
<indexterm role="2.6"><primary>g_option_group_new</primary></indexterm><programlisting><link linkend="GOptionGroup">GOptionGroup</link>*       g_option_group_new                  (const <link linkend="gchar">gchar</link> *name,
 
991
</variablelist><para role="since">Since 2.6</para></refsect2>
 
992
<refsect2 id="g-option-group-new" role="function" condition="since:2.6">
 
993
<title>g_option_group_new ()</title>
 
994
<indexterm zone="g-option-group-new" role="2.6"><primary sortas="g_option_group_new">g_option_group_new</primary></indexterm><programlisting><link linkend="GOptionGroup">GOptionGroup</link> *      g_option_group_new                  (const <link linkend="gchar">gchar</link> *name,
1060
995
                                                         const <link linkend="gchar">gchar</link> *description,
1061
996
                                                         const <link linkend="gchar">gchar</link> *help_description,
1062
997
                                                         <link linkend="gpointer">gpointer</link> user_data,
1064
999
<para>
1065
1000
Creates a new <link linkend="GOptionGroup"><type>GOptionGroup</type></link>.</para>
1066
1001
<para>
1067
 
 
1068
1002
</para><variablelist role="params">
1069
 
<varlistentry><term><parameter>name</parameter>&nbsp;:</term>
 
1003
<varlistentry><term><parameter>name</parameter>&#160;:</term>
1070
1004
<listitem><simpara> the name for the option group, this is used to provide
1071
1005
  help for the options in this group with <option>--help-</option><parameter>name</parameter>
1072
1006
</simpara></listitem></varlistentry>
1073
 
<varlistentry><term><parameter>description</parameter>&nbsp;:</term>
 
1007
<varlistentry><term><parameter>description</parameter>&#160;:</term>
1074
1008
<listitem><simpara> a description for this group to be shown in 
1075
1009
  <option>--help</option>. This string is translated using the translation
1076
1010
  domain or translation function of the group
1077
1011
</simpara></listitem></varlistentry>
1078
 
<varlistentry><term><parameter>help_description</parameter>&nbsp;:</term>
 
1012
<varlistentry><term><parameter>help_description</parameter>&#160;:</term>
1079
1013
<listitem><simpara> a description for the <option>--help-</option><parameter>name</parameter> option.
1080
1014
  This string is translated using the translation domain or translation function
1081
1015
  of the group
1082
1016
</simpara></listitem></varlistentry>
1083
 
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
1017
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
1084
1018
<listitem><simpara> user data that will be passed to the pre- and post-parse hooks,
1085
 
  the error hook and to callbacks of <link linkend="G-OPTION-ARG-CALLBACK:CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link> options, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
1086
 
</simpara></listitem></varlistentry>
1087
 
<varlistentry><term><parameter>destroy</parameter>&nbsp;:</term>
1088
 
<listitem><simpara> a function that will be called to free <parameter>user_data</parameter>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
1089
 
</simpara></listitem></varlistentry>
1090
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a newly created option group. It should be added 
 
1019
  the error hook and to callbacks of <link linkend="G-OPTION-ARG-CALLBACK--CAPS"><literal>G_OPTION_ARG_CALLBACK</literal></link> options, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 
1020
</simpara></listitem></varlistentry>
 
1021
<varlistentry><term><parameter>destroy</parameter>&#160;:</term>
 
1022
<listitem><simpara> a function that will be called to free <parameter>user_data</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 
1023
</simpara></listitem></varlistentry>
 
1024
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly created option group. It should be added 
1091
1025
  to a <link linkend="GOptionContext"><type>GOptionContext</type></link> or freed with <link linkend="g-option-group-free"><function>g_option_group_free()</function></link>.
1092
1026
 
1093
1027
</simpara></listitem></varlistentry>
1094
 
</variablelist><para role="since">Since  2.6
1095
 
</para></refsect2>
1096
 
<refsect2>
1097
 
<title><anchor id="g-option-group-free" role="function" condition="since:2.6"/>g_option_group_free ()</title>
1098
 
<indexterm role="2.6"><primary>g_option_group_free</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_group_free                 (<link linkend="GOptionGroup">GOptionGroup</link> *group);</programlisting>
 
1028
</variablelist><para role="since">Since 2.6</para></refsect2>
 
1029
<refsect2 id="g-option-group-free" role="function" condition="since:2.6">
 
1030
<title>g_option_group_free ()</title>
 
1031
<indexterm zone="g-option-group-free" role="2.6"><primary sortas="g_option_group_free">g_option_group_free</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_group_free                 (<link linkend="GOptionGroup">GOptionGroup</link> *group);</programlisting>
1099
1032
<para>
1100
1033
Frees a <link linkend="GOptionGroup"><type>GOptionGroup</type></link>. Note that you must <emphasis>not</emphasis>
1101
1034
free groups which have been added to a <link linkend="GOptionContext"><type>GOptionContext</type></link>.</para>
1102
1035
<para>
1103
 
 
1104
1036
</para><variablelist role="params">
1105
 
<varlistentry><term><parameter>group</parameter>&nbsp;:</term>
 
1037
<varlistentry><term><parameter>group</parameter>&#160;:</term>
1106
1038
<listitem><simpara> a <link linkend="GOptionGroup"><type>GOptionGroup</type></link>
1107
1039
</simpara></listitem></varlistentry>
1108
 
</variablelist><para role="since">Since  2.6
1109
 
</para></refsect2>
1110
 
<refsect2>
1111
 
<title><anchor id="g-option-group-add-entries" role="function" condition="since:2.6"/>g_option_group_add_entries ()</title>
1112
 
<indexterm role="2.6"><primary>g_option_group_add_entries</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_group_add_entries          (<link linkend="GOptionGroup">GOptionGroup</link> *group,
 
1040
</variablelist><para role="since">Since 2.6</para></refsect2>
 
1041
<refsect2 id="g-option-group-add-entries" role="function" condition="since:2.6">
 
1042
<title>g_option_group_add_entries ()</title>
 
1043
<indexterm zone="g-option-group-add-entries" role="2.6"><primary sortas="g_option_group_add_entries">g_option_group_add_entries</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_group_add_entries          (<link linkend="GOptionGroup">GOptionGroup</link> *group,
1113
1044
                                                         const <link linkend="GOptionEntry">GOptionEntry</link> *entries);</programlisting>
1114
1045
<para>
1115
1046
Adds the options specified in <parameter>entries</parameter> to <parameter>group</parameter>.</para>
1116
1047
<para>
1117
 
 
1118
1048
</para><variablelist role="params">
1119
 
<varlistentry><term><parameter>group</parameter>&nbsp;:</term>
 
1049
<varlistentry><term><parameter>group</parameter>&#160;:</term>
1120
1050
<listitem><simpara> a <link linkend="GOptionGroup"><type>GOptionGroup</type></link>
1121
1051
</simpara></listitem></varlistentry>
1122
 
<varlistentry><term><parameter>entries</parameter>&nbsp;:</term>
1123
 
<listitem><simpara> a <link linkend="NULL:CAPS"><literal>NULL</literal></link>-terminated array of <link linkend="GOptionEntry"><type>GOptionEntry</type></link><!-- -->s
 
1052
<varlistentry><term><parameter>entries</parameter>&#160;:</term>
 
1053
<listitem><simpara> a <link linkend="NULL--CAPS"><literal>NULL</literal></link>-terminated array of <link linkend="GOptionEntry"><type>GOptionEntry</type></link><!-- -->s
1124
1054
</simpara></listitem></varlistentry>
1125
 
</variablelist><para role="since">Since  2.6
1126
 
</para></refsect2>
1127
 
<refsect2>
1128
 
<title><anchor id="GOptionParseFunc" role="function"/>GOptionParseFunc ()</title>
1129
 
<indexterm><primary>GOptionParseFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            (*GOptionParseFunc)                 (<link linkend="GOptionContext">GOptionContext</link> *context,
 
1055
</variablelist><para role="since">Since 2.6</para></refsect2>
 
1056
<refsect2 id="GOptionParseFunc" role="function">
 
1057
<title>GOptionParseFunc ()</title>
 
1058
<indexterm zone="GOptionParseFunc"><primary sortas="GOptionParseFunc">GOptionParseFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            (*GOptionParseFunc)                 (<link linkend="GOptionContext">GOptionContext</link> *context,
1130
1059
                                                         <link linkend="GOptionGroup">GOptionGroup</link> *group,
1131
1060
                                                         <link linkend="gpointer">gpointer</link> data,
1132
1061
                                                         <link linkend="GError">GError</link> **error);</programlisting>
1133
1062
<para>
1134
 
The type of function that can be called before and after parsing. 
 
1063
The type of function that can be called before and after parsing.
1135
1064
</para><variablelist role="params">
1136
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
1065
<varlistentry><term><parameter>context</parameter>&#160;:</term>
1137
1066
<listitem><simpara>The active <link linkend="GOptionContext"><type>GOptionContext</type></link>
1138
1067
</simpara></listitem></varlistentry>
1139
 
<varlistentry><term><parameter>group</parameter>&nbsp;:</term>
 
1068
<varlistentry><term><parameter>group</parameter>&#160;:</term>
1140
1069
<listitem><simpara>The group to which the function belongs
1141
1070
</simpara></listitem></varlistentry>
1142
 
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
 
1071
<varlistentry><term><parameter>data</parameter>&#160;:</term>
1143
1072
<listitem><simpara>User data added to the <link linkend="GOptionGroup"><type>GOptionGroup</type></link> containing the option when it
1144
1073
  was created with <link linkend="g-option-group-new"><function>g_option_group_new()</function></link>
1145
1074
</simpara></listitem></varlistentry>
1146
 
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
1075
<varlistentry><term><parameter>error</parameter>&#160;:</term>
1147
1076
<listitem><simpara>A return location for error details
1148
1077
</simpara></listitem></varlistentry>
1149
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the function completed successfully, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if an error 
 
1078
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if the function completed successfully, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if an error 
1150
1079
  occurred, in which case <parameter>error</parameter> should be set with <link linkend="g-set-error"><function>g_set_error()</function></link>
1151
 
 
1152
 
 
1153
1080
</simpara></listitem></varlistentry>
1154
1081
</variablelist></refsect2>
1155
 
<refsect2>
1156
 
<title><anchor id="g-option-group-set-parse-hooks" role="function" condition="since:2.6"/>g_option_group_set_parse_hooks ()</title>
1157
 
<indexterm role="2.6"><primary>g_option_group_set_parse_hooks</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_group_set_parse_hooks      (<link linkend="GOptionGroup">GOptionGroup</link> *group,
 
1082
<refsect2 id="g-option-group-set-parse-hooks" role="function" condition="since:2.6">
 
1083
<title>g_option_group_set_parse_hooks ()</title>
 
1084
<indexterm zone="g-option-group-set-parse-hooks" role="2.6"><primary sortas="g_option_group_set_parse_hooks">g_option_group_set_parse_hooks</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_group_set_parse_hooks      (<link linkend="GOptionGroup">GOptionGroup</link> *group,
1158
1085
                                                         <link linkend="GOptionParseFunc">GOptionParseFunc</link> pre_parse_func,
1159
1086
                                                         <link linkend="GOptionParseFunc">GOptionParseFunc</link> post_parse_func);</programlisting>
1160
1087
<para>
1167
1094
<parameter>post_parse_func</parameter> can be specified when constructing the group
1168
1095
with <link linkend="g-option-group-new"><function>g_option_group_new()</function></link>.</para>
1169
1096
<para>
1170
 
 
1171
1097
</para><variablelist role="params">
1172
 
<varlistentry><term><parameter>group</parameter>&nbsp;:</term>
 
1098
<varlistentry><term><parameter>group</parameter>&#160;:</term>
1173
1099
<listitem><simpara> a <link linkend="GOptionGroup"><type>GOptionGroup</type></link>
1174
1100
</simpara></listitem></varlistentry>
1175
 
<varlistentry><term><parameter>pre_parse_func</parameter>&nbsp;:</term>
1176
 
<listitem><simpara> a function to call before parsing, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
1177
 
</simpara></listitem></varlistentry>
1178
 
<varlistentry><term><parameter>post_parse_func</parameter>&nbsp;:</term>
1179
 
<listitem><simpara> a function to call after parsing, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
1180
 
</simpara></listitem></varlistentry>
1181
 
</variablelist><para role="since">Since  2.6
1182
 
</para></refsect2>
1183
 
<refsect2>
1184
 
<title><anchor id="GOptionErrorFunc" role="function"/>GOptionErrorFunc ()</title>
1185
 
<indexterm><primary>GOptionErrorFunc</primary></indexterm><programlisting><link linkend="void">void</link>                (*GOptionErrorFunc)                 (<link linkend="GOptionContext">GOptionContext</link> *context,
 
1101
<varlistentry><term><parameter>pre_parse_func</parameter>&#160;:</term>
 
1102
<listitem><simpara> a function to call before parsing, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 
1103
</simpara></listitem></varlistentry>
 
1104
<varlistentry><term><parameter>post_parse_func</parameter>&#160;:</term>
 
1105
<listitem><simpara> a function to call after parsing, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 
1106
</simpara></listitem></varlistentry>
 
1107
</variablelist><para role="since">Since 2.6</para></refsect2>
 
1108
<refsect2 id="GOptionErrorFunc" role="function">
 
1109
<title>GOptionErrorFunc ()</title>
 
1110
<indexterm zone="GOptionErrorFunc"><primary sortas="GOptionErrorFunc">GOptionErrorFunc</primary></indexterm><programlisting><link linkend="void">void</link>                (*GOptionErrorFunc)                 (<link linkend="GOptionContext">GOptionContext</link> *context,
1186
1111
                                                         <link linkend="GOptionGroup">GOptionGroup</link> *group,
1187
1112
                                                         <link linkend="gpointer">gpointer</link> data,
1188
1113
                                                         <link linkend="GError">GError</link> **error);</programlisting>
1189
1114
<para>
1190
1115
The type of function to be used as callback when a parse error occurs.
1191
1116
</para><variablelist role="params">
1192
 
<varlistentry><term><parameter>context</parameter>&nbsp;:</term>
 
1117
<varlistentry><term><parameter>context</parameter>&#160;:</term>
1193
1118
<listitem><simpara>The active <link linkend="GOptionContext"><type>GOptionContext</type></link>
1194
1119
</simpara></listitem></varlistentry>
1195
 
<varlistentry><term><parameter>group</parameter>&nbsp;:</term>
 
1120
<varlistentry><term><parameter>group</parameter>&#160;:</term>
1196
1121
<listitem><simpara>The group to which the function belongs
1197
1122
</simpara></listitem></varlistentry>
1198
 
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
 
1123
<varlistentry><term><parameter>data</parameter>&#160;:</term>
1199
1124
<listitem><simpara>User data added to the <link linkend="GOptionGroup"><type>GOptionGroup</type></link> containing the option when it
1200
1125
  was created with <link linkend="g-option-group-new"><function>g_option_group_new()</function></link>
1201
1126
</simpara></listitem></varlistentry>
1202
 
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
1127
<varlistentry><term><parameter>error</parameter>&#160;:</term>
1203
1128
<listitem><simpara>The <link linkend="GError"><type>GError</type></link> containing details about the parse error
1204
 
 
1205
 
 
1206
1129
</simpara></listitem></varlistentry>
1207
1130
</variablelist></refsect2>
1208
 
<refsect2>
1209
 
<title><anchor id="g-option-group-set-error-hook" role="function" condition="since:2.6"/>g_option_group_set_error_hook ()</title>
1210
 
<indexterm role="2.6"><primary>g_option_group_set_error_hook</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_group_set_error_hook       (<link linkend="GOptionGroup">GOptionGroup</link> *group,
 
1131
<refsect2 id="g-option-group-set-error-hook" role="function" condition="since:2.6">
 
1132
<title>g_option_group_set_error_hook ()</title>
 
1133
<indexterm zone="g-option-group-set-error-hook" role="2.6"><primary sortas="g_option_group_set_error_hook">g_option_group_set_error_hook</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_group_set_error_hook       (<link linkend="GOptionGroup">GOptionGroup</link> *group,
1211
1134
                                                         <link linkend="GOptionErrorFunc">GOptionErrorFunc</link> error_func);</programlisting>
1212
1135
<para>
1213
1136
Associates a function with <parameter>group</parameter> which will be called 
1214
1137
from <link linkend="g-option-context-parse"><function>g_option_context_parse()</function></link> when an error occurs.
1215
1138
</para>
1216
1139
<para>
1217
 
Note that the user data to be passed to <parameter>pre_parse_func</parameter> and
1218
 
<parameter>post_parse_func</parameter> can be specified when constructing the group
1219
 
with <link linkend="g-option-group-new"><function>g_option_group_new()</function></link>.</para>
 
1140
Note that the user data to be passed to <parameter>error_func</parameter> can be
 
1141
specified when constructing the group with <link linkend="g-option-group-new"><function>g_option_group_new()</function></link>.</para>
1220
1142
<para>
1221
 
 
1222
1143
</para><variablelist role="params">
1223
 
<varlistentry><term><parameter>group</parameter>&nbsp;:</term>
 
1144
<varlistentry><term><parameter>group</parameter>&#160;:</term>
1224
1145
<listitem><simpara> a <link linkend="GOptionGroup"><type>GOptionGroup</type></link>
1225
1146
</simpara></listitem></varlistentry>
1226
 
<varlistentry><term><parameter>error_func</parameter>&nbsp;:</term>
 
1147
<varlistentry><term><parameter>error_func</parameter>&#160;:</term>
1227
1148
<listitem><simpara> a function to call when an error occurs
1228
1149
</simpara></listitem></varlistentry>
1229
 
</variablelist><para role="since">Since  2.6
1230
 
</para></refsect2>
1231
 
<refsect2>
1232
 
<title><anchor id="g-option-group-set-translate-func" role="function" condition="since:2.6"/>g_option_group_set_translate_func ()</title>
1233
 
<indexterm role="2.6"><primary>g_option_group_set_translate_func</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_group_set_translate_func   (<link linkend="GOptionGroup">GOptionGroup</link> *group,
 
1150
</variablelist><para role="since">Since 2.6</para></refsect2>
 
1151
<refsect2 id="g-option-group-set-translate-func" role="function" condition="since:2.6">
 
1152
<title>g_option_group_set_translate_func ()</title>
 
1153
<indexterm zone="g-option-group-set-translate-func" role="2.6"><primary sortas="g_option_group_set_translate_func">g_option_group_set_translate_func</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_group_set_translate_func   (<link linkend="GOptionGroup">GOptionGroup</link> *group,
1234
1154
                                                         <link linkend="GTranslateFunc">GTranslateFunc</link> func,
1235
1155
                                                         <link linkend="gpointer">gpointer</link> data,
1236
1156
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_notify);</programlisting>
1238
1158
Sets the function which is used to translate user-visible
1239
1159
strings, for <option>--help</option> output. Different
1240
1160
groups can use different <link linkend="GTranslateFunc"><type>GTranslateFunc</type></link><!-- -->s. If <parameter>func</parameter>
1241
 
is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, strings are not translated.
 
1161
is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, strings are not translated.
1242
1162
</para>
1243
1163
<para>
1244
1164
If you are using <link linkend="gettext"><function>gettext()</function></link>, you only need to set the translation
1245
1165
domain, see <link linkend="g-option-group-set-translation-domain"><function>g_option_group_set_translation_domain()</function></link>.</para>
1246
1166
<para>
1247
 
 
1248
1167
</para><variablelist role="params">
1249
 
<varlistentry><term><parameter>group</parameter>&nbsp;:</term>
 
1168
<varlistentry><term><parameter>group</parameter>&#160;:</term>
1250
1169
<listitem><simpara> a <link linkend="GOptionGroup"><type>GOptionGroup</type></link>
1251
1170
</simpara></listitem></varlistentry>
1252
 
<varlistentry><term><parameter>func</parameter>&nbsp;:</term>
1253
 
<listitem><simpara> the <link linkend="GTranslateFunc"><type>GTranslateFunc</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> 
1254
 
</simpara></listitem></varlistentry>
1255
 
<varlistentry><term><parameter>data</parameter>&nbsp;:</term>
1256
 
<listitem><simpara> user data to pass to <parameter>func</parameter>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
1257
 
</simpara></listitem></varlistentry>
1258
 
<varlistentry><term><parameter>destroy_notify</parameter>&nbsp;:</term>
1259
 
<listitem><simpara> a function which gets called to free <parameter>data</parameter>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>
1260
 
</simpara></listitem></varlistentry>
1261
 
</variablelist><para role="since">Since  2.6
1262
 
</para></refsect2>
1263
 
<refsect2>
1264
 
<title><anchor id="g-option-group-set-translation-domain" role="function" condition="since:2.6"/>g_option_group_set_translation_domain ()</title>
1265
 
<indexterm role="2.6"><primary>g_option_group_set_translation_domain</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_group_set_translation_domain
 
1171
<varlistentry><term><parameter>func</parameter>&#160;:</term>
 
1172
<listitem><simpara> the <link linkend="GTranslateFunc"><type>GTranslateFunc</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> 
 
1173
</simpara></listitem></varlistentry>
 
1174
<varlistentry><term><parameter>data</parameter>&#160;:</term>
 
1175
<listitem><simpara> user data to pass to <parameter>func</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 
1176
</simpara></listitem></varlistentry>
 
1177
<varlistentry><term><parameter>destroy_notify</parameter>&#160;:</term>
 
1178
<listitem><simpara> a function which gets called to free <parameter>data</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 
1179
</simpara></listitem></varlistentry>
 
1180
</variablelist><para role="since">Since 2.6</para></refsect2>
 
1181
<refsect2 id="g-option-group-set-translation-domain" role="function" condition="since:2.6">
 
1182
<title>g_option_group_set_translation_domain ()</title>
 
1183
<indexterm zone="g-option-group-set-translation-domain" role="2.6"><primary sortas="g_option_group_set_translation_domain">g_option_group_set_translation_domain</primary></indexterm><programlisting><link linkend="void">void</link>                g_option_group_set_translation_domain
1266
1184
                                                        (<link linkend="GOptionGroup">GOptionGroup</link> *group,
1267
1185
                                                         const <link linkend="gchar">gchar</link> *domain);</programlisting>
1268
1186
<para>
1269
1187
A convenience function to use <link linkend="gettext"><function>gettext()</function></link> for translating
1270
1188
user-visible strings.</para>
1271
1189
<para>
1272
 
 
1273
1190
</para><variablelist role="params">
1274
 
<varlistentry><term><parameter>group</parameter>&nbsp;:</term>
 
1191
<varlistentry><term><parameter>group</parameter>&#160;:</term>
1275
1192
<listitem><simpara> a <link linkend="GOptionGroup"><type>GOptionGroup</type></link>
1276
1193
</simpara></listitem></varlistentry>
1277
 
<varlistentry><term><parameter>domain</parameter>&nbsp;:</term>
 
1194
<varlistentry><term><parameter>domain</parameter>&#160;:</term>
1278
1195
<listitem><simpara> the domain to use
1279
1196
</simpara></listitem></varlistentry>
1280
 
</variablelist><para role="since">Since  2.6
1281
 
</para></refsect2>
 
1197
</variablelist><para role="since">Since 2.6</para></refsect2>
1282
1198
 
1283
1199
</refsect1>
1284
1200
 
1285
1201
 
1286
1202
 
1287
1203
 
1288
 
 
1289
 
<refsect1><refsect2 /><refsect2 /></refsect1>
1290
1204
</refentry>