new section from Lee Mallabone.

1999-08-28  Damon Chaplin  <damon@karuna.freeserve.co.uk>

	* gtk/tmpl/gtkbbox.sgml: new section from Lee Mallabone.

	* gdk/gdk-sections.txt: rearranged rgb, regions, and drawing sections.

	* gdk/tmpl/rgb.sgml: new section from Raph Levien, with a few changes
	by me, including a little example app.

	* gdk/tmpl/regions.sgml:
	* gdk/tmpl/event_structs.sgml:
	* gdk/tmpl/drawing.sgml: my first attempt.
	* gdk/tmpl/cursors.sgml: tiny changes.

8 files changed, 891 insertions, 472 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 0ff9ed7cd1..5aa1e3c8c2 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,17 @@
+1999-08-28  Damon Chaplin  <damon@karuna.freeserve.co.uk>
+
+	* gtk/tmpl/gtkbbox.sgml: new section from Lee Mallabone.
+
+	* gdk/gdk-sections.txt: rearranged rgb, regions, and drawing sections.
+
+	* gdk/tmpl/rgb.sgml: new section from Raph Levien, with a few changes
+	by me, including a little example app.
+
+	* gdk/tmpl/regions.sgml: 
+	* gdk/tmpl/event_structs.sgml: 
+	* gdk/tmpl/drawing.sgml: my first attempt.
+	* gdk/tmpl/cursors.sgml: tiny changes.
+
 Tue Aug 17 09:14:01 1999  Owen Taylor  <otaylor@redhat.com>
 
 	* gtk/tmpl/gtktypeutils.sgml: Fix corrupted end tag.
diff --git a/docs/reference/gdk/gdk-sections.txt b/docs/reference/gdk/gdk-sections.txt
index 033341a53e..661ef50317 100644
--- a/docs/reference/gdk/gdk-sections.txt
+++ b/docs/reference/gdk/gdk-sections.txt
@@ -77,29 +77,33 @@ gdk_image_destroy
 <SECTION>
 <TITLE>GdkRGB</TITLE>
 <FILE>rgb</FILE>
-GdkRgbCmap
+gdk_rgb_init
+
+<SUBSECTION>
+gdk_draw_rgb_image
+gdk_draw_rgb_image_dithalign
+gdk_draw_indexed_image
+gdk_draw_gray_image
+gdk_draw_rgb_32_image
 GdkRgbDither
 
-gdk_rgb_init
+<SUBSECTION>
 gdk_rgb_cmap_new
 gdk_rgb_cmap_free
+GdkRgbCmap
 
+<SUBSECTION>
 gdk_rgb_gc_set_foreground
 gdk_rgb_gc_set_background
-
-gdk_draw_rgb_image
-gdk_draw_indexed_image
-gdk_draw_gray_image
-gdk_draw_rgb_32_image
-gdk_draw_rgb_image_dithalign
 gdk_rgb_xpixel_from_rgb
 
-gdk_rgb_set_verbose
-gdk_rgb_ditherable
+<SUBSECTION>
 gdk_rgb_set_install
 gdk_rgb_set_min_colors
 gdk_rgb_get_visual
 gdk_rgb_get_cmap
+gdk_rgb_ditherable
+gdk_rgb_set_verbose
 </SECTION>
 
 <SECTION>
@@ -164,26 +168,29 @@ gdk_char_height
 <TITLE>Drawing Primitives</TITLE>
 <FILE>drawing</FILE>
 GdkFill
-GdkFillRule
 GdkLineStyle
 GdkCapStyle
 GdkJoinStyle
 
 gdk_draw_point
+gdk_draw_points
 gdk_draw_line
+gdk_draw_lines
+gdk_draw_segments
+GdkSegment
 gdk_draw_rectangle
 gdk_draw_arc
 gdk_draw_polygon
+
+<SUBSECTION>
 gdk_draw_string
 gdk_draw_text
 gdk_draw_text_wc
+
+<SUBSECTION>
 gdk_draw_pixmap
 gdk_draw_bitmap
 gdk_draw_image
-gdk_draw_points
-gdk_draw_segments
-GdkSegment
-gdk_draw_lines
 </SECTION>
 
 <SECTION>
@@ -410,27 +417,34 @@ gdk_color_context_get_index_from_palette
 <FILE>regions</FILE>
 GdkPoint
 
+<SUBSECTION>
 GdkRectangle
 gdk_rectangle_intersect
 gdk_rectangle_union
 
+<SUBSECTION>
 GdkRegion
 gdk_region_new
+gdk_region_polygon
+GdkFillRule
 gdk_region_destroy
-gdk_region_get_clipbox
+
+<SUBSECTION>
+gdk_regions_intersect
+gdk_regions_union
+gdk_regions_subtract
+gdk_regions_xor
+gdk_region_union_with_rect
+gdk_region_offset
+gdk_region_shrink
+
+<SUBSECTION>
 gdk_region_empty
 gdk_region_equal
 gdk_region_point_in
 gdk_region_rect_in
 GdkOverlapType
-gdk_region_polygon
-gdk_region_offset
-gdk_region_shrink
-gdk_region_union_with_rect
-gdk_regions_intersect
-gdk_regions_union
-gdk_regions_subtract
-gdk_regions_xor
+gdk_region_get_clipbox
 </SECTION>
 
 <SECTION>
diff --git a/docs/reference/gdk/tmpl/cursors.sgml b/docs/reference/gdk/tmpl/cursors.sgml
index 3757f955c9..5b33090b9a 100644
--- a/docs/reference/gdk/tmpl/cursors.sgml
+++ b/docs/reference/gdk/tmpl/cursors.sgml
@@ -2,7 +2,7 @@
 Cursors
 
 <!-- ##### SECTION Short_Description ##### -->
-
+standard and pixmap cursors.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
@@ -40,6 +40,7 @@ Creates a new standard cursor.
 <para>
 Creates a new cursor from a given pixmap and mask. Both the pixmap and mask
 must have a depth of 1 (i.e. each pixel has only 2 values - on or off).
+The standard cursor size is 16 by 16 pixels.
 </para>
 <example><title>Creating a custom cursor.</title>
 <programlisting>
diff --git a/docs/reference/gdk/tmpl/drawing.sgml b/docs/reference/gdk/tmpl/drawing.sgml
index 159690bace..d57db7b25a 100644
--- a/docs/reference/gdk/tmpl/drawing.sgml
+++ b/docs/reference/gdk/tmpl/drawing.sgml
@@ -2,11 +2,22 @@
 Drawing Primitives
 
 <!-- ##### SECTION Short_Description ##### -->
-
+functions for drawing points, lines, arcs, and text.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+These functions provide support for drawing points, lines, arcs and text
+onto what are called 'drawables'. Drawables, as the name suggests, are things
+which support drawing onto them, and are either #GdkWindow or #GdkPixmap
+objects.
+</para>
+<para>
+Many of the drawing operations take a #GdkGC argument, which represents a
+graphics context. This #GdkGC contains a number of drawing attributes such
+as foreground color, background color and line width, and is used to reduce
+the number of arguments needed for each drawing operation. See the
+<link linkend="gdk-Graphics-Contexts">Graphics Contexts</link> section for
+more information.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -16,171 +27,215 @@ Drawing Primitives
 
 <!-- ##### ENUM GdkFill ##### -->
 <para>
-
+Used to specify the way in which drawing operations are performed.
+See gdk_gc_set_fill().
 </para>
 
