docs: Move the GOption SECTION

Move the content to the new goption.md file.

Helps: #3037

docs/reference/glib/glib.toml.in

@@ -63,6 +63,7 @@ content_files = [
   "testing.md",
   "threads.md",
   "markup.md",
+  "goption.md",
 ]
 content_images = [
   "file-name-encodings.png",

docs/reference/glib/goption.md

@@ -0,0 +1,149 @@
+Title: Commandline option parser
+
+# Commandline option parser
+
+The GOption commandline parser is intended to be a simpler replacement
+for the popt library. It supports short and long commandline options,
+as shown in the following example:
+
+    testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2
+
+The example demonstrates a number of features of the GOption commandline parser:
+
+ - Options can be single letters, prefixed by a single dash.
+ - Multiple short options can be grouped behind a single dash.
+ - Long options are prefixed by two consecutive dashes.
+ - Options can have an extra argument, which can be a number, a string or
+   a filename. For long options, the extra argument can be appended with
+   an equals sign after the option name, which is useful if the extra
+   argument starts with a dash, which would otherwise cause it to be
+   interpreted as another option.
+ - Non-option arguments are returned to the application as rest arguments.
+ - An argument consisting solely of two dashes turns off further parsing,
+   any remaining arguments (even those starting with a dash) are returned
+   to the application as rest arguments.
+
+Another important feature of GOption is that it can automatically
+generate nicely formatted help output. Unless it is explicitly turned
+off with [method@GLib.OptionContext.set_help_enabled], GOption will recognize
+the `--help`, `-?`, `--help-all` and `--help-groupname` options (where `groupname`
+is the name of a [struct@GLib.OptionGroup]) and write a text similar to the one shown
+in the following example to stdout.
+
+    Usage:
+      testtreemodel [OPTION...] - test tree model performance
+
+    Help Options:
+      -h, --help               Show help options
+      --help-all               Show all help options
+      --help-gtk               Show GTK Options
+
+    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
+
+GOption groups options in [struct@GLib.OptionGroup]s, which makes it easy to
+incorporate options from multiple sources. The intended use for this is
+to let applications collect option groups from the libraries it uses,
+add them to their #GOptionContext, and parse all options by a single call
+to [method@GLib.OptionContext.parse].
+
+If an option is declared to be of type string or filename, GOption takes
+care of converting it to the right encoding; strings are returned in UTF-8,
+filenames are returned in the GLib filename encoding. Note that this only
+works if `setlocale()` has been called before [method@GLib.OptionContext.parse]
+
+Here is a complete example of setting up GOption to parse the example
+commandline above and produce the example help output.
+
+```c
+static gint repeats = 2;
+static gint max_size = 8;
+static gboolean verbose = FALSE;
+static gboolean beep = FALSE;
+static gboolean randomize = FALSE;
+
+static GOptionEntry entries[] =
+{
+  { "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Average over N repetitions", "N" },
+  { "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Test up to 2^M items", "M" },
+  { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL },
+  { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL },
+  { "rand", 0, 0, G_OPTION_ARG_NONE, &randomize, "Randomize the data", NULL },
+  G_OPTION_ENTRY_NULL
+};
+
+int
+main (int argc, char *argv[])
+{
+  GError *error = NULL;
+  GOptionContext *context;
+
+  context = g_option_context_new ("- test tree model performance");
+  g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE);
+  g_option_context_add_group (context, gtk_get_option_group (TRUE));
+  if (!g_option_context_parse (context, &argc, &argv, &error))
+    {
+      g_print ("option parsing failed: %s\n", error->message);
+      exit (1);
+    }
+
+  ...
+
+}
+```
+
+On UNIX systems, the argv that is passed to `main()` has no particular
+encoding, even to the extent that different parts of it may have different
+encodings. In general, normal arguments and flags will be in the current
+locale and filenames should be considered to be opaque byte strings.
+Proper use of `G_OPTION_ARG_FILENAME` vs `G_OPTION_ARG_STRING` is
+therefore important.
+
+Note that on Windows, filenames do have an encoding, but using
+[struct@GLib.OptionContext] with the argv as passed to `main()` will result
+in a program that can only accept commandline arguments with characters
+from the system codepage.This can cause problems when attempting to
+deal with filenames containing Unicode characters that fall outside
+of the codepage.
+
+A solution to this is to use `g_win32_get_command_line()` and
+[method@GLib.OptionContext.parse_strv] which will properly handle full
+Unicode filenames. If you are using #GApplication, this is done
+automatically for you.
+
+The following example shows how you can use #GOptionContext directly
+in order to correctly deal with Unicode filenames on Windows:
+
+```c
+int
+main (int argc, char **argv)
+{
+  GError *error = NULL;
+  GOptionContext *context;
+  gchar **args;
+
+#ifdef G_OS_WIN32
+  args = g_win32_get_command_line ();
+#else
+  args = g_strdupv (argv);
+#endif
+
+  // set up context
+
+  if (!g_option_context_parse_strv (context, &args, &error))
+    {
+      // error happened
+    }
+
+  ...
+
+  g_strfreev (args);
+
+  ...
+}
+```

docs/reference/glib/meson.build

@@ -161,6 +161,7 @@ expand_content_files = [
   'testing.md',
   'threads.md',
   'markup.md',
+  'goption.md',
 ]
 
 glib_gir = meson.current_source_dir() / 'GLib-2.0.gir'