[gtk+] Documentation polishing
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk+] Documentation polishing
- Date: Thu, 6 Jan 2011 06:14:18 +0000 (UTC)
commit 80a11b7483d70b72b882e4009649d8f3f892417e
Author: Matthias Clasen <mclasen redhat com>
Date: Thu Jan 6 01:11:49 2011 -0500
Documentation polishing
docs/reference/gtk/building.sgml | 113 +++++++++++++++++-------------------
docs/reference/gtk/compiling.sgml | 19 ------
gtk/gtkcellareacontext.c | 3 +-
gtk/gtkmain.c | 40 +++++++-------
gtk/gtkshow.c | 2 +-
5 files changed, 75 insertions(+), 102 deletions(-)
---
diff --git a/docs/reference/gtk/building.sgml b/docs/reference/gtk/building.sgml
index c02cf82..767ebac 100644
--- a/docs/reference/gtk/building.sgml
+++ b/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>
- script can be passed various command line arguments to determine how
- the package is built and installed. The most commonly useful
- argument is the <systemitem>--prefix</systemitem> argument which
+ makefiles customized for your operating system.
+ The <filename>configure</filename> script can be passed
+ various command line arguments to determine how the package
+ 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>
@@ -212,22 +213,6 @@ How to compile GTK+ itself
</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
Pango and GTK+. You should already have these installed on
your system, but it's possible that you'll need to install
@@ -246,12 +231,18 @@ 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>
is a framework for making introspection data available to
language bindings.
@@ -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
- by running the <command>gtk-demo</command> program that
+ applications</link>. You can test your GTK+ installation
+ 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
- demand. The <systemitem>--disable-modules</systemitem>
- argument indicates that they should all be built statically
- into the GTK+ library instead. This is useful for
- people who need to produce statically-linked binaries. If
- neither <systemitem>--disable-modules</systemitem> nor
- <systemitem>--enable-modules</systemitem> is specified, then
- the <command>configure</command> script will try to
+ as little shared libraries that are loaded on demand.
+ The <systemitem>--disable-modules</systemitem> argument
+ indicates that they should all be built statically
+ into the GTK+ library instead. This is useful for
+ people who need to produce statically-linked binaries.
+ If neither <systemitem>--disable-modules</systemitem> nor
+ <systemitem>--enable-modules</systemitem> is specified,
+ 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'
- 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
+ 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
@@ -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>
@@ -480,6 +473,21 @@ How to compile GTK+ itself
</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>
@@ -523,21 +531,6 @@ How to compile GTK+ itself
</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>
<para>
@@ -551,10 +544,10 @@ How to compile GTK+ itself
<formalpara>
<title><systemitem>--enable-x11-backend</systemitem>,
- <systemitem>--disable-x11-backend</systemitem>,
- <systemitem>--enable-win32-backend</systemitem>,
- <systemitem>--disable-win32-backend</systemitem>,
- <systemitem>--enable-quartz-backend</systemitem>,
+ <systemitem>--disable-x11-backend</systemitem>,
+ <systemitem>--enable-win32-backend</systemitem>,
+ <systemitem>--disable-win32-backend</systemitem>,
+ <systemitem>--enable-quartz-backend</systemitem>,
and <systemitem>--disable-quartz-backend</systemitem></title>
<para>
diff --git a/docs/reference/gtk/compiling.sgml b/docs/reference/gtk/compiling.sgml
index 1914b0e..1463765 100644
--- a/docs/reference/gtk/compiling.sgml
+++ b/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>
diff --git a/gtk/gtkcellareacontext.c b/gtk/gtkcellareacontext.c
index d2249d9..ca1ac3a 100644
--- a/gtk/gtkcellareacontext.c
+++ b/gtk/gtkcellareacontext.c
@@ -23,8 +23,7 @@
/**
* SECTION:gtkcellareacontext
- * @Short_Description: An object for a GtkCellArea to store geometrical
- * information for a series of rows.
+ * @Short_Description: Stores geometrical information for a series of rows in a GtkCellArea
* @Title: GtkCellAreaContext
*
* The #GtkCellAreaContext object is created by a given #GtkCellArea
diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c
index 38d2156..06ec9f3 100644
--- a/gtk/gtkmain.c
+++ b/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 @@
* /* The user lost interest */
* 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[
- * /* computation going on */
- * ...
+ * <programlisting>
+ * /* computation going on... */
+ *
* while (gtk_events_pending ())
* gtk_main_iteration ();
- * ...
- * /* computation continued */
- * ]]></programlisting>
+ *
+ * /* ...computation continued */
+ * </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[
- * #include <gtk/gtk.h>
+ * <programlisting>
+ * #include <gtk/gtk.h><
*
* int
* main (int argc, char **argv)
@@ -1934,7 +1934,7 @@ gtk_main_do_event (GdkEvent *event)
*
* return 0;
* }
- * ]]></programlisting>
+ * </programlisting>
* </example>
*
* Returns: %TRUE
diff --git a/gtk/gtkshow.c b/gtk/gtkshow.c
index 3b24c7b..ac3d1ac 100644
--- a/gtk/gtkshow.c
+++ b/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
*/
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
