Documentation polishing

docs/reference/gtk/building.sgml

@@ -30,7 +30,7 @@ How to compile GTK+ itself
       your operating system will be available, either from your
       operating system vendor or from independent sources. If such a
       set of packages is available, installing it will get you
-      programming wih GTK+ much faster than building it yourself. In
+      programming with GTK+ much faster than building it yourself. In
       fact, you may well already have GTK+ installed on your system
       already.
     </para>
@@ -45,7 +45,7 @@ How to compile GTK+ itself
     </para>
     <para>
       If you are building GTK+ from the distributed source packages,
-      then won't need these tools installed; the necessary pieces
+      then you won't need these tools installed; the necessary pieces
       of the tools are already included in the source packages. But
       it's useful to know a bit about how packages that use these
       tools work. A source package is distributed as a
@@ -57,14 +57,15 @@ How to compile GTK+ itself
       tar xvfj gtk+-3.0.0.tar.bz2
     </programlisting>
     <para>
-      In the toplevel of the directory that is created, there will be
+      In the toplevel directory that is created, there will be
       a shell script called <filename>configure</filename> which
       you then run to take the template makefiles called
       <filename>Makefile.in</filename> in the package and create
-      makefiles customized for your operating system. The <filename>configure</filename>
+      makefiles customized for your operating system.
-      script can be passed various command line arguments to determine how
+      The <filename>configure</filename> script can be passed
-      the package is built and installed. The most commonly useful
+      various command line arguments to determine how the package
-      argument is the <systemitem>--prefix</systemitem> argument which
+      is built and installed. The most commonly useful argument is
+      the <systemitem>--prefix</systemitem> argument which
       determines where the package is installed. To install a package
       in <filename>/opt/gtk</filename> you would run configure as:
     </para>
@@ -210,22 +211,6 @@ How to compile GTK+ itself
           message translation databases.
         </para>
       </listitem>
