Expand.

        * gdk/tmpl/general.sgml (gdk_set_program_class): Expand.

        * gtk/running.sgml: New file.

        * gtk/building.sgml: Document a few more configure options.

        * gtk/Makefile.am (content_files): Add running.sgml.

        * gtk/gtk-docs.sgml: Include running.sgml, sort H and V
        variants of widgets to be next to each other.

4 files changed, 461 insertions, 9 deletions

diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index 9d3240ab83..61d40133f7 100644
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -122,6 +122,7 @@ HTML_IMAGES = \
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE)
 content_files = 		\
+	running.sgml		\
 	building.sgml		\
 	changes-1.2.sgml	\
 	changes-2.0.sgml	\
diff --git a/docs/reference/gtk/building.sgml b/docs/reference/gtk/building.sgml
index 4f47b2c030..8cb24d6d49 100644
--- a/docs/reference/gtk/building.sgml
+++ b/docs/reference/gtk/building.sgml
@@ -60,11 +60,33 @@ How to compile GTK+ itself
 	    <arg>--with-included-loaders==LOADER1,LOADER2,...</arg>
 	  </group>
 	  <group>
+	    <arg>--enable-debug=[no|minimum|yes]</arg>
+	  </group>
+          <group>
+	    <arg>--disable-shm</arg>
+	    <arg>--enable-shm</arg>
+	  </group>
+          <group>
+	    <arg>--disable-xim</arg>
+	    <arg>--enable-xim</arg>
+	  </group>
+          <group>
+	    <arg>--disable-xim-inst</arg>
+	    <arg>--enable-xim-inst</arg>
+	  </group>
+          <group>
+	    <arg>--disable-xkb</arg>
+	    <arg>--enable-xkb</arg>
+	  </group>
+	  <group>
 	    <arg>--disable-gtk-doc</arg>
 	    <arg>--enable-gtk-doc</arg>
 	  </group>
+          <group>
+            <arg>--with-xinput=[no|gxi|xfree]</arg>
+          </group>
 	  <group>
-	    <arg>--with-gdktarget=[x11|linux-fb]</arg>
+	    <arg>--with-gdktarget=[x11|linux-fb|win32]</arg>
 	  </group>
 	  <group>
 	    <arg>--disable-shadowfb</arg>
@@ -102,6 +124,72 @@ How to compile GTK+ itself
       </formalpara>
 
       <formalpara>
+        <title><systemitem>--enable-debug</systemitem></title>
+          
+        <para>
+         Turns on various amounts of debugging support. Setting this to 'no' 
+	 disables g_assert(), g_return_if_fail(), g_return_val_if_fail() and
+         all cast checks between different object types. Setting it to 'minimum'
+         disables only cast checks. Setting it to 'yes' enables 
+         <link linkend="GTK-Debug-Options">runtime debugging</link>. 
+         The default is 'minimum'.
+         Note that 'no' is fast, but dangerous as it tends to destabilize 
+         even mostly bug-free software by changing the effect of many bugs 
+         from simple warnings into fatal crashes. Thus 
+         <option>--enable-debug=no</option> should <emphasis>not</emphasis> 
+         be used for stable releases of gtk+.
+        </para>
+      </formalpara>
+
+      <formalpara>
+        <title><systemitem>--disable-shm</systemitem> and
+          <systemitem>--enable-shm</systemitem></title>
+ 
+        <para>
+          These options can be used to control whether GTK+ will use shared 
+          memory to communicate with the X server when possible.
+          The default is yes.
+        </para>
+      </formalpara>
+
+      <formalpara>
+        <title><systemitem>--disable-xim</systemitem> and
+          <systemitem>--enable-xim</systemitem></title>
+ 
+        <para>
+          These options can be used to control whether GTK+ will 
+          be compiled with support for XIM. 
+          The default is yes.
+        </para>
+      </formalpara>
+
+      <formalpara>
+        <title><systemitem>--disable-xim-inst</systemitem> and
+          <systemitem>--enable-xim-inst</systemitem></title>
+ 
+        <para>
+          These options determine whether GTK+ will use the 
+	  XIM instantiate callback. 
+          The default is yes, unless the host system is Solaris,
+	  where <function>XRegisterIMInstantiateCallback</function>
+	  seems to cause a segfault.
+        </para>
+      </formalpara>
+
+      <formalpara>
+        <title><systemitem>--disable-xkb</systemitem> and
+          <systemitem>--enable-xkb</systemitem></title>
+ 
+        <para>
+	  By default the <command>configure</command> script will try
+	  to auto-detect whether the XKB extension is supported by
+          the X libraries GTK+ is linked with.
+          These options can be used to explicitly control whether
+	  GTK+ will support the XKB extension. 
+        </para>
+      </formalpara>
+
+      <formalpara>
 	<title><systemitem>--disable-gtk-doc</systemitem> and
 	  <systemitem>--enable-gtk-doc</systemitem></title>
 
