link to new X11 section in a lot of places when mentioning the window

2002-01-19  Havoc Pennington  <hp@pobox.com>

	* gtk/gtkwindow.c: link to new X11 section in a lot of places when
	mentioning the window manager.

	* gtk/gtkwidget.c (gtk_widget_hide_on_delete): don't mention
	window manager since we're portable.

2002-01-19  Havoc Pennington  <hp@pobox.com>

	* gtk/x11.sgml: add a mostly-empty X11 section

	* gtk/framebuffer.sgml: make title consistent with windows section

	* gtk/tmpl/gtkdrawingarea.sgml: couple of fixes

ChangeLog

@@ -1,3 +1,11 @@
+2002-01-19  Havoc Pennington  <hp@pobox.com>
+
+	* gtk/gtkwindow.c: link to new X11 section in a lot of places when
+	mentioning the window manager.
+
+	* gtk/gtkwidget.c (gtk_widget_hide_on_delete): don't mention
+	window manager since we're portable.
+
 Sat Jan 19 08:47:41 2002  Jeff Garzik  <jgarzik@mandrakesoft.com>
 
 	* gdk/linux-fb/gdkproperty-fb.c (gdk_atom_name):

ChangeLog.pre-2-0

@@ -1,3 +1,11 @@
+2002-01-19  Havoc Pennington  <hp@pobox.com>
+
+	* gtk/gtkwindow.c: link to new X11 section in a lot of places when
+	mentioning the window manager.
+
+	* gtk/gtkwidget.c (gtk_widget_hide_on_delete): don't mention
+	window manager since we're portable.
+
 Sat Jan 19 08:47:41 2002  Jeff Garzik  <jgarzik@mandrakesoft.com>
 
 	* gdk/linux-fb/gdkproperty-fb.c (gdk_atom_name):

ChangeLog.pre-2-10

@@ -1,3 +1,11 @@
+2002-01-19  Havoc Pennington  <hp@pobox.com>
+
+	* gtk/gtkwindow.c: link to new X11 section in a lot of places when
+	mentioning the window manager.
+
+	* gtk/gtkwidget.c (gtk_widget_hide_on_delete): don't mention
+	window manager since we're portable.
+
 Sat Jan 19 08:47:41 2002  Jeff Garzik  <jgarzik@mandrakesoft.com>
 
 	* gdk/linux-fb/gdkproperty-fb.c (gdk_atom_name):

ChangeLog.pre-2-2

@@ -1,3 +1,11 @@
+2002-01-19  Havoc Pennington  <hp@pobox.com>
+
+	* gtk/gtkwindow.c: link to new X11 section in a lot of places when
+	mentioning the window manager.
+
+	* gtk/gtkwidget.c (gtk_widget_hide_on_delete): don't mention
+	window manager since we're portable.
+
 Sat Jan 19 08:47:41 2002  Jeff Garzik  <jgarzik@mandrakesoft.com>
 
 	* gdk/linux-fb/gdkproperty-fb.c (gdk_atom_name):

ChangeLog.pre-2-4

@@ -1,3 +1,11 @@
+2002-01-19  Havoc Pennington  <hp@pobox.com>
+
+	* gtk/gtkwindow.c: link to new X11 section in a lot of places when
+	mentioning the window manager.
+
+	* gtk/gtkwidget.c (gtk_widget_hide_on_delete): don't mention
+	window manager since we're portable.
+
 Sat Jan 19 08:47:41 2002  Jeff Garzik  <jgarzik@mandrakesoft.com>
 
 	* gdk/linux-fb/gdkproperty-fb.c (gdk_atom_name):

ChangeLog.pre-2-6

@@ -1,3 +1,11 @@
+2002-01-19  Havoc Pennington  <hp@pobox.com>
+
+	* gtk/gtkwindow.c: link to new X11 section in a lot of places when
+	mentioning the window manager.
+
+	* gtk/gtkwidget.c (gtk_widget_hide_on_delete): don't mention
+	window manager since we're portable.
+
 Sat Jan 19 08:47:41 2002  Jeff Garzik  <jgarzik@mandrakesoft.com>
 
 	* gdk/linux-fb/gdkproperty-fb.c (gdk_atom_name):

