Document named icon system.

Wed Jul  2 18:15:21 2003  Owen Taylor  <otaylor@redhat.com>

        * gtk/Makefile.am gtk/gtk-docs.sgml gtk/gtksections.txt
        gtk/tmpl/gtkicontheme.sgml: Document named icon system.

        * gtk/tmpl/gtkrc.sgml: Mention specifying named icons
        as @"icon-name".

        * gtk/tmpl/gtkimage.sgml: Add a cross-reference to stock
        icons.

28 files changed, 792 insertions, 11 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 629d25afce..bbe543334d 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,14 @@
+Wed Jul  2 18:15:21 2003  Owen Taylor  <otaylor@redhat.com>
+
+	* gtk/Makefile.am gtk/gtk-docs.sgml gtk/gtksections.txt
+	gtk/tmpl/gtkicontheme.sgml: Document named icon system.
+
+	* gtk/tmpl/gtkrc.sgml: Mention specifying named icons
+	as @"icon-name".
+
+	* gtk/tmpl/gtkimage.sgml: Add a cross-reference to stock
+	icons.
+
 2003-07-01  Matthias Clasen  <maclas@gmx.de>
 
 	* gtk/tmpl/gtkcolorbutton.sgml: 
diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index b4f64f6884..eb4431356f 100644
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -27,6 +27,7 @@ IGNORE_HFILES=			\
 	gdk-pixbuf-loader.h	\
 	gtkdebug.h		\
 	gtkhsv.h		\
+	gtkiconthemeparser.h	\
 	gtkimmodule.h		\
 	gtkintl.h		\
 	gtkkeyhash.h		\
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 2cf412914f..49749dabb4 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -140,6 +140,7 @@
 <!ENTITY gtk-Types SYSTEM "xml/gtktypeutils.xml">
 <!ENTITY gtk-Bindings SYSTEM "xml/gtkbindings.xml">
 <!ENTITY gtk-Standard-Enumerations SYSTEM "xml/gtkenums.xml">
+<!ENTITY gtk-Named-Icons SYSTEM "xml/gtkicontheme.xml">
 <!ENTITY gtk-Stock-Items SYSTEM "xml/gtkstock.xml">
 <!ENTITY gtk-Themeable-Stock-Images SYSTEM "xml/gtkiconfactory.xml">
 <!ENTITY gtk-Settings SYSTEM "xml/gtksettings.xml">
@@ -275,6 +276,7 @@ that is, GUI components such as <link linkend="GtkButton">GtkButton</link> or
     &gtk-accel-map;
     &gtk-Clipboards;
     &gtk-Drag-and-Drop;
+    &gtk-Named-Icons;
     &gtk-Stock-Items;
     &gtk-Themeable-Stock-Images;
     &gtk-Resource-Files;   
diff --git a/docs/reference/gtk/gtk-sections.txt b/docs/reference/gtk/gtk-sections.txt
index 3cffd88129..fc638b511f 100644
--- a/docs/reference/gtk/gtk-sections.txt
+++ b/docs/reference/gtk/gtk-sections.txt
@@ -4518,6 +4518,55 @@ GTK_STOCK_ZOOM_IN
 GTK_STOCK_ZOOM_OUT
 </SECTION>
 
+<SECTION>
+<FILE>gtkicontheme</FILE>
+<TITLE>GtkIconTheme</TITLE>
+GtkIconInfo
+GtkIconTheme
+GtkIconLookupFlags
+GTK_ICON_THEME_ERROR
+GtkIconThemeError
+gtk_icon_theme_new
+gtk_icon_theme_get_default
+gtk_icon_theme_get_for_screen
+gtk_icon_theme_set_screen
+gtk_icon_theme_set_search_path
+gtk_icon_theme_get_search_path
+gtk_icon_theme_append_search_path
+gtk_icon_theme_prepend_search_path
+gtk_icon_theme_set_custom_theme
+gtk_icon_theme_has_icon
+gtk_icon_theme_lookup_icon
+gtk_icon_theme_load_icon
+gtk_icon_theme_list_icons
+gtk_icon_theme_get_example_icon_name
+gtk_icon_theme_rescan_if_needed
+gtk_icon_theme_add_builtin_icon
+gtk_icon_info_copy
+gtk_icon_info_free
+gtk_icon_info_get_base_size
+gtk_icon_info_get_filename
+gtk_icon_info_get_builtin_pixbuf
+gtk_icon_info_load_icon
+gtk_icon_info_set_raw_coordinates
+gtk_icon_info_get_embedded_rect
+gtk_icon_info_get_attach_points
+gtk_icon_info_get_display_name
+<SUBSECTION Standard>
+GtkIconThemeClass
+GTK_ICON_THEME
+GTK_IS_ICON_THEME
+GTK_TYPE_ICON_THEME
+gtk_icon_theme_get_type
+GTK_ICON_THEME_CLASS
+GTK_IS_ICON_THEME_CLASS
+GTK_ICON_THEME_GET_CLASS
+gtk_icon_info_get_type
+GTK_TYPE_ICON_INFO
+<SUBSECTION Private>
+GtkIconThemePrivate
+gtk_icon_theme_error_quark
+</SECTION>
 
 <SECTION>
 <FILE>gtkiconfactory</FILE>
