[Emacs-diffs] /srv/bzr/emacs/emacs-24 r107817: New Lisp manual nodes, Applying Customizations and Custom Themes.

[Chong Yidong]

------------------------------------------------------------
revno: 107817
committer: Chong Yidong <address@hidden>
branch nick: emacs-24
timestamp: Thu 2012-04-12 22:50:58 +0800
message:
  New Lisp manual nodes, Applying Customizations and Custom Themes.
  
  * doc/lispref/customize.texi (Applying Customizations):
  (Custom Themes): New nodes.
  
  * doc/lispref/display.texi (Defining Faces): Reference custom-set-faces.
  
  * doc/lispref/modes.texi (Defining Minor Modes, Defining Minor Modes):
  * doc/lispref/os.texi (Startup Summary): Copyedits.
  
  * doc/emacs/custom.texi (Creating Custom Themes): Add reference to Custom
  Themes node in Lisp manual.
  
  * lisp/custom.el (custom-theme-set-variables): Doc fix.
modified:
  doc/emacs/ChangeLog
  doc/emacs/custom.texi
  doc/lispref/ChangeLog
  doc/lispref/customize.texi
  doc/lispref/display.texi
  doc/lispref/elisp.texi
  doc/lispref/modes.texi
  doc/lispref/os.texi
  doc/lispref/vol1.texi
  doc/lispref/vol2.texi
  lisp/ChangeLog
  lisp/custom.el

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2012-04-12 05:18:15 +0000
+++ b/doc/emacs/ChangeLog       2012-04-12 14:50:58 +0000
@@ -1,3 +1,8 @@
+2012-04-12  Chong Yidong  <address@hidden>
+
+       * custom.texi (Creating Custom Themes): Add reference to Custom
+       Themes node in Lisp manual.
+
 2012-04-12  Glenn Morris  <address@hidden>
 
        * mule.texi (International): Copyedits.

=== modified file 'doc/emacs/custom.texi'
--- a/doc/emacs/custom.texi     2012-04-12 01:09:15 +0000
+++ b/doc/emacs/custom.texi     2012-04-12 14:50:58 +0000
@@ -684,9 +684,8 @@
   A theme file is simply an Emacs Lisp source file, and loading the
 Custom theme works by loading the Lisp file.  Therefore, you can edit
 a theme file directly instead of using the @file{*Custom Theme*}
-buffer.
address@hidden Add link to the relevant Emacs Lisp Reference manual node, once
address@hidden that is written.
+buffer.  @xref{Custom Themes,,, elisp, The Emacs Lisp Reference
+Manual}, for details.
 
 @node Variables
 @section Variables

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-04-12 01:09:15 +0000
+++ b/doc/lispref/ChangeLog     2012-04-12 14:50:58 +0000
@@ -1,3 +1,13 @@
+2012-04-12  Chong Yidong  <address@hidden>
+
+       * customize.texi (Applying Customizations):
+       (Custom Themes): New nodes.
+
+       * display.texi (Defining Faces): Reference custom-set-faces.
+
+       * modes.texi (Defining Minor Modes, Defining Minor Modes):
+       * os.texi (Startup Summary): Copyedits.
+
 2012-04-12  Glenn Morris  <address@hidden>
 
        * loading.texi (Loading Non-ASCII): "unibyte:" can also be at the end.

=== modified file 'doc/lispref/customize.texi'
--- a/doc/lispref/customize.texi        2012-04-10 07:11:23 +0000
+++ b/doc/lispref/customize.texi        2012-04-12 14:50:58 +0000
@@ -4,20 +4,25 @@
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/customize
 @node Customization, Loading, Macros, Top
address@hidden Writing Customization Definitions
-
address@hidden customization definitions
-  This chapter describes how to declare user options for customization,
-and also customization groups for classifying them.  We use the term
address@hidden item} to include both kinds of customization
-definitions---as well as face definitions (@pxref{Defining Faces}).
address@hidden Customization Settings
+
address@hidden customization item
+  This chapter describes how to declare customizable variables and
+customization groups for classifying them.  We use the term
address@hidden item} to include customizable variables,
+customization groups, as well as faces.
+
+  @xref{Defining Faces}, for the @code{defface} macro, which is used
+for declaring customizable faces.
 
 @menu