ChangeLog.pre-2-8

@@ -1,3 +1,11 @@
+2002-01-19  Havoc Pennington  <hp@pobox.com>
+
+	* gtk/gtkwindow.c: link to new X11 section in a lot of places when
+	mentioning the window manager.
+
+	* gtk/gtkwidget.c (gtk_widget_hide_on_delete): don't mention
+	window manager since we're portable.
+
 Sat Jan 19 08:47:41 2002  Jeff Garzik  <jgarzik@mandrakesoft.com>
 
 	* gdk/linux-fb/gdkproperty-fb.c (gdk_atom_name):

docs/reference/ChangeLog

@@ -1,3 +1,11 @@
+2002-01-19  Havoc Pennington  <hp@pobox.com>
+
+	* gtk/x11.sgml: add a mostly-empty X11 section
+
+	* gtk/framebuffer.sgml: make title consistent with windows section
+
+	* gtk/tmpl/gtkdrawingarea.sgml: couple of fixes
+
 2002-01-17  Matthias Clasen  <matthiasc@poet.de>
 
 	* gtk/resources.sgml: Tiny markup fix.

docs/reference/gtk/framebuffer.sgml

@@ -1,6 +1,6 @@
 <refentry id="gtk-framebuffer" revision="1 Jan 2002">
 <refmeta>
-<refentrytitle>Framebuffer</refentrytitle>
+<refentrytitle>Using GTK+ on the Framebuffer</refentrytitle>
 <manvolnum>3</manvolnum>
 <refmiscinfo>GTK Library</refmiscinfo>
 </refmeta>
@@ -8,7 +8,7 @@
 <refnamediv>
 <refname>Using GTK+ on the Framebuffer</refname>
 <refpurpose>
-Using embedded GTK+ on the Linux framebuffer
+Linux framebuffer aspects of using GTK+
 </refpurpose>
 </refnamediv>
 

docs/reference/gtk/gtk-docs.sgml

@@ -153,6 +153,7 @@
 <!entity gtk-Resources SYSTEM "resources.sgml">
 <!entity gtk-Windows SYSTEM "windows.sgml">
 <!entity gtk-Framebuffer SYSTEM "framebuffer.sgml">
+<!entity gtk-X11 SYSTEM "x11.sgml">
 <!entity gtk-Questions SYSTEM "question_index.sgml">
 <!entity gtk-Changes-1-2 SYSTEM "changes-1.2.sgml">
 <!entity gtk-Changes-2-0 SYSTEM "changes-2.0.sgml">
@@ -249,6 +250,7 @@ that is, GUI components such as #GtkButton or #GtkTextView.
     &gtk-Running;
     &gtk-Windows;
     &gtk-Framebuffer;
+    &gtk-X11;
     &gtk-Changes-1-2;
     &gtk-Changes-2-0;
     &gtk-Resources;

docs/reference/gtk/tmpl/gtkdrawingarea.sgml

@@ -80,17 +80,28 @@ gdk_window_invalidate_rect() are equally good ways to do this. You'll
 then get an expose event for the invalid region.
 </para>
 
+<para>
+The available routines for drawing are documented on the <link
+linkend="gdk-Drawing-Primitives">GDK Drawing Primitives</link> page.
+See also gdk_pixbuf_render_to_drawable() for drawing a #GdkPixbuf.
+</para>
+
 <para>
 To receive mouse events on a drawing area, you will need to enable
-them with gtk_widget_add_events(). To receive keyboard events, 
+them with gtk_widget_add_events(). To receive keyboard events, you
-you will need to set the #GTK_CAN_FOCUS flag on the drawing area, and
+will need to set the #GTK_CAN_FOCUS flag on the drawing area, and
 should probably draw some user-visible indication that the drawing
-area is focused. See gtk_paint_focus() for one way to draw focus.
+area is focused. Use the GTK_HAS_FOCUS() macro in your expose event
+handler to decide whether to draw the focus indicator. See
+gtk_paint_focus() for one way to draw focus.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+Sometimes #GtkImage is a useful alternative to a drawing area. 
+You can put a #GdkPixmap in the #GtkImage and draw to the #GdkPixmap, 
+calling gtk_widget_queue_draw() on the #GtkImage when you want to 
+refresh to the screen.
 </para>
 
 <!-- ##### STRUCT GtkDrawingArea ##### -->