@@ -120,11 +208,20 @@ How to compile GTK+ itself
       </formalpara>
 
       <formalpara>
+        <title><systemitem>--with-xinput</systemitem></title>
+
+        <para>
+          
+        </para>
+      </formalpara>
+
+      <formalpara>
 	<title><systemitem>--with-gdktarget</systemitem></title>
 
 	<para>
-          Toggles between the x11 and linux-fb backends for GDK. 
-          The default is x11.
+          Toggles between the supported backends for GDK. 
+          The default is x11, unless the platform is Windows, in which
+	  case the default is win32.
 	</para>
       </formalpara>
 
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index a0c4101508..4d02cae7b0 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -149,6 +149,7 @@
 <!entity gtk-TreeWidget SYSTEM "tree_widget.sgml">
 <!entity gtk-Compiling SYSTEM "compiling.sgml">
 <!entity gtk-Building SYSTEM "building.sgml">
+<!entity gtk-Running SYSTEM "running.sgml">
 <!entity gtk-Resources SYSTEM "resources.sgml">
 <!entity gtk-Windows SYSTEM "windows.sgml">
 <!entity gtk-Framebuffer SYSTEM "framebuffer.sgml">
@@ -245,6 +246,7 @@ that is, GUI components such as #GtkButton or #GtkTextView.
 
     &gtk-Building;
     &gtk-Compiling;
+    &gtk-Running;
     &gtk-Windows;
     &gtk-Framebuffer;
     &gtk-Changes-1-2;
@@ -318,8 +320,8 @@ that is, GUI components such as #GtkButton or #GtkTextView.
       <title>Numeric/Text Data Entry</title>
         &GtkEntry;
         &GtkHScale;      
-        &GtkSpinButton;
         &GtkVScale;
+        &GtkSpinButton;
     </sect1>
 
     <sect1 id="TextWidgetObjects">
@@ -383,15 +385,15 @@ that is, GUI components such as #GtkButton or #GtkTextView.
         &GtkAlignment;
         &GtkAspectFrame;
         &GtkHBox;
+        &GtkVBox;
         &GtkHButtonBox;
+        &GtkVButtonBox;
         &GtkFixed;
         &GtkHPaned;
+        &GtkVPaned;
         &GtkLayout;
         &GtkNotebook;
         &GtkTable;
-        &GtkVButtonBox;
-        &GtkVBox;
-        &GtkVPaned;
     </sect1>
 
     <sect1 id="Ornaments">
@@ -404,8 +406,8 @@ that is, GUI components such as #GtkButton or #GtkTextView.
     <sect1 id="ScrollingWidgets">
       <title>Scrolling</title>
         &GtkHScrollbar;
-        &GtkScrolledWindow;
         &GtkVScrollbar;
+        &GtkScrolledWindow;
     </sect1>
 
     <sect1 id="MiscObjects">
