Resurrect 1.2 documentation. (#62604)

* gdk/tmpl/visuals.sgml: Resurrect 1.2 documentation. (#62604)

        * gtk/tmpl/gtkpaned.sgml: Fixes. (#62146)

        * gtk/tmpl/gtkgamma.sgml: Fixes. (#62155)

        * gtk/Makefile.am (IGNORE_HFILES): Add xembed.h (#61929)

docs/reference/ChangeLog

@@ -1,5 +1,13 @@
 2001-10-18  Matthias Clasen   <matthiasc@poet.de>
 
+	* gdk/tmpl/visuals.sgml: Resurrect 1.2 documentation. (#62604)
+
+	* gtk/tmpl/gtkpaned.sgml: Fixes. (#62146)
+
+	* gtk/tmpl/gtkgamma.sgml: Fixes. (#62155)
+
+	* gtk/Makefile.am (IGNORE_HFILES): Add xembed.h (#61929)
+
 	* gdk-pixbuf/gdk-pixbuf.types: Add GdkPixbuf, 
 	GdkPixbufAnimation and GdkPixbufAnimationIter. (#62590)
 

docs/reference/gdk/gdk-sections.txt

@@ -439,7 +439,6 @@ GDK_TYPE_SUBWINDOW_MODE
 <TITLE>Visuals</TITLE>
 <FILE>visuals</FILE>
 GdkVisual
-GdkVisualClass
 GdkVisualType
 GdkByteOrder
 gdk_query_depths
@@ -462,6 +461,7 @@ GDK_TYPE_VISUAL_TYPE
 GDK_TYPE_VISUAL
 GDK_IS_VISUAL
 GDK_IS_VISUAL_CLASS
+GdkVisualClass
 GDK_VISUAL
 GDK_VISUAL_CLASS
 GDK_VISUAL_GET_CLASS

docs/reference/gdk/tmpl/visuals.sgml

@@ -7,13 +7,15 @@ Low-level display hardware information
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-A #GdkVisual describes a particular video hardware display format.  For example,
+A #GdkVisual describes a particular video hardware display format. It includes
-a piece of display hardware might support 24-bit color, 16-bit color, or 8-bit
+information about the number of bits used for each color, the way the bits are
-color; meaning 24/16/8-bit pixel sizes. For a given pixel size, pixels can be in
+translated into an RGB value for display, and the way the bits are stored in 
-different formats; for example the "red" element of an RGB pixel may be in the
+memory. For example, a piece of display hardware might support 24-bit color, 
-top 8 bits of the pixel, or may be in the lower 4 bits.
+16-bit color, or 8-bit color; meaning 24/16/8-bit pixel sizes. For a given 
+pixel size, pixels can be in different formats; for example the "red" element 
+of an RGB pixel may be in the top 8 bits of the pixel, or may be in the lower 
+4 bits.
 </para>
-
 <para>
 Usually you can avoid thinking about visuals in GTK+. Visuals are useful to
 interpret the contents of a #GdkImage, but you should avoid #GdkImage precisely
@@ -22,65 +24,134 @@ all but the most low-level purposes. Also, anytime you provide a #GdkColormap,
 the visual is implied as part of the colormap (gdk_colormap_get_visual()), so
 you won't have to provide a visual in addition.
 </para>
+<para>
+There are several standard visuals. The visual returned
+by gdk_visual_get_system() is the system's default
+visual. gdk_rgb_get_visual() return the visual most
+suited to displaying full-color image data. If you
+use the calls in #GdkRGB, you should create your windows
+using this visual (and the colormap returned by
+gdk_rgb_get_colormap()).
+</para>
+<para>
+A number of functions are provided for determining
+the "best" available visual. For the purposes of
+making this determination, higher bit depths are
+considered better, and for visuals of the same
+bit depth, %GDK_VISUAL_PSEUDO_COLOR is preferred at
+8bpp, otherwise, the visual types are ranked in the
+order of (highest to lowest) %GDK_VISUAL_DIRECT_COLOR,
+%GDK_VISUAL_TRUE_COLOR, %GDK_VISUAL_PSEUDO_COLOR,
+%GDK_VISUAL_STATIC_COLOR, %GDK_VISUAL_GRAYSCALE,
+then %GDK_VISUAL_STATIC_GRAY.
+</para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-#GdkImage, #GdkColormap
+#GdkImage, #GdkColormap, #GdkRGB
 </para>
 
 <!-- ##### STRUCT GdkVisual ##### -->
 <para>
-Description of an image data format
+The <type>GdkVisual</type> structure contains information about
+a particular visual.
 </para>
 
+<figure float="1" id="rgbmask">
+<title>Constructing a pixel value from components</title>
+<programlisting>
+guint
+pixel_from_rgb (GdkVisual *visual,
+                guchar r, guchar b, guchar g)
+{
+  return ((r >> (16 - visual->red_prec))   << visual->red_shift) |
+         ((g >> (16 - visual->green_prec)) << visual->green_shift) |
+         ((r >> (16 - visual->blue_prec))  << visual->blue_shift);
+}
+</programlisting>
+</figure>
+
 @parent_instance: inherited portion from #GObject
-@type: 
+@type: The type of this visual. 
-@depth: 
+@depth: The number of bits per pixel.
-@byte_order: 
+@byte_order: The byte-order for this visual.
-@colormap_size: 
+@colormap_size: The number of entries in the colormap, for
-@bits_per_rgb: 
+    visuals of type %GDK_VISUAL_PSEUDO_COLOR or
-@red_mask: 
+    %GDK_VISUAL_GRAY_SCALE. For other visual types, it
-@red_shift: 
+    is the number of possible levels per color component.
-@red_prec: 
+    If the visual has different numbers of levels for
-@green_mask: 
+    different components, the value of this field is undefined.
-@green_shift: 
+@bits_per_rgb: The number of significant bits per red, green, or blue
-@green_prec: 
+    when specifying colors for this visual. (For instance, for 
-@blue_mask: 
+    gdk_colormap_alloc_color())
-@blue_shift: 
+@red_mask: A mask giving the bits in a pixel value that
-@blue_prec: 
+    correspond to the red field. Significant only for
-
+    %GDK_VISUAL_PSEUDOCOLOR and %GDK_VISUAL_DIRECTCOLOR.
-<!-- ##### STRUCT GdkVisualClass ##### -->
+@red_shift: The <structfield>red_shift</structfield> and
-<para>
+    <structfield>red_prec</structfield> give an alternate presentation
-
+    of the information in <structfield>red_mask</structfield>.
-</para>
+    <structfield>red_mask</structfield> is a contiguous sequence
+    of <structfield>red_prec</structfield> bits starting at bit
+    number <structfield>red_shift</structfield>. For example,
+    <xref linkend="rgbmask"> shows constructing a pixel value
+    out of three 16 bit color values.
+@red_prec: See above.
+@green_mask: A mask giving the bits in a pixel value that
+    correspond to the green field.
+@green_shift: The <structfield>green_shift</structfield> and
+    <structfield>green_prec</structfield> give an alternate presentation
+    of the information in <structfield>green_mask</structfield>.
+@green_prec: See above.
+@blue_mask: A mask giving the bits in a pixel value that
+    correspond to the blue field.
+@blue_shift: The <structfield>blue_shift</structfield> and
+    <structfield>blue_prec</structfield> give an alternate presentation
+    of the information in <structfield>blue_mask</structfield>.
+@blue_prec: See above.
 
 
 <!-- ##### ENUM GdkVisualType ##### -->
 <para>
-
+A set of values that describe the manner in which the
+pixel values for a visual are converted into RGB
+values for display.
 </para>
 
-@GDK_VISUAL_STATIC_GRAY: 
+@GDK_VISUAL_STATIC_GRAY: Each pixel value indexes a grayscale value directly.
-@GDK_VISUAL_GRAYSCALE: 
+@GDK_VISUAL_GRAYSCALE: Each pixel is an index into a color map that maps pixel 
-@GDK_VISUAL_STATIC_COLOR: 
+   values into grayscale values. The color map can be changed by an application.
-@GDK_VISUAL_PSEUDO_COLOR: 
+@GDK_VISUAL_STATIC_COLOR: Each pixel value is an index into a predefined,
-@GDK_VISUAL_TRUE_COLOR: 
+   unmodifiable color map that maps pixel values into RGB values.
-@GDK_VISUAL_DIRECT_COLOR: 
+@GDK_VISUAL_PSEUDO_COLOR: Each pixel is an index into a color map that maps
+   pixel values into rgb values. The color map can be changed by an application.
+@GDK_VISUAL_TRUE_COLOR: Each pixel value directly contains red, green,
+   and blue components. The <structfield>red_mask</structfield>,
+   <structfield>green_mask</structfield>, and 
+   <structfield>blue_mask</structfield> fields of the #GdkVisual
+   structure describe how the components are assembled into a pixel value.
+@GDK_VISUAL_DIRECT_COLOR: Each pixel value contains red, green, and blue
+   components as for %GDK_TRUE_COLOR, but the components are mapped via a 
+   color table into the final output table instead of being converted directly. 
 
 <!-- ##### ENUM GdkByteOrder ##### -->
 <para>
-
+A set of values describing the possible byte-orders
+for storing pixel values in memory.
 </para>
 
-@GDK_LSB_FIRST: 
+@GDK_LSB_FIRST: The values are stored with the least-significant byte
-@GDK_MSB_FIRST: 
+  first. For instance, the 32-bit value 0xffeecc would be stored
+  in memory as 0xcc, 0xee, 0xff, 0x00. 
+@GDK_MSB_FIRST: The values are stored with the most-significant byte
+first. For instance, the 32-bit value 0xffeecc would be stored
+in memory as 0x00, 0xcc, 0xee, 0xff.
 
 <!-- ##### FUNCTION gdk_query_depths ##### -->
 <para>
 
 </para>
 
-@depths: 
+@depths:
 @count: 
 
 
@@ -90,7 +161,7 @@ Description of an image data format
 </para>
 
 @visual_types: 
-@count: 
+@count:
 
 
 <!-- ##### FUNCTION gdk_list_visuals ##### -->
@@ -98,7 +169,7 @@ Description of an image data format
 
 </para>
 
-@Returns: 
+@Returns:
 
 
 <!-- ##### FUNCTION gdk_visual_get_best_depth ##### -->
@@ -106,7 +177,7 @@ Description of an image data format
 
 </para>
 
-@Returns: 
+@Returns:
 
 
 <!-- ##### FUNCTION gdk_visual_get_best_type ##### -->
@@ -122,7 +193,7 @@ Description of an image data format
 
 </para>
 
-@Returns: 
+@Returns:
 
 
 <!-- ##### FUNCTION gdk_visual_get_best ##### -->
@@ -130,7 +201,7 @@ Description of an image data format
 
 </para>
 
-@Returns: 
+@Returns:
 
 
 <!-- ##### FUNCTION gdk_visual_get_best_with_depth ##### -->

docs/reference/gtk/Makefile.am

@@ -45,7 +45,8 @@ IGNORE_HFILES=			\
 	gtktextsegment.h	\
 	gtktexttagprivate.h	\
 	gtktexttypes.h		\
-	gtktypebuiltins.h
+	gtktypebuiltins.h	\
+	xembed.h
 
 # Images to copy into HTML directory
 HTML_IMAGES =

docs/reference/gtk/tmpl/gtkgamma.sgml

@@ -15,13 +15,13 @@ a subclass of #GtkCurve for editing gamma curves.
  distribution.
 </para>
 <para>
-The #GtkGammaCurve widget is a subclass of #GtkCurve specifically for
+The #GtkGammaCurve widget is a variant of #GtkCurve specifically for
 editing gamma curves, which are used in graphics applications such as the
 Gimp.
 </para>
 <para>
-The #GammaCurve widget shows a curve which the user can edit with the mouse
+The #GtkGammaCurve widget shows a curve which the user can edit with the 
-just like a #GtkCurve widget. On the right of the curve it also displays
+mouse just like a #GtkCurve widget. On the right of the curve it also displays
 5 buttons, 3 of which change between the 3 curve modes (spline, linear and
 free), and the other 2 set the curve to a particular gamma value, or reset it
 to a straight line.
@@ -34,7 +34,7 @@ to a straight line.
 
 <!-- ##### STRUCT GtkGammaCurve ##### -->
 <para>
-The #GtkGammaCurve-struct struct contains private data only, and
+The #GtkGammaCurve struct contains private data only, and
 should be accessed using the functions below.
 </para>
 

docs/reference/gtk/tmpl/gtkpaned.sgml

@@ -79,7 +79,7 @@ Add a child to the top or left pane with
 default parameters. This is equivalent
 to
 <programlisting>
-gtk_paned_pack1(paned, FALSE, TRUE);
+gtk_paned_pack1(paned, child, FALSE, TRUE);
 </programlisting>
 </para>
 
@@ -92,7 +92,7 @@ gtk_paned_pack1(paned, FALSE, TRUE);
 Add a child to the bottom or right pane with default
 parameters. This is equivalent to 
 <programlisting>
-gtk_paned_pack1(paned, FALSE, FALSE);
+gtk_paned_pack2(paned, child, TRUE, TRUE);
 </programlisting>
 </para>