Merge text from xresmini.

1 files changed, 232 insertions, 27 deletions

diff --git a/man/xresources.texi b/man/xresources.texi
index 156c04cceb4..e9233df25d5 100644
--- a/man/xresources.texi
+++ b/man/xresources.texi
@@ -8,15 +8,25 @@
   You can customize some X-related aspects of Emacs behavior using X
 resources, as is usual for programs that use X.  On MS-Windows, you
 can customize some of the same aspects using the system registry.
-@xref{MS-Windows Registry}.  Likewise, the Mac Carbon port emulates X
+@xref{MS-Windows Registry}.  Likewise, Emacs on MacOS Carbon emulates X
 resources using the Preferences system.  @xref{Mac Environment Variables}.
 
-  When Emacs is built using an `X toolkit', such as Lucid or LessTif,
-you need to use X resources to customize the appearance of the
-widgets, including the menu-bar, scroll-bar, and dialog boxes.  This
-is because the libraries that implement these don't provide for
+  When Emacs is built using an ``X toolkit'', such as Lucid or 
+LessTif, you need to use X resources to customize the appearance of
+the widgets, including the menu-bar, scroll-bar, and dialog boxes.
+This is because the libraries that implement these don't provide for
 customization through Emacs.  GTK+ widgets use a separate system of
-`GTK resources', which we will also describe.
+@ifnottex
+``GTK resources'', which we will also describe.
+@end ifnottex
+@iftex
+``GTK resources.''  In this chapter we describe the most commonly used
+resource specifications.  For full documentation, see the online
+manual.
+
+@c Add xref for LessTif/Motif menu resources.
+@end iftex
+
 
 @menu
 * Resources::           Using X resources with Emacs (in general).
@@ -57,6 +67,18 @@ only customizable via the system-wide settings in the Display Control
 Panel.  You can also set resources using the @samp{-xrm} command line
 option (see below.)
 
+@iftex
+  Applications such as Emacs look for resources with specific names
+and their particular meanings.  Case distinctions are significant in
+these names.  Each resource specification in @file{~/.Xdefaults}
+states the name of the program and the name of the resource.  For
+Emacs, the program name is @samp{Emacs}.  It looks like this:
+ 
+@example
+Emacs.borderWidth: 2
+@end example
+@end iftex
+@ifnottex
   Programs define named resources with particular meanings.  They also
 define how to group resources into named classes.  For instance, in
 Emacs, the @samp{internalBorder} resource controls the width of the
@@ -95,9 +117,12 @@ borders, but overrides this value with 4 for the external border:
 emacs.BorderWidth: 2
 emacs.borderWidth: 4
 @end example
+@end ifnottex
 
   The order in which the lines appear in the file does not matter.
 Also, command-line options always override the X resources file.
+
+@ifnottex
 Here is a list of X command-line options and their corresponding
 resource names.
 
@@ -145,13 +170,19 @@ take precedence over all other resource specifications.
 
   One way to experiment with the effect of different resource settings
 is to use the @code{editres} program.  Select @samp{Get Tree} from the
+@end ifnottex
+@iftex
+  You can experiment with the effect of different resource settings
+with the @code{editres} program.  Select @samp{Get Tree} from the
+@end iftex
 @samp{Commands} menu, then click on an Emacs frame.  This will display
 a tree showing the structure of X toolkit widgets used in an Emacs
 frame.  Select one of them, such as @samp{menubar}, then select
 @samp{Show Resource Box} from the @samp{Commands} menu.  This displays
-a list of all the meaningful X resources and allows you to edit them.
-Changes take effect immediately if you click on the @samp{Apply} button.
-(See the @code{editres} man page for more details.)
+a list of all the meaningful X resources for that widget, and allows
+you to edit them.  Changes take effect when you click on the
+@samp{Apply} button.  (See the @code{editres} man page for more
+details.)
 
 @node Table of Resources
 @appendixsec Table of X Resources for Emacs
@@ -164,25 +195,31 @@ with the class that it belongs to:
 @item @code{background} (class @code{Background})
 Background color name.
 
+@ifnottex
 @item @code{bitmapIcon} (class @code{BitmapIcon})
 Use a bitmap icon (a picture of a gnu) if @samp{on}, let the window
 manager choose an icon if @samp{off}.
+@end ifnottex
 
 @item @code{borderColor} (class @code{BorderColor})
 Color name for the external border.
 
+@ifnottex
 @item @code{borderWidth} (class @code{BorderWidth})
 Width in pixels of the external border.
+@end ifnottex
 
 @item @code{cursorColor} (class @code{Foreground})
 Color name for text cursor (point).
 
