More consistent doc formatting

Move some things around, make capitalization of short descriptions
more consistent.

docs/reference/glib/glib-docs.sgml

@@ -35,10 +35,9 @@ synchronize their operation.
     <xi:include href="compiling.sgml" />
     <xi:include href="running.sgml" />
     <xi:include href="changes.sgml" />
-    <xi:include href="regex-syntax.sgml" />
     <xi:include href="resources.sgml" />
- 
-  </chapter> 
+
+  </chapter>
 
   <chapter id="glib-fundamentals">
     <title>GLib Fundamentals</title>
@@ -92,6 +91,7 @@ synchronize their operation.
       <xi:include href="xml/option.xml" />
       <xi:include href="xml/patterns.xml" />
       <xi:include href="xml/gregex.xml" />
+      <xi:include href="regex-syntax.sgml" />
       <xi:include href="xml/markup.xml" />
       <xi:include href="xml/keyfile.xml" />
       <xi:include href="xml/bookmarkfile.xml" />

docs/reference/glib/gvariant-text.xml

@@ -4,6 +4,10 @@
  <refmeta>
   <refentrytitle>GVariant Text Format</refentrytitle>
  </refmeta>
+ <refnamediv>
+  <refname>GVariant Text Format</refname>
+  <refpurpose>textual representation of GVariants</refpurpose>
+ </refnamediv>
 
  <refsect1>
   <title>GVariant Text Format</title>

docs/reference/glib/gvariant-varargs.xml

@@ -4,12 +4,17 @@
  <refmeta>
   <refentrytitle>GVariant Format Strings</refentrytitle>
  </refmeta>
+ <refnamediv>
+  <refname>GVariant Format Strings</refname>
+  <refpurpose>varargs conversion of GVariants</refpurpose>
+ </refnamediv>
 
  <refsect1>
   <title>Variable Argument Conversions</title>
 
   <para>
-   This page attempts to document how to perform variable argument conversions with GVariant.
+   This page attempts to document how to perform variable argument
+   conversions with GVariant.
   </para>
   <para>
    Conversions occur according to format strings.  A format string is a two-way mapping between a single

docs/reference/glib/regex-syntax.sgml

@@ -3,9 +3,10 @@
                "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
 ]>
 <refentry id="glib-regex-syntax" revision="11 Jul 2006">
-<refmeta>
-<refentrytitle>Regular expression syntax</refentrytitle>
-</refmeta>
+ <refmeta>
+  <refentrytitle>Regular expression syntax</refentrytitle>
+ </refmeta>
+
 
 <!--
 Based on the man page for pcrepattern.
@@ -19,7 +20,7 @@ In sync with PCRE 7.0
 <refnamediv>
 <refname>Regular expression syntax</refname>
 <refpurpose>
-Syntax and semantics of the regular expressions supported by GRegex
+syntax and semantics of regular expressions supported by GRegex
 </refpurpose>
 </refnamediv>
 

docs/reference/glib/running.sgml

@@ -2,7 +2,7 @@
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
                "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
 ]>
-<refentry id="glib-running" revision="17 Jan 2002">
+<refentry id="glib-running">
 <refmeta>
 <refentrytitle>Running GLib Applications</refentrytitle>
 <manvolnum>3</manvolnum>
@@ -22,17 +22,39 @@ How to run and debug your GLib application
 <refsect2>
 <title>Environment variables</title>
 
-<para> 
-GLib inspects a few of environment variables in addition to standard
-variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>. 
+<para>
+  The runtime behaviour of GLib applications can be influenced by a
+  number of environment variables.
 </para>
 
+<formalpara>
+  <title>Standard variables</title>
+
+  <para>
+    GLib reads standard environment variables like <envar>LANG</envar>,
+    <envar>PATH</envar>, <envar>HOME</envar>, <envar>TMPDIR</envar>,
+    <envar>TZ</envar> and <envar>LOGNAME</envar>.
+  </para>
+</formalpara>
+
+<formalpara>
+  <title>XDG directories</title>
+
+  <para>
+    GLib consults the environment variables <envar>XDG_DATA_HOME</envar>,
+    <envar>XDG_DATA_DIRS</envar>, <envar>XDG_CONFIG_HOME</envar>,
+    <envar>XDG_CONFIG_DIRS</envar>, <envar>XDG_CACHE_HOME</envar> and
+    <envar>XDG_RUNTIME_DIR</envar> for the various XDG directories.
+    For more information, see the <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG basedir spec</ulink>.
+  </para>
+</formalpara>
+
 <formalpara id="G_FILENAME_ENCODING">
   <title><envar>G_FILENAME_ENCODING</envar></title>
 
   <para>
     This environment variable can be set to a comma-separated list of character