@@ -4552,6 +4601,7 @@ gtk_icon_source_get_direction
 gtk_icon_source_get_direction_wildcarded
 gtk_icon_source_get_filename
 gtk_icon_source_get_pixbuf
+gtk_icon_source_get_icon_name
 gtk_icon_source_get_size
 gtk_icon_source_get_size_wildcarded
 gtk_icon_source_get_state
@@ -4561,6 +4611,7 @@ gtk_icon_source_set_direction
 gtk_icon_source_set_direction_wildcarded
 gtk_icon_source_set_filename
 gtk_icon_source_set_pixbuf
+gtk_icon_source_set_icon_name
 gtk_icon_source_set_size
 gtk_icon_source_set_size_wildcarded
 gtk_icon_source_set_state
diff --git a/docs/reference/gtk/gtk.types b/docs/reference/gtk/gtk.types
index 66cd89ddc6..a78fc7c33e 100644
--- a/docs/reference/gtk/gtk.types
+++ b/docs/reference/gtk/gtk.types
@@ -47,6 +47,7 @@ gtk_hscale_get_type
 gtk_hscrollbar_get_type
 gtk_hseparator_get_type
 gtk_icon_factory_get_type
+gtk_icon_theme_get_type
 gtk_im_context_get_type
 gtk_im_context_simple_get_type
 gtk_im_multicontext_get_type
diff --git a/docs/reference/gtk/tmpl/gtkalignment.sgml b/docs/reference/gtk/tmpl/gtkalignment.sgml
index 2693f30ef7..e1994767dd 100644
--- a/docs/reference/gtk/tmpl/gtkalignment.sgml
+++ b/docs/reference/gtk/tmpl/gtkalignment.sgml
@@ -72,6 +72,50 @@ space allocated for the #GtkAlignment.
 unused space, from 0 to 1. The values are similar to @xscale.
 
 
+<!-- ##### FUNCTION gtk_alignment_get_padding ##### -->
+<para>
+
+</para>
+
+@alignment: 
+@padding_top: 
+@padding_bottom: 
+@padding_left: 
+@padding_right: 
+
+
+<!-- ##### FUNCTION gtk_alignment_set_padding ##### -->
+<para>
+
+</para>
+
+@alignment: 
+@padding_top: 
+@padding_bottom: 
+@padding_left: 
+@padding_right: 
+
+
+<!-- ##### ARG GtkAlignment:bottom-padding ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkAlignment:left-padding ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkAlignment:right-padding ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkAlignment:top-padding ##### -->
+<para>
+
+</para>
+
 <!-- ##### ARG GtkAlignment:xalign ##### -->
 <para>
 
diff --git a/docs/reference/gtk/tmpl/gtkbutton.sgml b/docs/reference/gtk/tmpl/gtkbutton.sgml
index 844ffd6a54..bc23ab0130 100644
--- a/docs/reference/gtk/tmpl/gtkbutton.sgml
+++ b/docs/reference/gtk/tmpl/gtkbutton.sgml
@@ -184,6 +184,24 @@ Returns the current relief style of the given #GtkButton.
 @value: 
 
 
+<!-- ##### FUNCTION gtk_button_set_focus_on_click ##### -->
+<para>
+
+</para>
+
+@button: 
+@focus_on_click: 
+
+
+<!-- ##### FUNCTION gtk_button_get_focus_on_click ##### -->
+<para>
+
+</para>
+
+@button: 
+@Returns: 
+
+
 <!-- ##### SIGNAL GtkButton::activate ##### -->
 <para>
 
@@ -229,6 +247,11 @@ mouse cursor is.
 
 @button: the object which received the signal.
 
+<!-- ##### ARG GtkButton:focus-on-click ##### -->
+<para>
+
+</para>
+
 <!-- ##### ARG GtkButton:label ##### -->
 <para>
 
diff --git a/docs/reference/gtk/tmpl/gtkcalendar.sgml b/docs/reference/gtk/tmpl/gtkcalendar.sgml
index 911f3f8077..67c16e38b3 100644
--- a/docs/reference/gtk/tmpl/gtkcalendar.sgml
+++ b/docs/reference/gtk/tmpl/gtkcalendar.sgml
@@ -159,6 +159,24 @@ Remove all visual markers.
 @calendar: a #GtkCalendar.
 
 
+<!-- ##### FUNCTION gtk_calendar_get_display_options ##### -->
+<para>
+
+</para>
+
+@calendar: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_calendar_set_display_options ##### -->
+<para>
+
+</para>
+
+@calendar: 
+@flags: 
+
+
 <!-- ##### FUNCTION gtk_calendar_display_options ##### -->
 <para>
 Sets display options (whether to display the heading and the month headings).
