sgml fixes

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

	* gtk/running.sgml: sgml fixes

	* gtk/tmpl/gtksignal.sgml: sgml fixes

	* gtk/tmpl/gtklabel.sgml: do the intro section

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

	* gtk/gtklabel.c: put in more links to Pango markup format docs
	(gtk_label_set_justify): mention gtk_misc_set_alignment

8 files changed, 158 insertions, 23 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 838711553d..7210bd3087 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,11 @@
+2002-01-11  Havoc Pennington  <hp@pobox.com>
+
+	* gtk/running.sgml: sgml fixes
+
+	* gtk/tmpl/gtksignal.sgml: sgml fixes
+
+	* gtk/tmpl/gtklabel.sgml: do the intro section
+
 2002-01-09  Matthias Clasen  <matthiasc@poet.de>
 
 	* gtk/tmpl/gtkaccellabel.sgml: Remove duplicate docs.
diff --git a/docs/reference/gtk/running.sgml b/docs/reference/gtk/running.sgml
index 5cdf669b59..a73f775430 100644
--- a/docs/reference/gtk/running.sgml
+++ b/docs/reference/gtk/running.sgml
@@ -20,8 +20,9 @@ How to run and debug your GTK+ application
 
 <para>
 All GTK+ applications support a number of standard commandline
-options. These are removed from <literal>argv</literal> by 
-gtk_init(). Modules may parse and remove further options.
+options. These are removed from <literal>argv</literal> by <link
+linkend="gtk-init">gtk_init()</link>. Modules may parse and remove
+further options.
 </para>
 
 <formalpara>
@@ -37,7 +38,10 @@ A list of modules to load in addition to those specified in the
 <title><systemitem>--g-fatal-warnings</systemitem></title>
 
 <para>
-Make GTK+ abort on all warnings.
+Make GTK+ abort on all warnings. This is useful to stop on the first
+warning in a debugger, if your application is printing multiple
+warnings.  It's almost always best to start debugging with the first
+warning that occurs.
 </para>
 </formalpara>
 
@@ -188,7 +192,7 @@ or <envar>DISPLAY</envar>; mostly to determine paths to look for certain files.
       <listitem><para>Visual feedback about window updates</para></listitem>
     </varlistentry>
   </variablelist>
-  The special value <term>all</term> can be used to turn on all debug options.
+  The special value <literal>all</literal> can be used to turn on all debug options.
   </para>
 </formalpara>
 
@@ -209,7 +213,7 @@ or <envar>DISPLAY</envar>; mostly to determine paths to look for certain files.
     (If <envar>GTK_EXE_PREFIX</envar> is defined, &lt;libdir&gt; is 
     <filename>$GTK_EXE_PREFIX/lib</filename>. Otherwise it is the libdir
     specified when GTK+ was configured, usually 
-    <filename>/usr/local/lib</libdir>.) 
+    <filename>/usr/local/lib</filename>.) 
     For each directory in the list, GTK+ actually looks first in 
     a subdirectory named after the version number of GTK+, then in the 
     directory itself and finally in the system-specific library path.
@@ -247,9 +251,9 @@ or <envar>DISPLAY</envar>; mostly to determine paths to look for certain files.
     the RC files, which in turn overwrites the default value 
     <filename>&lt;sysconfdir&gt;/gtk-2.0/gtk.immodules</filename>
     (&lt;sysconfdir&gt; is the sysconfdir specified when GTK+ was configured, 
-     usually <filename>/usr/local/etc</libdir>.)
+     usually <filename>/usr/local/etc</filename>.)
   </para>
-<formalpara>
+</formalpara>
 
 <formalpara>
   <title><envar>GTK_RC_FILES</envar></title>
@@ -257,6 +261,7 @@ or <envar>DISPLAY</envar>; mostly to determine paths to look for certain files.
   <para>
     Specifies a list of RC files to parse instead of the default ones;
     see <link linkend="gtk-Resource-Files">Resource Files</link>.
+  </para>
 </formalpara>
 
 <formalpara>
@@ -272,7 +277,7 @@ or <envar>DISPLAY</envar>; mostly to determine paths to look for certain files.
   <title><envar>GTK_DATA_PREFIX</envar></title>
 
   <para>
-    If set, makes GTK+ use <filename>$GTK_DATA_PREFIX<filename>
+    If set, makes GTK+ use <filename>$GTK_DATA_PREFIX</filename>
     instead of the prefix configured when GTK+ was compiled.
   </para>
 </formalpara>
@@ -318,7 +323,7 @@ nevertheless.
       <listitem><para>Information about XIM support</para></listitem>
     </varlistentry>
   </variablelist>