+@ifnottex
 @item @code{cursorBlink} (class @code{CursorBlink})
 Specifies whether to make the cursor blink. The default is @samp{on}.  Use
 @samp{off} or @samp{false} to turn cursor blinking off.
+@end ifnottex
 
 @item @code{font} (class @code{Font})
-Font name for text (or fontset name, @pxref{Fontsets}).
+Font name (or fontset name, @pxref{Fontsets}) for @code{default} font.
 
 @item @code{foreground} (class @code{Foreground})
 Color name for text.
@@ -197,14 +234,15 @@ initial Emacs frame (or, in the case of a resource for a specific frame
 name, only that frame).  However, the size, if specified here, applies to
 all frames.
 
+@ifnottex
 @item @code{fullscreen} (class @code{Fullscreen})
 The desired fullscreen size.  The value can be one of @code{fullboth},
 @code{fullwidth} or @code{fullheight}, which correspond to
 the command-line options @samp{-fs}, @samp{-fw}, and @samp{-fh}
 (@pxref{Window Size X}).
 
-Note that this applies to all frames created, not just the initial
-one.
+Note that this applies to the initial frame only.
+@end ifnottex
 
 @item @code{iconName} (class @code{Title})
 Name to display in the icon.
@@ -219,10 +257,16 @@ Additional space (@dfn{leading}) between lines, in pixels.
 
 @item @code{menuBar} (class @code{MenuBar})
 @cindex menu bar
-Give frames menu bars if @samp{on}; don't have menu bars if
-@samp{off}.  @xref{Lucid Resources}, and @ref{LessTif Resources}, for
-how to control the appearance of the menu bar if you have one.
+Give frames menu bars if @samp{on}; don't have menu bars if @samp{off}.
+@ifnottex
+@xref{Lucid Resources}, and @ref{LessTif Resources},
+@end ifnottex
+@iftex
+@xref{Lucid Resources},
+@end iftex
+for how to control the appearance of the menu bar if you have one.
 
+@ifnottex
 @item @code{minibuffer} (class @code{Minibuffer})
 If @samp{none}, don't make a minibuffer in this frame.
 It will use a separate minibuffer frame instead.
@@ -230,10 +274,12 @@ It will use a separate minibuffer frame instead.
 @item @code{paneFont} (class @code{Font})
 @cindex font for menus
 Font name for menu pane titles, in non-toolkit versions of Emacs.
+@end ifnottex
 
 @item @code{pointerColor} (class @code{Foreground})
 Color of the mouse cursor.
 
+@ifnottex
 @item @code{privateColormap} (class @code{PrivateColormap})
 If @samp{on}, use a private color map, in the case where the ``default
 visual'' of class PseudoColor and Emacs is using it.
@@ -241,12 +287,14 @@ visual'' of class PseudoColor and Emacs is using it.
 @item @code{reverseVideo} (class @code{ReverseVideo})
 Switch foreground and background default colors if @samp{on}, use colors as
 specified if @samp{off}.
+@end ifnottex
 
 @item @code{screenGamma} (class @code{ScreenGamma})
 @cindex gamma correction
 Gamma correction for colors, equivalent to the frame parameter
 @code{screen-gamma}.
 