@@ -247,3 +265,43 @@ calendar.
 
 @calendar: the object which received the signal.
 
+<!-- ##### ARG GtkCalendar:day ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkCalendar:month ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkCalendar:no-month-change ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkCalendar:show-day-names ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkCalendar:show-heading ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkCalendar:show-week-numbers ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkCalendar:week-start-monday ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkCalendar:year ##### -->
+<para>
+
+</para>
+
diff --git a/docs/reference/gtk/tmpl/gtkcelleditable.sgml b/docs/reference/gtk/tmpl/gtkcelleditable.sgml
index 90c5e266fa..6ef345d4ee 100644
--- a/docs/reference/gtk/tmpl/gtkcelleditable.sgml
+++ b/docs/reference/gtk/tmpl/gtkcelleditable.sgml
@@ -2,7 +2,7 @@
 GtkCellEditable
 
 <!-- ##### SECTION Short_Description ##### -->
-Interface for widgets which can are used for editing cells 
+Interface for widgets which can are used for editing cells
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkcolorbutton.sgml b/docs/reference/gtk/tmpl/gtkcolorbutton.sgml
index f9ff2fa72b..e2a0e511cf 100644
--- a/docs/reference/gtk/tmpl/gtkcolorbutton.sgml
+++ b/docs/reference/gtk/tmpl/gtkcolorbutton.sgml
@@ -4,7 +4,6 @@ GtkColorButton
 <!-- ##### SECTION Short_Description ##### -->
 A button to launch a color selection dialog
 
-
 <!-- ##### SECTION Long_Description ##### -->
 <para>
 The #GtkColorButton is a button which displays the currently selected color an allows to open a color 
diff --git a/docs/reference/gtk/tmpl/gtkdnd.sgml b/docs/reference/gtk/tmpl/gtkdnd.sgml
index 7042051d4a..a184996449 100644
--- a/docs/reference/gtk/tmpl/gtkdnd.sgml
+++ b/docs/reference/gtk/tmpl/gtkdnd.sgml
@@ -63,7 +63,7 @@ constraints on an entry in a #GtkTargetTable.
 @GTK_TARGET_SAME_APP: 
    If this is set, the target will only be selected
    for drags within a single application.
-@GTK_TARGET_SAME_WIDGET:
+@GTK_TARGET_SAME_WIDGET: 
    If this is set, the target will only be selected
    for drags within a single widget.
 
diff --git a/docs/reference/gtk/tmpl/gtkenums.sgml b/docs/reference/gtk/tmpl/gtkenums.sgml
index ee02d4aceb..e1e1c04bab 100644
--- a/docs/reference/gtk/tmpl/gtkenums.sgml
+++ b/docs/reference/gtk/tmpl/gtkenums.sgml
@@ -149,6 +149,7 @@ Used to specify the style of the expanders drawn by a #GtkTreeView.
 
 @GTK_IM_PREEDIT_NOTHING: 
 @GTK_IM_PREEDIT_CALLBACK: 
+@GTK_IM_PREEDIT_NONE: 
 
 <!-- ##### ENUM GtkIMStatusStyle ##### -->
 <para>
@@ -157,6 +158,7 @@ Used to specify the style of the expanders drawn by a #GtkTreeView.
 
 @GTK_IM_STATUS_NOTHING: 
 @GTK_IM_STATUS_CALLBACK: 
+@GTK_IM_STATUS_NONE: 
 
 <!-- ##### ENUM GtkJustification ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkiconfactory.sgml b/docs/reference/gtk/tmpl/gtkiconfactory.sgml
index 97557d8d26..09b59dd134 100644
--- a/docs/reference/gtk/tmpl/gtkiconfactory.sgml
+++ b/docs/reference/gtk/tmpl/gtkiconfactory.sgml
@@ -319,6 +319,15 @@ looking up the icon to use for a given stock ID.
 @Returns: 
 
 
+<!-- ##### FUNCTION gtk_icon_source_get_icon_name ##### -->
+<para>
+
+</para>
+
+@source: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gtk_icon_source_get_size ##### -->
 <para>
 
@@ -399,6 +408,15 @@ looking up the icon to use for a given stock ID.
 @pixbuf: 
 
 
+<!-- ##### FUNCTION gtk_icon_source_set_icon_name ##### -->
+<para>
+
+</para>
+
+@source: 
+@icon_name: 
+
+
 <!-- ##### FUNCTION gtk_icon_source_set_size ##### -->
 <para>
 
