Re: GTK documentation in Emacs

[Miles Bader <miles@lsi.nec.co.jp>]

[-- Attachment #1: Type: text/plain, Size: 167 bytes --]

Absolutely excellent -- I now understand what's going on!

Here's a patch that makes some minor clarifications, corrections, and
formatting changes to what you did:



[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Patch to xresources.texi --]
[-- Type: text/x-patch, Size: 13609 bytes --]

diff -up man/xresources.texi.\~2\~ man/xresources.texi
--- man/xresources.texi.~2~	2003-01-10 11:19:42.000000000 +0900
+++ man/xresources.texi	2003-01-10 12:24:24.000000000 +0900
@@ -1,5 +1,5 @@
 @c This is part of the Emacs manual.
-@c Copyright (C) 1987,93,94,95,1997,2001 Free Software Foundation, Inc.
+@c Copyright (C) 1987,93,94,95,1997,2001,03 Free Software Foundation, Inc.
 @c See file emacs.texi for copying conditions.
 @node X Resources, Antinews, Command Arguments, Top
 @appendix X Options and Resources
@@ -533,13 +533,13 @@ The color for the border shadow, on the 
   If the Emacs installed at your site was built to use the GTK widget set,
 then the menu bar, scroll bar and the dialogs can be customized with
 the standard GTK @file{~/.gtkrc-2.0} file or with the Emacs specific
-@file{~/.emacs.d/gtkrc} file.  Note that this is only for 
+@file{~/.emacs.d/gtkrc} file; note that these files are only for 
 customizing specific GTK widget features.  To customize Emacs font,
 background, faces etc., use the normal X resources, see @ref{Resources}.
 
-In these files one first defines a style and then apply that style 
-to widget paths.  Here is an example of how to change the font for
-Emacs menus:
+In these files one first defines a style and then how to apply that style
+to widget paths (@pxref{GTK widget paths}).  Here is an example of how to
+change the font for Emacs menus:
 
 @smallexample
 # This is a comment.
@@ -552,13 +552,15 @@ widget "*emacs-menuitem*" style "menufon
 
 @end smallexample
 
-  There are some items you can set without using any style or widget path,
-that affects GTK as a whole.  Most of these are poorly documented but
-can be found as properties in the documentation for @code{GtkSetting} in the
-GTK document references below.
-One property of interest is gtk-font-name which sets
-a default font.  You have to use Pango font names, see @ref{GTK styles}.
-A @file{~/.gtkrc-2.0} file that just sets a default font looks like this:
+  There are some things you can set without using any style or widget path,
+which affect GTK as a whole.  Most of these are poorly documented, but can
+be found in the `Properties' section of the documentation page for
+@code{GtkSetting}, in the GTK document references below.
+
+One property of interest is @code{gtk-font-name} which sets the default
+font for GTK; you must use Pango font names (@pxref{GTK styles}).  A
+@file{~/.gtkrc-2.0} file that just sets a default font looks like this:
+
 @smallexample
 gtk-font-name = "courier 12"
 @end smallexample
@@ -567,11 +569,11 @@ gtk-font-name = "courier 12"
   The syntax for GTK resource files is fully described in the GTK
 API reference manual.  You may have this on your site as:
 
-@file{prefix/share/gtk-doc/html/gtk/gtk-resource-files.html},
+@file{@var{prefix}/share/gtk-doc/html/gtk/gtk-resource-files.html},
 
 @noindent
-where ``prefix'' is where GTK is installed, usually @file{/usr}.
-You can find this online at
+where @var{prefix} is the prefix under which GTK is installed, usually
+@file{/usr} or @file{/usr/local}.  You can find the same document online at:
  
 @uref{http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html}.
 
@@ -588,37 +590,41 @@ You can find this online at
 @cindex GTK widget names
 @cindex GTK widget classes
 
-Widgets can be specified by widget class or by
-widget name.  Widgets have pathnames made from how they are contained.
-For example, if a @code{GtkWindow} contains a @code{GtkVBox} which in turn
-contains a @code{GtkMenuBar}, the class path would then be:
+Widgets can be specified by widget class or by widget name.  Widget paths
+are sequences of widget names or classes, corresponding to hierarchies of
+widgets embedded within other widgets.  For example, if a @code{GtkWindow}
+contains a @code{GtkVBox} which in turn contains a @code{GtkMenuBar}, the
+widget class path would then be:
+
 @smallexample
 GtkWindow.GtkVBox.GtkMenuBar
 @end smallexample
 
 @noindent
-If the widgets are named ``top'', ``box'' and ``menubar'', the widget
-path then becomes:
+If the widgets are named ``top'', ``box'' and ``menubar'', the widget name
+path would be:
+
 @smallexample
 top.box.menubar
 @end smallexample
 
-  When assigning a style to a path, one can use the class path,
-the widget path, or a mixture of both.  The key word 
-@code{widget_class} matches only against the class path.  The key word
-@code{widget} matches first against the name and secondly against the
-class.
-
-  Matching is done with shell ``glob'' syntax, that is *
-matches zero or more characters, ? matches one character.  So
-this assigns @code{base_style} to all widgets:
+  When assigning a style to a path, one can use the class path, the widget
+path, or a mixture of both.  There are two commands:  @code{widget_class}
+will assign a style to a widget path, matching only against the class path,
+whereas the @code{widget} command will match first against the name and
+secondly against the class.
+
+  Matching of widget paths uses shell ``glob'' syntax, that is @code{*}
+matches zero or more characters and @code{?} matches one character.  So the
+following would assign @code{base_style} to all widgets:
 
 @smallexample
 widget "*" style "base_style"
 @end smallexample
 
   Given the class path @code{GtkWindow.GtkVBox.GtkMenuBar} and the widget
-path @code{top.box.menubar}, these all assign @code{my_style} to the menu bar:
+path @code{top.box.menubar}, the following all assign @code{my_style} to
+the menu bar:
 
 @smallexample
 widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style"
@@ -653,7 +659,7 @@ widget_class "GtkWindow.GtkVBox.GtkMenuB
 @end smallexample
 
 @noindent
-And for the scroll bar, the full path is:
+For the scroll bar, the full path is:
 
 @smallexample
 widget_class 
@@ -661,28 +667,30 @@ widget_class 
      style "my_style"
 @end smallexample
 
-  The names for the widgets are:
+@noindent
+The names for the emacs widgets, and their classes, are:
 
-@multitable {@code{GtkFileSelection} and some} {@code{verticalScrollbar plus}}
-@item @code{GtkFileSelection}
-@tab @code{emacs-filedialog}
-@item @code{GtkDialog}
-@tab @code{emacs-dialog}
-@item @code{GtkWindow}
-@tab @code{Emacs}
-@item @code{GtkVHbox}
-@tab @code{pane}
-@item @code{GtkFixed}
-@tab @code{emacs}
-@item @code{GtkMenuBar}
-@tab @code{menubar}
-@item @code{GtkVScrollbar}
-@tab @code{verticalScrollbar}
-@item anything in menus
-@tab @code{emacs-menuitem}
+@multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some}
+@item @code{emacs-filedialog}
+@tab @code{GtkFileSelection}
+@item @code{emacs-dialog}
+@tab @code{GtkDialog}
+@item @code{Emacs}
+@tab @code{GtkWindow}
+@item @code{pane}
+@tab @code{GtkVHbox}
+@item @code{emacs}
+@tab @code{GtkFixed}
+@item @code{menubar}
+@tab @code{GtkMenuBar}
+@item @code{verticalScrollbar}
+@tab @code{GtkVScrollbar}
+@item @code{emacs-menuitem}
+@tab anything in menus
 @end multitable
 
-  Thus, for Emacs you can write the two examples above as:
+@noindent
+Thus, for Emacs you can write the two examples above as:
 
 @smallexample
 widget "Emacs.pane.menubar" style "my_style"
@@ -691,7 +699,7 @@ widget "Emacs.pane.emacs.verticalScrollb
 
   GTK absolute paths are quite strange when it comes to menus
 and dialogs.  The paths do not start with Emacs as they are free standing
-windows and not contained in the GTK sense by the Emacs GtkWindow.
+windows and not contained (in the GTK sense) by the Emacs GtkWindow.
 To customize the dialogs and menus, use wildcards like this:
 
 @smallexample
@@ -714,34 +722,35 @@ widget "*Menu*" style "my_menu_style"
 
 @node GTK styles,  , GTK names in Emacs, GTK resources
 @appendixsec GTK styles
-@cindex GTK style
+@cindex GTK styles
 
   This is mostly taken from the GTK reference documentation.
 Within a style declaration, the possible elements are:
 
 @table @code
-@item bg[state] = color
+@item bg[@var{state}] = @var{color}
 Sets the color used for the background of most widgets.  The widget where
-you edit text in Emacs ignores this.  Use X resources (i.e.
-@code{Emacs.background: color}) for this, see @ref{Resources}.  The values
-for @code{state} are enumerated below.
+you edit text in Emacs ignores this; for it, use X resources (i.e.
+@code{Emacs.background: color}; @ref{Resources})), or emacs faces
+(@pxref{Faces}).  The possible values for @var{state} are enumerated below.
 
-@item fg[state] = color
+@item fg[@var{state}] = @var{color}
 Sets the color used for the foreground of most widgets.  The widget where
-you edit text in Emacs ignores this.  Use X resources (i.e.
-@code{Emacs.foreground: color}) for this, see @ref{Resources}.
+you edit text in Emacs ignores this; for it, use X resources (i.e.
+@code{Emacs.foreground: @var{color}}; @ref{Resources})), or emacs faces
+(@pxref{Faces}).
 
-@item base[state] = color
+@item base[@var{state}] = @var{color}
 Sets the color used for the background of widgets displaying editable
 text. In Emacs, this color is used for the background of the text
 fields in the file dialog.
 
-@item text[state] = color
+@item text[@var{state}] = @var{color}
 Sets the color used for foreground of widgets using base for the background
 color.  In Emacs, this color is used for the text color in
 fields in the file dialog.
 
-@item bg_pixmap[state] = pixmap
+@item bg_pixmap[@var{state}] = @var{pixmap}
 Sets a background pixmap to be used in place of the background color.
 The special value @code{<parent>}
 may be used to indicate that the widget should use the same background
@@ -754,8 +763,8 @@ in @file{~/.emacs.d/gtkrc}, the pixmap i
 @file{~/.emacs.d}.  It does not seem possible to refer to a
 file by its absolute path name.
 
-@item font_name = font
-Sets the font for a widget.  The font must be a Pango font name,
+@item font_name = @var{font}
+Sets the font for a widget to @var{font}, which must be a Pango font name,
 for example ``Sans Italic 10'', ``Helvetica Bold 12'', ``Courier 14'',
 ``Times 18''.  See below for exact syntax.  The names are case insensitive.
 @end table
@@ -793,66 +802,43 @@ or @code{#rgb}, where r, g and b are hex
 as a triplet @code{@{ r, g, b @}}, where r, g and b are either integers 
 in the range 0-65535 or floats in the range 0.0-1.0.
 
-  Pang font names have the form ``FAMILY-LIST STYLE-OPTIONS SIZE''.
+  Pango font names have the form ``@var{family-list} @var{style-options}
+@var{size}''.
 
 @noindent
-FAMILY-LIST is a comma separated list of families optionally terminated 
-by a comma.  This way you can specify several families and the first
-one found will be used.  The FAMILY corresponds to the second part in
+@var{family-list} is a comma separated list of font families optionally
+terminated by a comma.  This way you can specify several families and the
+first one found will be used.  @var{family} corresponds to the second part in
 an X font name, for example in
-``-adobe-times-medium-r-normal--12-120-75-75-p-64-iso10646-1''
-the family name is ``times''.
+``-adobe-times-medium-r-normal--12-120-75-75-p-64-iso10646-1'' the family
+name is ``times''.
 
 @noindent
-STYLE-OPTIONS is a whitespace separated list of words where each word
-describes one of style, variant, weight, or stretch.
-The @code{normal} values below does not need to be specified in a Pango
-font name, they are the default.
-
+@var{style-options} is a whitespace separated list of words where each word
+is a style, variant, weight, or stretch.  The default value for all of
+these is @code{normal}.
 
 @noindent
-Style corresponds to the fourth part of an X font name.  In X font names
-it is the character ``r'', ``i'' or ``o''.  In Pango font names
-it is one of
-@itemize @bullet
-@item @code{normal}
-@item @code{italic}
-@item @code{oblique}
-@end itemize
+A `style' corresponds to the fourth part of an X font name.  In X font
+names it is the character ``r'', ``i'' or ``o''; in Pango font names the
+corresponding values are @code{normal}, @code{italic}, or @code{oblique}.
 
 @noindent
-Variant is either @code{normal} or @code{small-caps}.
+a `variant' is either @code{normal} or @code{small-caps}.
 Small caps is a font with the lower case characters replaced by
 smaller variants of the capital characters.
 
 @noindent
 Weight describes the ``boldness'' of a font.  It corresponds to the third
-part of an X font name.  It is one of
-@itemize @bullet
-@item @code{ultra-light}
-@item @code{light}
-@item @code{normal}
-@item @code{bold}
-@item @code{ultra-bold}
-@item @code{heavy}
-@end itemize
-
-@noindent
-Stretch gives the width of the font relative to other designs within a 
-family.  It corresponds to the fifth part of an X font name.
-It is one of
-@itemize @bullet
-@item @code{ultra-condensed}
-@item @code{extra-condensed}
-@item @code{condensed}
-@item @code{semi-condensed}
-@item @code{normal}
-@item @code{semi-expanded}
-@item @code{expanded}
-@item @code{extra-expanded}
-@item @code{ultra-expanded}
-@end itemize
+part of an X font name.  It is one of @code{ultra-light}, @code{light},
+@code{normal}, @code{bold}, @code{ultra-bold}, or @code{heavy}.
 
 @noindent
-SIZE is a decimal number that describes the font size in points.
+Stretch gives the width of the font relative to other designs within a
+family.  It corresponds to the fifth part of an X font name.  It is one of
+@code{ultra-condensed}, @code{extra-condensed}, @code{condensed},
+@code{semi-condensed}, @code{normal}, @code{semi-expanded},
+@code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}.
 
+@noindent
+@var{size} is a decimal number that describes the font size in points.

[-- Attachment #3: Type: text/plain, Size: 165 bytes --]



-Miles
-- 
I'm beginning to think that life is just one long Yoko Ono album; no rhyme
or reason, just a lot of incoherent shrieks and then it's over.  --Ian Wolff

[-- Attachment #4: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/emacs-devel