[Emacs-diffs] emacs/doc/emacs ChangeLog xresources.texi

[Chong Yidong]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Chong Yidong <cyd>      09/05/12 03:18:03

Modified files:
        doc/emacs      : ChangeLog xresources.texi 

Log message:
        * xresources.texi (Resources): Simplify descriptions.  Shorten
        description of editres, which is not very useful these days.
        (Table of Resources): Document fontBackend resource.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/emacs/ChangeLog?cvsroot=emacs&r1=1.317&r2=1.318
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/emacs/xresources.texi?cvsroot=emacs&r1=1.4&r2=1.5

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/doc/emacs/ChangeLog,v
retrieving revision 1.317
retrieving revision 1.318
diff -u -b -r1.317 -r1.318
--- ChangeLog   12 May 2009 02:05:55 -0000      1.317
+++ ChangeLog   12 May 2009 03:18:03 -0000      1.318
@@ -1,5 +1,9 @@
 2009-05-12  Chong Yidong  <address@hidden>
 
+       * xresources.texi (Resources): Simplify descriptions.  Shorten
+       description of editres, which is not very useful these days.
+       (Table of Resources): Document fontBackend resource.
+
        * trouble.texi (Quitting): Add other undo bindings to table.
        (DEL Does Not Delete): Note that the erasure key is usually labelled
        "Backspace".  Remove discussion of obscure Xmodmap issue.

Index: xresources.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/emacs/xresources.texi,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- xresources.texi     8 Jan 2009 05:28:53 -0000       1.4
+++ xresources.texi     12 May 2009 03:18:03 -0000      1.5
@@ -10,7 +10,7 @@
 can customize some of the same aspects using the system registry.
 @xref{MS-Windows Registry}.
 
-o  When Emacs is built using an ``X toolkit'', such as Lucid or
+  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
@@ -45,63 +45,49 @@
 
   Programs running under the X Window System organize their user
 options under a hierarchy of classes and resources.  You can specify
-default values for these options in your X resources file, usually
-named @file{~/.Xdefaults} or @file{~/.Xresources}.
-If changes in @file{~/.Xdefaults} do not
-take effect, it is because your X server stores its own list of
-resources; to update them, use the shell command @command{xrdb}---for
-instance, @samp{xrdb ~/.Xdefaults}.
-
-  Each line in the file specifies a value for one option or for a
-collection of related options, for one program or for several programs
-(optionally even for all programs).
+default values for these options in your @dfn{X resource file},
+usually named @file{~/.Xdefaults} or @file{~/.Xresources}.  Changes in
+this file do not take effect immediately, because the X server stores
+its own list of resources; to update it, use the command
address@hidden instance, @samp{xrdb ~/.Xdefaults}.
 
 @cindex Registry (MS-Windows)
-  MS-Windows systems do not support @file{~/.Xdefaults} files, so
-instead Emacs compiled for Windows looks for X resources in the
-Windows Registry, first under the key
address@hidden and then under the key
+  (MS-Windows systems do not support X resource files; on Windows,
+Emacs looks for X resources in the Windows Registry, first under the
+key @samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs} and then under the key
 @samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs}.  The menu and scroll
 bars are native widgets on MS-Windows, so they are 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.)
+also set resources using the @samp{-xrm} command line option, as
+explained below.)
 
address@hidden
-  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:
-
address@hidden
-Emacs.borderWidth: 2
address@hidden example
address@hidden iftex
address@hidden
-  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
-internal border, and the @samp{borderWidth} resource controls the width
-of the external border.  Both of these resources are part of the
address@hidden class.  Case distinctions are significant in these
-names.
-
-  Every resource definition is associated with a specific program
-name---the name of the executable file that you ran.  For Emacs, that
-is normally @samp{emacs}.  To specify a definition for all instances
-of Emacs, regardless of their names, use @samp{Emacs}.
-
-  In @file{~/.Xdefaults}, you can specify a value for a single resource
-on one line, like this:
+  Each line in the X resource file specifies a value for one option or
+for a collection of related options.  Each resource specification
+consists of a @dfn{program name} and a @dfn{resource name}.  Case
+distinctions are significant in each of these names.  Here is an
+example:
 
 @example
 emacs.borderWidth: 2
 @end example
 
address@hidden
-Or you can use a class name to specify the same value for all resources
-in that class.  Here's an example:
address@hidden
+  The program name is the name of the executable file to which the
+resource applies.  For Emacs, this is normally @samp{emacs}.  To
+specify a definition that applies to all instances of Emacs,
+regardless of the name of the Emacs executable, use @samp{Emacs}.
+
+  The resource name is the name of a program setting.  For instance,
+Emacs recognizes a @samp{borderWidth} resource that controls the width
+of the external border for graphical frames.
+
+  Resources are grouped into named classes.  For instance, the
address@hidden class contains both the @samp{borderWidth} resource
+(which we just described), as well as the @samp{internalBorder}
+resource, which controls the width of the internal border for
+graphical frames.  Instead of using a resource name, you can use a
+class name to specify the same value for all resources in that class.
+Here's an example:
 
 @example
 emacs.BorderWidth: 2