diff --git a/docs/reference/gtk/tmpl/gtkicontheme.sgml b/docs/reference/gtk/tmpl/gtkicontheme.sgml
new file mode 100644
index 0000000000..5eb7f3dd40
--- /dev/null
+++ b/docs/reference/gtk/tmpl/gtkicontheme.sgml
@@ -0,0 +1,398 @@
+<!-- ##### SECTION Title ##### -->
+GtkIconTheme
+
+<!-- ##### SECTION Short_Description ##### -->
+Looking up icons by name
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+#GtkIconTheme provides a facility for looking up icons by name
+and size. The main reason for using a name rather than simply
+providing a filename is to allow different icons to be used
+depending on what <firstterm>icon theme</firstterm> is selecetd
+by the user. The operation of icon themes on Linux and Unix
+follows the <ulink
+url="http://www.freedesktop.org/standards/icon-theme-spec.html">Icon
+Theme Specification</ulink>. There is a default icon theme,
+named <literal>hicolor</literal> where applications should install
+their icons, but more additional application themes can be
+installed as operating system vendors and users choose.
+</para>
+<para>
+Named icons are similar to the <xref linkend="gtk-Themeable-Stock-Images"/>
+facility, and the distinction between the two may be a bit confusing.
+A few things to keep in mind:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Stock images usually are used in conjunction with
+<xref linkend="gtk-Stock-Items"/>., such as %GTK_STOCK_OK or
+%GTK_STOCK_OPEN. Named icons are easier to set up and therefore
+are more useful for new icons that an application wants to
+add, such as application icons or window icons.
+</para>
+</listitem>
+<listitem>
+<para>
+Stock images can only be loaded at the symbolic sizes defined
+by the #GtkIconSize enumeration, or by custom sizes defined
+by gtk_icon_size_register(), while named icons are more flexible
+and any pixel size can be specified.
+</para>
+</listitem>
+<listitem>
+<para>
+Because stock images are closely tied to stock items, and thus
+to actions in the user interface, stock images may come in
+multiple variants for different widget states or writing
+directions. 
+</para>
+</listitem>
+</itemizedlist>
+<para>
+A good rule of thumb is that if there is a stock image for what
+you want to use, use it, otherwise use a named icon. It turns
+out that internally stock images are generally defined in
+terms of one or more named icons. (An example of the
+more than one case is icons that depend on writing direction;
+GTK_STOCK_GO_FORWARD uses the two themed icons
+"gtk-stock-go-forward-ltr" and "gtk-stock-go-forward-rtl".)
+</para>
+<para>
+In many cases, named themes are used indirectly, via #GtkImage
+or stock items, rather than directly, but looking up icons
+directly is also simple. The #GtkIconTheme object acts
+as a database of all the icons in the current theme. You
+can create new #GtkIconTheme objects, but its much more
+efficient to use the standard icon theme for the #GdkScreen
+so that the icon information is shared with other people
+looking up icons. In the case where the default screen is
+being used, looking up an icon can be as simple as:
+</para>
+<informalexample>
+<programlisting>
+GError *error = NULL;
+GtkIconTheme *icon_theme;
+GdkPixbuf *pixbuf;
+
+icon_theme = gtk_icon_theme_get_default ();
+pixbuf = gtk_icon_theme_load_icon (icon_theme,
+                                   "my-icon-name", /* icon name */
+                                   48, /* size */
+                                   0,  /* flags */);
+if (!pixbuf)
+  {
+    g_warning ("Couldn't load icon: &percnt;s", error->message);
+    g_error_free (message);
+  }
+else
+  {
+    /* Use the pixbuf */
+    g_object_unref (pixbuf);
+  }
+</programlisting>
+</informalexample>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### STRUCT GtkIconInfo ##### -->
+<para>
+Contains information found when looking up an icon in
+an icon theme.
+</para>
+
+
+<!-- ##### STRUCT GtkIconTheme ##### -->
+<para>
+Acts as a database of information about an icon theme.
+Normally, you retrieve the icon theme for a particular
+screen using gtk_icon_theme_get_for_screen() and it
+will contain information about current icon theme for
+that screen, but you can also create a new #GtkIconTheme
+object and set the icon theme name explicitely using
+gtk_icon_theme_set_custom_theme().
+</para>
+
+
+<!-- ##### ENUM GtkIconLookupFlags ##### -->
+<para>
+
+</para>
+
+@GTK_ICON_LOOKUP_NO_SVG: 
+@GTK_ICON_LOOKUP_FORCE_SVG: 
+@GTK_ICON_LOOKUP_USE_BUILTIN: 
+
+<!-- ##### MACRO GTK_ICON_THEME_ERROR ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### ENUM GtkIconThemeError ##### -->
+<para>
+
+</para>
+
+@GTK_ICON_THEME_NOT_FOUND: 
+@GTK_ICON_THEME_FAILED: 
+
+<!-- ##### FUNCTION gtk_icon_theme_new ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_icon_theme_get_default ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_icon_theme_get_for_screen ##### -->
+<para>
+
+</para>
+
+@screen: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_icon_theme_set_screen ##### -->
+<para>
+
+</para>
+
+@icon_theme: 
+@screen: 
+
+
+<!-- ##### FUNCTION gtk_icon_theme_set_search_path ##### -->
+<para>
+
+</para>
+
+@icon_theme: 
+@path: 
+@n_elements: 
+
+
+<!-- ##### FUNCTION gtk_icon_theme_get_search_path ##### -->
+<para>
+
+</para>
+
+@icon_theme: 
+@path: 
+@n_elements: 
+
+
+<!-- ##### FUNCTION gtk_icon_theme_append_search_path ##### -->
+<para>
+
+</para>
+
+@icon_theme: 
+@path: 
+
+
+<!-- ##### FUNCTION gtk_icon_theme_prepend_search_path ##### -->
+<para>
+
+</para>
+
+@icon_theme: 
+@path: 
+
+
+<!-- ##### FUNCTION gtk_icon_theme_set_custom_theme ##### -->
+<para>
+
+</para>
+
+@icon_theme: 
+@theme_name: 
+
+
+<!-- ##### FUNCTION gtk_icon_theme_has_icon ##### -->
+<para>
+
+</para>
+
+@icon_theme: 
+@icon_name: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_icon_theme_lookup_icon ##### -->
+<para>
+
+</para>
+
+@icon_theme: 
+@icon_name: 
+@size: 
+@flags: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_icon_theme_load_icon ##### -->
+<para>
+
+</para>
+
+@icon_theme: 
+@icon_name: 
+@size: 
+@flags: 
+@error: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_icon_theme_list_icons ##### -->
+<para>
+
+</para>
+
+@icon_theme: 
+@context: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_icon_theme_get_example_icon_name ##### -->
+<para>
+
+</para>
+
+@icon_theme: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_icon_theme_rescan_if_needed ##### -->
+<para>
+
+</para>
+
+@icon_theme: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_icon_theme_add_builtin_icon ##### -->
+<para>
+
+</para>
+
+@icon_name: 
+@size: 
+@pixbuf: 
+
+
+<!-- ##### FUNCTION gtk_icon_info_copy ##### -->
+<para>
+
+</para>
+
+@icon_info: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_icon_info_free ##### -->
+<para>
+
+</para>
+
+@icon_info: 
+
+
+<!-- ##### FUNCTION gtk_icon_info_get_base_size ##### -->
+<para>
+
+</para>
+
+@icon_info: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_icon_info_get_filename ##### -->
+<para>
+
+</para>
+
+@icon_info: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_icon_info_get_builtin_pixbuf ##### -->
+<para>
+
+</para>
+
+@icon_info: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_icon_info_load_icon ##### -->
+<para>
+
+</para>
+
+@icon_info: 
+@error: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_icon_info_set_raw_coordinates ##### -->
+<para>
+
+</para>
+
+@icon_info: 
+@raw_coordinates: 
+
+
+<!-- ##### FUNCTION gtk_icon_info_get_embedded_rect ##### -->
+<para>
+
+</para>
+
+@icon_info: 
+@rectangle: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_icon_info_get_attach_points ##### -->
+<para>
+
+</para>
+
+@icon_info: 
+@points: 
+@n_points: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gtk_icon_info_get_display_name ##### -->
+<para>
+
+</para>
+
+@icon_info: 
+@Returns: 
+
+
+<!-- ##### SIGNAL GtkIconTheme::changed ##### -->
+<para>
+
+</para>
+
+@icontheme: the object which received the signal.
+
diff --git a/docs/reference/gtk/tmpl/gtkimage.sgml b/docs/reference/gtk/tmpl/gtkimage.sgml
index f406e97603..51a5e6d12e 100644
--- a/docs/reference/gtk/tmpl/gtkimage.sgml
+++ b/docs/reference/gtk/tmpl/gtkimage.sgml
@@ -123,7 +123,7 @@ functions), but they will all return %NULL values.
 @GTK_IMAGE_PIXMAP: the widget contains a #GdkPixmap
 @GTK_IMAGE_IMAGE: the widget contains a #GdkImage
 @GTK_IMAGE_PIXBUF: the widget contains a #GdkPixbuf