-    set names. GLib assumes that filenames are encoded in the first character 
+    set names. GLib assumes that filenames are encoded in the first character
     set from that list rather than in UTF-8. The special token "@locale" can be
     used to specify the character set for the current locale.
   </para>
@@ -42,9 +64,9 @@ variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
   <title><envar>G_BROKEN_FILENAMES</envar></title>
 
   <para>
-    If this environment variable is set, GLib assumes that filenames are in 
+    If this environment variable is set, GLib assumes that filenames are in
     the locale encoding rather than in UTF-8. G_FILENAME_ENCODING takes
-    priority over G_BROKEN_FILENAMES. 
+    priority over G_BROKEN_FILENAMES.
   </para>
 </formalpara>
 
@@ -52,7 +74,7 @@ variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
   <title><envar>G_MESSAGES_PREFIXED</envar></title>
 
   <para>
-    A list of log levels for which messages should be prefixed by the 
+    A list of log levels for which messages should be prefixed by the
     program name and PID of the application. The default is to prefix
     everything except <literal>G_LOG_LEVEL_MESSAGE</literal> and
     <literal>G_LOG_LEVEL_INFO</literal>.
@@ -68,7 +90,7 @@ variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
     <literal>help</literal>.
   </para>
   <para>
-    This environment variable only affects the GLib log handler,
+    This environment variable only affects the default log handler,
     g_log_default_handler().
   </para>
 </formalpara>
@@ -85,130 +107,107 @@ variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
     You can also use the special value <literal>all</literal>.
   </para>
   <para>
-    This environment variable only affects the GLib log handler,
+    This environment variable only affects the default log handler,
     g_log_default_handler().
   </para>
 </formalpara>
 
 <formalpara id="G-DEBUG:CAPS">
   <title><envar>G_DEBUG</envar></title>
+
   <para>
-    If GLib has been configured with <option>--enable-debug=yes</option>,
-    this variable can be set to a list of debug options, which cause GLib
-    to print out different types of debugging information.
+    This environment variable can be set to a list of debug options,
+    which cause GLib to print out different types of debugging information.
     <variablelist>
       <varlistentry>
-        <term>fatal_warnings</term>
+        <term>fatal-warnings</term>
         <listitem><para>Causes GLib to abort the program at the first call
-           to <link linkend="g-warning">g_warning</link>() or
-	   <link linkend="g-critical">g_critical</link>(). This option is 
-           special in that it doesn't require GLib to be configured with 
-           debugging support.</para>
+           to g_warning() or g_critical().</para>
         </listitem>
       </varlistentry>
       <varlistentry>
-        <term>fatal_criticals</term>
+        <term>fatal-criticals</term>
         <listitem><para>Causes GLib to abort the program at the first call
-           to <link linkend="g-critical">g_critical</link>(). This option is 
-           special in that it doesn't require GLib to be configured with 
-           debugging support.</para>
+           to g_critical().</para>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term>gc-friendly</term>
-	<listitem>
-		<para>
-		  Newly allocated memory that isn't directly initialized, as well
-		  as memory being freed will be reset to 0. The point here is to
-		  allow memory checkers and similar programs that use bohem GC alike
-		  algorithms to produce more accurate results.
-		  This option is special in that it doesn't require GLib to be
-		  configured with debugging support.
-		</para>
+        <listitem><para>Newly allocated memory that isn't directly initialized,
+          as well as memory being freed will be reset to 0. The point here is
+          to allow memory checkers and similar programs that use Boehm GC alike
+          algorithms to produce more accurate results.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term>resident-modules</term>
-	<listitem>
-	  <para>
-	    All modules loaded by GModule will be made resident. This can be useful
-	    for tracking memory leaks in modules which are later unloaded; but it can
-	    also hide bugs where code is accessed after the module would have normally
-	    been unloaded.
-	    This option is special in that it doesn't require GLib to be
- 	    configured with debugging support.
-	  </para>
+        <listitem><para>All modules loaded by GModule will be made resident.
+          This can be useful for tracking memory leaks in modules which are
+          later unloaded; but it can also hide bugs where code is accessed
+          after the module would have normally been unloaded.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term>bind-now-modules</term>
-	<listitem>
-	  <para>
-	    All modules loaded by GModule will bind their symbols at load time, even
-	    when the code uses %G_MODULE_BIND_LAZY.
-	    This option is special in that it doesn't require GLib to be
- 	    configured with debugging support.
-	  </para>
+        <listitem><para>All modules loaded by GModule will bind their symbols
+          at load time, even when the code uses %G_MODULE_BIND_LAZY.</para>
         </listitem>
       </varlistentry>
     </variablelist>
