Doc typo fix. (#68172)

        * gtk/gtksocket.c (gtk_socket_get_id): Doc typo fix. (#68172)

        * gtk/gtktreemodel.c (gtk_tree_path_is_descendant): Fix docs.

        * gtk/gtktreemodel.c (gtk_tree_model_rows_reordered): Document.

        * gtk/gtkwindow.c (gtk_window_remove_accel_group): Fix docs.

        * gtk/gtkrc.c (gtk_rc_get_style_by_paths),
        gtk/gtkwidget.c (gtk_widget_get_toplevel,
        gtk_widget_push_composite_child), gtk/gtkdialog.c
        (gtk_dialog_new_with_buttons, gtk_dialog_run): Keep gtk-doc
        from messing up the indentation of inline examples.

        * gtk/gtkmain.c, gtk/gtkrc.c: Consistently call g_getenv()
        instead of getenv().

        * gtk/gtktreemodel.c, gtk/gtkaccelgroup.c, gtk/gtkclipboard.c,
        gtk/gtkdnd.c, gtk/gtkiconfactory.c, gtk/gtkrc.c,
        gtk/gtkstyle.c, gtk/gtkselection.c: Doc fixes.

        * gtk/gtkaccelmap.c (gtk_accel_map_add_filter,
        gtk_accel_map_foreach_unfiltered, gtk_accel_map_load_scanner):
        Document.

        * gtk/tmpl/gtksocket.sgml: Mention gtk_socket_get_id()
        instead of GTK_WINDOW_XWINDOW().  (#68172)

        * gtk/gtk-sections.txt: Move functions which are documented
        as "private" or "internal" into Private subsections.

        * gtk/tmpl/gtkdnd.sgml, gtk/tmpl/gtkobject.sgml,
        gtk/tmpl/gtkrc.sgml, gtk/tmpl/gtktooltips.sgml,
        gtk/tmpl/gtkwidget.sgml, gtk/tmpl/gtkclipboard.sgml,
        gtk/tmpl/gtkstyle.sgml, gtk/tmpl/gtkselection.sgml,
        gtk/tmpl/gtkfeatures.sgml: Minor markup fixes.

        * gtk/tmpl/gtksignal.sgml: Add link to GLib signal docs.

        * gtk/tmpl/gtkpreview.sgml, gtk/tmpl/gtktext.sgml,
        gtk/tmpl/gtktree.sgml: Remove "deprecated" from short desc.

        * gtk/tmpl/gtkrc.sgml: Correct names of default RC files.

1 files changed, 49 insertions, 74 deletions

diff --git a/docs/reference/gtk/tmpl/gtkrc.sgml b/docs/reference/gtk/tmpl/gtkrc.sgml
index d3fdb314c..9dd83a8f9 100644
--- a/docs/reference/gtk/tmpl/gtkrc.sgml
+++ b/docs/reference/gtk/tmpl/gtkrc.sgml
@@ -16,28 +16,33 @@ at runtime.
 An application can cause GTK+ to parse a specific RC
 file by calling gtk_rc_parse(). In addition to this,
 certain files will be read at the end of gtk_init().
-Unless modified, the files looked for will be <filename>.gtkrc</filename>
-in the users home directory, and 
-<filename>$localstatedir/gtk/gtkrc</filename> 
-(<literal>$localstatedir</literal> defaults to 
-<filename>/usr/local/etc</filename>).
+Unless modified, the files looked for will be 
+<filename>&lt;SYSCONFDIR&gt;/gtk-2.0/gtkrc</filename> 
+and <filename>.gtkrc-2.0</filename> in the users home directory.
+(<filename>&lt;SYSCONFDIR&gt;</filename> defaults to 
+<filename>/usr/local/etc</filename>. It can be changed with the
+<option>--prefix</option> or <option>--sysconfdir</option> options when 
+configuring GTK+.)
 </para>
 <para>
 The set of these <firstterm>default</firstterm> files
 can be retrieved with gtk_rc_get_default_files()
 and modified with gtk_rc_add_default_file() and
 gtk_rc_set_default_files().
+Additionally, the <envar>GTK_RC_FILES</envar> environment variable
+can be set to a #G_SEARCHPATH_SEPARATOR_S-separated list of files
+in order to overwrite the set of default files at runtime.
 </para>
 <para>
 For each default file, in addition to the file itself,
 GTK+ will look for a locale-specific file that will
-be parsed in addition to the main file. For instance,
-if <literal>LANG</literal> is set to <literal>ja_JP.ujis</literal>,
+be parsed before the main file. For instance,
+if <envar>LANG</envar> is set to <literal>ja_JP.ujis</literal>,
 when loading the default file <filename>~/.gtkrc</filename>
 then GTK+ looks for <filename>~/.gtkrc.ja_JP.ujis</filename>,
 <filename>~/.gtkrc.ja_JP</filename>, and
-<filename>~/.gtkrc.ja</filename>, and parses the
-first one it finds.
+<filename>~/.gtkrc.ja</filename>, and parses all files that 
+it finds.
 </para>
 </refsect2>
 
@@ -68,12 +73,12 @@ hierarchy. Both the widget and the class paths consists of a
 parents of the widget and the widget itself from
 outermost to innermost. The difference is that in
 the widget path, the name assigned by
-<function>gtk_widget_set_name()</function> is used
+gtk_widget_set_name() is used
 if present, otherwise the class name of the widget, while
 for the widget path, the class name is always used.
 </para>
 <para>
-So, if you have a <classname>GtkEntry</classname> named
+So, if you have a #GtkEntry named
 <literal>"myentry"</literal>, inside of a of a window
 named <literal>"mywindow"</literal>, then the
 widget path is: <literal>"mwindow.GtkHBox.myentry"</literal>
@@ -87,18 +92,18 @@ pattern:
 <informalexample><programlisting>
 class "GtkButton" style "my-style"
 </programlisting></informalexample>
-will match not just <classname>GtkButton</classname> widgets,
-but also <classname>GtkToggleButton</classname> and
-<classname>GtkCheckButton</classname> widgets, since
-those classes derive from <classname>GtkButton</classname>.
+will match not just #GtkButton widgets,
+but also #GtkToggleButton and
+#GtkCheckButton widgets, since
+those classes derive from #GtkButton.
 </para>
 </refsect2>
 
 <refsect2><title>Toplevel declarations</title>
 <para>
 An RC file is a text file which is composed of a sequence
-of declarations. '#' characters delimit comments and
-the portion of a line after a '#' is ignored when parsing
+of declarations. <literal>'#'</literal> characters delimit comments and
+the portion of a line after a <literal>'#'</literal> is ignored when parsing
 an RC file.
 </para>
 
@@ -110,7 +115,7 @@ The possible toplevel declarations are:
     <term><literal>binding <replaceable>name</replaceable>
      { ... }</literal></term>
     <listitem>
-      <para>Declare a binding set</para>
+      <para>Declares a binding set.</para>
     </listitem>
   </varlistentry>
   <varlistentry>
@@ -118,14 +123,14 @@ The possible toplevel declarations are:
           [ style | binding [ : <replaceable>priority</replaceable> ]]
           <replaceable>name</replaceable></literal></term>
     <listitem>
-     <para>Specify a style or binding set for a particular
+     <para>Specifies a style or binding set for a particular
      branch of the inheritance hierarchy.</para>
     </listitem>
   </varlistentry>
   <varlistentry>
     <term><literal>include <replaceable>filename</replaceable></literal></term>
     <listitem>
-      <para>Parse another file at this point</para>
+      <para>Parses another file at this point.</para>
     </listitem>
   </varlistentry>
   <varlistentry>
@@ -148,7 +153,7 @@ The possible toplevel declarations are:
     <term><literal>style <replaceable>name</replaceable> [ =
     <replaceable>parent</replaceable> ] { ... }</literal></term>
     <listitem>
-      <para>Declare a style</para>
+      <para>Declares a style.</para>
     </listitem>
   </varlistentry>
   <varlistentry>
@@ -156,7 +161,7 @@ The possible toplevel declarations are:
           [ style | binding [ : <replaceable>priority</replaceable> ]]
           <replaceable>name</replaceable></literal></term>
     <listitem>
-     <para>Specify a style or binding set for a particular
+     <para>Specifies a style or binding set for a particular
      group of widgets by matching on the widget pathname.</para>
     </listitem>
   </varlistentry>
@@ -165,7 +170,7 @@ The possible toplevel declarations are:
           [ style | binding [ : <replaceable>priority</replaceable> ]]
           <replaceable>name</replaceable></literal></term>
     <listitem>
-     <para>Specify a style or binding set for a particular
+     <para>Specifies a style or binding set for a particular
      group of widgets by matching on the class pathname.</para>
     </listitem>
   </varlistentry>
@@ -197,7 +202,7 @@ elements are:
       <replaceable>color</replaceable></literal></term>
      <listitem>
        <para>
-         Set color used for the background of most widgets.
+         Sets the color used for the background of most widgets.
        </para>
      </listitem>
   </varlistentry>
@@ -206,7 +211,7 @@ elements are:
       <replaceable>color</replaceable></literal></term>
      <listitem>
        <para>
-         Set color used for the foreground of most widgets.
+         Sets the color used for the foreground of most widgets.
        </para>
      </listitem>
   </varlistentry>
@@ -215,7 +220,7 @@ elements are:
       <replaceable>color</replaceable></literal></term>
      <listitem>
        <para>
-         Set color used for the background of widgets displaying
+         Sets the color used for the background of widgets displaying
          editable text. This color is used for the background
          of, among others, #GtkText, #GtkEntry, #GtkList, and #GtkClist.
        </para>
@@ -226,7 +231,7 @@ elements are:
       <replaceable>color</replaceable></literal></term>
      <listitem>
        <para>
-         Set color used for foreground of widgets using
+         Sets the color used for foreground of widgets using
          <literal>base</literal> for the background color.
        </para>
      </listitem>
@@ -236,7 +241,7 @@ elements are:
       <replaceable>pixmap</replaceable></literal></term>
      <listitem>
        <para>
-         Set a background pixmap to be used in place of
+         Sets a background pixmap to be used in place of
          the <literal>bg</literal> color (or for #GtkText,
          in place of the <literal>base</literal> color. The special
          value "&lt;parent&gt;" may be used to indicate that the widget should
@@ -249,7 +254,7 @@ elements are:
     <term><literal>font = <replaceable>font</replaceable></literal></term>
      <listitem>
        <para>
-         Set the font for a widget.
+         Sets the font for a widget.
        </para>
      </listitem>
   </varlistentry>
@@ -257,7 +262,7 @@ elements are:
     <term><literal>fontset = <replaceable>font</replaceable></literal></term>
      <listitem>
        <para>
-         Set the fontset for a widget. Overrides any
+         Sets the fontset for a widget. Overrides any
          <literal>font</literal> declarations.
        </para>
      </listitem>
@@ -281,7 +286,7 @@ state of the widget. The states are:
     <term><literal>NORMAL</literal></term>
     <listitem>
       <para>
-        A color used for a widget in its normal state
+        A color used for a widget in its normal state.
       </para>
     </listitem>
   </varlistentry>
@@ -314,8 +319,8 @@ state of the widget. The states are:
     <listitem>
       <para>
         A color used to highlight data selected by the user.
-        for instance, the selected ListItems in a List widget, and the
-        selection in an Editable widget.
+        for instance, the selected items in a list widget, and the
+        selection in an editable widget.
       </para>
     </listitem>
   </varlistentry>
@@ -324,7 +329,7 @@ state of the widget. The states are:
     <listitem>
       <para>
         A color used for the background of widgets that have
-        been set insensitive with gtk_widget_set_sensitive()
+        been set insensitive with gtk_widget_set_sensitive().
       </para>
     </listitem>
   </varlistentry>
@@ -515,41 +520,11 @@ The #GtkRcFlags enumeration is used as a bitmask
 to specify which fields of a #GtkRcStyle have been
 set for each state.
 </para>
-<variablelist>
- <varlistentry><term> %GTK_RC_FG </term>
- <listitem>
-   <para>
-   If present, the foreground color has been set for this state.
-   </para>
- </listitem>
- </varlistentry>
- <varlistentry><term> %GTK_RC_BG </term>
- <listitem>
-   <para>
-   If present, the background color has been set for this state.
-   </para>
- </listitem>
- </varlistentry>
- <varlistentry><term> %GTK_RC_TEXT </term>
- <listitem>
-   <para>
-   If present, the text color has been set for this state.
-   </para>
- </listitem>
- </varlistentry>
- <varlistentry><term> %GTK_RC_BASE </term>
- <listitem>
-   <para>
-   If present, the base color has been set for this state.
-   </para>
- </listitem>
- </varlistentry>
-</variablelist>
 
-@GTK_RC_FG: 
-@GTK_RC_BG: 
-@GTK_RC_TEXT: 
-@GTK_RC_BASE: 
+@GTK_RC_FG: If present, the foreground color has been set for this state.
+@GTK_RC_BG: If present, the background color has been set for this state.
+@GTK_RC_TEXT: If present, the text color has been set for this state.
+@GTK_RC_BASE: If present, the base color has been set for this state.
 
 <!-- ##### ENUM GtkRcTokenType ##### -->
 <para>
@@ -628,7 +603,7 @@ specific portions of a RC file.
 
 <!-- ##### FUNCTION gtk_rc_add_widget_name_style ##### -->
 <para>
-Adds a RcStyle that will be looked up by a match against
+Adds a #GtkRcStyle that will be looked up by a match against
 the widget's pathname. This is equivalent to a:
 <literal>
 widget PATTERN style STYLE
@@ -642,7 +617,7 @@ statement in a RC file.
 
 <!-- ##### FUNCTION gtk_rc_add_widget_class_style ##### -->
 <para>
-Adds a RcStyle that will be looked up by a match against
+Adds a #GtkRcStyle that will be looked up by a match against
 the widget's class pathname. This is equivalent to a:
 <literal>
 widget_class PATTERN style STYLE
@@ -656,7 +631,7 @@ statement in a RC file.
 
 <!-- ##### FUNCTION gtk_rc_add_class_style ##### -->
 <para>
-Adds a RcStyle that will be looked up by a matching against
+Adds a #GtkRcStyle that will be looked up by a matching against
 the class hierarchy of the widget. This is equivalent to a:
 <literal>
 class PATTERN style STYLE
@@ -765,7 +740,7 @@ Looks up a file in the current module path.
 </para>
 
 @module_file: The name of the module to search for.
-@Returns: The filename, if found. (Must be freed with g_free()),
+@Returns: The filename, if found (must be freed with g_free()),
 otherwise %NULL.
 
 
@@ -777,7 +752,7 @@ otherwise %NULL.
 @scanner: a #GtkScanner. Used for printing out warning messages
 if the file is not found.
 @pixmap_file: The name of the file to search for.
-@Returns: The filename, if found. (Must be freed with g_free()),
+@Returns: The filename, if found (must be freed with g_free()),
 otherwise %NULL.
 <!-- # Unused Parameters # -->
 @context: 
@@ -815,7 +790,7 @@ be installed. (GTK+ does not actually use this directory
 itself.)
 </para>
 
-@Returns: The directory. (Must be freed with g_free())
+@Returns: The directory (must be freed with g_free()).
 
 
 <!-- ##### FUNCTION gtk_rc_style_new ##### -->