-@GTK_IMAGE_STOCK: the widget contains a stock icon name
+@GTK_IMAGE_STOCK: the widget contains a stock icon name (see <xref linkend="gtk-Stock-Items"/>)
 @GTK_IMAGE_ICON_SET: the widget contains a #GtkIconSet
 @GTK_IMAGE_ANIMATION: the widget contains a #GdkPixbufAnimation
 
diff --git a/docs/reference/gtk/tmpl/gtkimcontext.sgml b/docs/reference/gtk/tmpl/gtkimcontext.sgml
index ab552bce78..c85cf1fdd6 100644
--- a/docs/reference/gtk/tmpl/gtkimcontext.sgml
+++ b/docs/reference/gtk/tmpl/gtkimcontext.sgml
@@ -2,7 +2,7 @@
 GtkIMContext
 
 <!-- ##### SECTION Short_Description ##### -->
-Base class for input method contexts 
+Base class for input method contexts
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtknotebook.sgml b/docs/reference/gtk/tmpl/gtknotebook.sgml
index 715cfd908b..69bb714914 100644
--- a/docs/reference/gtk/tmpl/gtknotebook.sgml
+++ b/docs/reference/gtk/tmpl/gtknotebook.sgml
@@ -534,3 +534,23 @@ Emitted when the user or a function changes the current page.
 
 </para>
 