-@GDK_SOLID: 
-@GDK_TILED: 
-@GDK_STIPPLED: 
-@GDK_OPAQUE_STIPPLED: 
+@GDK_SOLID: graphics are drawn in a solid color, usually the foreground color
+of the #GdkGC.
+@GDK_TILED: graphics are drawn using a tile pixmap. See gdk_gc_set_tile().
+@GDK_STIPPLED: graphics are drawn with a stipple (a pixmap with a depth of 1).
+Bits set in the stipple are drawn in the foreground color. Bits not set in the
+stipple are left as they are. See gdk_gc_set_stipple().
+@GDK_OPAQUE_STIPPLED: graphics are drawn with a stipple, as in @GDK_STIPPLED,
+except that the bits not set in the stipple are drawn in the background color
+instead of being left as they are. See gdk_gc_set_stipple().
 
 <!-- ##### ENUM GdkFillRule ##### -->
 <para>
-
+The method for determining which pixels are included in a region, when
+creating a #GdkRegion from a polygon.
+The fill rule is only relevant for polygons which overlap themselves.
 </para>
 
-@GDK_EVEN_ODD_RULE: 
-@GDK_WINDING_RULE: 
+@GDK_EVEN_ODD_RULE: areas which are overlapped an odd number of times are
+included in the region, while areas overlapped an even number of times are not.
+@GDK_WINDING_RULE: overlapping areas are always included.
+
 
 <!-- ##### ENUM GdkLineStyle ##### -->
 <para>
-
+Used to specify how lines are drawn. See gdk_gc_set_line_attributes().
 </para>
 
-@GDK_LINE_SOLID: 
-@GDK_LINE_ON_OFF_DASH: 
-@GDK_LINE_DOUBLE_DASH: 
+@GDK_LINE_SOLID: lines are drawn in a solid color, the foreground color.
+@GDK_LINE_ON_OFF_DASH: dashed lines are drawn, with the pixels between the
+dashes left as they are. The #GdkCapStyle is applied to each end of the dashes.
+@GDK_LINE_DOUBLE_DASH: dashed lines are drawn, alternating between the
+foreground and background colors. The %GDK_CAP_BUTT style is used where
+dashes and gaps meet.
 
 <!-- ##### ENUM GdkCapStyle ##### -->
 <para>
-
+Used to specify how the ends of lines and dashes are drawn.
+See gdk_gc_set_line_attributes().
 </para>
 
-@GDK_CAP_NOT_LAST: 
-@GDK_CAP_BUTT: 
-@GDK_CAP_ROUND: 
-@GDK_CAP_PROJECTING: 
+@GDK_CAP_NOT_LAST: this is equivalent to %GDK_CAP_BUTT, except that for a line
+width of 0 the final endpoint is not drawn.
+@GDK_CAP_BUTT: the ends of the line are square with no projection beyond the
+endpoint.
+@GDK_CAP_ROUND: the ends of the line are rounded using a circular arc centered
+on the endpoint. This is equivalent to %GDK_CAP_BUTT when the line width is 0.
+@GDK_CAP_PROJECTING: the ends of the line are square, but project beyond the
+endpoint to a distance of half the line width.
+This is equivalent to %GDK_CAP_BUTT when the line width is 0.
 
 <!-- ##### ENUM GdkJoinStyle ##### -->
 <para>
-
+Used to specify how the the joins between lines are drawn.
+See gdk_gc_set_line_attributes().
 </para>
 
-@GDK_JOIN_MITER: 
-@GDK_JOIN_ROUND: 
-@GDK_JOIN_BEVEL: 
+@GDK_JOIN_MITER: the ends of the lines are extended to meet at a point.
+If the angle between the lines is less than 11 degrees, %GDK_JOIN_BEVEL is
+used instead.
+@GDK_JOIN_ROUND: the ends of the lines are rounded with a circular arc
+centered on the joinpoint, with a diameter equal to the line width.
+@GDK_JOIN_BEVEL: the lines have %GDK_CAP_BUTT cap styles, with the triangular
+notch filled.
 
 <!-- ##### FUNCTION gdk_draw_point ##### -->
 <para>
-
+Draws a point, using the foreground color and other attributes of the #GdkGC.
 </para>
 
-@drawable: 
-@gc: 
-@x: 
-@y: 
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@x: the x coordinate of the point.
+@y: the y coordinate of the point.
 
 
 <!-- ##### FUNCTION gdk_draw_line ##### -->
 <para>
-
+Draws a line, using the foreground color and other attributes of the #GdkGC.
 </para>
 
-@drawable: 
-@gc: 
-@x1: 
-@y1: 
-@x2: 
-@y2: 
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@x1: the x coordinate of the start point.
+@y1: the y coordinate of the start point.
+@x2: the x coordinate of the end point.
+@y2: the y coordinate of the end point.
 
 
 <!-- ##### FUNCTION gdk_draw_rectangle ##### -->
 <para>
-
+Draws a rectangular outline or filled rectangle, using the foreground color
+and other attributes of the #GdkGC.
 </para>
+<note>
+<para>
+A rectangle drawn filled is 1 pixel smaller in both dimensions than a rectangle
+outlined. Calling gdk_draw_rectangle (window, gc, TRUE, 0, 0, 20, 20) results
+in a filled rectangle 20 pixels wide and 20 pixels high. Calling
+gdk_draw_rectangle (window, gc, FALSE, 0, 0, 20, 20) results in an outlined
+rectangle with corners at (0, 0), (0, 20), (20, 20), and (20, 0), which
+makes it 21 pixels wide and 21 pixels high.
+</para>
+</note>
 
-@drawable: 
-@gc: 
-@filled: 
-@x: 
-@y: 
-@width: 
-@height: 
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@filled: TRUE if the rectangle should be filled.
+@x: the x coordinate of the left edge of the rectangle.
+@y: the y coordinate of the top edge of the rectangle.
+@width: the width of the rectangle.
+@height: the height of the rectangle.
 
 
 <!-- ##### FUNCTION gdk_draw_arc ##### -->
 <para>
-
+Draws an arc or a filled 'pie slice'. The arc is defined by the bounding
+rectangle of the entire ellipse, and the start and end angles of the part of
+the ellipse to be drawn.
 </para>
 
-@drawable: 
-@gc: 
-@filled: 
-@x: 
-@y: 
-@width: 
-@height: 
-@angle1: 
-@angle2: 
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@filled: TRUE if the arc should be filled, producing a 'pie slice'.
+@x: the x coordinate of the left edge of the bounding rectangle.
+@y: the y coordinate of the top edge of the bounding rectangle.
+@width: the width of the bounding rectangle.
+@height: the height of the bounding rectangle.
+@angle1: the start angle of the arc, relative to the 3 o'clock position,
+counter-clockwise, in 1/64ths of a degree.
+@angle2: the end angle of the arc, similar to @angle1.
 
 
 <!-- ##### FUNCTION gdk_draw_polygon ##### -->
 <para>
-
+Draws an outlined or filled polygon.
 </para>
 
-@drawable: 
-@gc: 
-@filled: 
-@points: 
-@npoints: 
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@filled: TRUE if the polygon should be filled. The polygon is closed
+automatically, connecting the last point to the first point if necessary.
+@points: an array of #GdkPoint structures specifying the points making up the
+polygon.
+@npoints: the number of points.
 
 
 <!-- ##### FUNCTION gdk_draw_string ##### -->
 <para>