@@ -109,9 +95,10 @@
 
   If you specify a value for a class, it becomes the default for all
 resources in that class.  You can specify values for individual
-resources as well; these override the class value, for those particular
-resources.  Thus, this example specifies 2 as the default width for all
-borders, but overrides this value with 4 for the external border:
+resources as well; these override the class value, for those
+particular resources.  The following example specifies 2 as the
+default width for all borders, but overrides this value with 4 for the
+external border:
 
 @example
 emacs.BorderWidth: 2
@@ -123,66 +110,49 @@
 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.
+  The following X command-line options affect how X resources are
+processed:
 
 @table @samp
 @item -name @var{name}
 @opindex --name
 @itemx address@hidden
 @cindex resource name, command-line argument
-Use @var{name} as the resource name (and the title) for the initial
-Emacs frame.  This option does not affect subsequent frames, but Lisp
-programs can specify frame names when they create frames.
+This option sets the program name of the initial Emacs frame to
address@hidden  It also sets the title of the initial frame to
address@hidden  This option does not affect subsequent frames.
 
 If you don't specify this option, the default is to use the Emacs
-executable's name as the resource name.
+executable's name as the program name.
+
+For consistency, @samp{-name} also specifies the name to use for other
+resource values that do not belong to any particular frame.
+
+The resources that name Emacs invocations also belong to a class,
+named @samp{Emacs}.  If you write @samp{Emacs} instead of
address@hidden, the resource applies to all frames in all Emacs jobs,
+regardless of frame titles and regardless of the name of the
+executable file.
 
 @item -xrm @var{resource-values}
 @opindex --xrm
 @itemx address@hidden
 @cindex resource values, command-line argument
-Specify X resource values for this Emacs job (see below).
address@hidden table
+This option specifies X resource values for the present Emacs job.
 
-  For consistency, @samp{-name} also specifies the name to use for
-other resource values that do not belong to any particular frame.
-
-  The resources that name Emacs invocations also belong to a class; its
-name is @samp{Emacs}.  If you write @samp{Emacs} instead of
address@hidden, the resource applies to all frames in all Emacs jobs,
-regardless of frame titles and regardless of the name of the executable
-file.  Here is an example:
-
address@hidden
-Emacs.BorderWidth: 2
-Emacs.borderWidth: 4
address@hidden example
-
-  You can specify a string of additional resource values for Emacs to
-use with the command line option @samp{-xrm @var{resources}}.  The text
address@hidden should have the same format that you would use inside a file
-of X resources.  To include multiple resource specifications in
address@hidden, put a newline between them, just as you would in a file.
-You can also use @samp{#include "@var{filename}"} to include a file full
-of resource specifications.  Resource values specified with @samp{-xrm}
-take precedence over all other resource specifications.
address@hidden should have the same format that you would use
+inside a file of X resources.  To include multiple resource
+specifications in @var{resource-values}, put a newline between them,
+just as you would in a file.  You can also use @samp{#include
+"@var{filename}"} to include a file full of resource specifications.
+Resource values specified with @samp{-xrm} take precedence over all
+other resource specifications.
address@hidden table
address@hidden ifnottex
 
   One way to experiment with the effect of different resource settings
-is to use the @code{editres} program.  Select @samp{Get Tree} from the
address@hidden ifnottex
address@hidden
-  You can experiment with the effect of different resource settings
-with the @code{editres} program.  Select @samp{Get Tree} from the
address@hidden iftex
address@hidden 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
address@hidden Resource Box} from the @samp{Commands} menu.  This displays
-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
address@hidden button.  (See the @code{editres} man page for more
-details.)
+is to use the @code{editres} program.  See the @code{editres} man page
+for more details.
 
 @node Table of Resources
 @appendixsec Table of X Resources for Emacs
@@ -219,7 +189,17 @@
 @end ifnottex
 
 @item @code{font} (class @code{Font})
-Font name (or fontset name, @pxref{Fontsets}) for @code{default} font.
+Font name for the @code{default} font.  @xref{Font X}.  You can also
+specify a fontset name (@pxref{Fontsets}).
+
address@hidden @code{fontBackend} (class @code{FontBackend})
+The backend(s) to use for drawing fonts; if multiple backends are
+specified, they must be comma-delimited and given in order of
+precedence.  On X, for instance, the value @samp{x,xft} tells Emacs to
+draw fonts using the X core font driver, falling back on the Xft font
+driver if that fails.  Normally, you can leave this resource unset, in
+which case Emacs tries using all font backends available on your
+graphical device.
 
 @item @code{foreground} (class @code{Foreground})
 Color name for text.