Documentation tweaks

6 files changed, 56 insertions, 36 deletions

diff --git a/docs/reference/gtk/building.sgml b/docs/reference/gtk/building.sgml
index 70802e53c9..9e60e927be 100644
--- a/docs/reference/gtk/building.sgml
+++ b/docs/reference/gtk/building.sgml
@@ -172,7 +172,7 @@ How to compile GTK+ itself
           such as high level data types, Unicode manipulation, and
           an object and type system to C programs. It is available
           from the <ulink url="ftp://ftp.gtk.org/pub/glib/">GTK+
-          FTP site.</ulink>
+          FTP site</ulink>.
         </para>
       </listitem>
       <listitem>
@@ -180,7 +180,7 @@ How to compile GTK+ itself
           <ulink url="http://www.pango.org">Pango</ulink> is a library
           for internationalized text handling. It is available from
           the <ulink url="ftp://ftp.gtk.org/pub/pango/">GTK+ FTP
-          site.</ulink>.
+          site</ulink>.
         </para>
       </listitem>
       <listitem>
@@ -189,7 +189,7 @@ How to compile GTK+ itself
           interfaces allowing accessibility technologies such as
           screen readers to interact with a graphical user interface.
           It is available from the <ulink
-          url="ftp://ftp.gtk.org/pub/atk/">GTK+ FTP site.</ulink>
+          url="ftp://ftp.gtk.org/pub/atk/">GTK+ FTP site</ulink>.
         </para>
       </listitem>
       <listitem>
@@ -309,49 +309,60 @@ How to compile GTK+ itself
 
         <cmdsynopsis>
           <command>configure</command>
-
+          <sbr/>
           <group>
             <arg>--disable-modules</arg>
             <arg>--enable-modules</arg>
           </group>
+          <sbr/>
           <group>
             <arg>--with-included-immodules=MODULE1,MODULE2,...</arg>
           </group>
+          <sbr/>
           <group>
             <arg>--enable-debug=[no/minimum/yes]</arg>
           </group>
+          <sbr/>
           <group>
             <arg>--disable-Bsymbolic</arg>
             <arg>--enable-Bsymbolic</arg>
           </group>
+          <sbr/>
           <group>
             <arg>--disable-xkb</arg>
             <arg>--enable-xkb</arg>
           </group>
+          <sbr/>
           <group>
             <arg>--disable-xinerama</arg>
             <arg>--enable-xinerama</arg>
           </group>
+          <sbr/>
           <group>
             <arg>--disable-gtk-doc</arg>
             <arg>--enable-gtk-doc</arg>
           </group>
+          <sbr/>
           <group>
             <arg>--disable-cups</arg>
             <arg>--enable-cups</arg>
           </group>
+          <sbr/>
           <group>
             <arg>--disable-papi</arg>
             <arg>--enable-papi</arg>
           </group>
+          <sbr/>
           <group>
             <arg>--enable-xinput</arg>
             <arg>--disable-xinput</arg>
           </group>
+          <sbr/>
           <group>
             <arg>--enable-packagekit</arg>
             <arg>--disable-packagekit</arg>
           </group>
+          <sbr/>
           <group>
             <arg>--enable-x11-backend</arg>
             <arg>--disable-x11-backend</arg>
@@ -360,9 +371,11 @@ How to compile GTK+ itself
             <arg>--enable-quartz-backend</arg>
             <arg>--disable-quartz-backend</arg>
           </group>
+          <sbr/>
           <group>
             <arg>--enable-introspection=[no/auto/yes]</arg>
           </group>
+          <sbr/>
           <group>
             <arg>--enable-gtk2-dependency</arg>
             <arg>--disable-gtk2-dependency</arg>
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 0274da7a8f..2deabd9232 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -10,9 +10,13 @@
   <bookinfo>
     <title>GTK+ 3 Reference Manual</title>
     <releaseinfo>
