[gtk+] Improve GtkBox and GtkTable docs a bit

[Matthias Clasen <matthiasc src gnome org>]

commit 56e797397be074f73a41c8cc9801146e18b4e117
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Oct 15 10:58:35 2010 -0400

    Improve GtkBox and GtkTable docs a bit
    
    This adds some details gleaned from the tutorial, before its
    impending demise.

 docs/reference/gtk/tmpl/gtktable.sgml |   18 ++++++++++++++++--
 gtk/gtkbox.c                          |   25 ++++++++++++++-----------
 2 files changed, 30 insertions(+), 13 deletions(-)
---
diff --git a/docs/reference/gtk/tmpl/gtktable.sgml b/docs/reference/gtk/tmpl/gtktable.sgml
index 7a85843..a95a319 100644
--- a/docs/reference/gtk/tmpl/gtktable.sgml
+++ b/docs/reference/gtk/tmpl/gtktable.sgml
@@ -22,8 +22,11 @@ convenient (but slightly less flexible) gtk_table_attach_defaults().
 To alter the space next to a specific row, use gtk_table_set_row_spacing(),
 and for a column, gtk_table_set_col_spacing().</para>
 <para>
-The gaps between <emphasis>all</emphasis> rows or columns can be changed by calling
-gtk_table_set_row_spacings() or gtk_table_set_col_spacings() respectively.
+The gaps between <emphasis>all</emphasis> rows or columns can be changed by
+calling gtk_table_set_row_spacings() or gtk_table_set_col_spacings()
+respectively. Note that spacing is added <emphasis>between</emphasis> the
+children, while padding added by gtk_table_atach() is added <emphasis>on
+either side</emphasis> of the widget it belongs to.
 </para>
 <para>
 gtk_table_set_homogeneous(), can be used to set whether all cells in the
@@ -169,6 +172,17 @@ specified by @left_attach, @right_attach, @top_attach and @bottom_attach.
 These each represent the leftmost, rightmost, uppermost and lowest column
 and row numbers of the table. (Columns and rows are indexed from zero).
 </para>
+<para>
+To make a button occupy the lower right cell of a 2x2 table, use
+<informalexample><programlisting>
+gtk_table_attach (table, button,
+                  1, 2, /* left, right attach */
+                  1, 2, /* top, bottom attach */
+                  xoptions, yoptions,
+                  xpadding, ypadding);
+</programlisting></informalexample>
+If you want to make the button span the entire bottom row, use @left_attach == 0 and @right_attach = 2 instead.
+</para>
 
 @table: The #GtkTable to add a new widget to.
 @child: The widget to add.
diff --git a/gtk/gtkbox.c b/gtk/gtkbox.c
index ae00779..a083af1 100644
--- a/gtk/gtkbox.c
+++ b/gtk/gtkbox.c
@@ -63,7 +63,10 @@
  * of the GtkBox are forced to get the same amount of space.
  *
  * Use gtk_box_set_spacing() to determine how much space will be
- * minimally placed between all children in the GtkBox.
+ * minimally placed between all children in the GtkBox. Note that
+ * spacing is added <emphasis>between</emphasis> the children, while
+ * padding added by gtk_box_pack_start() or gtk_box_pack_end() is added
+ * <emphasis>on either side</emphasis> of the widget it belongs to.
  *
  * Use gtk_box_reorder_child() to move a GtkBox child to a different
  * place in the box.
@@ -1256,22 +1259,22 @@ gtk_box_new (GtkOrientation orientation,
  * gtk_box_pack_start:
  * @box: a #GtkBox
  * @child: the #GtkWidget to be added to @box
- * @expand: %TRUE if the new child is to be given extra space allocated to
- * @box.  The extra space will be divided evenly between all children of
- * @box that use this option
+ * @expand: %TRUE if the new child is to be given extra space allocated
+ *     to @box. The extra space will be divided evenly between all children
+ *     that use this option
  * @fill: %TRUE if space given to @child by the @expand option is
- *   actually allocated to @child, rather than just padding it.  This
- *   parameter has no effect if @expand is set to %FALSE.  A child is
- *   always allocated the full height of a #GtkHBox and the full width 
- *   of a #GtkVBox. This option affects the other dimension
+ *     actually allocated to @child, rather than just padding it.  This
+ *     parameter has no effect if @expand is set to %FALSE.  A child is
+ *     always allocated the full height of a #GtkHBox and the full width
+ *     of a #GtkVBox. This option affects the other dimension
  * @padding: extra space in pixels to put between this child and its
  *   neighbors, over and above the global amount specified by
- *   #GtkBox:spacing property.  If @child is a widget at one of the 
- *   reference ends of @box, then @padding pixels are also put between 
+ *   #GtkBox:spacing property.  If @child is a widget at one of the
+ *   reference ends of @box, then @padding pixels are also put between
  *   @child and the reference edge of @box
  *
  * Adds @child to @box, packed with reference to the start of @box.
- * The @child is packed after any other child packed with reference 
+ * The @child is packed after any other child packed with reference
  * to the start of @box.
  */
 void