[glib: 2/3] docs: Various markup improvements to glib-mkenums man page

[Christoph Reiter <creiter src gnome org>]

commit 95e00c75812f86753286a925ff41ace8e4879f3d
Author: Philip Withnall <withnall endlessm com>
Date:   Mon Mar 4 11:14:22 2019 +0000

    docs: Various markup improvements to glib-mkenums man page
    
    Signed-off-by: Philip Withnall <withnall endlessm com>

 docs/reference/gobject/glib-mkenums.xml | 62 +++++++++++++++++----------------
 1 file changed, 32 insertions(+), 30 deletions(-)
---
diff --git a/docs/reference/gobject/glib-mkenums.xml b/docs/reference/gobject/glib-mkenums.xml
index 84023e9b1..4c8641657 100644
--- a/docs/reference/gobject/glib-mkenums.xml
+++ b/docs/reference/gobject/glib-mkenums.xml
@@ -35,20 +35,21 @@
 <para><command>glib-mkenums</command> is a small utility that parses C code to
 extract enum definitions and produces enum descriptions based on text templates
 specified by the user. Typically, you can use this tool to generate enumeration
-types for the GType type system, for #GObject properties and signal marshalling;
-additionally, you can use it to generate enumeration values of #GSettings schemas.
+types for the GType type system, for GObject properties and signal marshalling;
+additionally, you can use it to generate enumeration values of GSettings schemas.
 </para>
 
 <para><command>glib-mkenums</command> takes a list of valid C code files as
 input. The options specified control the text that generated, substituting various
-keywords enclosed in @ characters in the templates.
+keywords enclosed in <literal>@</literal> characters in the templates.
 </para>
 
 <refsect2><title>Production text substitutions</title>
 <para>
-Certain keywords enclosed in @ characters will be substituted in the
+Certain keywords enclosed in <literal>@</literal> characters will be substituted in the
 emitted text. For the substitution examples of the keywords below,
 the following example enum definition is assumed:
+</para>
 <informalexample><programlisting>
 typedef enum
 {
@@ -58,7 +59,7 @@ typedef enum
 </programlisting></informalexample>
 <variablelist>
 <varlistentry>
-<term>@EnumName@</term>
+<term><literal>@EnumName@</literal>></term>
 <listitem><para>
 The name of the enum currently being processed, enum names are assumed to be
 properly namespaced and to use mixed capitalization to separate
@@ -67,7 +68,7 @@ words (e.g. <literal>PrefixTheXEnum</literal>).
 </varlistentry>
 
 <varlistentry>
-<term>@enum_name@</term>
+<term><literal>@enum_name@</literal></term>
 <listitem><para>
 The enum name with words lowercase and word-separated by underscores
 (e.g. <literal>prefix_the_xenum</literal>).
@@ -75,7 +76,7 @@ The enum name with words lowercase and word-separated by underscores
 </varlistentry>
 
 <varlistentry>
-<term>@ENUMNAME@</term>
+<term><literal>@ENUMNAME@</literal></term>
 <listitem><para>
 The enum name with words uppercase and word-separated by underscores
 (e.g. <literal>PREFIX_THE_XENUM</literal>).
@@ -83,7 +84,7 @@ The enum name with words uppercase and word-separated by underscores
 </varlistentry>
 
 <varlistentry>
-<term>@ENUMSHORT@</term>
+<term><literal>@ENUMSHORT@</literal></term>
 <listitem><para>
 The enum name with words uppercase and word-separated by underscores,
 prefix stripped (e.g. <literal>THE_XENUM</literal>).
@@ -91,14 +92,14 @@ prefix stripped (e.g. <literal>THE_XENUM</literal>).
 </varlistentry>
 
 <varlistentry>
-<term>@ENUMPREFIX@</term>
+<term><literal>@ENUMPREFIX@</literal></term>
 <listitem><para>
 The prefix of the enum name (e.g. <literal>PREFIX</literal>).
 </para></listitem>
 </varlistentry>
 
 <varlistentry>
-<term>@VALUENAME@</term>
+<term><literal>@VALUENAME@</literal></term>
 <listitem><para>
 The enum value name currently being processed with words uppercase and
 word-separated by underscores,
@@ -108,7 +109,7 @@ this is the assumed literal notation of enum values in the C sources
 </varlistentry>
 
 <varlistentry>
-<term>@valuenick@</term>
+<term><literal>@valuenick@</literal></term>
 <listitem><para>
 A nick name for the enum value currently being processed, this is usually
 generated by stripping common prefix words of all the enum values of the
@@ -118,7 +119,7 @@ minus (e.g. <literal>the-xvalue</literal>).
 </varlistentry>
 
 <varlistentry>
-<term>@valuenum@</term>
+<term><literal>@valuenum@</literal></term>
 <listitem><para>
 The integer value for the enum value currently being processed. If the
 evaluation fails then <command>glib-mkenums</command> will exit with an
@@ -128,61 +129,61 @@ appears in your value production template. (Since: 2.26)
 </varlistentry>
 
 <varlistentry>
-<term>@type@</term>
+<term><literal>@type@</literal></term>
 <listitem><para>
 This is substituted either by "enum" or "flags", depending on whether the
-enum value definitions contained bit-shift operators or not (e.g. flags).
+enum value definitions contained bit-shift operators or not (e.g. <literal>flags</literal>).
 </para></listitem>
 </varlistentry>
 
 <varlistentry>
-<term>@Type@</term>
+<term><literal>@Type@</literal></term>
 <listitem><para>
-The same as <literal>@type@</literal> with the first letter capitalized (e.g. Flags).
+The same as <literal>@type@</literal> with the first letter capitalized (e.g. <literal>Flags</literal>).
 </para></listitem>
 </varlistentry>
 
 <varlistentry>
-<term>@TYPE@</term>
+<term><literal>@TYPE@</literal></term>
 <listitem><para>
-The same as <literal>@type@</literal> with all letters uppercased (e.g. FLAGS).
+The same as <literal>@type@</literal> with all letters uppercased (e.g. <literal>FLAGS</literal>).
 </para></listitem>
 </varlistentry>
 
 <varlistentry>
-<term>@filename@</term>
+<term><literal>@filename@</literal></term>
 <listitem><para>
-The name of the input file currently being processed (e.g. foo.h).
+The name of the input file currently being processed (e.g. <literal>foo.h</literal>).
 </para></listitem>
 </varlistentry>
 
 <varlistentry>
-<term>@basename@</term>
+<term><literal>@basename@</literal></term>
 <listitem><para>
-The base name of the input file currently being processed (e.g. foo.h). Typically
+The base name of the input file currently being processed (e.g. <literal>foo.h</literal>). Typically
 you want to use <literal>@basename@</literal> in place of <literal>@filename@</literal> in your templates, 
to improve the reproducibility of the build. (Since: 2.22)
 </para></listitem>
 </varlistentry>
 </variablelist>
-</para>
 </refsect2>
 <refsect2><title>Trigraph extensions</title>
 <para>
 Some C comments are treated specially in the parsed enum definitions,
 such comments start out with the trigraph sequence <literal>/*&lt;</literal>
 and end with the trigraph sequence <literal>&gt;*/</literal>.
-Per enum definition, the options "skip" and "flags" can be specified, to
+Per enum definition, the options <literal>skip</literal> and <literal>flags</literal> can be specified, to
 indicate this enum definition to be skipped, or for it to be treated as
 a flags definition, or to specify the common prefix to be stripped from
-all values to generate value nicknames, respectively. The "underscore_name"
-option can be used to specify the word separation used in the *_get_type()
+all values to generate value nicknames, respectively. The <literal>underscore_name</literal>
+option can be used to specify the word separation used in the <function>*_get_type()</function>
 function. For instance, <literal>/*&lt; underscore_name=gnome_vfs_uri_hide_options &gt;*/</literal>.
 </para>
 <para>
-Per value definition, the options "skip" and "nick" are supported.
+Per value definition, the options <literal>skip</literal> and <literal>nick</literal> are supported.
 The former causes the value to be skipped, and the latter can be used to
 specify the otherwise auto-generated nickname.
 Examples:
+</para>
 <informalexample><programlisting>
 typedef enum /*&lt; skip &gt;*/
 {
@@ -196,7 +197,6 @@ typedef enum /*&lt; flags,prefix=PREFIX &gt;*/
   PREFIX_THE_THIRD_VALUE,      /*&lt; nick=the-last-value &gt;*/
 } PrefixTheFlagsEnum;
 </programlisting></informalexample>
-</para>
 </refsect2>
 </refsect1>
 
@@ -317,12 +317,14 @@ Template for auto-generated comments, the default (for C code generations) is
 <term><option>--template</option> <replaceable>FILE</replaceable></term>
 <listitem><para>
 Read templates from the given file. The templates are enclosed in
-specially-formatted C comments
+specially-formatted C comments:
+</para>
 <informalexample><programlisting>
 /*** BEGIN section ***/
 /*** END section ***/
 </programlisting></informalexample>
-where section may be <literal>file-header</literal>,
+<para>
+<replaceable>section</replaceable> may be <literal>file-header</literal>,
 <literal>file-production</literal>, <literal>file-tail</literal>,
 <literal>enumeration-production</literal>, <literal>value-header</literal>,
 <literal>value-production</literal>, <literal>value-tail</literal> or