docs: Ditch more markup

Some markup was hiding in docs in headers. Drop it there, too.

4 files changed, 114 insertions, 140 deletions

diff --git a/glib/gbacktrace.h b/glib/gbacktrace.h
index 76ed83280..03b6029dd 100644
--- a/glib/gbacktrace.h
+++ b/glib/gbacktrace.h
@@ -45,7 +45,7 @@ void g_on_error_stack_trace (const gchar *prg_name);
  * Inserts a breakpoint instruction into the code.
  *
  * On x86 and alpha systems this is implemented as a soft interrupt
- * and on other architectures it raises a <literal>SIGTRAP</literal> signal.
+ * and on other architectures it raises a `SIGTRAP` signal.
  */
 #if (defined (__i386__) || defined (__x86_64__)) && defined (__GNUC__) && __GNUC__ >= 2
 #  define G_BREAKPOINT()        G_STMT_START{ __asm__ __volatile__ ("int $03"); }G_STMT_END
diff --git a/glib/gmarkup.h b/glib/gmarkup.h
index c7efea5ec..71ff6aa30 100644
--- a/glib/gmarkup.h
+++ b/glib/gmarkup.h
@@ -79,7 +79,7 @@ GQuark g_markup_error_quark (void);
  * @G_MARKUP_TREAT_CDATA_AS_TEXT: When this flag is set, CDATA marked
  *     sections are not passed literally to the @passthrough function of
  *     the parser. Instead, the content of the section (without the
- *     <literal>&lt;![CDATA[</literal> and <literal>]]&gt;</literal>) is
+ *     `<![CDATA[` and `]]>`) is
  *     passed to the @text function. This flag was added in GLib 2.12
  * @G_MARKUP_PREFIX_ERROR_POSITION: Normally errors caught by GMarkup
  *     itself have line/column information prefixed to them to let the
@@ -119,7 +119,7 @@ typedef struct _GMarkupParser GMarkupParser;
  *     is seen.
  * @end_element: Callback to invoke when the closing tag of an element
  *     is seen. Note that this is also called for empty tags like
- *     <literal>&lt;empty/&gt;</literal>.
+ *     `<empty/>`.
  * @text: Callback to invoke when some text is seen (text is always
  *     inside an element). Note that the text of an element may be spread
  *     over multiple calls of this function. If the
diff --git a/glib/goption.h b/glib/goption.h
index 3162dd289..98085a28f 100644
--- a/glib/goption.h
+++ b/glib/goption.h
@@ -53,28 +53,28 @@ typedef struct _GOptionEntry   GOptionEntry;
 
 /**
  * GOptionFlags:
- * @G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option>
- *  output.
+ * @G_OPTION_FLAG_HIDDEN: The option doesn't appear in `--help` 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.
- * @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this flag
- *  indicates that the sense of the option is reversed.
+ *     `--help` output, even if it is defined in a group.
+ * @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this
+ *     flag indicates that the sense of the option is reversed.
  * @G_OPTION_FLAG_NO_ARG: For options of the %G_OPTION_ARG_CALLBACK kind,
- *  this flag indicates that the callback does not take any argument
- *  (like a %G_OPTION_ARG_NONE option). Since 2.8
+ *     this flag indicates that the callback does not take any argument
+ *     (like a %G_OPTION_ARG_NONE option). Since 2.8
  * @G_OPTION_FLAG_FILENAME: For options of the %G_OPTION_ARG_CALLBACK
- *  kind, this flag indicates that the argument should be passed to the
- *  callback in the GLib filename encoding rather than UTF-8. Since 2.8
+ *     kind, this flag indicates that the argument should be passed to the
+ *     callback in the GLib filename encoding rather than UTF-8. Since 2.8
  * @G_OPTION_FLAG_OPTIONAL_ARG: For options of the %G_OPTION_ARG_CALLBACK 
- *  kind, this flag indicates that the argument supply is optional. If no argument
- *  is given then data of %GOptionParseFunc will be set to NULL. Since 2.8
- * @G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict resolution
- *  which prefixes long option names with <literal>groupname-</literal> if 
- *  there is a conflict. This option should only be used in situations where
- *  aliasing is necessary to model some legacy commandline interface. It is
- *  not safe to use this option, unless all option groups are under your 
- *  direct control. Since 2.8.
- * 
+ *     kind, this flag indicates that the argument supply is optional.
+ *     If no argument is given then data of %GOptionParseFunc will be
+ *     set to NULL. Since 2.8
+ * @G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict
+ *     resolution which prefixes long option names with `groupname-` if 
+ *     there is a conflict. This option should only be used in situations
+ *     where aliasing is necessary to model some legacy commandline interface.
+ *     It is not safe to use this option, unless all option groups are under
+ *     your direct control. Since 2.8.
+ *
  * Flags which modify individual options.
  */
 typedef enum
