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

6 files changed, 134 insertions, 9 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index a08e4b4b4f..515370a203 100644
--- a/docs/reference/ChangeLog
+++ b/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.
diff --git a/docs/reference/gtk/framebuffer.sgml b/docs/reference/gtk/framebuffer.sgml
index 0ff649cd6a..17c1778383 100644
--- a/docs/reference/gtk/framebuffer.sgml
+++ b/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>
 
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 4d02cae7b0..4936f1ba41 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/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;
diff --git a/docs/reference/gtk/tmpl/gtkdrawingarea.sgml b/docs/reference/gtk/tmpl/gtkdrawingarea.sgml
index 4c6346e065..9b686dd64a 100644
--- a/docs/reference/gtk/tmpl/gtkdrawingarea.sgml
+++ b/docs/reference/gtk/tmpl/gtkdrawingarea.sgml
@@ -81,16 +81,27 @@ 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, 
-you will need to set the #GTK_CAN_FOCUS flag on the drawing area, and
+them with gtk_widget_add_events(). To receive keyboard events, you
+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
diff --git a/docs/reference/gtk/tmpl/gtkmenu.sgml b/docs/reference/gtk/tmpl/gtkmenu.sgml
index f0db72f47a..c060e31b92 100644
--- a/docs/reference/gtk/tmpl/gtkmenu.sgml
+++ b/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.
 
diff --git a/docs/reference/gtk/x11.sgml b/docs/reference/gtk/x11.sgml
new file mode 100644
index 0000000000..9054e42a91
--- /dev/null
+++ b/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>