From 80a11b7483d70b72b882e4009649d8f3f892417e Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 6 Jan 2011 01:11:49 -0500 Subject: [PATCH] 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 c02cf82f61..767ebacd68 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. @@ -45,7 +45,7 @@ How to compile GTK+ itself 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 - 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 configure which you then run to take the template makefiles called Makefile.in in the package and create - makefiles customized for your operating system. The configure - script can be passed various command line arguments to determine how - the package is built and installed. The most commonly useful - argument is the --prefix argument which + makefiles customized for your operating system. + The configure script can be passed + various command line arguments to determine how the package + is built and installed. The most commonly useful argument is + the --prefix argument which determines where the package is installed. To install a package in /opt/gtk you would run configure as: @@ -210,22 +211,6 @@ How to compile GTK+ itself message translation databases. - - - The JPEG, - PNG, and - TIFF 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 - dependencies directory on the the - GTK+ - FTP site.. (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.) - - The libraries from the X window system are needed to build @@ -246,10 +231,16 @@ How to compile GTK+ itself Cairo 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. + + + The GdkPixbuf library provides facilities for loading + images in a variety of file formats. + + gobject-introspection @@ -289,8 +280,8 @@ How to compile GTK+ itself make install mentioned above. If you're lucky, this will all go smoothly, and you'll be ready to start compiling your own GTK+ - applications. You can test your GTK+ installation - by running the gtk-demo program that + applications. You can test your GTK+ installation + by running the gtk3-demo program that GTK+ installs. @@ -360,8 +351,8 @@ How to compile GTK+ itself --enable-packagekit --disable-packagekit - - + + --enable-x11-backend --disable-x11-backend --enable-win32-backend @@ -381,14 +372,14 @@ How to compile GTK+ itself Normally GTK+ will try to build the input method modules - as little shared libraries that are loaded on - demand. The --disable-modules - 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 --disable-modules nor - --enable-modules is specified, then - the configure script will try to + as little shared libraries that are loaded on demand. + The --disable-modules 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 --disable-modules nor + --enable-modules is specified, + then the configure script will try to auto-detect whether shared modules work on your system. @@ -398,7 +389,8 @@ How to compile GTK+ itself 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. @@ -406,10 +398,9 @@ How to compile GTK+ itself <systemitem>--enable-debug</systemitem> - 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 runtime debugging. 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 The option --disable-Bsymbolic turns off the use of the -Bsymbolic-functions linker flag. + This is only necessary if you want to override GTK+ functions + by using LD_PRELOAD. @@ -479,6 +472,21 @@ How to compile GTK+ itself + + <systemitem>--disable-xinput</systemitem> and + <systemitem>--enable-xinput</systemitem> + + 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. + + + <systemitem>--disable-gtk-doc</systemitem> and <systemitem>--enable-gtk-doc</systemitem> @@ -522,21 +530,6 @@ How to compile GTK+ itself - - <systemitem>--disable-xinput</systemitem> and - <systemitem>--enable-xinput</systemitem> - - 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. - - - <systemitem>--disable-packagekit</systemitem> and <systemitem>--enable-packagekit</systemitem> @@ -551,10 +544,10 @@ How to compile GTK+ itself <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> diff --git a/docs/reference/gtk/compiling.sgml b/docs/reference/gtk/compiling.sgml index 1914b0ee2d..146376545a 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 -DGTK_MULTIDEVICE_SAFE=1. - -The recommended way of using GTK+ has always been to only include the -toplevel headers gtk.h, gdk.h, -gdk-pixbuf.h. -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: gdkkeysyms.h is not included in -gdk.h because the file is quite large; see -Key Values documentation. -gdkx.h must be included independently because It's -platform-specific; see -X Window System Interaction -documentation. -The same for gtkunixprint.h if you use the non-portable -GtkPrintUnixDialog API. - - diff --git a/gtk/gtkcellareacontext.c b/gtk/gtkcellareacontext.c index d2249d9219..ca1ac3a0d8 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 38d2156a6b..06ec9f3d7a 100644 --- a/gtk/gtkmain.c +++ b/gtk/gtkmain.c @@ -57,7 +57,7 @@ * * * Typical <function>main()</function> function for a GTK+ application - * * int * main (int argc, char **argv) * { @@ -82,7 +82,7 @@ * /* The user lost interest */ * return 0; * } - * ]]> + * * * * 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 libtool 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 libtool 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) * * * Updating the UI during a long computation - * + * /* computation going on... */ + * * while (gtk_events_pending ()) * gtk_main_iteration (); - * ... - * /* computation continued */ - * ]]> + * + * /* ...computation continued */ + * * * * Returns: %TRUE if any events are pending, %FALSE otherwise @@ -1907,8 +1907,8 @@ gtk_main_do_event (GdkEvent *event) * * * A persistent window - * + * + * #include <gtk/gtk.h>< * * int * main (int argc, char **argv) @@ -1934,7 +1934,7 @@ gtk_main_do_event (GdkEvent *event) * * return 0; * } - * ]]> + * * * * Returns: %TRUE diff --git a/gtk/gtkshow.c b/gtk/gtkshow.c index 3b24c7b3a6..ac3d1ac974 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 */