-    The special value all can be used to turn on all debug options. 
-    The special value help can be used to print all available options.  
+    The special value all can be used to turn on all debug options.
+    The special value help can be used to print all available options.
   </para>
 </formalpara>
 
 <formalpara id="G_SLICE">
-	<title><envar>G_SLICE</envar></title>
-	<para>
-	  This environment variable allows reconfiguration of the GSlice
-	  memory allocator.
-	  <variablelist>
-	    <varlistentry>
-	      <term>always-malloc</term>
-	      <listitem>
-		<para>
-		  This will cause all slices allocated through g_slice_alloc() and
-		  released by g_slice_free1() to be actually allocated via direct
-		  calls to g_malloc() and g_free().
-		  This is most useful for memory checkers and similar programs that
-		  use Bohem GC alike algorithms to produce more accurate results.
-		  It can also be in conjunction with debugging features of the system's
-		  malloc implementation such as glibc's MALLOC_CHECK_=2 to debug
-		  erroneous slice allocation code, allthough <literal>debug-blocks</literal>
-		  usually is a better suited debugging tool.
-		</para>
-	      </listitem>
-	    </varlistentry>
-	    <varlistentry>
-	      <term>debug-blocks</term>
-	      <listitem>
-		<para>
-		  Using this option (present since GLib-2.13) engages extra code
-		  which performs sanity checks on the released memory slices.
-		  Invalid slice adresses or slice sizes will be reported and lead to
-		  a program halt.
-		  This option is for debugging scenarios.
-		  In particular, client packages sporting their own test suite should
-		  <emphasis>always enable this option when running tests</emphasis>.
-		  Global slice validation is ensured by storing size and address information
-		  for each allocated chunk, and maintaining a global hash table of that data.
-		  That way, multi-thread scalability is given up, and memory consumption is
-		  increased. However, the resulting code usually performs acceptably well,
-		  possibly better than with comparable memory checking carried out using
-		  external tools. An example of a memory corruption scenario that cannot be
-		  reproduced with <literal>G_SLICE=always-malloc</literal>, but will be caught
-		  by <literal>G_SLICE=debug-blocks</literal> is as follows:
-		  <programlisting>
-		    void *slist = g_slist_alloc(); /* void* gives up type-safety */
-		    g_list_free (slist);           /* corruption: sizeof (GSList) != sizeof (GList) */
-		  </programlisting>
-		</para>
-	      </listitem>
-	    </varlistentry>
-	  </variablelist>
-          The special value all can be used to turn on all options. 
-          The special value help can be used to print all available options.  
-	</para>
+  <title><envar>G_SLICE</envar></title>
+
+  <para>
+    This environment variable allows reconfiguration of the GSlice
+    memory allocator.
+    <variablelist>
+      <varlistentry>
+        <term>always-malloc</term>
+        <listitem><para>This will cause all slices allocated through
+          g_slice_alloc() and released by g_slice_free1() to be actually
+          allocated via direct calls to g_malloc() and g_free().
+          This is most useful for memory checkers and similar programs that
+          use Boehm GC alike algorithms to produce more accurate results.
+          It can also be in conjunction with debugging features of the system's
+          malloc() implementation such as glibc's MALLOC_CHECK_=2 to debug
+          erroneous slice allocation code, although
+          <literal>debug-blocks</literal> is usually a better suited debugging
+          tool.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>debug-blocks</term>
+        <listitem><para>Using this option (present since GLib 2.13) engages
+          extra code which performs sanity checks on the released memory
+          slices. Invalid slice adresses or slice sizes will be reported and
+          lead to a program halt. This option is for debugging scenarios.
+          In particular, client packages sporting their own test suite should
+          <emphasis>always enable this option when running tests</emphasis>.
+          Global slice validation is ensured by storing size and address
+          information for each allocated chunk, and maintaining a global
+          hash table of that data. That way, multi-thread scalability is
+          given up, and memory consumption is increased. However, the
+          resulting code usually performs acceptably well, possibly better
+          than with comparable memory checking carried out using external
+          tools.</para>
+          <para>An example of a memory corruption scenario that cannot be
+          reproduced with <literal>G_SLICE=always-malloc</literal>, but will
+          be caught by <literal>G_SLICE=debug-blocks</literal> is as follows:
+          <programlisting>
+            void *slist = g_slist_alloc (); /* void* gives up type-safety */
+            g_list_free (slist);            /* corruption: sizeof (GSList) != sizeof (GList) */
+          </programlisting></para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    The special value all can be used to turn on all options.
+    The special value help can be used to print all available options.
+  </para>
 </formalpara>
 
 <formalpara id="G_RANDOM_VERSION">
