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

6 files changed, 136 insertions, 14 deletions

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,