-* Common Keywords::      Common keyword arguments for all kinds of
-                           customization declarations.
-* Group Definitions::    Writing customization group definitions.
-* Variable Definitions:: Declaring user options.
-* Customization Types::  Specifying the type of a user option.
+* Common Keywords::         Common keyword arguments for all kinds of
+                             customization declarations.
+* Group Definitions::       Writing customization group definitions.
+* Variable Definitions::    Declaring user options.
+* Customization Types::     Specifying the type of a user option.
+* Applying Customizations:: Functions to apply customization settings.
+* Custom Themes::           Writing Custom themes.
 @end menu
 
 @node Common Keywords
@@ -306,7 +311,7 @@
 @item :set @var{setfunction}
 @kindex address@hidden, @code{defcustom} keyword}
 Specify @var{setfunction} as the way to change the value of this
-option when using the Customize user interface.  The function
+option when using the Customize interface.  The function
 @var{setfunction} should take two arguments, a symbol (the option
 name) and the new value, and should do whatever is necessary to update
 the value properly for this option (which may not mean simply setting
@@ -1250,3 +1255,132 @@
 the data structure is itself recursive, this conversion is an infinite
 recursion.  The @code{lazy} widget prevents the recursion: it convert
 its @code{:type} argument only when needed.
+
address@hidden Applying Customizations
address@hidden Applying Customizations
+
+The following functions are responsible for installing the user's
+customization settings for variables and faces, respectively.  When
+the user invokes @samp{Save for future sessions} in the Customize
+interface, that takes effect by writing a @code{custom-set-variables}
+and/or a @code{custom-set-faces} form into the custom file, to be
+evaluated the next time Emacs starts up.
+
address@hidden custom-set-variables &rest args
+This function installs the variable customizations specified by
address@hidden  Each argument in @var{args} should have the form
+
address@hidden
+(@var{var} @var{expression} address@hidden address@hidden address@hidden)
address@hidden example
+
address@hidden
address@hidden is a variable name (a symbol), and @var{expression} is an
+expression which evaluates to the desired customized value.
+
+If the @code{defcustom} form for @var{var} has been evaluated prior to
+this @code{custom-set-variables} call, @var{expression} is immediately
+evaluated, and the variable's value is set to the result.  Otherwise,
address@hidden is stored into the variable's @code{saved-value}
+property, to be evaluated when the relevant @code{defcustom} is called
+(usually when the library defining that variable is loaded into
+Emacs).
+
+The @var{now}, @var{request}, and @var{comment} entries are for
+internal use only, and may be omitted.  @var{now}, if address@hidden,
+means to set the variable's value now, even if the variable's
address@hidden form has not been evaluated.  @var{request} is a list
+of features to be loaded immediately (@pxref{Named Features}).
address@hidden is a string describing the customization.
address@hidden defun
+
address@hidden custom-set-faces &rest args
+This function installs the face customizations specified by
address@hidden  Each argument in @var{args} should have the form
+
address@hidden
+(@var{face} @var{spec} address@hidden address@hidden)
address@hidden example
+
address@hidden
address@hidden is a face name (a symbol), and @var{spec} is the customized
+face specification for that face (@pxref{Defining Faces}).
+
+The @var{now} and @var{comment} entries are for internal use only, and
+may be omitted.  @var{now}, if address@hidden, means to install the
+face specification now, even if the @code{defface} form has not been
+evaluated.  @var{comment} is a string describing the customization.
address@hidden defun
+
address@hidden Custom Themes
address@hidden Custom Themes
+
+  @dfn{Custom themes} are collections of settings that can be enabled
+or disabled as a unit.  @xref{Custom Themes,,, emacs, The GNU Emacs
+Manual}.  Each Custom theme is defined by an Emacs Lisp source file,
+which should follow the conventions described in this section.
+(Instead of writing a Custom theme by hand, you can also create one
+using a Customize-like interface; @pxref{Creating Custom Themes,,,
+emacs, The GNU Emacs Manual}.)
+
+  A Custom theme file should be named @address@hidden, where
address@hidden is the theme name.  The first Lisp form in the file should
+be a call to @code{deftheme}, and the last form should be a call to
address@hidden
+
address@hidden deftheme theme &optional doc
+This macro declares @var{theme} (a symbol) as the name of a Custom
+theme.  The optional argument @var{doc} specifies a string describing
+the theme; this is the description shown when the user invokes the
address@hidden (@code{describe-theme}) command in the @samp{*Custom Themes*}
+buffer.
+
+Two special theme names are disallowed: @code{user} is a ``dummy
+theme'' used to store the user's direct customization settings, and
address@hidden is a ``dummy theme'' used to store changes made outside
+of the Customize system.  If you specify either of these as the
address@hidden argument, @code{deftheme} signals an error.
address@hidden defmac
+
address@hidden provide-theme theme
+This macro declares that the theme named @var{theme} has been fully
+specified.
address@hidden defmac
+
+  In between @code{deftheme} and @code{provide-theme} are the Lisp
+forms specifying the theme settings---usually a call to
address@hidden and/or a call to
address@hidden:
+
address@hidden custom-theme-set-variables theme &rest args
+This function declares that the Custom theme @var{theme} (a symbol)
+customizes the variables in @var{args}.  Each argument in @var{args}
+should be a list of the form
+
address@hidden
+(@var{var} @var{expression} address@hidden address@hidden address@hidden)
address@hidden example
+
address@hidden
+where the list entries have the same meanings as in
address@hidden  @xref{Applying Customizations}.
address@hidden defun
+
address@hidden custom-theme-set-faces theme &rest args
+This function declares that the Custom theme @var{theme} (a symbol)
+customizes the faces in @var{args}.  Each argument in @var{args}
+should be a list of the form
+
address@hidden
+(@var{face} @var{spec} address@hidden address@hidden)
address@hidden example
+
address@hidden
+where the list entries have the same meanings as in
address@hidden  @xref{Applying Customizations}.
address@hidden defun
+
+  In principle, a theme file can also contain other Lisp forms, which
+would be evaluated when loading the theme; but it is ``bad form'' for
+a theme to do this.  (For reasons of security, Emacs prompts the user
+before loading any non-built-in theme.)

=== modified file 'doc/lispref/display.texi'
--- a/doc/lispref/display.texi  2012-04-10 07:11:23 +0000
+++ b/doc/lispref/display.texi  2012-04-12 14:50:58 +0000
@@ -1885,7 +1885,7 @@
 attributes in one frame (@pxref{Attribute Functions}).
 
 @menu
-* Defining Faces::      How to define a face with @code{defface}.
+* Defining Faces::      How to define a face.
 * Face Attributes::     What is in a face?
 * Attribute Functions::  Functions to examine and set face attributes.
 * Displaying Faces::     How Emacs combines the faces specified for a 
character.
@@ -1904,22 +1904,17 @@
 @node Defining Faces
 @subsection Defining Faces
 
-  The way to define a new face is with @code{defface}.  This creates a
-kind of customization item which the user can customize using the
-Customization buffer (@pxref{Customization}).
-
-  People are sometimes tempted to create variables whose values specify
-which faces to use (for example, Font-Lock does this).  In the vast
-majority of cases, this is not necessary, and simply using faces
-directly is preferable.
+  The @code{defface} macro defines a face and specifies its default
+appearance.  The user can subsequently customize the face using the
+Customize interface (@pxref{Customization}).
 
 @defmac defface face spec doc [keyword address@hidden
-This declares @var{face} as a customizable face whose default
+This macro declares @var{face} as a customizable face whose default
 attributes are given by @var{spec}.  You should not quote the symbol
 @var{face}, and it should not end in @samp{-face} (that would be
-redundant).  The argument @var{doc} specifies the face documentation.
-The keywords you can use in @code{defface} are the same as in
address@hidden and @code{defcustom} (@pxref{Common Keywords}).
+redundant).  The argument @var{doc} is a documentation string for the
+face.  The additional @var{keyword} arguments have the same meanings
+as in @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
 
 When @code{defface} executes, it defines the face according to
 @var{spec}, then uses any customizations that were read from the
@@ -1930,12 +1925,14 @@
 overrides any customizations of the face.  This way, the face reflects
 exactly what the @code{defface} says.
 
-The purpose of @var{spec} is to specify how the face should appear on
-different kinds of terminals.  It should be an alist whose elements
-have the form @code{(@var{display} @var{atts})}.  @var{display}
-specifies a class of terminals (see below), while @var{atts} is a
-property list of face attributes and their values, specifying the
-appearance of the face on matching terminals
address@hidden face specification
+The @var{spec} argument is a @dfn{face specification}, which states
+how the face should appear on different kinds of terminals.  It should
+be an alist whose elements each have the form @code{(@var{display}
address@hidden)}.  @var{display} specifies a class of terminals (see
+below), while @var{atts} is a property list of face attributes and
+their values, specifying the appearance of the face on matching
+terminals
 @iftex
 (see the next section for details about face attributes).
 @end iftex
@@ -2022,14 +2019,22 @@
   :group 'basic-faces)
 @end example
 
-  Internally, @code{defface} uses the symbol property
address@hidden to record the specified face attributes.  The
-attributes saved by the user with the customization buffer are
-recorded in the symbol property @code{saved-face}; the attributes
-customized by the user for the current session, but not saved, are
-recorded in the symbol property @code{customized-face}.  The
-documentation string is recorded in the symbol property
address@hidden
+  Internally, Emacs stores the face's default specification in its
address@hidden symbol property (@pxref{Property Lists}).
+The @code{saved-face} property stores the face specification saved by
+the user, using the customization buffer; the @code{customized-face}
+property stores the face specification customized for the current
+session, but not saved; and the @code{theme-face} property stores an
+alist associating the active customization settings and Custom themes
+with their specifications for that face.  The face's documentation
+string is stored in the @code{face-documentation} property.  But
+normally you should not try to set any of these properties directly.
address@hidden Customizations}, for the @code{custom-set-faces}
+function, which is used to apply customized face settings.
+
+  People are sometimes tempted to create variables whose values
+specify a face to use.  In the vast majority of cases, this is not
+necessary; it is preferable to simply use faces directly.
 
 @defopt frame-background-mode
 This option, if address@hidden, specifies the background type to use for

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2012-04-05 18:32:38 +0000
+++ b/doc/lispref/elisp.texi    2012-04-12 14:50:58 +0000
@@ -123,7 +123,7 @@
 * Functions::               A function is a Lisp program
                               that can be invoked from other functions.
 * Macros::                  Macros are a way to extend the Lisp language.