+<!-- ##### ARG GtkNotebook:has-backward-stepper ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkNotebook:has-forward-stepper ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkNotebook:has-secondary-backward-stepper ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkNotebook:has-secondary-forward-stepper ##### -->
+<para>
+
+</para>
+
diff --git a/docs/reference/gtk/tmpl/gtkpaned.sgml b/docs/reference/gtk/tmpl/gtkpaned.sgml
index 8a02018464..0845dc727d 100644
--- a/docs/reference/gtk/tmpl/gtkpaned.sgml
+++ b/docs/reference/gtk/tmpl/gtkpaned.sgml
@@ -215,6 +215,16 @@ gutter (the area between the two panes). It does nothing now.
 
 </para>
 
+<!-- ##### ARG GtkPaned:resize ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkPaned:shrink ##### -->
+<para>
+
+</para>
+
 <!-- ##### ARG GtkPaned:handle-size ##### -->
 <para>
 
diff --git a/docs/reference/gtk/tmpl/gtkrc.sgml b/docs/reference/gtk/tmpl/gtkrc.sgml
index be55c5abe9..d83a9b4df8 100644
--- a/docs/reference/gtk/tmpl/gtkrc.sgml
+++ b/docs/reference/gtk/tmpl/gtkrc.sgml
@@ -409,9 +409,13 @@ the range 0-65535 or floats in the range 0.0-1.0.
 
 <para>
 In a <literal>stock</literal> definition, icon sources are specified as a
-4-tuple of image filename, text direction, widget state, and size, in that
-order.  Each icon source specifies an image filename to use with a given
-direction, state, and size. The <literal>*</literal> character can be used as a
+4-tuple of image filename or icon name, text direction, widget state, and size, in that
+order.  Each icon source specifies an image filename or icon name to use with a given
+direction, state, and size. Filenames are specified as a string such
+as <literal>"itemltr.png"</literal>, while icon names (looked up
+in the current icon theme), are specified with a leading
+<literal>@</literal>, such as <literal>@"item-ltr"</literal>.
+The <literal>*</literal> character can be used as a
 wildcard, and if direction/state/size are omitted they default to
 <literal>*</literal>. So for example, the following specifies different icons to
 use for left-to-right and right-to-left languages:
diff --git a/docs/reference/gtk/tmpl/gtktextbuffer.sgml b/docs/reference/gtk/tmpl/gtktextbuffer.sgml
index 645683606e..44ee0a1753 100644
--- a/docs/reference/gtk/tmpl/gtktextbuffer.sgml
+++ b/docs/reference/gtk/tmpl/gtktextbuffer.sgml
@@ -343,6 +343,16 @@ types related to the text widget and how they work together.
 @where: 
 
 
+<!-- ##### FUNCTION gtk_text_buffer_select_range ##### -->
+<para>
+
+</para>
+
+@buffer: 
+@ins: 
+@bound: 
+
+
 <!-- ##### FUNCTION gtk_text_buffer_apply_tag ##### -->
 <para>
 
diff --git a/docs/reference/gtk/tmpl/gtktextview.sgml b/docs/reference/gtk/tmpl/gtktextview.sgml
index 267e7192d4..bf92112268 100644
--- a/docs/reference/gtk/tmpl/gtktextview.sgml
+++ b/docs/reference/gtk/tmpl/gtktextview.sgml
@@ -435,6 +435,24 @@ multiple views.
 @Returns: 
 
 
+<!-- ##### FUNCTION gtk_text_view_set_overwrite ##### -->
+<para>
+
+</para>
+
+@text_view: 
+@overwrite: 
+
+
+<!-- ##### FUNCTION gtk_text_view_get_overwrite ##### -->
+<para>
+
+</para>
+
+@text_view: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gtk_text_view_set_pixels_above_lines ##### -->
 <para>
 
@@ -669,6 +687,14 @@ in an idle job in the background.
 @textview: the object which received the signal.
 @arg1: 
 
+<!-- ##### SIGNAL GtkTextView::select-all ##### -->
+<para>
+
+</para>
+
+@textview: the object which received the signal.
+@arg1: 
+
 <!-- ##### SIGNAL GtkTextView::set-anchor ##### -->
 <para>
 
@@ -692,6 +718,11 @@ in an idle job in the background.
 
 @textview: the object which received the signal.
 
+<!-- ##### ARG GtkTextView:buffer ##### -->
+<para>
+
+</para>
+
 <!-- ##### ARG GtkTextView:cursor-visible ##### -->
 <para>
 
@@ -717,6 +748,11 @@ in an idle job in the background.
 
 </para>
 
+<!-- ##### ARG GtkTextView:overwrite ##### -->
+<para>
+
+</para>
+
 <!-- ##### ARG GtkTextView:pixels-above-lines ##### -->
 <para>
 