-      <listitem>
-        <para>
-          The <ulink url="http://en.wikipedia.org/wiki/Libjpeg">JPEG</ulink>,
-          <ulink url="http://www.libpng.org">PNG</ulink>, and
-          <ulink url="http://www.libtiff.org">TIFF</ulink> image
-          loading libraries are needed to compile GTK+. You probably
-          already have these libraries installed, but if not, the
-          versions you need are available in the
-           <filename>dependencies</filename> directory on the the
-          <ulink url="ftp://ftp.gtk.org/pub/gtk/v2.10/dependencies/">GTK+
-            FTP site.</ulink>. (Before installing these libraries
-          from source, you should check if your operating system
-          vendor has prebuilt packages of these libraries that you
-          don't have installed.)
-        </para>
-      </listitem>
       <listitem>
         <para>
           The libraries from the X window system are needed to build
@@ -246,10 +231,16 @@ How to compile GTK+ itself
         <para>
           <ulink url="http://www.cairographics.org">Cairo</ulink>
           is a graphics library that supports vector graphics and image
-          compositing. Both Pango and GTK+ use cairo for much of their
+          compositing. Both Pango and GTK+ use cairo for all of their
           drawing.
         </para>
       </listitem>
+      <listitem>
+        <para>
+          The GdkPixbuf library provides facilities for loading
+          images in a variety of file formats.
+        </para>
+      </listitem>
       <listitem>
         <para>
           <ulink url="http://live.gnome.org/GObjectIntrospection">gobject-introspection</ulink>
@@ -289,8 +280,8 @@ How to compile GTK+ itself
       <literal>make install</literal> mentioned above. If you're
       lucky, this will all go smoothly, and you'll be ready to
       <link linkend="gtk-compiling">start compiling your own GTK+
-        applications</link>. You can test your GTK+ installation
+      applications</link>. You can test your GTK+ installation
-      by running the <command>gtk-demo</command> program that
+      by running the <command>gtk3-demo</command> program that
       GTK+ installs.
     </para>
     <para>
@@ -360,8 +351,8 @@ How to compile GTK+ itself
           <group>
             <arg>--enable-packagekit</arg>
             <arg>--disable-packagekit</arg>
-	  </group>
+          </group>
-	  <group>
+          <group>
             <arg>--enable-x11-backend</arg>
             <arg>--disable-x11-backend</arg>
             <arg>--enable-win32-backend</arg>
@@ -381,14 +372,14 @@ How to compile GTK+ itself
 
         <para>
           Normally GTK+ will try to build the input method modules
-          as little shared libraries that are loaded on
+          as little shared libraries that are loaded on demand.
-          demand.  The <systemitem>--disable-modules</systemitem>
+          The <systemitem>--disable-modules</systemitem> argument
-          argument indicates that they should all be built statically
+          indicates that they should all be built statically
-          into the GTK+ library instead.  This is useful for
+          into the GTK+ library instead. This is useful for
-          people who need to produce statically-linked binaries.  If
+          people who need to produce statically-linked binaries.
-          neither <systemitem>--disable-modules</systemitem> nor
+          If neither <systemitem>--disable-modules</systemitem> nor
-          <systemitem>--enable-modules</systemitem> is specified, then
+          <systemitem>--enable-modules</systemitem> is specified,
-          the <command>configure</command> script will try to
+          then the <command>configure</command> script will try to
           auto-detect whether shared modules work on your system.
         </para>
       </formalpara>
@@ -398,7 +389,8 @@ How to compile GTK+ itself
 
         <para>
          This option allows you to specify which input method modules you
-         want to include.
+         want to include directly into the GTK+ shared library, as opposed
+         to building them as loadable modules.
         </para>
       </formalpara>
 
@@ -406,10 +398,9 @@ How to compile GTK+ itself
         <title><systemitem>--enable-debug</systemitem></title>
 
         <para>
-         Turns on various amounts of debugging support. Setting this to 'no'
+         Turns on various amounts of debugging support. Setting this to
-         disables g_assert(), g_return_if_fail(), g_return_val_if_fail() and
+         'no' disables g_assert(), g_return_if_fail(), g_return_val_if_fail()           and all cast checks between different object types. Setting it
-         all cast checks between different object types. Setting it to 'minimum'
+         to 'minimum' disables only cast checks. Setting it to 'yes' enables
-         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
@@ -426,6 +417,8 @@ How to compile GTK+ itself
         <para>
           The option <systemitem>--disable-Bsymbolic</systemitem>
           turns off the use of the -Bsymbolic-functions linker flag.
+          This is only necessary if you want to override GTK+ functions
+          by using <envar>LD_PRELOAD</envar>.
         </para>
       </formalpara>
 
@@ -479,6 +472,21 @@ How to compile GTK+ itself
         </para>
       </formalpara>
 
+      <formalpara>
+        <title><systemitem>--disable-xinput</systemitem> and
+           <systemitem>--enable-xinput</systemitem></title>
+        <para>
+          Controls whether GTK+ is built with support for the XInput
+          or XInput2 extension. These extensions provide an extended
+          interface to input devices such as graphics tablets.
+          When this support is compiled in, specially written
+          GTK+ programs can get access to subpixel positions,
+          multiple simultaneous input devices, and extra "axes"
+          provided by the device such as pressure and tilt
+          information.
+        </para>
+      </formalpara>
+
       <formalpara>
         <title><systemitem>--disable-gtk-doc</systemitem> and
           <systemitem>--enable-gtk-doc</systemitem></title>
@@ -522,21 +530,6 @@ How to compile GTK+ itself
         </para>
       </formalpara>
 
-      <formalpara>
-        <title><systemitem>--disable-xinput</systemitem> and
-           <systemitem>--enable-xinput</systemitem></title>
-        <para>
-          Controls whether GTK+ is built with support for the XInput
-          or XInput2 extension. These extensions provide an extended
-          interface to input devices such as graphics tablets.
-          When this support is compiled in, specially written
-          GTK+ programs can get access to subpixel positions,
-          multiple simultaneous input devices, and extra "axes"
-          provided by the device such as pressure and tilt
-          information.
-        </para>
-      </formalpara>
-
       <formalpara>
         <title><systemitem>--disable-packagekit</systemitem> and
            <systemitem>--enable-packagekit</systemitem></title>
@@ -551,10 +544,10 @@ How to compile GTK+ itself
 
       <formalpara>
         <title><systemitem>--enable-x11-backend</systemitem>,
-	  <systemitem>--disable-x11-backend</systemitem>,
+          <systemitem>--disable-x11-backend</systemitem>,
-	  <systemitem>--enable-win32-backend</systemitem>,
+          <systemitem>--enable-win32-backend</systemitem>,
-	  <systemitem>--disable-win32-backend</systemitem>,
+          <systemitem>--disable-win32-backend</systemitem>,
-	  <systemitem>--enable-quartz-backend</systemitem>,
+          <systemitem>--enable-quartz-backend</systemitem>,
           and <systemitem>--disable-quartz-backend</systemitem></title>
 
         <para>

docs/reference/gtk/compiling.sgml

@@ -69,24 +69,5 @@ define the preprocessor symbol GDK_MULTIDEVICE_SAFE by using the command
 line option <literal>-DGTK_MULTIDEVICE_SAFE=1</literal>.
 </para>
 
-<para>
-The recommended way of using GTK+ has always been to only include the
-toplevel headers <filename>gtk.h</filename>, <filename>gdk.h</filename>,
-<filename>gdk-pixbuf.h</filename>.
-If you want to make sure that your program follows this recommended
-practise, you can define the preprocessor symbols GTK_DISABLE_SINGLE_INCLUDES
-and GDK_PIXBUF_DISABLE_SINGLE_INCLUDES to make GTK+ generate an error
-when individual headers are directly included.
-There are some exceptions: <filename>gdkkeysyms.h</filename> is not included in
-<filename>gdk.h</filename> because the file is quite large; see
-<link linkend="gdk-Keyboard-Handling">Key Values documentation</link>.
-<filename>gdkx.h</filename> must be included independently because It's
-platform-specific; see
-<link linkend="gdk-X-Window-System-Interaction">X Window System Interaction</link>
-documentation.
-The same for <filename>gtkunixprint.h</filename> if you use the non-portable
-<link linkend="GtkPrintUnixDialog">GtkPrintUnixDialog</link> API.
-</para>
-
 </refsect1>
 </refentry>

gtk/gtkcellareacontext.c

@@ -23,8 +23,7 @@
 
 /**
  * SECTION:gtkcellareacontext
- * @Short_Description: An object for a GtkCellArea to store geometrical
+ * @Short_Description: Stores geometrical information for a series of rows in a GtkCellArea
- *     information for a series of rows.
  * @Title: GtkCellAreaContext
  *
  * The #GtkCellAreaContext object is created by a given #GtkCellArea

gtk/gtkmain.c

@@ -57,7 +57,7 @@
  * </para>
  * <example>
  * <title>Typical <function>main()</function> function for a GTK+ application</title>
- * <programlisting><![CDATA[
+ * <programlisting>
  * int
  * main (int argc, char **argv)
  * {
@@ -82,7 +82,7 @@
  *   /&ast; The user lost interest &ast;/
  *   return 0;
  * }
- * ]]></programlisting>
+ * </programlisting>
  * </example>
  * <para>
  * It's OK to use the GLib main loop directly instead of gtk_main(), though it
@@ -262,7 +262,7 @@ static const GDebugKey gtk_debug_keys[] = {
  * macro, which represents the major version of the GTK+ headers you
  * have included when compiling your code.
  *
- * Returns: the major version number of the GTK+ library.
+ * Returns: the major version number of the GTK+ library
  *
  * Since: 3.0
  */
@@ -283,7 +283,7 @@ gtk_get_major_version (void)
  * #GTK_MINOR_VERSION macro, which represents the minor version of the
  * GTK+ headers you have included when compiling your code.
  *
- * Returns: the minor version number of the GTK+ library.
+ * Returns: the minor version number of the GTK+ library
  *
  * Since: 3.0
  */
@@ -304,7 +304,7 @@ gtk_get_minor_version (void)
  * #GTK_MICRO_VERSION macro, which represents the micro version of the
  * GTK+ headers you have included when compiling your code.
  *
- * Returns: the micro version number of the GTK+ library.
+ * Returns: the micro version number of the GTK+ library
  *
  * Since: 3.0
  */
@@ -322,7 +322,7 @@ gtk_get_micro_version (void)
  * If <application>libtool</application> means nothing to you, don't
  * worry about it.
  *
- * Returns: the binary age of the GTK+ library.
+ * Returns: the binary age of the GTK+ library
  *
  * Since: 3.0
  */
@@ -340,7 +340,7 @@ gtk_get_binary_age (void)
  * If <application>libtool</application> means nothing to you, don't
  * worry about it.
  *
- * Returns: the interface age of the GTK+ library.
+ * Returns: the interface age of the GTK+ library
  *
  * Since: 3.0
  */
@@ -393,13 +393,13 @@ gtk_check_version (guint required_major,
   gint required_effective_micro = 100 * required_minor + required_micro;
 
   if (required_major > GTK_MAJOR_VERSION)
-    return "Gtk+ version too old (major mismatch)";
+    return "GTK+ version too old (major mismatch)";
   if (required_major < GTK_MAJOR_VERSION)
-    return "Gtk+ version too new (major mismatch)";
+    return "GTK+ version too new (major mismatch)";
   if (required_effective_micro < gtk_effective_micro - GTK_BINARY_AGE)
-    return "Gtk+ version too new (micro mismatch)";
+    return "GTK+ version too new (micro mismatch)";
   if (required_effective_micro > gtk_effective_micro)
-    return "Gtk+ version too old (micro mismatch)";
+    return "GTK+ version too old (micro mismatch)";
   return NULL;
 }
 
@@ -1385,14 +1385,14 @@ gtk_main_quit (void)
  *
  * <example>
  * <title>Updating the UI during a long computation</title>
- * <programlisting><![CDATA[
+ * <programlisting>
- *  /&ast; computation going on &ast;/
+ *  /&ast; computation going on... &ast;/
- *  ...
+ *
  *  while (gtk_events_pending ())
  *    gtk_main_iteration ();
- *  ...
+ *
- *  /&ast; computation continued &ast;/
+ *  /&ast; ...computation continued &ast;/
- * ]]></programlisting>
+ * </programlisting>
  * </example>
  *
  * Returns: %TRUE if any events are pending, %FALSE otherwise
@@ -1907,8 +1907,8 @@ gtk_main_do_event (GdkEvent *event)
  *
  * <example>
  * <title>A persistent window</title>
- * <programlisting><![CDATA[
+ * <programlisting>
- * #include <gtk/gtk.h>
+ * #include &lt;gtk/gtk.h>&lt;
  *
  * int
  * main (int argc, char **argv)
@@ -1934,7 +1934,7 @@ gtk_main_do_event (GdkEvent *event)
  *
  *   return 0;
  * }
- * ]]></programlisting>
+ * </programlisting>
  * </example>
  *
  * Returns: %TRUE

gtk/gtkshow.c

@@ -51,7 +51,7 @@
  * This function can be used as a replacement for gnome_vfs_url_show()
  * and gnome_url_show().
  *
- * Returns: %TRUE on success, %FALSE on error.
+ * Returns: %TRUE on success, %FALSE on error
  *
  * Since: 2.14
  */