-      This document is for GTK+ 3 library; the latest version can be found online at
-      <ulink role="online-location" url="http://library.gnome.org/devel/gtk/unstable/">http://library.gnome.org/devel/gtk/unstable/</ulink>.  
-      If you're looking for the older GTK+ 2 series of libraries, they can be found under their version numbers; for example, 2.22 is available at <ulink role="online-location" url="http://library.gnome.org/devel/gtk/2.22/">http://library.gnome.org/devel/gtk/2.22/</ulink>.
+      This document is for the GTK+ 3 library, version &version;.
+      The latest version can be found online at
+      <ulink role="online-location" url="http://library.gnome.org/devel/gtk/unstable/">http://library.gnome.org/devel/gtk/unstable/</ulink>.
+      If you are looking for the older GTK+ 2 series of libraries,
+      they can be found under their version numbers; for example,
+      2.22 is available at
+      <ulink role="online-location" url="http://library.gnome.org/devel/gtk/2.22/">http://library.gnome.org/devel/gtk/2.22/</ulink>.
     </releaseinfo>
   </bookinfo>
 
diff --git a/docs/reference/gtk/gtk-query-immodules-3.0.xml b/docs/reference/gtk/gtk-query-immodules-3.0.xml
index c9e541b6d2..97af84df11 100644
--- a/docs/reference/gtk/gtk-query-immodules-3.0.xml
+++ b/docs/reference/gtk/gtk-query-immodules-3.0.xml
@@ -5,13 +5,14 @@
 <refentry id="gtk-query-immodules-3.0">
 
 <refmeta>
-<refentrytitle>gtk-query-immodules-3.0</refentrytitle>
-<manvolnum>1</manvolnum>
+  <refentrytitle>gtk-query-immodules-3.0</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="manual">User Commands</refmiscinfo>
 </refmeta>
 
 <refnamediv>
-<refname>gtk-query-immodules-3.0</refname>
-<refpurpose>Input method module registration utility</refpurpose>
+  <refname>gtk-query-immodules-3.0</refname>
+  <refpurpose>Input method module registration utility</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
@@ -38,8 +39,8 @@ may be absolute or relative paths.
 </para>
 <para>
 Normally, the output of <command>gtk-query-immodules-3.0</command> is written
-to <filename><replaceable>libdir</replaceable>gtk-3.0/3.0.0/immodules.cache</filename>, where GTK+ looks for it by default. If it is written to some other
-location, the environment variable <link linkend="GTK_IM_MODULE_FILE"><envar>GTK_IM_MODULE_FILE</envar></link>
+to <filename><replaceable>libdir</replaceable>/gtk-3.0/3.0.0/immodules.cache</filename>, where GTK+ looks for it by default. If it is written to some other
+location, the environment variable <link linkend="gtk-im-module-file"><envar>GTK_IM_MODULE_FILE</envar></link>
 can be set to point GTK+ at the file.
 </para>
 </refsect1>
@@ -56,7 +57,7 @@ can be set to point GTK+ at the file.
 
 <refsect1><title>Environment</title>
 <para>
-The environment variable <link linkend="GTK_PATH"><envar>GTK_PATH</envar></link>
+The environment variable <link linkend="gtk-path"><envar>GTK_PATH</envar></link>
 can be used to prepend directories to the input method module path.
 </para>
 </refsect1>
diff --git a/docs/reference/gtk/gtk-update-icon-cache.xml b/docs/reference/gtk/gtk-update-icon-cache.xml
index 2a5bc27fbf..d6f3ac850f 100644
--- a/docs/reference/gtk/gtk-update-icon-cache.xml
+++ b/docs/reference/gtk/gtk-update-icon-cache.xml
@@ -5,13 +5,14 @@
 <refentry id="gtk-update-icon-cache">
 
 <refmeta>
-<refentrytitle>gtk-update-icon-cache</refentrytitle>
-<manvolnum>1</manvolnum>
+  <refentrytitle>gtk-update-icon-cache</refentrytitle>
+  <manvolnum>1</manvolnum>
+  <refmiscinfo class="manual">User Commands</refmiscinfo>
 </refmeta>
 
 <refnamediv>
-<refname>gtk-update-icon-cache</refname>
-<refpurpose>Icon theme caching utility</refpurpose>
+  <refname>gtk-update-icon-cache</refname>
+  <refpurpose>Icon theme caching utility</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
@@ -20,28 +21,29 @@
 <arg choice="opt">--force</arg>
 <arg choice="opt">--ignore-theme-index</arg>
 <arg choice="opt">--index-only</arg>
-<arg choice="opt">--source<arg>name</arg></arg>
+<arg choice="opt">--source <arg choice="plain"><replaceable>NAME</replaceable></arg></arg>
 <arg choice="opt">--quiet</arg>
 <arg choice="opt">--validate</arg>