diff --git a/docs/reference/gtk/tmpl/gtktoolbar.sgml b/docs/reference/gtk/tmpl/gtktoolbar.sgml
index 71686ff362..1265bd66ef 100644
--- a/docs/reference/gtk/tmpl/gtktoolbar.sgml
+++ b/docs/reference/gtk/tmpl/gtktoolbar.sgml
@@ -360,6 +360,24 @@ Sets if the tooltips of a toolbar should be active or not.
 @toolbar: 
 
 
+<!-- ##### SIGNAL GtkToolbar::focus-home-or-end ##### -->
+<para>
+
+</para>
+
+@toolbar: the object which received the signal.
+@arg1: 
+@Returns: 
+
+<!-- ##### SIGNAL GtkToolbar::move-focus ##### -->
+<para>
+
+</para>
+
+@toolbar: the object which received the signal.
+@arg1: 
+@Returns: 
+
 <!-- ##### SIGNAL GtkToolbar::orientation-changed ##### -->
 <para>
 Should be used if you wish to perform an action when the orientation of a toolbar is changed.
@@ -368,6 +386,13 @@ Should be used if you wish to perform an action when the orientation of a toolba
 @toolbar: the object which received the signal.
 @orientation: the new #GtkOrientation of the toolbar.
 
+<!-- ##### SIGNAL GtkToolbar::popup-context-menu ##### -->
+<para>
+
+</para>
+
+@toolbar: the object which received the signal.
+
 <!-- ##### SIGNAL GtkToolbar::style-changed ##### -->
 <para>
 Should be used if you wish to perform an action when ever the style of a toolbar is adjusted. For example, this would be a useful signal to connect to if you want to display more items on the toolbar when it is in icon-only mode; each item takes less space on the bar.
@@ -381,11 +406,31 @@ Should be used if you wish to perform an action when ever the style of a toolbar
 
 </para>
 
+<!-- ##### ARG GtkToolbar:show-arrow ##### -->
+<para>
+
+</para>
+
 <!-- ##### ARG GtkToolbar:toolbar-style ##### -->
 <para>
 
 </para>
 
+<!-- ##### ARG GtkToolbar:expand ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkToolbar:homogeneous ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkToolbar:pack-end ##### -->
+<para>
+
+</para>
+
 <!-- ##### ARG GtkToolbar:button-relief ##### -->
 <para>
 
diff --git a/docs/reference/gtk/tmpl/gtktreednd.sgml b/docs/reference/gtk/tmpl/gtktreednd.sgml
index 4b19f634a7..9414655b6b 100644
--- a/docs/reference/gtk/tmpl/gtktreednd.sgml
+++ b/docs/reference/gtk/tmpl/gtktreednd.sgml
@@ -2,7 +2,7 @@
 GtkTreeView drag-and-drop
 
 <!-- ##### SECTION Short_Description ##### -->
-Interfaces for drag-and-drop support in GtkTreeView
+
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtktreesortable.sgml b/docs/reference/gtk/tmpl/gtktreesortable.sgml
index f0c0b658fd..9e96ee3f5e 100644
--- a/docs/reference/gtk/tmpl/gtktreesortable.sgml
+++ b/docs/reference/gtk/tmpl/gtktreesortable.sgml
@@ -1,5 +1,5 @@
 <!-- ##### SECTION Title ##### -->
-GtkTreeSortable 
+GtkTreeSortable
 
 <!-- ##### SECTION Short_Description ##### -->
 The interface for sortable models used by GtkTreeView
diff --git a/docs/reference/gtk/tmpl/gtktreeviewcolumn.sgml b/docs/reference/gtk/tmpl/gtktreeviewcolumn.sgml
index c1502bb340..a65dc1b1a3 100644
--- a/docs/reference/gtk/tmpl/gtktreeviewcolumn.sgml
+++ b/docs/reference/gtk/tmpl/gtktreeviewcolumn.sgml
@@ -309,6 +309,24 @@ calling gtk_tree_view_column_set_cell_data_func()
 @Returns: 
 
 
+<!-- ##### FUNCTION gtk_tree_view_column_set_expand ##### -->
+<para>
+
+</para>
+
+@tree_column: 
+@expand: 
+
+
+<!-- ##### FUNCTION gtk_tree_view_column_get_expand ##### -->
+<para>
+
+</para>
+
+@tree_column: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gtk_tree_view_column_set_clickable ##### -->
 <para>
 
@@ -462,6 +480,18 @@ calling gtk_tree_view_column_set_cell_data_func()
 @height: 
 
 
+<!-- ##### FUNCTION gtk_tree_view_column_cell_get_position ##### -->
+<para>
+
+</para>
+
+@tree_column: 
+@cell_renderer: 
+@start_pos: 
+@width: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gtk_tree_view_column_cell_is_visible ##### -->
 <para>
 
diff --git a/docs/reference/gtk/tmpl/gtktypeutils.sgml b/docs/reference/gtk/tmpl/gtktypeutils.sgml
index d181785eac..e4d679ceb7 100644
--- a/docs/reference/gtk/tmpl/gtktypeutils.sgml
+++ b/docs/reference/gtk/tmpl/gtktypeutils.sgml
@@ -39,6 +39,7 @@ Returns the type name of @class.
 @class: a #GtkTypeClass.
 @Deprecated: Use g_type_name() and G_TYPE_FROM_CLASS() instead.
 