@@ -452,8 +454,8 @@ that is, GUI components such as #GtkButton or #GtkTextView.
       <title>Special-purpose features</title>
         &GtkCurve;
         &GtkGammaCurve;
-        &GtkHRuler;
         &GtkRuler;
+        &GtkHRuler;
         &GtkVRuler;
     </sect1>
 
diff --git a/docs/reference/gtk/running.sgml b/docs/reference/gtk/running.sgml
new file mode 100644
index 0000000000..5cdf669b59
--- /dev/null
+++ b/docs/reference/gtk/running.sgml
@@ -0,0 +1,352 @@
+<refentry id="gtk-running" revision="10 Jan 2002">
+<refmeta>
+<refentrytitle>Running GTK+ Applications</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>GTK Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Running GTK+ Applications</refname>
+<refpurpose>
+How to run and debug your GTK+ application
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>Running and debugging GTK+ Applications</title>
+
+<refsect2>
+<title>Common commandline options</title>
+
+<para>
+All GTK+ applications support a number of standard commandline
+options. These are removed from <literal>argv</literal> by 
+gtk_init(). Modules may parse and remove further options.
+</para>
+
+<formalpara>
+<title><systemitem>--gtk-module <replaceable>module</replaceable></systemitem></title>
+
+<para>
+A list of modules to load in addition to those specified in the 
+<envar>GTK_MODULES</envar> environment variable.
+</para>
+</formalpara>
+
+<formalpara>
+<title><systemitem>--g-fatal-warnings</systemitem></title>
+
+<para>
+Make GTK+ abort on all warnings.
+</para>
+</formalpara>
+
+<formalpara>
+<title><systemitem>--gtk-debug <replaceable>options</replaceable></systemitem></title>
+
+<para>
+A list of <link linkend="GTK-Debug-Options">debug options</link> 
+to turn on in addition to those specified in the <envar>GTK_DEBUG</envar> 
+environment variable. 
+This option is only available if GTK+ has been configured with
+<option>--enable-debug=yes</option>.
+</para>
+</formalpara>
+
+<formalpara>
+<title><systemitem>--gtk-no-debug <replaceable>options</replaceable></systemitem></title>
+
+<para>
+A list of <link linkend="GTK-Debug-Options">debug options</link> 
+to turn off.
+This option is only available if GTK+ has been configured with
+<option>--enable-debug=yes</option>.
+</para>
+</formalpara>
+
+<para>
+The following options are really used by GDK, not by GTK+, but we
+list them here for completeness nevertheless.
+</para>
+
+<formalpara>
+<title><systemitem>--class <replaceable>class</replaceable></systemitem></title>
+
+<para>
+Sets the program class; see gdk_set_program_class(). 
+</para>
+</formalpara>
+
+<formalpara>
+<title><systemitem>--name <replaceable>name</replaceable></systemitem></title>
+
+<para>
+Sets the program name.
+</para>
+</formalpara>
+
+<formalpara>
+<title><systemitem>--gdk-debug <replaceable>options</replaceable></systemitem></title>
+
+<para>
+A list of <link linkend="GDK-Debug-Options">debug options</link> 
+to turn on in addition to those 
+specified in the <envar>GDK_DEBUG</envar> environment variable. 
+This option is only available if GTK+ has been configured with
+<option>--enable-debug=yes</option>.
+</para>
+</formalpara>
+
+<formalpara>
+<title><systemitem>--gdk-no-debug <replaceable>options</replaceable></systemitem></title>
+
+<para>
+A list of <link linkend="GDK-Debug-Options">debug options</link> 
+to turn off.
+This option is only available if GTK+ has been configured with
+<option>--enable-debug=yes</option>.
+</para>
+</formalpara>
+
+<formalpara>
+<title><systemitem>--display <replaceable>display</replaceable></systemitem></title>
+
+<para>
+The name of the X display to open instead of the one specified
+in the <envar>DISPLAY</envar>. 
+This option is only available if GTK+ has been configured with
+<option>--gdk-target=x11</option>.
+</para>
+</formalpara>
+
+<formalpara>
+<title><systemitem>--sync</systemitem></title>
+
+<para>
+Makes all X requests synchronously. This is a useful option for 
+debugging, but it will slow down the performance considerably.
+This option is only available if GTK+ has been configured with
+<option>--gdk-target=x11</option>.
+</para>
+</formalpara>
+
+<formalpara>
+<title><systemitem>--gxid-host <replaceable>host</replaceable></systemitem></title>
+
+<para>
+The host to contact the <application>gxid</application> daemon on; overwrites 
+the <link linkend="GXID"><envar>GXID_HOST</envar></link> environment variable.
+This option is only available if GTK+ has been configured with
+<option>--gdk-target=x11</option>.
+</para>
+</formalpara>
+
+<formalpara>
+<title><systemitem>--gxid-port <replaceable>port</replaceable></systemitem></title>
+
+<para>
+The port for the connection to <application>gxid</application>; overwrites 
+the <link linkend="GXID"><envar>GXID_PORT</envar></link> environment variable.
+This option is only available if GTK+ has been configured with
+<option>--gdk-target=x11</option>.
+</para>
+</formalpara>
+
+</refsect2>
+
+<refsect2>
+<title>Environment variables</title>
+
+<para> 
+GTK+ inspects a number of environment variables in addition to standard
+variables like <envar>LANG</envar>, <envar>PATH</envar>, <envar>HOME</envar> 
+or <envar>DISPLAY</envar>; mostly to determine paths to look for certain files.
+</para>
+
+<formalpara id="GTK-Debug-Options">
+  <title><envar>GTK_DEBUG</envar></title>
+
+  <para>
+  If GTK+ has been configured with <option>--enable-debug=yes</option>,
+  this variable can be set to a list of debug options, which cause GTK+
+  to print out different types of debugging information.
+  <variablelist>
+    <varlistentry>
+      <term>misc</term>
+      <listitem><para>Miscellaneous information</para></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>text</term>
+      <listitem><para>Information about text widget internals</para></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>tree</term>
+      <listitem><para>Information about tree widget internals</para></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>updates</term>
+      <listitem><para>Visual feedback about window updates</para></listitem>
+    </varlistentry>
+  </variablelist>
+  The special value <term>all</term> can be used to turn on all debug options.
+  </para>
+</formalpara>
+
+<formalpara>
+  <title><envar>GTK_MODULES</envar></title>
+
+  <para>
+    A list of modules to load.
+  </para>
+</formalpara>
+
+<formalpara>
+  <title><envar>GTK_MODULE_PATH</envar></title>
+
+  <para>
+    A list of directories to search for modules before the default module 
+    directory, which is <filename>&lt;libdir&gt;/gtk-2.0/modules</filename>.
+    (If <envar>GTK_EXE_PREFIX</envar> is defined, &lt;libdir&gt; is 
+    <filename>$GTK_EXE_PREFIX/lib</filename>. Otherwise it is the libdir
+    specified when GTK+ was configured, usually 
+    <filename>/usr/local/lib</libdir>.) 
+    For each directory in the list, GTK+ actually looks first in 
+    a subdirectory named after the version number of GTK+, then in the 
+    directory itself and finally in the system-specific library path.
+  </para>
+</formalpara>
+
+<formalpara>
+  <title><envar>GTK_IM_MODULE</envar></title>
+
+  <para>
+    Specifies an IM module to use in preference to the one determined
+    from the locale. 
+  </para>
+</formalpara>
+
+<formalpara>
+  <title><envar>GTK_IM_MODULE_PATH</envar></title>
+
+  <para>
+    Specifies the path where GTK+ looks for IM modules. This environment 
+    variable overwrites the <literal>im_module_path</literal> specified in the 
+    RC files, which in turn overwrites the default
+    value <filename>$lt;libdir$gt;/gtk-2.0/immodules/&lt;version&gt;</filename>
+    (where &lt;version&gt; is the GTK+ version, and &lt;libdir&gt; is as 
+    explained above).
+  </para>
+</formalpara>
+ 
+<formalpara>
+  <title><envar>GTK_IM_MODULE_FILE</envar></title>
+
+  <para>
+    Specifies the file listing the IM modules to load. This environment
+    variable overwrites the <literal>im_module_file</literal> specified in 
+    the RC files, which in turn overwrites the default value 
+    <filename>&lt;sysconfdir&gt;/gtk-2.0/gtk.immodules</filename>
+    (&lt;sysconfdir&gt; is the sysconfdir specified when GTK+ was configured, 
+     usually <filename>/usr/local/etc</libdir>.)
+  </para>
+<formalpara>
+
+<formalpara>
+  <title><envar>GTK_RC_FILES</envar></title>
+  
+  <para>
+    Specifies a list of RC files to parse instead of the default ones;
+    see <link linkend="gtk-Resource-Files">Resource Files</link>.
+</formalpara>
+
+<formalpara>
+  <title><envar>GTK_EXE_PREFIX</envar></title>
+
+  <para>
+    If set, GTK+ uses <filename>$GTK_EXE_PREFIX/lib</filename> instead of 
+    the libdir configured when GTK+ was compiled.
+  </para>
+</formalpara>
+
+<formalpara>
+  <title><envar>GTK_DATA_PREFIX</envar></title>
+
+  <para>
+    If set, makes GTK+ use <filename>$GTK_DATA_PREFIX<filename>
+    instead of the prefix configured when GTK+ was compiled.
+  </para>
+</formalpara>
+
+<para>
+The following environment variables are used by GdkPixbuf, GDK or
+Pango, not by GTK+ itself, but we list them here for completeness
+nevertheless.
+</para>
+
+<formalpara>
+  <title><envar>GDK_PIXBUF_MODULEDIR</envar></title>
+
+  <para>
+    Specifies the directory to look for GdkPixbuf loader modules. 
+    By default, GdkPixbuf looks for its loaders in 
+    <filename>&lt;libdir&gt;/gtk-2.0/&lt;version&gt;/loaders</filename>.
+  </para>
+ </formalpara>
+
+<formalpara id="GDK-Debug-Options">
+  <title><envar>GDK_DEBUG</envar></title>
+
+  <para>
+  If GTK+ has been configured with <option>--enable-debug=yes</option>,
+  this variable can be set to a list of debug options, which cause GDK
+  to print out different types of debugging information.
+  <variablelist>
+    <varlistentry>
+      <term>misc</term>
+      <listitem><para>Miscellaneous information</para></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>events</term>
+      <listitem><para>Show all events received by GDK</para></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>dnd</term>
+      <listitem><para>Information about drag-and-drop</para></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>xim</term>
+      <listitem><para>Information about XIM support</para></listitem>
+    </varlistentry>
+  </variablelist>
+  The special value <term>all</term> can be used to turn on all debug options.
+  </para>
+</formalpara>
+
+<formalpara id="GXID">
+  <title><envar>GXID_HOST</envar> and <envar>GXID_PORT</envar></title>
+
+  <para>
+    The host and port to contact the <application>gxid</application> daemon on. 
+    <application>gxid</application> is only necessary on X servers which 
+    don't support using the pointer and extension devices at once, and is
+    only built if GTK+ is configured with <option>--with-xinput=gxi</option>. 
+    The <application>XFree86</application> X servers don't have this 
+    restriction.
+  </para>
+</formalpara>
+
+<formalpara>
+  <title><envar>GDK_USE_XFT</envar></title>
+
+  <para>
+    If this variable is set to 1, GTK+ will use the Pango Xft backend instead
+    of the X backend when possible (i.e. when the X server supports the XRender
+    extension and Pango has been built with Xft support). 
+  </para>
+</formalpara>
+
+</refsect2>
+
+</refsect1>
+
+</refentry>