-<arg choice="req">iconpath</arg>
+<arg choice="plain"><replaceable>PATH</replaceable></arg>
 </cmdsynopsis>
 </refsynopsisdiv>
 
 <refsect1><title>Description</title>
 <para>
-  <command>gtk-update-icon-cache</command> creates mmap()able cache
+  <command>gtk-update-icon-cache</command> creates mmapable cache
   files for icon themes.
 </para>
 <para>
-  It expects to be given the path to a icon theme directory containing an
-  <filename>index.theme</filename>, e.g. <filename>/usr/share/icons/hicolor</filename>,
-  and writes a <filename>icon-theme.cache</filename> containing cached
-  information about the icons in the directory tree below the given directory.
+  It expects to be given the <replaceable>PATH</replaceable> to a icon theme
+  directory containing an <filename>index.theme</filename>, e.g.
+  <filename>/usr/share/icons/hicolor</filename>, and writes a
+  <filename>icon-theme.cache</filename> containing cached information about
+  the icons in the directory tree below the given directory.
 </para>
 <para>
   GTK+ can use the cache files created by <command>gtk-update-icon-cache</command>
   to avoid a lot of system call and disk seek overhead when the application
-  starts. Since the format of the cache files allows them to be mmap()ed
+  starts. Since the format of the cache files allows them to be mmaped
   shared between multiple applications, the overall memory consumption is
   reduced as well.
 </para>
@@ -59,8 +61,8 @@
   <varlistentry>
     <term>--ignore-theme-index</term>
     <term>-t</term>
-    <listitem><para>Don't check for the existence of 'index.theme' in the icon
-     theme directory. Without this option, <command>gtk-update-icon-cache</command>
+    <listitem><para>Don't check for the existence of <filename>index.theme</filename>
+     in the icon theme directory. Without this option, <command>gtk-update-icon-cache</command>
      refuses to create an icon cache in a directory which does not appear to
      be the toplevel directory of an icon theme.
     </para></listitem>
@@ -77,7 +79,7 @@
     <term>--source</term>
     <term>-c</term>
     <listitem><para>Output a C header file declaring a constant
-     <replaceable>name</replaceable> with the contents of the icon
+     <replaceable>NAME</replaceable> with the contents of the icon
      cache.</para></listitem>
   </varlistentry>
 
diff --git a/docs/reference/gtk/question_index.sgml b/docs/reference/gtk/question_index.sgml
index b633a48f4d..24f6b99413 100644
--- a/docs/reference/gtk/question_index.sgml
+++ b/docs/reference/gtk/question_index.sgml
@@ -35,11 +35,11 @@ How do I get started with GTK+?
 </para></question>
 
 <answer><para>
-The GTK+ <ulink url="http://www.gtk.org">website</ulink> offers a
-<ulink url="http://www.gtk.org/tutorial">tutorial</ulink> and a
-<ulink url="http://www.gtk.org/faq">FAQ</ulink>. More documentation ranging
-from whitepapers to online books can be found at the
-<ulink url="http://library.gnome.org/devel/">GNOME developer's site</ulink>.
+The GTK+ <ulink url="http://www.gtk.org">website</ulink> offers some
+<ulink url="http://www.gtk.org/documentation">tutorials</ulink> and other
+documentation (most of it about GTK+ 2.x, but mostly still applicable).
+More documentation ranging from whitepapers to online books can be found at
+the <ulink url="http://library.gnome.org/devel/">GNOME developer's site</ulink>.
 After studying these materials you should be well prepared to come back to
 this reference manual for details.
 </para></answer>
diff --git a/docs/reference/gtk/running.sgml b/docs/reference/gtk/running.sgml
index b2b894601b..40a70d7ac0 100644
--- a/docs/reference/gtk/running.sgml
+++ b/docs/reference/gtk/running.sgml
@@ -205,7 +205,7 @@ additional environment variables.
   </warning>
 </formalpara>
 
-<formalpara>
+<formalpara id="gtk-path">
   <title><envar>GTK_PATH</envar></title>
 
   <para>
@@ -265,7 +265,7 @@ additional environment variables.
   </para>
 </formalpara>
 
-<formalpara id="im-module-file">
+<formalpara id="gtk-im-module-file">
   <title><envar>GTK_IM_MODULE_FILE</envar></title>
 
   <para>