Doc additions.

8 files changed, 96 insertions, 41 deletions

diff --git a/ChangeLog b/ChangeLog
index 1542390c8..a21e9a456 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,7 @@
 2004-10-29  Matthias Clasen  <mclasen@redhat.com>
 
+	* glib/goption.c: Doc additions.
+
 	* glib/goption.c (parse_arg): Convert filenames to UTF-8 on
 	Windows.
 
diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index 1542390c8..a21e9a456 100644
--- a/ChangeLog.pre-2-10
+++ b/ChangeLog.pre-2-10
@@ -1,5 +1,7 @@
 2004-10-29  Matthias Clasen  <mclasen@redhat.com>
 
+	* glib/goption.c: Doc additions.
+
 	* glib/goption.c (parse_arg): Convert filenames to UTF-8 on
 	Windows.
 
diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12
index 1542390c8..a21e9a456 100644
--- a/ChangeLog.pre-2-12
+++ b/ChangeLog.pre-2-12
@@ -1,5 +1,7 @@
 2004-10-29  Matthias Clasen  <mclasen@redhat.com>
 
+	* glib/goption.c: Doc additions.
+
 	* glib/goption.c (parse_arg): Convert filenames to UTF-8 on
 	Windows.
 
diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6
index 1542390c8..a21e9a456 100644
--- a/ChangeLog.pre-2-6
+++ b/ChangeLog.pre-2-6
@@ -1,5 +1,7 @@
 2004-10-29  Matthias Clasen  <mclasen@redhat.com>
 
+	* glib/goption.c: Doc additions.
+
 	* glib/goption.c (parse_arg): Convert filenames to UTF-8 on
 	Windows.
 
diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8
index 1542390c8..a21e9a456 100644
--- a/ChangeLog.pre-2-8
+++ b/ChangeLog.pre-2-8
@@ -1,5 +1,7 @@
 2004-10-29  Matthias Clasen  <mclasen@redhat.com>
 
+	* glib/goption.c: Doc additions.
+
 	* glib/goption.c (parse_arg): Convert filenames to UTF-8 on
 	Windows.
 
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 9fd67d467..fa8c45bd1 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,5 +1,7 @@
 2004-10-29  Matthias Clasen  <mclasen@redhat.com>
 
+	* glib/tmpl/option.sgml: Add an example.
+
 	* glib/glib-sections.txt: Add G_OPTION_REMAINING
 
 	* glib/tmpl/option.sgml: Add docs.
diff --git a/docs/reference/glib/tmpl/option.sgml b/docs/reference/glib/tmpl/option.sgml
index 2b2cae594..2a92f7a7b 100644
--- a/docs/reference/glib/tmpl/option.sgml
+++ b/docs/reference/glib/tmpl/option.sgml
@@ -12,7 +12,7 @@ following example:
 </para>
 
 <para>
-<literal>test -x 1 --long-y foo --flag --long-z=baz -uvw -- file1 file2</literal>
+<literal>testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2</literal>
 </para>
 
 <para>
@@ -46,9 +46,9 @@ Another important feature of GOption is that it can automatically generate nicel
 formatted help output. Unless it is explicitly turned off with 
 g_option_context_set_help_enabled(), GOption will recognize the 
 <option>--help</option>, <option>-?</option>, <option>--help-all</option>