+@ifnottex
 @item @code{selectionFont} (class @code{SelectionFont})
 Font name for pop-up menu items, in non-toolkit versions of Emacs.  (For
 toolkit versions, see @ref{Lucid Resources}, also see @ref{LessTif
@@ -262,6 +310,7 @@ A value of 0 means wait as long as necessary.
 @cindex synchronous X mode
 Run Emacs in synchronous mode if @samp{on}.  Synchronous mode is
 useful for debugging X problems.
+@end ifnottex
 
 @item @code{title} (class @code{Title})
 Name to display in the title bar of the initial Emacs frame.
@@ -286,6 +335,7 @@ especially slow X client/server links.
 Give frames scroll bars if @samp{on}; don't have scroll bars if
 @samp{off}.
 
+@ifnottex
 @item @code{visualClass} (class @code{VisualClass})
 Specify the ``visual'' that X should use.  This tells X how to handle
 colors.
@@ -296,6 +346,7 @@ The value should start with one of @samp{TrueColor},
 @samp{-@var{depth}}, where @var{depth} is the number of color planes.
 Most terminals only allow a few ``visuals,'' and the @samp{dpyinfo}
 program outputs information saying which ones.
+@end ifnottex
 @end table
 
 @node Face Resources
@@ -358,6 +409,7 @@ Italic flag for face @var{face}---instead of @code{attributeSlant}.
 @cindex Menu X Resources (Lucid widgets)
 @cindex Lucid Widget X Resources
 
+@ifnottex
   If the Emacs installed at your site was built to use the X toolkit
 with the Lucid menu widgets, then the menu bar is a separate widget and
 has its own resources.  The resource names contain @samp{pane.menubar}
@@ -371,6 +423,14 @@ Emacs.pane.menubar.@var{resource}:  @var{value}
 @noindent
 For example, to specify the font @samp{8x16} for the menu-bar items,
 write this:
+@end ifnottex
+@iftex
+   If the Emacs installed at your site was built to use the X toolkit
+with the Lucid menu widgets, then the menu bar is a separate widget
+and has its own resources.  The resource specifications start with
+@samp{Emacs.pane.menubar}---for instance, to specify the font
+@samp{8x16} for the menu-bar items, write this:
+@end iftex
 
 @example
 Emacs.pane.menubar.font:  8x16
@@ -378,37 +438,43 @@ Emacs.pane.menubar.font:  8x16
 
 @noindent
 Resources for @emph{non-menubar} toolkit pop-up menus have
-@samp{menu*}, in like fashion.  For example, to specify the font
-@samp{8x16} for the pop-up menu items, write this:
+@samp{menu*} instead of @samp{pane.menubar}.  For example, to specify 
+the font @samp{8x16} for the pop-up menu items, write this:
 
 @example
 Emacs.menu*.font:       8x16
 @end example
 
 @noindent
-For dialog boxes, use @samp{dialog} instead of @samp{menu}:
+For dialog boxes, use @samp{dialog*}:
 
 @example
 Emacs.dialog*.font:     8x16
 @end example
 
 @noindent
-The Lucid menus can display multilingual text in your locale.  For more 
-information about fontsets see the man page for XCreateFontSet.  To enable
-multilingual menu text you specify a fontSet resource instead of the font
-resource.  If both font and fontSet resources are specified, the fontSet
-resource is used.  To specify
-@samp{-*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,*} for both the popup and
-menu bar menus, write this:
+The Lucid menus can display multilingual text in your locale.  For
+more information about fontsets see the man page for
+@code{XCreateFontSet}.  To enable multilingual menu text you specify a
+@code{fontSet} resource instead of the font resource.  If both
+@code{font} and @code{fontSet} resources are specified, the
+@code{fontSet} resource is used.
+
+  Thus, to specify @samp{-*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,*}
+for both the popup and menu bar menus, write this:
 
 @example
-Emacs*fontSet:  -*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,*
+Emacs*menu*fontSet:  -*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,*
 @end example
 
 @noindent
+The @samp{*menu*} as a wildcard matches @samp{pane.menubar} and
+@samp{menu@dots{}}.
+
 Experience shows that on some systems you may need to add
 @samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}.  On
-some other systems, you must not add @samp{shell.}.
+some other systems, you must not add @samp{shell.}.  The generic wildcard
+approach should work on both kinds of systems.
 
   Here is a list of the specific resources for menu bars and pop-up menus:
 
@@ -423,6 +489,7 @@ Color of the foreground.
 Color of the background.
 @item buttonForeground
 In the menu bar, the color of the foreground for a selected item.
+@ifnottex
 @item horizontalSpacing
 Horizontal spacing in pixels between items.  Default is 3.
 @item verticalSpacing
@@ -440,10 +507,12 @@ difference between ``in'' and ``out'' buttons is difficult to see, set
 this to 2.  If you have no problems with visibility, the default
 probably looks better.  The background color may also have some effect
 on the contrast.
+@end ifnottex
 @item margin
 The margin of the menu bar, in characters.  Default is 1.
 @end table
 
+@ifnottex
 @node LessTif Resources
 @appendixsec LessTif Menu X Resources
 @cindex Menu X Resources (LessTif widgets)
@@ -576,10 +645,145 @@ The color for the border shadow, on the bottom and the right.
 @item topShadowColor
 The color for the border shadow, on the top and the left.
 @end table
+@end ifnottex
 
 
 @node GTK resources
 @appendixsec GTK resources
+@iftex
+  The most common way to customize the GTK widgets Emacs uses (menus, dialogs
+tool bars and scroll bars) is by choosing an appropriate theme, for example
+with the GNOME theme selector.  You can also do Emacs specific customization
+by inserting GTK style directives in the file @file{~/.emacs.d/gtkrc}.  Some GTK
+themes ignore customizations in @file{~/.emacs.d/gtkrc} so not everything
+works with all themes.  To customize Emacs font, background, faces, etc., use
+the normal X resources (@pxref{Resources}).  We will present some examples of
+customizations here, but for a more detailed description, see the online manual
+
+  The first example is just one line.  It changes the font on all GTK widgets
+to courier with size 12:
+
+@smallexample
+gtk-font-name = "courier 12"
+@end smallexample
+
+  The thing to note is that the font name is not an X font name, like
+-*-helvetica-medium-r-*--*-120-*-*-*-*-*-*, but a Pango font name.  A Pango
+font name is basically of the format "family style size", where the style
+is optional as in the case above.  A name with a style could be for example:
+
+@smallexample
+gtk-font-name = "helvetica bold 10"
+@end smallexample
+
+  To customize widgets you first define a style and then apply the style to
+the widgets.  Here is an example that sets the font for menus, but not
+for other widgets:
+
+@smallexample
+# @r{Define the style @samp{menufont}.}
+style "menufont"
+@{
+  font_name = "helvetica bold 14"  # This is a Pango font name
+@}
+
+# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{menufont}.}
+widget "*emacs-menuitem*" style "menufont"
+@end smallexample
+
+The widget name in this example contains wildcards, so the style will be
+applied to all widgets that match "*emacs-menuitem*".  The widgets are
+named by the way they are contained, from the outer widget to the inner widget.
+So to apply the style "my_style" (not shown) with the full, absolute name, for
+the menubar and the scroll bar in Emacs we use:
+
+@smallexample
+widget "Emacs.pane.menubar" style "my_style"
+widget "Emacs.pane.emacs.verticalScrollBar" style "my_style"
+@end smallexample
+ 
+But to avoid having to type it all, wildcards are often used.  @samp{*}
+matches zero or more characters and @samp{?} matches one character.  So "*"
+matches all widgets.
+
+  Each widget has a class (for example GtkMenuItem) and a name (emacs-menuitem).
+You can assign styles by name or by class.  In this example we have used the
+class:
+
+@smallexample
+style "menufont"
+@{
+  font_name = "helvetica bold 14"
+@}
+
+widget_class "*GtkMenuBar" style "menufont"
+@end smallexample
+
+@noindent
+The names and classes for the GTK widgets Emacs uses are:
+
+@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{verticalScrollBar}
+@tab @code{GtkVScrollbar}
+@item @code{emacs-toolbar}
+@tab @code{GtkToolbar}
+@item @code{menubar}
+@tab @code{GtkMenuBar}
+@item @code{emacs-menuitem}
+@tab anything in menus
+@end multitable
+
+  GTK absolute names are quite strange when it comes to menus
+and dialogs.  The names do not start with @samp{Emacs}, as they are
+free-standing windows and not contained (in the GTK sense) by the
+Emacs GtkWindow.  To customize the dialogs and menus, use wildcards like this:
+
+@smallexample
+widget "*emacs-dialog*" style "my_dialog_style"
+widget "*emacs-filedialog* style "my_file_style"
+widget "*emacs-menuitem* style "my_menu_style"
+@end smallexample
+
+  If you specify a customization in @file{~/.emacs.d/gtkrc}, then it
+automatically applies only to Emacs, since other programs don't read
+that file.  For example, the drop down menu in the file dialog can not
+be customized by any absolute widget name, only by an absolute class
+name.  This is because the widgets in the drop down menu do not
+have names and the menu is not contained in the Emacs GtkWindow.  To
+have all menus in Emacs look the same, use this in
+@file{~/.emacs.d/gtkrc}:
+
+@smallexample
+widget_class "*Menu*" style "my_menu_style"
+@end smallexample
+
+  Here is a more elaborate example, showing how to change the parts of
+the scroll bar:
+
+@smallexample
+style "scroll"
+@{
+  fg[NORMAL] = "red"@ @ @ @ @ # @r{The arrow color.}
+  bg[NORMAL] = "yellow"@ @ # @r{The thumb and background around the arrow.}
+  bg[ACTIVE] = "blue"@ @ @ @ # @r{The trough color.}
+  bg[PRELIGHT] = "white"@ # @r{The thumb color when the mouse is over it.}
+@}
+
+widget "*verticalScrollBar*" style "scroll"
+@end smallexample
+@end iftex
+
+@ifnottex
 @cindex GTK resources and customization
 @cindex resource files for GTK
 @cindex @file{~/.gtkrc-2.0} file
@@ -996,6 +1200,7 @@ family.  It corresponds to the fifth part of an X font name.  It is one of
 
 @noindent
 @var{size} is a decimal number that describes the font size in points.
+@end ifnottex
 
 @ignore
    arch-tag: 9b6ff773-48b6-41f6-b2f9-f114b8bdd97f