-
+Draws a string of characters in the given font or fontset.
 </para>
 
-@drawable: 
-@font: 
-@gc: 
-@x: 
-@y: 
-@string: 
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@font: a #GdkFont.
+q@gc: a #GdkGC.
+@x: the x coordinate of the left edge of the text.
+@y: the y coordinate of the baseline of the text.
+@string: the string of characters to draw.
 
 
 <!-- ##### FUNCTION gdk_draw_text ##### -->
 <para>
-
+Draws a number of characters in the given font or fontset.
 </para>
 
-@drawable: 
-@font: 
-@gc: 
-@x: 
-@y: 
-@text: 
-@text_length: 
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@font: a #GdkFont.
+@gc: a #GdkGC.
+@x: the x coordinate of the left edge of the text.
+@y: the y coordinate of the baseline of the text.
+@text: the characters to draw.
+@text_length: the number of characters of @text to draw.
 
 
 <!-- ##### FUNCTION gdk_draw_text_wc ##### -->
 <para>
-
+Draws a number of wide characters using the given font of fontset.
+If the font is a 1-byte font, the string is converted into 1-byte characters
+(discarding the high bytes) before output.
 </para>
 
-@drawable: 
-@font: 
-@gc: 
-@x: 
-@y: 
-@text: 
-@text_length: 
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@font: a #GdkFont.
+@gc: a #GdkGC.
+@x: the x coordinate of the left edge of the text.
+@y: the y coordinate of the baseline of the text.
+@text: the wide characters to draw.
+@text_length: the number of characters to draw.
 
 
 <!-- ##### FUNCTION gdk_draw_pixmap ##### -->
 <para>
-
+Draws a pixmap, or a part of a pixmap, onto another drawable.
 </para>
 
-@drawable: 
-@gc: 
-@src: 
-@xsrc: 
-@ysrc: 
-@xdest: 
-@ydest: 
-@width: 
-@height: 
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@src: the source #GdkPixmap to draw.
+@xsrc: the left edge of the source rectangle within @src.
+@ysrc: the top of the source rectangle within @src.
+@xdest: the x coordinate of the destination within @drawable.
+@ydest: the y coordinate of the destination within @drawable.
+@width: the width of the area to be copied, or -1 to make the area extend to
+the right edge of the source pixmap.
+@height: the height of the area to be copied, or -1 to make the area extend
+to the bottom edge of the source pixmap.
 
 
 <!-- ##### FUNCTION gdk_draw_bitmap ##### -->
@@ -188,7 +243,7 @@ Drawing Primitives
 
 </para>
 
-@drawable: 
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 @gc: 
 @src: 
 @xsrc: 
@@ -204,7 +259,7 @@ Drawing Primitives
 
 </para>
 
-@drawable: 
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 @gc: 
 @image: 
 @xsrc: 
@@ -217,13 +272,14 @@ Drawing Primitives
 
 <!-- ##### FUNCTION gdk_draw_points ##### -->
 <para>
-
+Draws a number of points, using the foreground color and other attributes of
+the #GdkGC.
 </para>
 
-@drawable: 
-@gc: 
-@points: 
-@npoints: 
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@points: an array of #GdkPoint structures.
+@npoints: the number of points to be drawn.
 
 
 <!-- ##### FUNCTION gdk_draw_segments ##### -->
@@ -231,7 +287,7 @@ Drawing Primitives
 
 </para>
 
-@drawable: 
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
 @gc: 
 @segs: 
 @nsegs: 
@@ -249,12 +305,16 @@ Drawing Primitives
 
 <!-- ##### FUNCTION gdk_draw_lines ##### -->
 <para>
-
+Draws a series of lines connecting the given points.
+The way in which joins between lines are draw is determined by the
+#GdkCapStyle value in the #GdkGC. This can be set with
+gdk_gc_set_line_attributes().
 </para>
 
-@drawable: 
-@gc: 
-@points: 
-@npoints: 
+@drawable: a #GdkDrawable (a #GdkWindow or a #GdkPixmap).
+@gc: a #GdkGC.
+@points: an array of #GdkPoint structures specifying the endpoints of the
+lines.
+@npoints: the number of endpoints.
 
 
diff --git a/docs/reference/gdk/tmpl/event_structs.sgml b/docs/reference/gdk/tmpl/event_structs.sgml
index 417d599c11..5a4370bc1e 100644
--- a/docs/reference/gdk/tmpl/event_structs.sgml
+++ b/docs/reference/gdk/tmpl/event_structs.sgml
@@ -8,6 +8,12 @@ Event Structures
 <para>
 
 </para>
+<note>
+<para>
+A common mistake is to forget to set the event mask of a widget so that the
+required events are received. See gtk_widget_set_events().
+</para>
+</note>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
@@ -16,12 +22,13 @@ Event Structures
 
 <!-- ##### STRUCT GdkEventAny ##### -->
 <para>
-
+Contains the fields which are common to all event structs.
+Any event can safely be cast to a #GdkEventAny to access these fields.
 </para>
 
-@type: 
-@window: 
-@send_event: 
+@type: the type of the event.
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
 
 <!-- ##### STRUCT GdkEventExpose ##### -->
 <para>
@@ -85,24 +92,55 @@ Event Structures
 
 <!-- ##### STRUCT GdkEventButton ##### -->
 <para>
-
+Used for button press and button release events. The
+<structfield>type</structfield> field will be one of %GDK_BUTTON_PRESS,
+%GDK_2BUTTON_PRESS, GDK_3BUTTON_PRESS, and GDK_BUTTON_RELEASE.
+</para>
+<para>
+Double and treble-clicks result in a sequence of events being received.
+For double-clicks the order of events will be:
+<orderedlist>
+<listitem><para>%GDK_BUTTON_PRESS</para></listitem>
+<listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
+<listitem><para>%GDK_BUTTON_PRESS</para></listitem>
+<listitem><para>%GDK_2BUTTON_PRESS</para></listitem>
+<listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
+</orderedlist>
+Note that the first click is received just like a normal
+button press, while the second click results in a %GDK_2BUTTON_PRESS being
+received just after the %GDK_BUTTON_PRESS.
+</para>
+<para>
+Treble-clicks are very similar to double-clicks, except that %GDK_3BUTTON_PRESS
+is inserted after the third click. The order of the events is:
+<orderedlist>
+<listitem><para>%GDK_BUTTON_PRESS</para></listitem>
+<listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
+<listitem><para>%GDK_BUTTON_PRESS</para></listitem>
+<listitem><para>%GDK_2BUTTON_PRESS</para></listitem>
+<listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
+<listitem><para>%GDK_BUTTON_PRESS</para></listitem>
+<listitem><para>%GDK_3BUTTON_PRESS</para></listitem>
+<listitem><para>%GDK_BUTTON_RELEASE</para></listitem>
+</orderedlist>
 </para>
 
-@type: 
-@window: 
-@send_event: 
-@time: 
-@x: 
-@y: 
-@pressure: 
+@type: the type of the event.
+@window: the window which received the event.
+@send_event: TRUE if the event was sent explicitly (e.g. using XSendEvent).
+@time: the time of the event in milliseconds. This wraps around every 50 days.
+@x: the x coordinate of the mouse relative to the window.
+@y: the y coordinate of the mouse relative to the window.
+@pressure: the pressure of the button press, intended for input devices such
+as graphics tablets. It defaults to 0.5.
 @xtilt: 
 @ytilt: 
 @state: 
 @button: 
 @source: 
 @deviceid: 