-* Customization::           Writing customization declarations.
+* Customization::           Making variables and faces customizable.
 
 * Loading::                 Reading files of Lisp code into Lisp.
 * Byte Compilation::        Compilation makes programs run faster.
@@ -500,6 +500,8 @@
 * Group Definitions::       Writing customization group definitions.
 * Variable Definitions::    Declaring user options.
 * Customization Types::     Specifying the type of a user option.
+* Applying Customizations:: Functions to apply customization settings.
+* Custom Themes::           Writing Custom themes.
 
 Customization Types
 
@@ -1295,7 +1297,7 @@
 
 Faces
 
-* Defining Faces::          How to define a face with @code{defface}.
+* Defining Faces::          How to define a face.
 * Face Attributes::         What is in a face?
 * Attribute Functions::     Functions to examine and set face attributes.
 * Displaying Faces::        How Emacs combines the faces specified for

=== modified file 'doc/lispref/modes.texi'
--- a/doc/lispref/modes.texi    2012-04-10 07:11:23 +0000
+++ b/doc/lispref/modes.texi    2012-04-12 14:50:58 +0000
@@ -1571,8 +1571,8 @@
 
 One of the effects of making a minor mode global is that the
 @var{mode} variable becomes a customization variable.  Toggling it
-through the Custom interface turns the mode on and off, and its value
-can be saved for future Emacs sessions (@pxref{Saving
+through the Customize interface turns the mode on and off, and its
+value can be saved for future Emacs sessions (@pxref{Saving
 Customizations,,, emacs, The GNU Emacs Manual}.  For the saved
 variable to work, you should ensure that the @code{define-minor-mode}
 form is evaluated each time Emacs starts; for packages that are not
@@ -1691,7 +1691,7 @@
 in Fundamental mode.
 
 This defines the customization option @var{global-mode} 
(@pxref{Customization}),
-which can be toggled in the Custom interface to turn the minor mode on
+which can be toggled in the Customize interface to turn the minor mode on
 and off.  As with @code{define-minor-mode}, you should ensure that the
 @code{define-globalized-minor-mode} form is evaluated each time Emacs
 starts, for example by providing a @code{:require} keyword.

=== modified file 'doc/lispref/os.texi'
--- a/doc/lispref/os.texi       2012-04-10 07:11:23 +0000
+++ b/doc/lispref/os.texi       2012-04-12 14:50:58 +0000
@@ -290,9 +290,9 @@
 
 Emacs explicitly checks for an expression as shown above in your init
 file; your login name must appear in the expression as a Lisp string
-constant.  You can also use the Custom interface.  Other methods of setting
address@hidden to the same value do not
-inhibit the startup message.  This way, you can easily inhibit the
+constant.  You can also use the Customize interface.  Other methods of
+setting @code{inhibit-startup-echo-area-message} to the same value do
+not inhibit the startup message.  This way, you can easily inhibit the
 message for yourself if you wish, but thoughtless copying of your init
 file will not inhibit the message for someone else.
 @end defopt

=== modified file 'doc/lispref/vol1.texi'
--- a/doc/lispref/vol1.texi     2012-04-05 18:32:38 +0000
+++ b/doc/lispref/vol1.texi     2012-04-12 14:50:58 +0000
@@ -141,7 +141,7 @@
 * Functions::               A function is a Lisp program
                               that can be invoked from other functions.
 * Macros::                  Macros are a way to extend the Lisp language.
-* Customization::           Writing customization declarations.
+* Customization::           Making variables and faces customizable.
 
 * Loading::                 Reading files of Lisp code into Lisp.
 * Byte Compilation::        Compilation makes programs run faster.
@@ -520,6 +520,8 @@
 * Group Definitions::       Writing customization group definitions.
 * Variable Definitions::    Declaring user options.
 * Customization Types::     Specifying the type of a user option.
+* Applying Customizations:: Functions to apply customization settings.
+* Custom Themes::           Writing Custom themes.
 
 Customization Types
 
@@ -1317,7 +1319,7 @@
 
 Faces
 
-* Defining Faces::          How to define a face with @code{defface}.
+* Defining Faces::          How to define a face.
 * Face Attributes::         What is in a face?
 * Attribute Functions::     Functions to examine and set face attributes.
 * Displaying Faces::        How Emacs combines the faces specified for

=== modified file 'doc/lispref/vol2.texi'
--- a/doc/lispref/vol2.texi     2012-04-05 18:32:38 +0000
+++ b/doc/lispref/vol2.texi     2012-04-12 14:50:58 +0000
@@ -140,7 +140,7 @@
 * Functions::               A function is a Lisp program
                               that can be invoked from other functions.
 * Macros::                  Macros are a way to extend the Lisp language.
-* Customization::           Writing customization declarations.
+* Customization::           Making variables and faces customizable.
 
 * Loading::                 Reading files of Lisp code into Lisp.
 * Byte Compilation::        Compilation makes programs run faster.
@@ -519,6 +519,8 @@
 * Group Definitions::       Writing customization group definitions.
 * Variable Definitions::    Declaring user options.
 * Customization Types::     Specifying the type of a user option.
+* Applying Customizations:: Functions to apply customization settings.
+* Custom Themes::           Writing Custom themes.
 
 Customization Types
 
@@ -1316,7 +1318,7 @@
 
 Faces
 
-* Defining Faces::          How to define a face with @code{defface}.
+* Defining Faces::          How to define a face.
 * Face Attributes::         What is in a face?
 * Attribute Functions::     Functions to examine and set face attributes.
 * Displaying Faces::        How Emacs combines the faces specified for

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-04-12 01:09:15 +0000
+++ b/lisp/ChangeLog    2012-04-12 14:50:58 +0000
@@ -1,3 +1,7 @@
+2012-04-12  Chong Yidong  <address@hidden>
+
+       * custom.el (custom-theme-set-variables): Doc fix.
+
 2012-04-12  Glenn Morris  <address@hidden>
 
        * international/mule.el (set-auto-coding-for-load): Doc fix.

=== modified file 'lisp/custom.el'
--- a/lisp/custom.el    2012-03-25 14:05:51 +0000
+++ b/lisp/custom.el    2012-04-12 14:50:58 +0000
@@ -934,16 +934,21 @@
 
   (SYMBOL EXP [NOW [REQUEST [COMMENT]]])
 
-This stores EXP (without evaluating it) as the saved value for SYMBOL.
-If NOW is present and non-nil, then also evaluate EXP and set
-the default value for the SYMBOL to the value of EXP.
-
-REQUEST is a list of features we must require in order to
-handle SYMBOL properly.
-COMMENT is a comment string about SYMBOL.
-
-EXP itself is saved unevaluated as SYMBOL property `saved-value' and
-in SYMBOL's list property `theme-value' \(using `custom-push-theme')."
+SYMBOL is the variable name, and EXP is an expression which
+evaluates to the customized value.  EXP will also be stored,
+without evaluating it, in SYMBOL's `saved-value' property, so
+that it can be restored via the Customize interface.  It is also
+added to the alist in SYMBOL's `theme-value' property \(by
+calling `custom-push-theme').
+
+NOW, if present and non-nil, means to install the variable's
+value directly now, even if its `defcustom' declaration has not
+been executed.  This is for internal use only.
+
+REQUEST is a list of features to `require' (which are loaded
+prior to evaluating EXP).
+
+COMMENT is a comment string about SYMBOL."
   (custom-check-theme theme)
 
   ;; Process all the needed autoloads before anything else, so that the