-  The special value <term>all</term> can be used to turn on all debug options.
+  The special value <literal>all</literal> can be used to turn on all debug options.
   </para>
 </formalpara>
 
diff --git a/docs/reference/gtk/tmpl/gtk-unused.sgml b/docs/reference/gtk/tmpl/gtk-unused.sgml
index 456bfeb3dd..a3bb8b493e 100644
--- a/docs/reference/gtk/tmpl/gtk-unused.sgml
+++ b/docs/reference/gtk/tmpl/gtk-unused.sgml
@@ -2550,12 +2550,6 @@ Internal function used by #GtkHPaned and #GtkVPaned
 @child1_req: 
 @child2_req: 
 
-<!-- ##### MACRO gtk_paned_handle_size ##### -->
-<para>
-Old name for gtk_paned_set_handle_size().
-</para>
-
-
 <!-- ##### FUNCTION gtk_paned_set_handle_size ##### -->
 <para>
 Set the the handle size to @size x @size pixels.
diff --git a/docs/reference/gtk/tmpl/gtkaccellabel.sgml b/docs/reference/gtk/tmpl/gtkaccellabel.sgml
index 27460fd6e3..a781002931 100644
--- a/docs/reference/gtk/tmpl/gtkaccellabel.sgml
+++ b/docs/reference/gtk/tmpl/gtkaccellabel.sgml
@@ -118,7 +118,7 @@ Creates a new #GtkAccelLabel.
 </para>
 
 @accel_label: 
-@accel_widget:
+@accel_widget: 
 
 
 <!-- ##### FUNCTION gtk_accel_label_get_accel_width ##### -->
diff --git a/docs/reference/gtk/tmpl/gtklabel.sgml b/docs/reference/gtk/tmpl/gtklabel.sgml
index b3e18791f6..707e7d4fc2 100644
--- a/docs/reference/gtk/tmpl/gtklabel.sgml
+++ b/docs/reference/gtk/tmpl/gtklabel.sgml
@@ -6,11 +6,132 @@ A widget that displays a small to medium amount of text.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-The #GtkLabel widget is usually used directly by the programmer to display
-word(s) describing an adjacent widget or its use.  It is also used internally
-by Gtk+ as #GtkButton labels, #GtkMenu items, and many other widgets which
-use text.
+The #GtkLabel widget displays a small amount of text. As the name
+implies, most labels are used to label another widget such as a
+#GtkButton, a #GtkMenuItem, or a #GtkOptionMenu.
+</para>
+
+<refsect2>
+<title>Mnemonics</title>
+
+<para>
+Labels may contain <firstterm>mnemonics</firstterm>. Mnemonics are
+underlined characters in the label, used for keyboard navigation.
+Mnemonics are created by providing a string with an underscore before
+the mnemonic character, such as <literal>"_File"</literal>, to the
+functions gtk_label_new_with_mnemonic() or
+gtk_label_set_text_with_mnemonic().
+</para>
+
+<para>
+Mnemonics automatically activate any activatable widget the label is
+inside, such as a #GtkButton; if the label is not inside the
+mnemonic's target widget, you have to tell the label about the target
+using gtk_label_set_mnemonic_widget(). Here's a simple example where
+the label is inside a button:
+
+<informalexample>
+<programlisting>
+  /* Pressing Alt+H will activate this button */
+  button = gtk_button_new ();
+  label = gtk_label_new_with_mnemonic ("_Hello");
+  gtk_container_add (GTK_CONTAINER (button), label);
+</programlisting>
+</informalexample>
+There's a convenience function to create buttons with a mnemonic label 
+already inside:
+
+<informalexample>
+<programlisting>
+  /* Pressing Alt+H will activate this button */
+  button = gtk_button_new_with_mnemonic ("_Hello");
+</programlisting>
+</informalexample>
+
+To create a mnemonic for a widget alongside the label, such as a 
+#GtkEntry, you have to point the label at the entry with 
+gtk_label_set_mnemonic_widget():
+<informalexample>
+<programlisting>
+  /* Pressing Alt+H will focus the entry */
+  entry = gtk_entry_new ();
+  label = gtk_label_new_with_mnemonic ("_Hello");
+  gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry);
+</programlisting>
+</informalexample>
+
+</para>
+
+</refsect2>
+
+<refsect2>
+<title>Markup (styled text)</title>
+
+<para>
+To make it easy to format text in a label (changing colors, fonts,
+etc.), label text can be provided in a simple <link
+linkend="PangoMarkupFormat">markup format</link>.
+Here's how to create a label with a small font:
+<informalexample>
+<programlisting>
+  label = gtk_label_new (NULL);
+  gtk_label_set_markup (GTK_LABEL (label), "&lt;small&gt;Small text&lt;/small&gt;");
+</programlisting>
+</informalexample>
+(See <link
+linkend="PangoMarkupFormat">complete documentation</link> of available
+tags in the Pango manual.)
+</para>
+<para>
+The markup passed to gtk_label_set_markup() must be valid; for
+example, literal &lt;/&gt;/&amp; characters must be escaped as 
+&amp;lt;, &amp;gt;, and &amp;amp;. If you pass text obtained from 
+the user, file, or a network to gtk_label_set_markup(), 
+you'll want to escape it with g_markup_escape_text().
 </para>