-@x_root: 
-@y_root: 
+@x_root: the x coordinate of the mouse relative to the root of the screen.
+@y_root: the y coordinate of the mouse relative to the root of the screen.
 
 <!-- ##### STRUCT GdkEventKey ##### -->
 <para>
@@ -193,14 +231,6 @@ Event Structures
 @time: 
 @state: 
 
-<!-- ##### ENUM GdkPropertyState ##### -->
-<para>
-
-</para>
-
-@GDK_PROPERTY_NEW_VALUE: 
-@GDK_PROPERTY_DELETE: 
-
 <!-- ##### STRUCT GdkEventSelection ##### -->
 <para>
 
diff --git a/docs/reference/gdk/tmpl/regions.sgml b/docs/reference/gdk/tmpl/regions.sgml
index 5f4f228d2b..dcb3b89682 100644
--- a/docs/reference/gdk/tmpl/regions.sgml
+++ b/docs/reference/gdk/tmpl/regions.sgml
@@ -2,11 +2,25 @@
 Points, Rectangles and Regions
 
 <!-- ##### SECTION Short_Description ##### -->
-
+simple graphical data types.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+GDK provides the #GdkPoint, #GdkRectangle and #GdkRegion data types for
+representing pixels and sets of pixels on the screen.
+</para>
+<para>
+#GdkPoint is a simple structure containing an x and y coordinate of a point.
+</para>
+<para>
+#GdkRectangle is a structure holding the position and size of a rectangle.
+The intersection of two rectangles can be computed with
+gdk_rectangle_intersect(). To find the union of two rectangles use
+gdk_rectangle_union().
+</para>
+<para>
+#GdkRegion is an opaque data type holding a set of arbitrary pixels, and is
+usually used for clipping graphical operations (see gdk_gc_set_clip_region()).
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -16,202 +30,218 @@ Points, Rectangles and Regions
 
 <!-- ##### STRUCT GdkPoint ##### -->
 <para>
-
+Defines the x and y coordinates of a point.
+Note that both are defined as #gint16 values, so the coordinates are limited
+to between -32,768 and 32,767.
 </para>
 
-@x: 
-@y: 
+@x: the x coordinate of the point.
+@y: the y coordinate of the point.
 
 <!-- ##### STRUCT GdkRectangle ##### -->
 <para>
-
+Defines the position and size of a rectangle.
 </para>
 
-@x: 
-@y: 
-@width: 
-@height: 
+@x: the x coordinate of the left edge of the rectangle.
+@y: the y coordinate of the top of the rectangle.
+@width: the width of the rectangle.
+@height: the height of the rectangle.
 
 <!-- ##### FUNCTION gdk_rectangle_intersect ##### -->
 <para>
-
+Calculates the intersection of two rectangles.
 </para>
 
-@src1: 
-@src2: 
-@dest: 
-@Returns: 
+@src1: a #GdkRectangle.
+@src2: a #GdkRectangle.
+@dest: the intersection of @src1 and @src2.
+@Returns: TRUE if the rectangles intersect.
 
 
 <!-- ##### FUNCTION gdk_rectangle_union ##### -->
 <para>
-
+Calculates the union of two rectangles.
+The union of rectangles @src1 and @src2 is the smallest rectangle which
+includes both @src1 and @src2 within it.
 </para>
 
-@src1: 
-@src2: 
-@dest: 
+@src1: a #GdkRectangle.
+@src2: a #GdkRectangle.
+@dest: the union of @src1 and @src2.
 
 
 <!-- ##### STRUCT GdkRegion ##### -->
 <para>
-
+A GdkRegion represents a set of pixels on the screen.
+The only user-visible field of the structure is the user_data member, which
+can be used to attach arbitrary data to the #GdkRegion.
 </para>
 
-@user_data: 
+@user_data: arbitrary data attached to the #GdkRegion.
 
 <!-- ##### FUNCTION gdk_region_new ##### -->
 <para>
-
+Creates a new empty #GdkRegion.
 </para>
 
-@Returns: 
+@Returns: a new empty #GdkRegion.
 
 
 <!-- ##### FUNCTION gdk_region_destroy ##### -->
 <para>
-
+Destroys a #GdkRegion.
 </para>
 
-@region: 
+@region: a #GdkRegion.
 
 
 <!-- ##### FUNCTION gdk_region_get_clipbox ##### -->
 <para>
-
+Returns the smallest rectangle which includes the entire #GdkRegion.
 </para>
 
-@region: 
-@rectangle: 
+@region: a #GdkRegion.
+@rectangle: returns the smallest rectangle which includes all of @region.
 
 
 <!-- ##### FUNCTION gdk_region_empty ##### -->
 <para>
-
+Returns TRUE if the #GdkRegion is empty.
 </para>
 
-@region: 
-@Returns: 
+@region: a #GdkRegion.
+@Returns: TRUE if @region is empty.
 
 
 <!-- ##### FUNCTION gdk_region_equal ##### -->
 <para>
-
+Returns TRUE if the two regions are the same.
 </para>
 
-@region1: 
-@region2: 
-@Returns: 
+@region1: a #GdkRegion.
+@region2: a #GdkRegion.
+@Returns: TRUE if @region1 and @region2 are equal.
 
 
 <!-- ##### FUNCTION gdk_region_point_in ##### -->
 <para>
-
+Returns TRUE if a point is in a region.
 </para>
 
-@region: 
-@x: 
-@y: 
-@Returns: 
+@region: a #GdkRegion.
+@x: the x coordinate of a point.
+@y: the y coordinate of a point.
+@Returns: TRUE if the point is in @region.
 
 
 <!-- ##### FUNCTION gdk_region_rect_in ##### -->
 <para>
-
+Tests whether a rectangle is within a region.
 </para>
 
-@region: 
-@rect: 
-@Returns: 
+@region: a #GdkRegion.
+@rect: a #GdkRectangle.
+@Returns: GDK_OVERLAP_RECTANGLE_IN, GDK_OVERLAP_RECTANGLE_OUT, or
+GDK_OVERLAP_RECTANGLE_PART, depending on whether the rectangle is inside,
+outside, or partly inside the #GdkRegion, respectively.
 
 
 <!-- ##### ENUM GdkOverlapType ##### -->
 <para>
-
+Specifies the possible values returned by gdk_region_rect_in().
 </para>
 
-@GDK_OVERLAP_RECTANGLE_IN: 
-@GDK_OVERLAP_RECTANGLE_OUT: 
-@GDK_OVERLAP_RECTANGLE_PART: 
+@GDK_OVERLAP_RECTANGLE_IN: if the rectangle is inside the #GdkRegion.
+@GDK_OVERLAP_RECTANGLE_OUT: if the rectangle is outside the #GdkRegion.
+@GDK_OVERLAP_RECTANGLE_PART: if the rectangle is partly inside the #GdkRegion.
 
 <!-- ##### FUNCTION gdk_region_polygon ##### -->
 <para>
+Creates a new #GdkRegion using the polygon defined by a number of points.
 
 </para>
 
-@points: 
-@npoints: 
-@fill_rule: 
-@Returns: 
+@points: an array of #GdkPoint structs.
+@npoints: the number of elements in the @points array.
+@fill_rule: specifies which pixels are included in the region when the polygon
+overlaps itself.
+@Returns: a new #GdkRegion based on the given polygon.
 
 
 <!-- ##### FUNCTION gdk_region_offset ##### -->
 <para>