@@ -94,24 +94,24 @@ typedef enum
  * @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.
+ *     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.
+ *     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.
+ *     multiple uses of the option are collected into an array of strings.
  * @G_OPTION_ARG_DOUBLE: The option takes a double argument. The argument
- *  can be formatted either for the user's locale or for the "C" locale. Since 2.12
- * @G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like %G_OPTION_ARG_INT
- *  but for larger numbers. The number can be in decimal base, or in hexadecimal
- *  (when prefixed with <literal>0x</literal>, for example, <literal>0xffffffff</literal>).
- *  Since 2.12
+ *     can be formatted either for the user's locale or for the "C" locale.
+ *     Since 2.12
+ * @G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like
+ *     %G_OPTION_ARG_INT but for larger numbers. The number can be in
+ *     decimal base, or in hexadecimal (when prefixed with `0x`, for
+ *     example, `0xffffffff`). Since 2.12
  * 
  * 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>.
+ * options expect to find. If an option expects an extra argument, it can
+ * be specified in several ways; with a short option: `-x arg`, with a long
+ * option: `--name arg` or combined in a single argument: `--name=arg`.
  */
 typedef enum
 {
@@ -213,67 +213,44 @@ GQuark g_option_error_quark (void);
 /**
  * GOptionEntry:
  * @long_name: The long name of an option can be used to specify it
- *  in a commandline as --<replaceable>long_name</replaceable>. Every
- *  option must have a long name. To resolve conflicts if multiple
- *  option groups contain the same long name, it is also possible to
- *  specify the option as 
- *  --<replaceable>groupname</replaceable>-<replaceable>long_name</replaceable>.
+ *     in a commandline as `--long_name`. Every option must have a
+ *     long name. To resolve conflicts if multiple option groups contain
+ *     the same long name, it is also possible to specify the option as 
+ *     `--groupname-long_name`.
  * @short_name: If an option has a short name, it can be specified
- *  -<replaceable>short_name</replaceable> in a commandline. @short_name must be 
- *  a printable ASCII character different from '-', or zero if the option has no
- *  short name.
- * @flags: Flags from #GOptionFlags.
- * @arg: The type of the option, as a #GOptionArg.
- * @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must 
- *  point to a #GOptionArgFunc callback function, which will be called to handle 
- *  the extra argument. Otherwise, @arg_data is a pointer to a location to store 
- *  the value, the required type of the location depends on the @arg type:
- *  <variablelist>
- *  <varlistentry>
- *  <term>%G_OPTION_ARG_NONE</term>
- *  <listitem><para>%gboolean</para></listitem>
- *  </varlistentry>
- *  <varlistentry>
- *  <term>%G_OPTION_ARG_STRING</term>
- *  <listitem><para>%gchar*</para></listitem>
- *  </varlistentry>
- *  <varlistentry>
- *  <term>%G_OPTION_ARG_INT</term>
- *  <listitem><para>%gint</para></listitem>
- *  </varlistentry>
- *  <varlistentry>
- *  <term>%G_OPTION_ARG_FILENAME</term>
- *  <listitem><para>%gchar*</para></listitem>
- *  </varlistentry>
- *  <varlistentry>
- *  <term>%G_OPTION_ARG_STRING_ARRAY</term>
- *  <listitem><para>%gchar**</para></listitem>
- *  </varlistentry>
- *  <varlistentry>
- *  <term>%G_OPTION_ARG_FILENAME_ARRAY</term>
- *  <listitem><para>%gchar**</para></listitem>
- *  </varlistentry>
- *  <varlistentry>
- *  <term>%G_OPTION_ARG_DOUBLE</term>
- *  <listitem><para>%gdouble</para></listitem>
- *  </varlistentry>
- *  </variablelist>
- *  If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME the location
- *  will contain a newly allocated string if the option was given. That string
- *  needs to be freed by the callee using g_free(). Likewise if @arg type is
- *  %G_OPTION_ARG_STRING_ARRAY or %G_OPTION_ARG_FILENAME_ARRAY, the data should
- *  be freed using g_strfreev().
- * @description: the description for the option in <option>--help</option>
- *  output. The @description is translated using the @translate_func of the
- *  group, see g_option_group_set_translation_domain().
+ *     `-short_name` in a commandline. @short_name must be  a printable
+ *     ASCII character different from '-', or zero if the option has no
+ *     short name.
+ * @flags: Flags from #GOptionFlags
+ * @arg: The type of the option, as a #GOptionArg
+ * @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data
+ *     must point to a #GOptionArgFunc callback function, which will be
+ *     called to handle the extra argument. Otherwise, @arg_data is a
+ *     pointer to a location to store the value, the required type of
+ *     the location depends on the @arg type:
+ *     - %G_OPTION_ARG_NONE: %gboolean
+ *     - %G_OPTION_ARG_STRING: %gchar*
+ *     - %G_OPTION_ARG_INT: %gint
+ *     - %G_OPTION_ARG_FILENAME: %gchar*
+ *     - %G_OPTION_ARG_STRING_ARRAY: %gchar**
+ *     - %G_OPTION_ARG_FILENAME_ARRAY: %gchar**
+ *     - %G_OPTION_ARG_DOUBLE: %gdouble
+ *     If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME,
+ *     the location will contain a newly allocated string if the option
+ *     was given. That string needs to be freed by the callee using g_free().
+ *     Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or
+ *     %G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev().
+ * @description: the description for the option in `--help`
+ *     output. The @description is translated using the @translate_func
+ *     of the group, see g_option_group_set_translation_domain().
  * @arg_description: The placeholder to use for the extra argument parsed
- *  by the option in <option>--help</option>
- *  output. The @arg_description is translated using the @translate_func of the
- *  group, see g_option_group_set_translation_domain().
+ *     by the option in `--help` output. The @arg_description is translated
+ *     using the @translate_func of the group, see
+ *     g_option_group_set_translation_domain().
  * 
- * A <structname>GOptionEntry</structname> defines a single option.
- * To have an effect, they must be added to a #GOptionGroup with
- * g_option_context_add_main_entries() or g_option_group_add_entries().
+ * A GOptionEntry struct defines a single option. To have an effect, they
+ * must be added to a #GOptionGroup with g_option_context_add_main_entries()
+ * or g_option_group_add_entries().
  */
 struct _GOptionEntry
 {
@@ -293,12 +270,12 @@ struct _GOptionEntry
  * 
  * If a long option in the main group has this name, it is not treated as a 
  * regular option. Instead it collects all non-option arguments which would
- * otherwise be left in <literal>argv</literal>. The option must be of type
+ * otherwise be left in `argv`. The option must be of type
  * %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY
  * or %G_OPTION_ARG_FILENAME_ARRAY.
  * 
  * 
- * Using #G_OPTION_REMAINING instead of simply scanning <literal>argv</literal>
+ * Using #G_OPTION_REMAINING instead of simply scanning `argv`
  * for leftover arguments has the advantage that GOption takes care of 
  * necessary encoding conversions for strings or filenames.
  * 
diff --git a/glib/gspawn.h b/glib/gspawn.h
index 7a993e970..eb7304bb8 100644
--- a/glib/gspawn.h
+++ b/glib/gspawn.h
@@ -45,25 +45,25 @@ G_BEGIN_DECLS
  * @G_SPAWN_ERROR_FORK: Fork failed due to lack of memory.
  * @G_SPAWN_ERROR_READ: Read or select on pipes failed.
  * @G_SPAWN_ERROR_CHDIR: Changing to working directory failed.
- * @G_SPAWN_ERROR_ACCES: execv() returned <literal>EACCES</literal>
- * @G_SPAWN_ERROR_PERM: execv() returned <literal>EPERM</literal>
- * @G_SPAWN_ERROR_TOO_BIG: execv() returned <literal>E2BIG</literal>
+ * @G_SPAWN_ERROR_ACCES: execv() returned `EACCES`
+ * @G_SPAWN_ERROR_PERM: execv() returned `EPERM`
+ * @G_SPAWN_ERROR_TOO_BIG: execv() returned `E2BIG`
  * @G_SPAWN_ERROR_2BIG: deprecated alias for %G_SPAWN_ERROR_TOO_BIG
- * @G_SPAWN_ERROR_NOEXEC: execv() returned <literal>ENOEXEC</literal>
- * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned <literal>ENAMETOOLONG</literal>
- * @G_SPAWN_ERROR_NOENT: execv() returned <literal>ENOENT</literal>
- * @G_SPAWN_ERROR_NOMEM: execv() returned <literal>ENOMEM</literal>
- * @G_SPAWN_ERROR_NOTDIR: execv() returned <literal>ENOTDIR</literal>
- * @G_SPAWN_ERROR_LOOP: execv() returned <literal>ELOOP</literal>
- * @G_SPAWN_ERROR_TXTBUSY: execv() returned <literal>ETXTBUSY</literal>
- * @G_SPAWN_ERROR_IO: execv() returned <literal>EIO</literal>
- * @G_SPAWN_ERROR_NFILE: execv() returned <literal>ENFILE</literal>
- * @G_SPAWN_ERROR_MFILE: execv() returned <literal>EMFILE</literal>
- * @G_SPAWN_ERROR_INVAL: execv() returned <literal>EINVAL</literal>
- * @G_SPAWN_ERROR_ISDIR: execv() returned <literal>EISDIR</literal>
- * @G_SPAWN_ERROR_LIBBAD: execv() returned <literal>ELIBBAD</literal>
+ * @G_SPAWN_ERROR_NOEXEC: execv() returned `ENOEXEC`
+ * @G_SPAWN_ERROR_NAMETOOLONG: execv() returned `ENAMETOOLONG`
+ * @G_SPAWN_ERROR_NOENT: execv() returned `ENOENT`
+ * @G_SPAWN_ERROR_NOMEM: execv() returned `ENOMEM`
+ * @G_SPAWN_ERROR_NOTDIR: execv() returned `ENOTDIR`
+ * @G_SPAWN_ERROR_LOOP: execv() returned `ELOOP`
+ * @G_SPAWN_ERROR_TXTBUSY: execv() returned `ETXTBUSY`
+ * @G_SPAWN_ERROR_IO: execv() returned `EIO`
+ * @G_SPAWN_ERROR_NFILE: execv() returned `ENFILE`
+ * @G_SPAWN_ERROR_MFILE: execv() returned `EMFILE`
+ * @G_SPAWN_ERROR_INVAL: execv() returned `EINVAL`
+ * @G_SPAWN_ERROR_ISDIR: execv() returned `EISDIR`
+ * @G_SPAWN_ERROR_LIBBAD: execv() returned `ELIBBAD`
  * @G_SPAWN_ERROR_FAILED: Some other fatal failure,
- *   <literal>error-&gt;message</literal> should explain.
+ *   `error->message` should explain.
  *
  * Error codes returned by spawning processes.
  */
@@ -124,51 +124,48 @@ typedef enum
  * functions.
  *
  * However, even on POSIX, you are extremely limited in what you can
- * safely do from a #GSpawnChildSetupFunc, because any mutexes that
- * were held by other threads in the parent process at the time of the
- * fork() will still be locked in the child process, and they will
- * never be unlocked (since the threads that held them don't exist in
- * the child). POSIX allows only async-signal-safe functions (see
- * <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>)
- * to be called in the child between fork() and exec(), which
- * drastically limits the usefulness of child setup functions.
+ * safely do from a #GSpawnChildSetupFunc, because any mutexes that were
+ * held by other threads in the parent process at the time of the fork()
+ * will still be locked in the child process, and they will never be
+ * unlocked (since the threads that held them don't exist in the child).
+ * POSIX allows only async-signal-safe functions (see signal(7)) to be
+ * called in the child between fork() and exec(), which drastically limits
+ * the usefulness of child setup functions.
  *
  * In particular, it is not safe to call any function which may
  * call malloc(), which includes POSIX functions such as setenv().
  * If you need to set up the child environment differently from
  * the parent, you should use g_get_environ(), g_environ_setenv(),
  * and g_environ_unsetenv(), and then pass the complete environment
- * list to the <literal>g_spawn...</literal> function.
+ * list to the `g_spawn...` function.
  */
 typedef void (* GSpawnChildSetupFunc) (gpointer user_data);
 
 /**
  * GSpawnFlags:
  * @G_SPAWN_DEFAULT: no flags, default behaviour
- * @G_SPAWN_LEAVE_DESCRIPTORS_OPEN: the parent's open file descriptors will be
- *   inherited by the child; otherwise all descriptors except stdin/stdout/stderr
- *   will be closed before calling exec() in the child.
- * @G_SPAWN_DO_NOT_REAP_CHILD: the child will not be automatically reaped; you
- *   must use g_child_watch_add() yourself (or call waitpid()
- *   or handle <literal>SIGCHLD</literal> yourself), or the child will become a zombie.
- * @G_SPAWN_SEARCH_PATH: <literal>argv[0]</literal> need not be an absolute path,
- *   it will be looked for in the user's <envar>PATH</envar>.
+ * @G_SPAWN_LEAVE_DESCRIPTORS_OPEN: the parent's open file descriptors will
+ *     be inherited by the child; otherwise all descriptors except stdin,
+ *     stdout and stderr will be closed before calling exec() in the child.
+ * @G_SPAWN_DO_NOT_REAP_CHILD: the child will not be automatically reaped;
+ *     you must use g_child_watch_add() yourself (or call waitpid() or handle
+ *     `SIGCHLD` yourself), or the child will become a zombie.
+ * @G_SPAWN_SEARCH_PATH: `argv[0]` need not be an absolute path, it will be
+ *     looked for in the user's `PATH`.
  * @G_SPAWN_STDOUT_TO_DEV_NULL: the child's standard output will be discarded,
- *   instead of going to the same location as the parent's standard output.
+ *     instead of going to the same location as the parent's standard output.
  * @G_SPAWN_STDERR_TO_DEV_NULL: the child's standard error will be discarded.
  * @G_SPAWN_CHILD_INHERITS_STDIN: the child will inherit the parent's standard
- *   input (by default, the child's standard input is attached to
- *   <filename>/dev/null</filename>).
- * @G_SPAWN_FILE_AND_ARGV_ZERO: the first element of <literal>argv</literal> is
- *   the file to execute, while the remaining elements are the actual argument
- *   vector to pass to the file. Normally g_spawn_async_with_pipes() uses
- *   <literal>argv[0]</literal> as the file to execute, and passes all of
- *   <literal>argv</literal> to the child.
- * @G_SPAWN_SEARCH_PATH_FROM_ENVP: if <literal>argv[0]</literal> is not an abolute path,
- *   it will be looked for in the <envar>PATH</envar> from the passed child 
- *   environment. Since: 2.34
- * @G_SPAWN_CLOEXEC_PIPES: create all pipes with the O_CLOEXEC flag set.
- *   Since: 2.40.
+ *     input (by default, the child's standard input is attached to `/dev/null`).
+ * @G_SPAWN_FILE_AND_ARGV_ZERO: the first element of `argv` is the file to
+ *     execute, while the remaining elements are the actual argument vector
+ *     to pass to the file. Normally g_spawn_async_with_pipes() uses `argv[0]`
+ *     as the file to execute, and passes all of `argv` to the child.
+ * @G_SPAWN_SEARCH_PATH_FROM_ENVP: if `argv[0]` is not an abolute path,
+ *     it will be looked for in the `PATH` from the passed child environment.
+ *     Since: 2.34
+ * @G_SPAWN_CLOEXEC_PIPES: create all pipes with the `O_CLOEXEC` flag set.
+ *     Since: 2.40
  *
  * Flags passed to g_spawn_sync(), g_spawn_async() and g_spawn_async_with_pipes().
  */