@@ -217,22 +216,22 @@ variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
   <para>
     If this environment variable is set to '2.0', the outdated
     pseudo-random number seeding and generation algorithms from
-    GLib-2.0 are used instead of the new better ones. Use the GLib-2.0
-    algorithms only if you have sequences of numbers generated with
-    Glib-2.0 that you need to reproduce exactly.  
+    GLib 2.0 are used instead of the newer, better ones. You should
+    only set this variable if you have sequences of numbers that were
+    generated with Glib 2.0 that you need to reproduce exactly.
   </para>
-</formalpara> 
+</formalpara>
 
 <formalpara id="LIBCHARSET_ALIAS_DIR">
   <title><envar>LIBCHARSET_ALIAS_DIR</envar></title>
 
   <para>
-    Allows to specify a nonstandard location for the 
+    Allows to specify a nonstandard location for the
     <filename>charset.aliases</filename> file that is used by the
-    character set conversion routines. The default location is the 
+    character set conversion routines. The default location is the
     <replaceable>libdir</replaceable> specified at compilation time.
   </para>
-</formalpara> 
+</formalpara>
 
 <formalpara id="TZDIR">
   <title><envar>TZDIR</envar></title>
@@ -253,7 +252,7 @@ variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
 <para>
 A number of interfaces in GLib depend on the current locale in which
 an application is running. Therefore, most GLib-using applications should
-call <function>setlocale (LC_ALL, "")</function> to set up the current 
+call <function>setlocale (LC_ALL, "")</function> to set up the current
 locale.
 </para>
 
@@ -282,9 +281,9 @@ returned by functions like <function>strftime()</function>.
 <indexterm><primary>g_trap_free_size</primary></indexterm>
 <indexterm><primary>g_trap_realloc_size</primary></indexterm>
 <indexterm><primary>g_trap_malloc_size</primary></indexterm>
-Some code portions contain trap variables that can be set during debugging 
-time if GLib has been configured with <option>--enable-debug=yes</option>. 
-Such traps lead to immediate code halts to examine the current program state 
+Some code portions contain trap variables that can be set during debugging
+time if GLib has been configured with <option>--enable-debug=yes</option>.
+Such traps lead to immediate code halts to examine the current program state
 and backtrace.
 </para>
 
@@ -295,11 +294,11 @@ static volatile gulong g_trap_free_size;
 static volatile gulong g_trap_realloc_size;
 static volatile gulong g_trap_malloc_size;
 </programlisting>
-If set to a size > 0, <link linkend="g-free">g_free</link>(), 
-<link linkend="g-realloc">g_realloc</link>() and 
-<link linkend="g-malloc">g_malloc</link>() will be intercepted if the size 
-matches the size of the corresponding memory block. This will only work with 
-<literal>g_mem_set_vtable (glib_mem_profiler_table)</literal> upon startup 
+If set to a size > 0, <link linkend="g-free">g_free</link>(),
+<link linkend="g-realloc">g_realloc</link>() and
+<link linkend="g-malloc">g_malloc</link>() will be intercepted if the size
+matches the size of the corresponding memory block. This will only work with
+<literal>g_mem_set_vtable (glib_mem_profiler_table)</literal> upon startup
 though, because memory profiling is required to match on the memory block sizes.
 </para>
 <para>