+<para>
+Markup strings are just a convenient way to set the #PangoAttrList on
+a label; gtk_label_set_attributes() may be a simpler way to set
+attributes in some cases. Be careful though; #PangoAttrList tends to
+cause internationalization problems, unless you're applying attributes
+to the entire string (i.e. unless you set the range of each attribute
+to [0, G_MAXINT)). The reason is that specifying the start_index and
+end_index for a #PangoAttribute requires knowledge of the exact string
+being displayed, so translations will cause problems.
+</para>
+</refsect2>
+
+<refsect2>
+<title>Selectable labels</title>
+
+<para>
+Labels can be made selectable with gtk_label_set_selectable(). 
+Selectable labels allow the user to copy the label contents to 
+the clipboard. Only labels that contain useful-to-copy information
+&mdash; such as error messages &mdash; should be made selectable.
+</para>
+</refsect2>
+
+<refsect2>
+<title>Text layout</title>
+
+<para>
+A label can contain any number of paragraphs, but will have
+performance problems if it contains more than a small number.
+Paragraphs are separated by newlines or other paragraph separators
+understood by Pango.
+</para>
+<para>
+Labels can automatically wrap text if you call
+gtk_label_set_line_wrap().
+</para>
+<para>
+gtk_label_set_justify() sets how the lines in a label align 
+with one another. If you want to set how the label as a whole 
+aligns in its available space, see gtk_misc_set_alignment().
+</para>
+
+</refsect2>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkpaned.sgml b/docs/reference/gtk/tmpl/gtkpaned.sgml
index 1e3b1df6b8..33f24283a3 100644
--- a/docs/reference/gtk/tmpl/gtkpaned.sgml
+++ b/docs/reference/gtk/tmpl/gtkpaned.sgml
@@ -95,6 +95,13 @@ parameters. This is equivalent to
 @child: the child to add
 
 
+<!-- ##### MACRO gtk_paned_handle_size ##### -->
+<para>
+Old name for gtk_paned_set_handle_size().
+</para>
+
+
+
 <!-- ##### MACRO gtk_paned_gutter_size ##### -->
 <para>
 Old name for gtk_paned_set_gutter_size().
diff --git a/docs/reference/gtk/tmpl/gtksignal.sgml b/docs/reference/gtk/tmpl/gtksignal.sgml
index 827568577f..ec510317dc 100644
--- a/docs/reference/gtk/tmpl/gtksignal.sgml
+++ b/docs/reference/gtk/tmpl/gtksignal.sgml
@@ -7,7 +7,7 @@ Object methods and callbacks.
 <!-- ##### SECTION Long_Description ##### -->
 <para>
 The GTK+ signal system merely proxies the GLib signal system now. For future 
-usage, direct use of the <link linkend="gobject-Signals">GSignal</linkend> API is recommended, this avoids significant 
+usage, direct use of the <link linkend="gobject-Signals">GSignal</link> API is recommended, this avoids significant 
 performance hits where #GtkArg structures have to be converted into #GValue<!>s.
 </para>
 
diff --git a/docs/reference/gtk/tmpl/gtkwidget.sgml b/docs/reference/gtk/tmpl/gtkwidget.sgml
index 736f571294..8b7e56523f 100644
--- a/docs/reference/gtk/tmpl/gtkwidget.sgml
+++ b/docs/reference/gtk/tmpl/gtkwidget.sgml
@@ -76,8 +76,8 @@ Tells about certain properties of the widget.
 @GTK_COMPOSITE_CHILD: 
         Indicates that the widget is a composite child of its parent; see 
         gtk_widget_push_composite_child(), gtk_widget_pop_composite_child().
-@GTK_NO_REPARENT:
-	Unused since before GTK+ 1.2, will be removed in a future version. 
+@GTK_NO_REPARENT: 
+	Unused since before GTK+ 1.2, will be removed in a future version.
 @GTK_APP_PAINTABLE: 
         Set and unset by gtk_widget_set_app_paintable().
         Must be set on widgets whose window the application directly draws on,