-
+Moves a region.
 </para>
 
-@region: 
-@dx: 
-@dy: 
+@region: a #GdkRegion.
+@dx: the distance to move the region horizontally.
+@dy: the distance to move the region vertically.
 
 
 <!-- ##### FUNCTION gdk_region_shrink ##### -->
 <para>
-
+Resizes a region.
 </para>
 
-@region: 
+@region: a #GdkRegion.
 @dx: 
 @dy: 
 
 
 <!-- ##### FUNCTION gdk_region_union_with_rect ##### -->
 <para>
-
+Returns the union of a region and a rectangle.
 </para>
 
-@region: 
-@rect: 
-@Returns: 
+@region: a #GdkRegion.
+@rect: a #GdkRectangle.
+@Returns: the union of @region and @rect.
 
 
 <!-- ##### FUNCTION gdk_regions_intersect ##### -->
 <para>
-
+Returns the intersection of two regions.
 </para>
 
-@source1: 
-@source2: 
-@Returns: 
+@source1: a #GdkRegion.
+@source2: a #GdkRegion.
+@Returns: the intersection of @source1 and @source2.
 
 
 <!-- ##### FUNCTION gdk_regions_union ##### -->
 <para>
-
+Returns the union of two regions.
+This is all pixels in either of @source1 or @source2.
 </para>
 
-@source1: 
-@source2: 
-@Returns: 
+@source1: a #GdkRegion.
+@source2: a #GdkRegion.
+@Returns: the union of @source1 and @source2.
 
 
 <!-- ##### FUNCTION gdk_regions_subtract ##### -->
 <para>
-
+Subtracts one region from another.
+The result is a region containing all the pixels which are in @source1, but
+which are not in @source2.
 </para>
 
-@source1: 
-@source2: 
-@Returns: 
+@source1: a #GdkRegion.
+@source2: a #GdkRegion to subtract from @source1.
+@Returns: @source1 - @source2.
 
 
 <!-- ##### FUNCTION gdk_regions_xor ##### -->
 <para>
-
+Returns the difference between the union and the intersection of two regions.
+This is a region containing the pixels that are in one of the source regions,
+but which are not in both.
 </para>
 
-@source1: 
-@source2: 
-@Returns: 
+@source1: a #GdkRegion.
+@source2: a #GdkRegion.
+@Returns: the difference between the union and the intersection of @source1
+and @source2.
 
 
diff --git a/docs/reference/gdk/tmpl/rgb.sgml b/docs/reference/gdk/tmpl/rgb.sgml
index 12b8f72d87..928753dc61 100644
--- a/docs/reference/gdk/tmpl/rgb.sgml
+++ b/docs/reference/gdk/tmpl/rgb.sgml
@@ -2,215 +2,449 @@
 GdkRGB
 
 <!-- ##### SECTION Short_Description ##### -->
-
+displays RGB images (as well as grayscale and colormapped) to
+the native window.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
 