@@ -110,6 +121,7 @@ Creates a new drawing area.
 
 <!-- ##### FUNCTION gtk_drawing_area_size ##### -->
 <para>
+(Use gtk_widget_set_size_request() instead.)
 Sets the size that the drawing area will request
 in response to a "size_request" signal. The 
 drawing area may actually be allocated a size

docs/reference/gtk/tmpl/gtkmenu.sgml

@@ -96,9 +96,9 @@ Creates a new #GtkMenu.
 Adds a new #GtkMenuItem to the end of the menu's item list.
 </para>
 
-<!-- # Unused Parameters # -->
 @menu: a #GtkMenu.
 @child: The #GtkMenuItem to add.
+<!-- # Unused Parameters # -->
 @m: 
 @c: 
 
@@ -108,9 +108,9 @@ Adds a new #GtkMenuItem to the end of the menu's item list.
 Adds a new #GtkMenuItem to the beginning of the menu's item list.
 </para>
 
-<!-- # Unused Parameters # -->
 @menu: a #GtkMenu.
 @child: The #GtkMenuItem to add.
+<!-- # Unused Parameters # -->
 @menu_child: 
 @m: 
 @c: 
@@ -122,10 +122,10 @@ Adds a new #GtkMenuItem to the menu's item list at the position
 indicated by @position. 
 </para>
 
-<!-- # Unused Parameters # -->
 @menu: a #GtkMenu.
 @child: The #GtkMenuItem to add.
 @pos: 
+<!-- # Unused Parameters # -->
 @position: The position in the item list where @child is added.
 Positions are numbered from 0 to n-1.
 

docs/reference/gtk/x11.sgml

@@ -0,0 +1,103 @@
+<refentry id="gtk-x11" revision="17 Jan 2002">
+<refmeta>
+<refentrytitle>Using GTK+ on the X Window System</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>GTK Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Using GTK+ on the X Window System</refname>
+<refpurpose>
+X11 aspects of using GTK+
+</refpurpose>
+</refnamediv>
+
+<refsect1>
+<title>GTK+ for the X Window System</title>
+
+<para>
+On UNIX, the X backend is the default build for GTK+. So 
+you don't need to do anything special when compiling it,
+and everything should "just work."
+</para>
+
+<para>
+To mix low-level Xlib routines into a GTK program, 
+see <link linkend="gdk-X-Window-System-Interaction">GDK X Window
+System interaction</link> in the GDK manual.
+</para>
+
+</refsect1>
+
+<refsect1 id="gtk-X11-arch">
+<title>Understanding the X11 architecture</title>
+
+<para>
+People coming from a Windows or MacOS background often find certain
+aspects of the X Window System surprising. This section introduces
+some basic X concepts at a high level. For more details, the book most
+people use is called the <citetitle pubwork="book">Xlib Programming
+Manual</citetitle> by Adrian Nye; this book is volume one in the
+O'Reilly X Window System series.
+</para>
+<para>
+Standards are another important resource if you're poking in low-level
+X11 details, in particular the ICCCM and the Extended Window Manager
+Hints specifications. <ulink
+url="http://www.freedesktop.org/standards/">freedesktop.org</ulink>
+has links to many relevant specifications.
+</para>
+<para>
+The GDK manual covers <link
+linkend="gdk-X-Window-System-Interaction">using Xlib in a GTK
+program</link>.
+</para>
+
+<refsect2>
+<title>Server, client, window manager</title>
+
+<para>
+Other window systems typically put all their functionality in the
+application itself. With X, each application involves three different
+programs: the <firstterm>X server</firstterm>, the application (called
+a <firstterm>client</firstterm> because it's a client of the X
+server), and a special client called the <firstterm>window
+manager</firstterm>.
+</para>
+
+<para>
+The X server is in charge of managing resources, processing drawing
+requests, and dispatching events such as keyboard and mouse events to
+interested applications. So client applications can ask the X server
+to create a window, draw a circle, or move windows around.
+</para>
+
+<para>
+The window manager is in charge of rendering the frame or borders
+around windows; it also has final say on the size of each window,
+and window states such as minimized, maximized, and so forth.
+On Windows and MacOS the application handles most of this.
+On X11, if you wish to modify the window's state, or 
+change its frame, you must ask the window manager to do so on your
+behalf, using an established  <ulink
+url="http://www.freedesktop.org/standards/">convention</ulink>.
+</para>
+
+<para>
+GTK+ has functions for asking the window manager to do various things;
+see for example <link
+linkend="gtk-window-iconify">gtk_window_iconify()</link> or <link
+linkend="gtk-window-maximize">gtk_window_maximize()</link> or <link
+linkend="gtk-window-set-decorated">gtk_window_set_decorated()</link>.
+Keep in mind that <link
+linkend="gtk-window-move">gtk_window_move()</link> and window sizing
+are ultimately controlled by the window manager as well and most
+window managers <emphasis>will</emphasis> ignore certain requests from
+time to time, in the interests of good user interface.
+</para>
+
+</refsect2>
+
+</refsect1>
+
+</refentry>