@@ -310,7 +309,7 @@ break g_malloc
 condition 1 n_bytes == 20
 </programlisting>
 to break only on g_malloc() calls where the size of the allocated memory block
-is 20. 
+is 20.
 </para>
 </refsect2>
 
@@ -366,13 +365,13 @@ are in your shared SystemTap scripts directory.
 
 <para>
 g_mem_profile() will output a summary g_malloc() memory usage, if memory
-profiling has been enabled by calling 
+profiling has been enabled by calling
 <literal>g_mem_set_vtable (glib_mem_profiler_table)</literal> upon startup.
 </para>
 
 <para>
 If GLib has been configured with <option>--enable-debug=yes</option>,
-then g_slice_debug_tree_statistics() can be called in a debugger to 
+then g_slice_debug_tree_statistics() can be called in a debugger to
 output details about the memory usage of the slice allocator.
 </para>
 

glib/gchecksum.c

@@ -35,7 +35,7 @@
 /**
  * SECTION:checksum
  * @title: Data Checksums
- * @short_description: Computes the checksum for data
+ * @short_description: computes the checksum for data
  *
  * GLib provides a generic API for computing checksums (or "digests")
  * for a sequence of arbitrary bytes, using various hashing algorithms

glib/gconvert.c

@@ -69,7 +69,7 @@
 /**
  * SECTION:conversions
  * @title: Character Set Conversion
- * @short_description: Convert strings between different character sets
+ * @short_description: convert strings between different character sets
  *
  * The g_convert() family of function wraps the functionality of iconv(). In
  * addition to pure character set conversions, GLib has functions to deal

glib/gdatetime.c

@@ -81,7 +81,7 @@
 /**
  * SECTION:date-time
  * @title: GDateTime
- * @short_description: A structure representing Date and Time
+ * @short_description: a structure representing Date and Time
  * @see_also: #GTimeZone
  *
  * #GDateTime is a structure that combines a Gregorian date and time

glib/ghmac.c

@@ -39,7 +39,7 @@
 /**
  * SECTION:hmac
  * @title: Secure HMAC Digests
- * @short_description: Computes the HMAC for data
+ * @short_description: computes the HMAC for data
  *
  * HMACs should be used when producing a cookie or hash based on data
  * and a key. Simple mechanisms for using SHA1 and other algorithms to

glib/glist.c

@@ -38,9 +38,7 @@
 /**
  * SECTION:linked_lists_double
  * @title: Doubly-Linked Lists
- * @short_description: linked lists containing integer values or
- *                     pointers to data, with the ability to iterate
- *                     over the list in both directions
+ * @short_description: linked lists that can be iterated over in both directions
  *
  * The #GList structure and its associated functions provide a standard
  * doubly-linked list data structure.

glib/gslist.c

@@ -38,9 +38,7 @@
 /**
  * SECTION:linked_lists_single
  * @title: Singly-Linked Lists
- * @short_description: linked lists containing integer values or
- *                     pointers to data, limited to iterating over the
- *                     list in one direction
+ * @short_description: linked lists that can be iterated in one direction
  *
  * The #GSList structure and its associated functions provide a
  * standard singly-linked list data structure.

glib/gtimezone.c

@@ -39,7 +39,7 @@
 /**
  * SECTION:timezone
  * @title: GTimeZone
- * @short_description: A structure representing a time zone
+ * @short_description: a structure representing a time zone
  * @see_also: #GDateTime
  *
  * #GTimeZone is a structure that represents a time zone, at no

glib/gurifuncs.c

@@ -35,9 +35,10 @@
 
 /**
  * SECTION:gurifuncs
- * @short_description: URI Functions
- * 
- * Functions for manipulating Universal Resource Identifiers (URIs) as 
+ * @title: URI Functions
+ * @short_description: manipulating URIs
+ *
+ * Functions for manipulating Universal Resource Identifiers (URIs) as
  * defined by <ulink url="http://www.ietf.org/rfc/rfc3986.txt">
  * RFC 3986</ulink>. It is highly recommended that you have read and
  * understand RFC 3986 for understanding this API.

glib/gversion.c

@@ -31,7 +31,7 @@
 /**
  * SECTION:version
  * @Title: Version Information
- * @Short_description: Variables and functions to check the GLib version
+ * @Short_description: variables and functions to check the GLib version
  *
  * GLib provides version information, primarily useful in configure
  * checks for builds that have a configure script. Applications will