+
 <!-- ##### MACRO GTK_CLASS_TYPE ##### -->
 <para>
 Returns the type of @class.
@@ -47,6 +48,7 @@ Returns the type of @class.
 @class: a #GtkTypeClass.
 @Deprecated: Use G_TYPE_FROM_CLASS() instead.
 
+
 <!-- ##### MACRO GTK_TYPE_IS_OBJECT ##### -->
 <para>
 Returns %TRUE if @type is a %GTK_TYPE_OBJECT.
@@ -55,6 +57,7 @@ Returns %TRUE if @type is a %GTK_TYPE_OBJECT.
 @type: a #GtkType.
 @Deprecated: Use G_TYPE_IS_OBJECT() instead.
 
+
 <!-- ##### MACRO GTK_TYPE_FUNDAMENTAL_LAST ##### -->
 <para>
 The highest-numbered structured or flat enumerated type value.
@@ -62,6 +65,7 @@ The highest-numbered structured or flat enumerated type value.
 
 @Deprecated: Use #G_TYPE_LAST_RESERVED_FUNDAMENTAL - 1 instead.
 
+
 <!-- ##### MACRO GTK_TYPE_FUNDAMENTAL_MAX ##### -->
 <para>
 The maximum fundamental enumerated type value.
@@ -69,6 +73,7 @@ The maximum fundamental enumerated type value.
 
 @Deprecated: Use #G_TYPE_FUNDAMENTAL_MAX instead.
 
+
 <!-- ##### MACRO GTK_STRUCT_OFFSET ##### -->
 <para>
 Use in place of <function>offsetof()</function>, which is used if it exists.
@@ -76,6 +81,7 @@ Use in place of <function>offsetof()</function>, which is used if it exists.
 
 @Deprecated: Use G_STRUCT_OFFSET() instead.
 
+
 <!-- ##### MACRO GTK_CHECK_CAST ##### -->
 <para>
 Casts the object in @tobj into @cast.  If %G_DISABLE_CAST_CHECKS is
@@ -83,6 +89,8 @@ defined, just cast it.  Otherwise, check to see if we can cast @tobj
 into a @cast.
 </para>
 
+
+
 <!-- ##### MACRO GTK_CHECK_CLASS_CAST ##### -->
 <para>
 Casts the object in @tobj into @cast.  If %G_DISABLE_CAST_CHECKS is
@@ -90,6 +98,7 @@ defined, just cast it.  Otherwise, check to see if we can cast @tobj
 into a @cast.
 </para>
 
+<!-- # Unused Parameters # -->
 @tclass: a #GtkClassInitFunc
 @cast_type: a GTK+ type.
 @cast: a C type
@@ -100,6 +109,7 @@ into a @cast.
 Determines whether @type_object is a type of @otype.
 </para>
 
+<!-- # Unused Parameters # -->
 @type_object: a #GtkTypeObject object
 @otype: 
 
@@ -109,6 +119,7 @@ Determines whether @type_object is a type of @otype.
 Determines whether @type_class is a type of @otype.
 </para>
 
+<!-- # Unused Parameters # -->
 @type_class: a #GtkTypeClass class.
 @otype: 
 
@@ -118,6 +129,7 @@ Determines whether @type_class is a type of @otype.
 Gets the class of @tobj.
 </para>
 
+<!-- # Unused Parameters # -->
 @tobj: a #GtkObject.
 
 
@@ -126,6 +138,7 @@ Gets the class of @tobj.
 Converts a GTK+ type into a fundamental type.
 </para>
 
+<!-- # Unused Parameters # -->
 @type: 
 
 
diff --git a/docs/reference/gtk/tmpl/gtkwidget.sgml b/docs/reference/gtk/tmpl/gtkwidget.sgml
index 32095a417b..dbe9810857 100644
--- a/docs/reference/gtk/tmpl/gtkwidget.sgml
+++ b/docs/reference/gtk/tmpl/gtkwidget.sgml
@@ -351,7 +351,7 @@ A <structname>GtkRequisition</structname> represents the desired size of a widge
 </para>
 
 @width: the widget's desired width
-@height: the widget's desired height 
+@height: the widget's desired height
 
 <!-- ##### STRUCT GtkAllocation ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkwindow.sgml b/docs/reference/gtk/tmpl/gtkwindow.sgml
index 3666509f3a..c2ab3c9315 100644
--- a/docs/reference/gtk/tmpl/gtkwindow.sgml
+++ b/docs/reference/gtk/tmpl/gtkwindow.sgml
@@ -916,6 +916,11 @@ Deprecated alias for gtk_window_set_position().
 
 </para>
 
+<!-- ##### ARG GtkWindow:role ##### -->
+<para>
+
+</para>
+
 <!-- ##### ARG GtkWindow:screen ##### -->
 <para>