gtk/gtkwidget.c

@@ -1726,10 +1726,11 @@ gtk_widget_real_hide (GtkWidget *widget)
  * 
  * Utility function; intended to be connected to the "delete_event"
  * signal on a #GtkWindow. The function calls gtk_widget_hide() on its
- * argument, then returns %TRUE. If connected to "delete_event",
+ * argument, then returns %TRUE. If connected to "delete_event", the
- * the result is that clicking the window manager close button for
+ * result is that clicking the close button for a window (on the
- * will hide but not destroy the window. By default, GTK+ destroys
+ * window frame, top right corner usually) will hide but not destroy
- * windows when "delete_event" is received.
+ * the window. By default, GTK+ destroys windows when "delete_event"
+ * is received.
  * 
  * Return value: %TRUE
  **/

gtk/gtkwindow.c

@@ -764,7 +764,8 @@ gtk_window_get_property (GObject      *object,
  * you might use #GTK_WINDOW_POPUP. #GTK_WINDOW_POPUP is not for
  * dialogs, though in some other toolkits dialogs are called "popups".
  * In GTK+, #GTK_WINDOW_POPUP means a pop-up menu or pop-up tooltip.
- * Popup windows are not controlled by the window manager.
+ * On X11, popup windows are not controlled by the <link
+ * linkend="gtk-X11-arch">window manager</link>.
  *
  * If you simply want an undecorated window (no window borders), use
  * gtk_window_set_decorated(), don't use #GTK_WINDOW_POPUP.
@@ -790,12 +791,14 @@ gtk_window_new (GtkWindowType type)
  * @window: a #GtkWindow
  * @title: title of the window
  * 
- * Sets the title of the #GtkWindow. The title of a window will be displayed in
+ * Sets the title of the #GtkWindow. The title of a window will be
- * its title bar; on the X Window System, the title bar is rendered by the
+ * displayed in its title bar; on the X Window System, the title bar
- * window manager, so exactly how the title appears to users may vary according
+ * is rendered by the <link linkend="gtk-X11-arch">window
- * to a user's exact configuration. The title should help a user distinguish
+ * manager</link>, so exactly how the title appears to users may vary
- * this window from other windows they may have open. A good title might
+ * according to a user's exact configuration. The title should help a
- * include the application name and current document filename, for example.
+ * user distinguish this window from other windows they may have
+ * open. A good title might include the application name and current
+ * document filename, for example.
  * 
  **/
 void
@@ -874,11 +877,14 @@ gtk_window_set_wmclass (GtkWindow *window,
  * @window: a #GtkWindow
  * @role: unique identifier for the window to be used when restoring a session
  *
+ * This function is only useful on X11, not with other GTK+ targets.
+ * 
  * In combination with the window title, the window role allows a
- * window manager to identify "the same" window when an application is
+ * <link linkend="gtk-X11-arch">window manager</link> to identify "the
- * restarted. So for example you might set the "toolbox" role on your
+ * same" window when an application is restarted. So for example you
- * app's toolbox window, so that when the user restarts their session,
+ * might set the "toolbox" role on your app's toolbox window, so that
- * the window manager can put the toolbox back in the same place.
+ * when the user restarts their session, the window manager can put
+ * the toolbox back in the same place.
  *
  * If a window already has a unique title, you don't need to set the
  * role, since the WM can use the title to identify the window when
@@ -1361,8 +1367,8 @@ gtk_window_activate_default (GtkWindow *window)
  * with other windows in the same application. To keep modal dialogs
  * on top of main application windows, use
  * gtk_window_set_transient_for() to make the dialog transient for the
- * parent; most window managers will then disallow lowering the dialog
+ * parent; most <link linkend="gtk-X11-arch">window managers</link>
- * below the parent.
+ * will then disallow lowering the dialog below the parent.
  * 
  * 
  **/
@@ -1569,11 +1575,16 @@ gtk_window_unset_transient_for  (GtkWindow *window)
  * @parent: parent window
  *
  * Dialog windows should be set transient for the main application
- * window they were spawned from. This allows window managers to
+ * window they were spawned from. This allows <link
- * e.g. keep the dialog on top of the main window, or center the
+ * linkend="gtk-X11-arch">window managers</link> to e.g. keep the
- * dialog over the main window. gtk_dialog_new_with_buttons() and
+ * dialog on top of the main window, or center the dialog over the
- * other convenience functions in GTK+ will sometimes call
+ * main window. gtk_dialog_new_with_buttons() and other convenience
+ * functions in GTK+ will sometimes call
  * gtk_window_set_transient_for() on your behalf.
+ *
+ * On Windows, this function will and put the child window
+ * on top of the parent, much as the window manager would have
+ * done on X.
  * 
  **/
 void       
@@ -1815,10 +1826,14 @@ gtk_window_set_geometry_hints (GtkWindow       *window,
  * @setting: %TRUE to decorate the window
  *
  * By default, windows are decorated with a title bar, resize
- * controls, etc.  Some window managers allow GTK+ to disable these
+ * controls, etc.  Some <link linkend="gtk-X11-arch">window
- * decorations, creating a borderless window. If you set the decorated
+ * managers</link> allow GTK+ to disable these decorations, creating a
- * property to %FALSE using this function, GTK+ will do its best to
+ * borderless window. If you set the decorated property to %FALSE
- * convince the window manager not to decorate the window.
+ * using this function, GTK+ will do its best to convince the window
+ * manager not to decorate the window.
+ *
+ * On Windows, this function always works, since there's no window manager
+ * policy involved.
  * 
  **/
 void
@@ -2493,10 +2508,11 @@ gtk_window_resize (GtkWindow *window,
  * @width: return location for width, or %NULL
  * @height: return location for height, or %NULL
  *
- * Obtains the current size of @window. If @window is not onscreen,
+ * Obtains the current size of @window. If @window is not onscreen, it
- * it returns the size GTK+ will suggest to the window manager for the
+ * returns the size GTK+ will suggest to the <link
- * initial window size (but this is not reliably the same as the size
+ * linkend="gtk-X11-arch">window manager</link> for the initial window
- * the window manager will actually select). The size obtained by
+ * size (but this is not reliably the same as the size the window
+ * manager will actually select). The size obtained by
  * gtk_window_get_size() is the last size received in a
  * #GdkEventConfigure, that is, GTK+ uses its locally-stored size,
  * rather than querying the X server for the size. As a result, if you
@@ -2533,9 +2549,9 @@ gtk_window_resize (GtkWindow *window,
  * application cannot.
  *
  * In any case, if you insist on application-specified window
- * positioning, there's <emphasis>still</emphasis> a better way than doing it yourself -
+ * positioning, there's <emphasis>still</emphasis> a better way than
- * gtk_window_set_position() will frequently handle the details
+ * doing it yourself - gtk_window_set_position() will frequently
- * for you.
+ * handle the details for you.
  * 
  **/
 void
@@ -2582,11 +2598,11 @@ gtk_window_get_size (GtkWindow *window,
  * @x: X coordinate to move window to
  * @y: Y coordinate to move window to
  *
- * Asks the window manager to move @window to the given position.
+ * Asks the <link linkend="gtk-X11-arch">window manager</link> to move
- * Window managers are free to ignore this; most window managers
+ * @window to the given position.  Window managers are free to ignore
- * ignore requests for initial window positions (instead using a
+ * this; most window managers ignore requests for initial window
- * user-defined placement algorithm) and honor requests after the
+ * positions (instead using a user-defined placement algorithm) and
- * window has already been shown.
+ * honor requests after the window has already been shown.
  *
  * Note: the position is the position of the gravity-determined
  * reference point for the window. The gravity determines two things:
@@ -2704,10 +2720,11 @@ gtk_window_move (GtkWindow *window,
  * Thus GTK+ is using a "best guess" that works with most
  * window managers.
  *
- * Moreover, nearly all window managers are broken with respect to
+ * Moreover, nearly all window managers are historically broken with
- * their handling of window gravity. So moving a window to its current
+ * respect to their handling of window gravity. So moving a window to
- * position as returned by gtk_window_get_position() tends to
+ * its current position as returned by gtk_window_get_position() tends
- * result in moving the window slightly.
+ * to result in moving the window slightly. Window managers are
+ * slowly getting better over time.
  *
  * If a window has gravity #GDK_GRAVITY_STATIC the window manager
  * frame is not relevant, and thus gtk_window_get_position() will
@@ -4847,12 +4864,13 @@ gtk_window_present (GtkWindow *window)
  * gtk_window_iconify:
  * @window: a #GtkWindow
  *
- * Asks to iconify (i.e. minimize) the specified @window. Note that you
+ * Asks to iconify (i.e. minimize) the specified @window. Note that
- * shouldn't assume the window is definitely iconified afterward,
+ * you shouldn't assume the window is definitely iconified afterward,
- * because other entities (e.g. the user or window manager) could
+ * because other entities (e.g. the user or <link
- * deiconify it again, or there may not be a window manager in which
+ * linkend="gtk-X11-arch">window manager</link>) could deiconify it
- * case iconification isn't possible, etc. But normally the window
+ * again, or there may not be a window manager in which case
- * will end up iconified. Just don't write code that crashes if not.
+ * iconification isn't possible, etc. But normally the window will end
+ * up iconified. Just don't write code that crashes if not.
  *
  * It's permitted to call this function before showing a window,
  * in which case the window will be iconified before it ever appears
@@ -4889,9 +4907,9 @@ gtk_window_iconify (GtkWindow *window)
  *
  * Asks to deiconify (i.e. unminimize) the specified @window. Note
  * that you shouldn't assume the window is definitely deiconified
- * afterward, because other entities (e.g. the user or window manager)
+ * afterward, because other entities (e.g. the user or <link
- * could iconify it again before your code which assumes
+ * linkend="gtk-X11-arch">window manager</link>) could iconify it
- * deiconification gets to run.
+ * again before your code which assumes deiconification gets to run.
  *
  * You can track iconification via the "window_state_event" signal
  * on #GtkWidget.
@@ -4923,10 +4941,11 @@ gtk_window_deiconify (GtkWindow *window)
  *
  * Asks to stick @window, which means that it will appear on all user
  * desktops. Note that you shouldn't assume the window is definitely
- * stuck afterward, because other entities (e.g. the user or window
+ * stuck afterward, because other entities (e.g. the user or <link
- * manager) could unstick it again, and some window managers do not
+ * linkend="gtk-X11-arch">window manager</link>) could unstick it
- * support sticking windows. But normally the window will end up
+ * again, and some window managers do not support sticking
- * stuck. Just don't write code that crashes if not.
+ * windows. But normally the window will end up stuck. Just don't
+ * write code that crashes if not.
  *
  * It's permitted to call this function before showing a window.
  *
@@ -4962,9 +4981,9 @@ gtk_window_stick (GtkWindow *window)
  * Asks to unstick @window, which means that it will appear on only
  * one of the user's desktops. Note that you shouldn't assume the
  * window is definitely unstuck afterward, because other entities
- * (e.g. the user or window manager) could stick it again. But
+ * (e.g. the user or <link linkend="gtk-X11-arch">window
- * normally the window will end up stuck. Just don't write code that
+ * manager</link>) could stick it again. But normally the window will
- * crashes if not.
+ * end up stuck. Just don't write code that crashes if not.
  *
  * You can track stickiness via the "window_state_event" signal
  * on #GtkWidget.
@@ -4997,10 +5016,11 @@ gtk_window_unstick (GtkWindow *window)
  *
  * Asks to maximize @window, so that it becomes full-screen. Note that
  * you shouldn't assume the window is definitely maximized afterward,
- * because other entities (e.g. the user or window manager) could
+ * because other entities (e.g. the user or <link
- * unmaximize it again, and not all window managers support
+ * linkend="gtk-X11-arch">window manager</link>) could unmaximize it
- * maximization. But normally the window will end up maximized. Just
+ * again, and not all window managers support maximization. But
- * don't write code that crashes if not.
+ * normally the window will end up maximized. Just don't write code
+ * that crashes if not.
  *
  * It's permitted to call this function before showing a window,
  * in which case the window will be maximized when it appears onscreen
@@ -5037,10 +5057,10 @@ gtk_window_maximize (GtkWindow *window)
  *
  * Asks to unmaximize @window. Note that you shouldn't assume the
  * window is definitely unmaximized afterward, because other entities
- * (e.g. the user or window manager) could maximize it again, and not
+ * (e.g. the user or <link linkend="gtk-X11-arch">window
- * all window managers honor requests to unmaximize. But normally the
+ * manager</link>) could maximize it again, and not all window
- * window will end up unmaximized. Just don't write code that crashes
+ * managers honor requests to unmaximize. But normally the window will
- * if not.
+ * end up unmaximized. Just don't write code that crashes if not.
  *
  * You can track maximization via the "window_state_event" signal
  * on #GtkWidget.
@@ -5160,9 +5180,10 @@ gtk_window_get_gravity (GtkWindow *window)
  *
  * Starts resizing a window. This function is used if an application
  * has window resizing controls. When GDK can support it, the resize
- * will be done using the standard mechanism for the window manager or
+ * will be done using the standard mechanism for the <link
- * windowing system. Otherwise, GDK will try to emulate window
+ * linkend="gtk-X11-arch">window manager</link> or windowing
- * resizing, potentially not all that well, depending on the windowing system.
+ * system. Otherwise, GDK will try to emulate window resizing,
+ * potentially not all that well, depending on the windowing system.
  * 
  **/
 void
@@ -5202,10 +5223,11 @@ gtk_window_begin_resize_drag  (GtkWindow    *window,
  *
  * (Note: this is a special-purpose function intended for the
  *  framebuffer port; see gtk_window_set_has_frame(). It will not
- *  return the size of the window border drawn by the window manager,
+ *  return the size of the window border drawn by the <link
- *  which is the normal case when using a windowing system.
+ *  linkend="gtk-X11-arch">window manager</link>, which is the normal
- *  See gdk_window_get_frame_extents() to get the standard
+ *  case when using a windowing system.  See
- *  window border extents.)
+ *  gdk_window_get_frame_extents() to get the standard window border
+ *  extents.)
  * 
  * Retrieves the dimensions of the frame window for this toplevel.
  * See gtk_window_set_has_frame(), gtk_window_set_frame_dimensions().
@@ -5237,11 +5259,12 @@ gtk_window_get_frame_dimensions (GtkWindow *window,
  * @root_y: Y position where the user clicked to initiate the drag
  * @timestamp: timestamp from the click event that initiated the drag
  *
- * Starts moving a window. This function is used if an application
+ * Starts moving a window. This function is used if an application has
- * has window movement grips. When GDK can support it, the window movement
+ * window movement grips. When GDK can support it, the window movement
- * will be done using the standard mechanism for the window manager or
+ * will be done using the standard mechanism for the <link
- * windowing system. Otherwise, GDK will try to emulate window
+ * linkend="gtk-X11-arch">window manager</link> or windowing
- * movement, potentially not all that well, depending on the windowing system.
+ * system. Otherwise, GDK will try to emulate window movement,
+ * potentially not all that well, depending on the windowing system.
  * 
  **/
 void