-and <option>--help-</option><replaceable>groupname</replaceable> options (where 
-<replaceable>groupname</replaceable> is the name of a #GOptionGroup) and 
-write a text similar to the one shown in the following example to stdout.
+and <option>--help-</option><replaceable>groupname</replaceable> options 
+(where <replaceable>groupname</replaceable> is the name of a #GOptionGroup) 
+and write a text similar to the one shown in the following example to stdout.
 </para>
 
 <informalexample><screen>
@@ -64,6 +64,9 @@ Application Options:
   -r, --repeats=N          Average over N repetitions
   -m, --max-size=M         Test up to 2^M items
   --display=DISPLAY        X display to use
+  -v, --verbose            Be verbose
+  -b, --beep               Beep when done   
+  --rand                   Randomize the data
 </screen></informalexample>
 
 <para>
@@ -80,12 +83,47 @@ care of converting it to the right encoding; strings are returned in UTF-8,
 filenames are returned in the GLib filename encoding.
 </para>
 
+<para>
+Here is a complete example of setting up GOption to parse the example
+commandline above and produce the example help output.
+</para>
+<informalexample><programlisting>
+static gint repeats = 2;
+static gint max_size = 8;
+static gboolean verbose = FALSE;
+static gboolean beep = FALSE;
+static gboolean rand = FALSE;
+
+static GOptionEntry entries[] = 
+{
+  { "repeats", 'r', 0, G_OPTION_ARG_INT, &amp;repeats, "Average over N repetitions", "N" },
+  { "max-size", 'm', 0, G_OPTION_ARG_INT, &amp;max_size, "Test up to 2^M items", "M" },
+  { "verbose", 'v', 0, G_OPTION_ARG_NONE, &amp;verbose, "Be verbose", NULL },
+  { "beep", 'b', 0, G_OPTION_ARG_NONE, &amp;beep, "Beep when done", NULL },
+  { "rand", 0, 0, G_OPTION_ARG_NONE, &amp;rand, "Randomize the data", NULL },
+  { NULL }
+};
+
+int 
+main (int argc, char *argv[])
+{
+  GError *error = NULL;
+
+  context = g_option_context_new ("[OPTION...]");
+  g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE);
+  g_option_context_add_group (context, gtk_get_option_group (TRUE));
+  g_option_context_parse (context, &amp;argc, &amp;argv, &amp;error);
+  
+  /* ... */
+
+}
+</programlisting></informalexample>
+
 <!-- ##### SECTION See_Also ##### -->
 <para>
 
 </para>
 
-
 <!-- ##### ENUM GOptionError ##### -->
 <para>
 Error codes returned by option parsing.
@@ -94,10 +132,9 @@ Error codes returned by option parsing.
 @G_OPTION_ERROR_UNKNOWN_OPTION: An option was not known to the parser.
   This error will only be reported, if the parser hasn't been instructed
   to ignore unknown options, see g_option_context_set_ignore_unknown_options().
-@G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed. 
+@G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed.
 @G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed.
 
-
 <!-- ##### MACRO G_OPTION_ERROR ##### -->
 <para>
 Error domain for option parsing. Errors in this domain will
@@ -106,36 +143,6 @@ error domains.
 </para>
 
 
-<!-- ##### ENUM GOptionFlags ##### -->
-<para>
-Flags which modify individual options.
-</para>
-
-@G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option>
-   output.
-@G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the
-   <option>--help</option> output, even if it is defined in a group.
-
-
-<!-- ##### ENUM GOptionArg ##### -->
-<para>
-The #GOptionArg enum values determine which type of extra argument the
-options expect to find. If an option expects an extra argument, it
-can be specified in several ways; with a short option:
-<option>-x arg</option>, with a long option: <option>--name arg</option>
-or combined in a single argument: <option>--name=arg</option>.
-</para>
-
-@G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags.
-@G_OPTION_ARG_STRING: The option takes a string argument.
-@G_OPTION_ARG_INT: The option takes an integer argument.
-@G_OPTION_ARG_CALLBACK: The option provides a callback to parse the
-  extra argument.
-@G_OPTION_ARG_FILENAME: The option takes a filename as argument.
-@G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple
-  uses of the option are collected into an array of strings.
-@G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument, 
-  multiple uses of the option are collected into an array of strings.
 
 <!-- ##### USER_FUNCTION GOptionArgFunc ##### -->
 <para>
@@ -228,6 +235,36 @@ fields and should not be directly accessed.
 @Returns: 
 
 
+<!-- ##### ENUM GOptionArg ##### -->
+<para>
+The #GOptionArg enum values determine which type of extra argument the
+options expect to find. If an option expects an extra argument, it
+can be specified in several ways; with a short option:
+<option>-x arg</option>, with a long option: <option>--name arg</option>
+or combined in a single argument: <option>--name=arg</option>.
+</para>
+
+@G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags.
+@G_OPTION_ARG_STRING: The option takes a string argument.
+@G_OPTION_ARG_INT: The option takes an integer argument.
+@G_OPTION_ARG_CALLBACK: The option provides a callback to parse the
+  extra argument.
+@G_OPTION_ARG_FILENAME: The option takes a filename as argument.
+@G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple
+  uses of the option are collected into an array of strings.
+@G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument, 
+  multiple uses of the option are collected into an array of strings.
+
+<!-- ##### ENUM GOptionFlags ##### -->
+<para>
+Flags which modify individual options.
+</para>
+
+@G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option>
+   output.
+@G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the
+   <option>--help</option> output, even if it is defined in a group.
+
 <!-- ##### MACRO G_OPTION_REMAINING ##### -->
 <para>
 If a long option in the main group has this name, it is not treated as a 
@@ -256,7 +293,7 @@ g_option_context_add_main_entries() or g_option_group_add_entries().
   in a commandline as --<replaceable>long_name</replaceable>. Every
   option must have a long name.
 @short_name: If an option has a short name, it can be specified
-  -<replaceable>short_name</replaceable> in a commandline. 
+  -<replaceable>short_name</replaceable> in a commandline.
 @flags: Flags from #GOptionEntryFlags.
 @arg: The type of the option, as a #GOptionArg.
 @arg_data:  If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must 
@@ -382,7 +419,9 @@ the application can then add to its #GOptionContext.
 The type of function that can be called before and after parsing.
 </para>
 
-@context The active #GOptionContext 
+@context The active #GOptionContext
+
+@context: 
 @group: The group to which the function belongs
 @data: User data added to the #GOptionGroup containing the option when it
   was created with g_option_group_new()
@@ -390,6 +429,7 @@ The type of function that can be called before and after parsing.
 @Returns: %TRUE if the function completed successfully, %FALSE if an error 
   occurred
 
+
 <!-- ##### FUNCTION g_option_group_set_parse_hooks ##### -->
 <para>
 
@@ -406,7 +446,9 @@ The type of function to be used as callback when a parse error
 occurs.
 </para>
 
-@context The active #GOptionContext 
+@context The active #GOptionContext
+
+@context: 
 @group: The group to which the function belongs
 @data: User data added to the #GOptionGroup containing the option when it
   was created with g_option_group_new()
diff --git a/glib/goption.c b/glib/goption.c
index 5905382ff..b40afb2f7 100644
--- a/glib/goption.c
+++ b/glib/goption.c
@@ -221,7 +221,8 @@ g_option_context_get_help_enabled (GOptionContext *context)
  * g_option_context_parse() treats unknown options as error.
  * 
  * This setting does not affect non-option arguments (i.e. arguments 
- * which don't start with a dash).
+ * which don't start with a dash). But note that GOption cannot reliably
+ * determine whether a non-option belongs to a preceding unknown option.
  *
  * Since: 2.6
  **/