+GdkRgb converts RGB, grayscale, and colormapped images into the native
+window pixel format and displays them. It takes care of colormaps,
+visuals, dithering, and management of the temporary buffers.
+
+</para>
+
+<para>
+You must call gdk_rgb_init() before using any GdkRgb functionality. If
+you fail to do so, expect coredumps. All Gtk+ widgets that use GdkRgb
+(including #GtkPreview) call gdk_rgb_init() in their class_init method.
+Thus, if you use GdkRgb only indirectly, you don't need to worry
+about it.
+</para>
+
+<para>
+GdkRgb tries to use the system default visual and colormap, but
+doesn't always succeed. Thus, you have to be prepared to install the
+visual and colormap generated by GdkRgb. The following code sequence
+(before any widgets are created) should work in most applications:
+</para>
+
+<informalexample>
+<programlisting>
+  gdk_rgb_init ();
+
+  gtk_widget_set_default_colormap (gdk_rgb_get_cmap ());
+  gtk_widget_set_default_visual (gdk_rgb_get_visual ());
+</programlisting>
+</informalexample>
+
+<para>
+You can also push the colormap and visual, but in general it doesn't
+work unless the push wraps the window creation call. If you wrap the
+push around a widget which is embedded in a window without the GdkRgb
+colormap and visual, it probably won't work, and is likely to cause
+colormap flashing, as well.
+</para>
+
+<para>
+On 8-bit systems, the colormaps used by Imlib and GdkRgb may
+conflict. There is no good general solution to this other than phasing
+out the dependence on Imlib.
+</para>
+
+<para>
+You can set the threshold for installing colormaps with
+gdk_rgb_set_min_colors (). The default is 5x5x5 (125). If a colorcube
+of this size or larger can be allocated in the default colormap, then
+that's done. Otherwise, GdkRgb creates its own private colormap.
+Setting it to 0 means that it always tries to use the default
+colormap, and setting it to 256 means that it always creates a private
+one. Note, however, that setting it to 0 doesn't let you get away with
+ignoring the colormap and visual - a colormap is always created in
+grayscale and direct color modes, and the visual is changed in cases
+where a "better" visual than the default is available.
 </para>
 
+<example>
+<title>A simple example program using GdkRGB.</title>
+<programlisting>
+#include &lt;gtk/gtk.h&gt;
+
+#define IMAGE_WIDTH	256
+#define IMAGE_HEIGHT	256
+
+guchar rgbbuf[IMAGE_WIDTH * IMAGE_HEIGHT * 3];
+
+gboolean on_darea_expose (GtkWidget *widget,
+			  GdkEventExpose *event,
+			  gpointer user_data);
+
+int
+main (int argc, char *argv[])
+{
+  GtkWidget *window, *darea;
+  gint x, y;
+  guchar *pos;
+
+  gtk_init (&amp;argc, &amp;argv);
+  gdk_rgb_init ();
+  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
+  darea = gtk_drawing_area_new ();
+  gtk_drawing_area_size (GTK_DRAWING_AREA (darea), IMAGE_WIDTH, IMAGE_HEIGHT);
+  gtk_container_add (GTK_CONTAINER (window), darea);
+  gtk_signal_connect (GTK_OBJECT (darea), "expose-event",
+                      GTK_SIGNAL_FUNC (on_darea_expose), NULL);
+  gtk_widget_show_all (window);
+
+  /* Set up the RGB buffer. */
+  pos = rgbbuf;
+  for (y = 0; y < IMAGE_HEIGHT; y++)
+    {
+      for (x = 0; x < IMAGE_WIDTH; x++)
+	{
+	  *pos++ = x - x % 32;			/* Red. */
+	  *pos++ = (x / 32) * 4 + y - y % 32;	/* Green. */
+	  *pos++ = y - y % 32;			/* Blue. */
+	}
+    }
+
+  gtk_main ();
+  return 0;
+}
+
+
+gboolean
+on_darea_expose (GtkWidget *widget,
+		 GdkEventExpose *event,
+		 gpointer user_data)
+{
+  gdk_draw_rgb_image (widget->window, widget->style->fg_gc[GTK_STATE_NORMAL],
+		      0, 0, IMAGE_WIDTH, IMAGE_HEIGHT,
+		      GDK_RGB_DITHER_MAX, rgbbuf, IMAGE_WIDTH * 3);
+}
+</programlisting>
+</example>
+
+
 <!-- ##### SECTION See_Also ##### -->
 <para>
+<variablelist>
+
+<varlistentry>
+<term>#GdkColor</term>
+<listitem><para>The underlying Gdk mechanism for allocating
+colors.</para></listitem>
+</varlistentry>
+
+</variablelist>
 
 </para>
 
 <!-- ##### STRUCT GdkRgbCmap ##### -->
 <para>
-
+A private data structure which maps color indices to actual RGB
+colors. This is used only for gdk_draw_indexed_image().
 </para>
 
-@colors: 
-@lut: 
 
 <!-- ##### ENUM GdkRgbDither ##### -->
 <para>
 
+Selects whether or not GdkRgb applies dithering
+to the image on display. There are three values:
 </para>
 
-@GDK_RGB_DITHER_NONE: 
-@GDK_RGB_DITHER_NORMAL: 
-@GDK_RGB_DITHER_MAX: 
+<itemizedlist>
 
-<!-- ##### FUNCTION gdk_rgb_init ##### -->
+<listitem>
 <para>
+%GDK_RGB_DITHER_NONE: Never use dithering.
+</para>
+</listitem>
 
+<listitem>
+<para>
+%GDK_RGB_DITHER_NORMAL: Use dithering in 8 bits per pixel (and below)
+only.
 </para>
+</listitem>
 
+<listitem>
+<para>
+%GDK_RGB_DITHER_MAX: Use dithering in 16 bits per pixel and below.
+</para>
+</listitem>
 
+</itemizedlist>
 
-<!-- ##### FUNCTION gdk_rgb_cmap_new ##### -->
 <para>
+Since GdkRgb currently only handles images with 8 bits per component,
+dithering on 24 bit per pixel displays is a moot point.
+</para>
+
 
+<!-- ##### FUNCTION gdk_rgb_init ##### -->
+<para>
+Initializes GdkRgb statically. It may be called more than once with no
+ill effects. It must, however, be called before any other GdkRgb
+operations are performed.
 </para>
 
-@colors: 
-@n_colors: 
-@Returns: 
+<para>
+The GdkRgb "context" is allocated statically. Thus, GdkRgb may be used
+to drive only one visual in any given application. GdkRgb
+automatically selects a best visual and sets its own colormap, if
+necessary. gdk_rgb_get_visual() and gdk_rgb_get_cmap () retrieve
+the chosen visual and colormap, respectively.
+</para>
 
 
-<!-- ##### FUNCTION gdk_rgb_cmap_free ##### -->
+<!-- ##### FUNCTION gdk_rgb_cmap_new ##### -->
 <para>
+Creates a new #GdkRgbCmap structure. The cmap maps color indexes to
+RGB colors. If @n_colors is less than 256, then images containing
+color values greater than or equal to @n_colors will produce undefined
+results, including possibly segfaults.
+</para>
 
+@colors: The colors, represented as 0xRRGGBB integer values.
+@n_colors: The number of colors in the cmap.
+@Returns: The newly created #GdkRgbCmap
+
+
+<!-- ##### FUNCTION gdk_rgb_cmap_free ##### -->
+<para>
+Frees the memory associated with a #GdkRgbCmap created by gdk_rgb_cmap_new().
 </para>
 
-@cmap: 
+@cmap: The #GdkRgbCmap to free.
 
 
 <!-- ##### FUNCTION gdk_rgb_gc_set_foreground ##### -->
 <para>
-
+Sets the foreground color in @gc to the specified color (or the
+closest approximation, in the case of limited visuals).
 </para>
 
-@gc: 
-@rgb: 
+@gc: The @GdkGC to modify.
+@rgb: The color, represented as a 0xRRGGBB integer value.
 
 
 <!-- ##### FUNCTION gdk_rgb_gc_set_background ##### -->
 <para>
-
+Sets the background color in @gc to the specified color (or the
+closest approximation, in the case of limited visuals).
 </para>
 
-@gc: 
-@rgb: 
+@gc: The @GdkGC to modify.
+@rgb: The color, represented as a 0xRRGGBB integer value.
 
 
 <!-- ##### FUNCTION gdk_draw_rgb_image ##### -->
 <para>
+Draws an RGB image in the drawable. This is the core GdkRgb
+function, and likely the only one you will need to use other than the
+initialization stuff.
+</para>
+
+<para>
+The @rowstride parameter allows for lines to be aligned more flexibly.
+For example, lines may be allocated to begin on 32-bit boundaries,
+even if the width of the rectangle is odd. Rowstride is also useful
+when drawing a subrectangle of a larger image in memory. Finally, to
+replicate the same line a number of times, the trick of setting
+@rowstride to 0 is allowed.
+</para>
 
+<para>
+In general, for 0 &lt;= i &lt; @width and 0 &lt;= j &lt; height,
+the pixel (x + i, y + j) is colored with red value @rgb_buf[@j *
+@rowstride + @i * 3], green value @rgb_buf[@j * @rowstride + @i * 3 +
+1], and blue value @rgb_buf[@j * @rowstride + @i * 3 + 2].
 </para>
 
-@drawable: 
-@gc: 
-@x: 
-@y: 
-@width: 
-@height: 
-@dith: 
-@rgb_buf: 
-@rowstride: 
+@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
+@gc: The graphics context (all Gdk drawing operations require one; its
+contents are ignored).
+@x: The x coordinate of the top-left corner in the drawable.
+@y: The y coordinate of the top-left corner in the drawable.
+@width: The width of the rectangle to be drawn.
+@height: The height of the rectangle to be drawn.
+@dith: A #GdkRgbDither value, selecting the desired dither mode. 
+@rgb_buf: The pixel data, represented as packed 24-bit data.
+@rowstride: The number of bytes from the start of one row in @rgb_buf to the
+start of the next.
 
 
 <!-- ##### FUNCTION gdk_draw_indexed_image ##### -->
 <para>
-
+Draws an indexed image in the drawable, using a #GdkRgbCmap to assign
+actual colors to the color indices.
 </para>
 
-@drawable: 
-@gc: 
-@x: 
-@y: 
-@width: 
-@height: 
-@dith: 
-@buf: 
-@rowstride: 
-@cmap: 
+@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
+@gc: The graphics context.
+@x: The x coordinate of the top-left corner in the drawable.
+@y: The y coordinate of the top-left corner in the drawable.
+@width: The width of the rectangle to be drawn.
+@height: The height of the rectangle to be drawn.
+@dith: A #GdkRgbDither value, selecting the desired dither mode. 
+@buf: The pixel data, represented as 8-bit color indices.
+@rowstride: The number of bytes from the start of one row in @buf to the
+start of the next.
+@cmap: The #GdkRgbCmap used to assign colors to the color indices.
 
 
 <!-- ##### FUNCTION gdk_draw_gray_image ##### -->
 <para>
+Draws a grayscale image in the drawable.
 
 </para>
 
-@drawable: 
-@gc: 
-@x: 
-@y: 
-@width: 
-@height: 
-@dith: 
-@buf: 
-@rowstride: 
+
+@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
+@gc: The graphics context.
+@x: The x coordinate of the top-left corner in the drawable.
+@y: The y coordinate of the top-left corner in the drawable.
+@width: The width of the rectangle to be drawn.
+@height: The height of the rectangle to be drawn.
+@dith: A #GdkRgbDither value, selecting the desired dither mode. 
+@buf: The pixel data, represented as 8-bit gray values.
+@rowstride: The number of bytes from the start of one row in @buf to the
+start of the next.
 
 
 <!-- ##### FUNCTION gdk_draw_rgb_32_image ##### -->
 <para>
+Draws a padded RGB image in the drawable. The image is stored as one
+pixel per 32-bit word. It is laid out as a red byte, a green byte, a
+blue byte, and a padding byte.
+</para>
 
+<para>
+It's unlikely that this function will give significant performance
+gains in practice. In my experience, the performance gain from having
+pixels aligned to 32-bit boundaries is cancelled out by the increased
+memory bandwidth.
 </para>
 
-@drawable: 
-@gc: 
-@x: 
-@y: 
-@width: 
-@height: 
-@dith: 
-@buf: 
-@rowstride: 
+@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
+@gc: The graphics context.
+@x: The x coordinate of the top-left corner in the drawable.
+@y: The y coordinate of the top-left corner in the drawable.
+@width: The width of the rectangle to be drawn.
+@height: The height of the rectangle to be drawn.
+@dith: A #GdkRgbDither value, selecting the desired dither mode. 
+@buf: The pixel data, represented as padded 32-bit data.
+@rowstride: The number of bytes from the start of one row in @buf to the
+start of the next.
 
 
 <!-- ##### FUNCTION gdk_draw_rgb_image_dithalign ##### -->
 <para>
+Draws an RGB image in the drawable, with an adjustment for dither alignment.
+</para>
+
+<para>
+This function is useful when drawing dithered images into a window
+that may be scrolled. Pixel (x, y) will be drawn dithered as if its
+actual location is (x + @xdith, y + @ydith). Thus, if you draw an
+image into a window using zero dither alignment, then scroll up one
+pixel, subsequent draws to the window should have @ydith = 1.
+</para>
 
+<para>
+Setting the dither alignment correctly allows updating of small parts
+of the screen while avoiding visible "seams" between the different
+dither textures.
 </para>
 
-@drawable: 
-@gc: 
-@x: 
-@y: 
-@width: 
-@height: 
-@dith: 
-@rgb_buf: 
-@rowstride: 
-@xdith: 
-@ydith: 
+@drawable: The #GdkDrawable to draw in (usually a #GdkWindow).
+@gc: The graphics context.
+@x: The x coordinate of the top-left corner in the drawable.
+@y: The y coordinate of the top-left corner in the drawable.
+@width: The width of the rectangle to be drawn.
+@height: The height of the rectangle to be drawn.
+@dith: A #GdkRgbDither value, selecting the desired dither mode. 
+@rgb_buf: The pixel data, represented as packed 24-bit data.
+@rowstride: The number of bytes from the start of one row in @rgb_buf to the
+start of the next.
+@xdith: An x offset for dither alignment.
+@ydith: A y offset for dither alignment.
 
 
 <!-- ##### FUNCTION gdk_rgb_xpixel_from_rgb ##### -->
 <para>
-
+Finds the X pixel closest in color to the @rgb color specified. This
+value may be used to set the <structfield>pixel</structfield> field of
+a #GdkColor struct.
 </para>
 
-@rgb: 
-@Returns: 
+@rgb: The color, represented as a 0xRRGGBB integer value.
+@Returns: The X pixel value.
 
 
 <!-- ##### FUNCTION gdk_rgb_set_verbose ##### -->
 <para>
-
+Sets the "verbose" flag. This is generally only useful for debugging.
 </para>
 
-@verbose: 
+@verbose: TRUE if verbose messages are desired.
 
 
 <!-- ##### FUNCTION gdk_rgb_ditherable ##### -->
 <para>
-
+Determine whether the visual is ditherable. This function may be
+useful for presenting a user interface choice to the user about which
+dither mode is desired; if the display is not ditherable, it may make
+sense to gray out or hide the corresponding UI widget.
 </para>
 
-@Returns: 
+@Returns: TRUE if the visual is ditherable.
 
 
 <!-- ##### FUNCTION gdk_rgb_set_install ##### -->
 <para>
+If @install is TRUE, directs GdkRgb to always install a new "private"
+colormap rather than trying to find a best fit with the colors already
+allocated. Ordinarily, GdkRgb will install a colormap only if a
+sufficient cube cannot be allocated.
+</para>
 
+<para>
+A private colormap has more colors, leading to better quality display,
+but also leads to the dreaded "colormap flashing" effect.
 </para>
 
-@install: 
+@install: TRUE to set install mode.
 
 
 <!-- ##### FUNCTION gdk_rgb_set_min_colors ##### -->
 <para>
-
+Sets the minimum number of colors for the color cube. Generally,
+GdkRgb tries to allocate the largest color cube it can. If it can't
+allocate a color cube at least as large as @min_colors, it installs a
+private colormap.
 </para>
 
-@min_colors: 
+@min_colors: The minimum number of colors accepted.
 
 
 <!-- ##### FUNCTION gdk_rgb_get_visual ##### -->
 <para>
-
+Gets the visual chosen by GdkRgb. This visual and the corresponding
+colormap should be used when creating windows that will be drawn in by GdkRgb.
 </para>
 
-@Returns: 
+@Returns: The @GdkVisual chosen by GdkRgb.
 
 
 <!-- ##### FUNCTION gdk_rgb_get_cmap ##### -->
 <para>
-
+Gets the colormap set by GdkRgb. This colormap and the corresponding
+visual should be used when creating windows that will be drawn in by GdkRgb.
 </para>
 
-@Returns: 
+@Returns: The @GdkColormap set by GdkRgb.
 
 
diff --git a/docs/reference/gtk/tmpl/gtkbbox.sgml b/docs/reference/gtk/tmpl/gtkbbox.sgml
index 834df6912f..4d77c5b258 100644
--- a/docs/reference/gtk/tmpl/gtkbbox.sgml
+++ b/docs/reference/gtk/tmpl/gtkbbox.sgml
@@ -1,159 +1,195 @@
-<!-- ##### SECTION Title ##### -->
-GtkButtonBox
-
-<!-- ##### SECTION Short_Description ##### -->
-
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### STRUCT GtkButtonBox ##### -->
-<para>
-
-</para>
-
-@box: 
-@spacing: 
-@child_min_width: 
-@child_min_height: 
-@child_ipad_x: 
-@child_ipad_y: 
-@layout_style: 
-
-<!-- ##### MACRO GTK_BUTTONBOX_DEFAULT ##### -->
-<para>
-
-</para>
-
-
-
-<!-- ##### FUNCTION gtk_button_box_get_child_size_default ##### -->
-<para>
-
-</para>
-
-@min_width: 
-@min_height: 
-
-
-<!-- ##### FUNCTION gtk_button_box_get_child_ipadding_default ##### -->
-<para>
-
-</para>
-
-@ipad_x: 
-@ipad_y: 
-
-
-<!-- ##### FUNCTION gtk_button_box_set_child_size_default ##### -->
-<para>
-
-</para>
-
-@min_width: 
-@min_height: 
-
-
-<!-- ##### FUNCTION gtk_button_box_set_child_ipadding_default ##### -->
-<para>
-
-</para>
-
-@ipad_x: 
-@ipad_y: 
-
-
-<!-- ##### FUNCTION gtk_button_box_get_spacing ##### -->
-<para>
-
-</para>
-
-@widget: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_button_box_get_layout ##### -->
-<para>
-
-</para>
-
-@widget: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_button_box_get_child_size ##### -->
-<para>
-
-</para>
-
-@widget: 
-@min_width: 
-@min_height: 
-
-
-<!-- ##### FUNCTION gtk_button_box_get_child_ipadding ##### -->
-<para>
-
-</para>
-
-@widget: 
-@ipad_x: 
-@ipad_y: 
-
-
-<!-- ##### FUNCTION gtk_button_box_set_spacing ##### -->
-<para>
-
-</para>
-
-@widget: 
-@spacing: 
-
-
-<!-- ##### FUNCTION gtk_button_box_set_layout ##### -->
-<para>
-
-</para>
-
-@widget: 
-@layout_style: 
-
-
-<!-- ##### FUNCTION gtk_button_box_set_child_size ##### -->
-<para>
-
-</para>
-
-@widget: 
-@min_width: 
-@min_height: 
-
-
-<!-- ##### FUNCTION gtk_button_box_set_child_ipadding ##### -->
-<para>
-
-</para>
-
-@widget: 
-@ipad_x: 
-@ipad_y: 
-
-
-<!-- ##### FUNCTION gtk_button_box_child_requisition ##### -->
-<para>
-
-</para>
-
-@widget: 
-@nvis_children: 
-@width: 
-@height: 
-
-
+<!-- ##### SECTION Title ##### -->

+GtkButtonBox

+

+<!-- ##### SECTION Short_Description ##### -->

+Base class for #GtkHButtonBox and #GtkVButtonBox

+

+<!-- ##### SECTION Long_Description ##### -->

+<para>

+The primary purpose of this class is to keep track of the various properties

+of #GtkHButtonBox and #GtkVButtonBox widgets.

+</para>

+<para>

+gtk_button_box_get_child_size_default() retrieves the default minimum width and height 

+for widgets in any button box. gtk_button_box_set_child_size_default()

+changes the default minimum child widget size.

+</para>

+<para>

+gtk_button_box_get_child_size() retrieves the minimum width and height 

+for widgets in a given button box. gtk_button_box_set_child_size() 

+allows those properties to be changed.

+</para>

+<para>

+gtk_button_box_get_child_ipadding_default() gets the default number of pixels of 

+horizontal and vertical padding that are applied to each button in every button box.

+gtk_button_box_set_child_ipadding_default() allows these defaults to be

+changed.

+</para>

+<para>

+The internal padding of buttons can be retrieved and changed per button box using

+gtk_button_box_get_child_ipadding() and gtk_button_box_set_child_ipadding()

+respectively.

+</para>

+<para>

+gtk_button_box_get_spacing() and gtk_button_box_set_spacing() retrieve and

+change default number of pixels between buttons, respectively.

+</para>

+<para>

+gtk_button_box_get_layout() and gtk_button_box_set_layout() retrieve and alter the method

+used to spread the buttons in a button box across the container, respectively.

+</para>

+

+<para>

+

+</para>

+

+<!-- ##### SECTION See_Also ##### -->

+<para>

+<variablelist>

+<varlistentry>

+<term>#GtkVButtonBox</term>

+<listitem><para>Vertical sub-class of #GtkButtonBox.</para></listitem>

+</varlistentry>

+<varlistentry>

+<term>#GtkHButtonBox</term>

+<listitem><para>Horizontal sub-class of #GtkButtonBox.</para></listitem>

+</varlistentry>

+</variablelist>

+</para>

+

+<!-- ##### STRUCT GtkButtonBox ##### -->

+<para>

+This is a read-only struct; no members should be modified directly.

+</para>

+

+

+<!-- ##### MACRO GTK_BUTTONBOX_DEFAULT ##### -->

+<para>

+Used internally only.

+</para>

+

+

+

+<!-- ##### FUNCTION gtk_button_box_get_child_size_default ##### -->

+<para>

+Retrieves the default minimum width and height for all button boxes, and

+places the values in @min_width and @min_height, respectively.

+</para>

+

+@min_width: the default minimum width of a child widget.

+@min_height: the default minimum height of a child widget.

+

+

+<!-- ##### FUNCTION gtk_button_box_get_child_ipadding_default ##### -->

+<para>

+The internal padding of a button is the amount of space between the outside

+of the button and the widget it contains. This function gets the default

+amount of horizontal and vertical padding, placing the results in @ipad_x

+and @ipad_y, respectively.

+</para>

+

+@ipad_x: the default horizontal internal button padding.

+@ipad_y: the default vertical internal button padding.

+

+

+<!-- ##### FUNCTION gtk_button_box_set_child_size_default ##### -->

+<para>

+Sets the default size of child buttons.

+</para>

+

+@min_width: minimum default width for child buttons.

+@min_height: minimum default height for child buttons.

+

+

+<!-- ##### FUNCTION gtk_button_box_set_child_ipadding_default ##### -->

+<para>

+Sets the default number of pixels that pad each button in every button box.

+</para>

+

+@ipad_x: new default horizontal padding.

+@ipad_y: new default vertical padding.

+

+

+<!-- ##### FUNCTION gtk_button_box_get_spacing ##### -->

+<para>

+Retrieves how much space a button box is placing between each child button.

+</para>

+

+@widget: a #GtkButtonBox.

+@Returns: the current spacing applied to the buttons in @widget.

+

+

+<!-- ##### FUNCTION gtk_button_box_get_layout ##### -->

+<para>

+Retrieves the method being used to arrange the buttons in a button box.

+</para>

+

+@widget: a #GtkButtonBox.

+@Returns: the method used to layout buttons in @widget.

+

+

+<!-- ##### FUNCTION gtk_button_box_get_child_size ##### -->

+<para>

+Retrieves the current width and height of all child widgets in a button box.

+@min_width and @min_height are filled with those values, respectively.

+</para>

+

+@widget: a #GtkButtonBox.

+@min_width: the width of the buttons contained by @widget.

+@min_height: the height of the buttons contained by @widget.

+

+

+<!-- ##### FUNCTION gtk_button_box_get_child_ipadding ##### -->

+<para>

+Gets the default number of pixels that pad the buttons in a given button box.

+</para>

+

+@widget: a #GtkButtonBox.

+@ipad_x: the horizontal padding used by buttons in @widget.

+@ipad_y: the vertical padding used by buttons in @widget.

+

+

+<!-- ##### FUNCTION gtk_button_box_set_spacing ##### -->

+<para>

+Sets the amount of spacing between buttons in a given button box.

+</para>

+

+@widget: a #GtkButtonBox.

+@spacing: the number of pixels of spacing.

+

+

+<!-- ##### FUNCTION gtk_button_box_set_layout ##### -->

+<para>

+Changes the way buttons are arranged in their container.

+</para>

+

+@widget: a #GtkButtonBox.

+@layout_style: the new layout style.

+

+

+<!-- ##### FUNCTION gtk_button_box_set_child_size ##### -->

+<para>

+Sets a new default size for the children of a given button box.

+</para>

+

+@widget: a #GtkButtonBox.

+@min_width: a default width for buttons in @widget.

+@min_height: a default height for buttons in @widget.

+

+

+<!-- ##### FUNCTION gtk_button_box_set_child_ipadding ##### -->

+<para>

+Changes the amount of internal padding used by all buttons in a given button

+box.

+</para>

+

+@widget: a #GtkButtonBox.

+@ipad_x: the horizontal padding that should be used by each button in @widget.

+@ipad_y: the vertical padding that should be used by each button in @widget.

+

+

+<!-- ##### FUNCTION gtk_button_box_child_requisition ##### -->

+<para>

+This is an internally used function and should never be called from an

+application.

+</para>