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.

10 files changed, 213 insertions, 54 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 8f384720170..5b4ab363202 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,8 @@
+2012-04-12  Chong Yidong  <cyd@gnu.org>
+
+	* custom.texi (Creating Custom Themes): Add reference to Custom
+	Themes node in Lisp manual.
+
 2012-04-12  Glenn Morris  <rgm@gnu.org>
 
 	* mule.texi (International): Copyedits.
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 6bc96bda9ca..72b4961e209 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -684,9 +684,8 @@ the @samp{[Merge Theme]} button and specifying the special theme named
   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.
-@c Add link to the relevant Emacs Lisp Reference manual node, once
-@c that is written.
+buffer.  @xref{Custom Themes,,, elisp, The Emacs Lisp Reference
+Manual}, for details.
 
 @node Variables
 @section Variables
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 3990db3d602..21050287fcc 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,13 @@
+2012-04-12  Chong Yidong  <cyd@gnu.org>
+
+	* 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  <rgm@gnu.org>
 
 	* loading.texi (Loading Non-ASCII): "unibyte:" can also be at the end.
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 167dfe7d4c5..7e6b9ad40ac 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -4,20 +4,25 @@
 @c See the file elisp.texi for copying conditions.
 @setfilename ../../info/customize
 @node Customization, Loading, Macros, Top
-@chapter Writing Customization Definitions
+@chapter Customization Settings
 
-@cindex customization definitions
-  This chapter describes how to declare user options for customization,
-and also customization groups for classifying them.  We use the term
-@dfn{customization item} to include both kinds of customization
-definitions---as well as face definitions (@pxref{Defining Faces}).
+@cindex customization item
+  This chapter describes how to declare customizable variables and
+customization groups for classifying them.  We use the term
+@dfn{customization 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 @@ individual types for a description of how to use @code{:options}.
 @item :set @var{setfunction}
 @kindex set@r{, @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 inferior widgets will convert @emph{their} inferior widgets.  If
 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.
+
+@node Applying Customizations
+@section 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.
+
+@defun custom-set-variables &rest args
+This function installs the variable customizations specified by
+@var{args}.  Each argument in @var{args} should have the form
+
+@example
+(@var{var} @var{expression} [@var{now} [@var{request} [@var{comment}]]])
+@end example
+
+@noindent
+@var{var} 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,
+@var{expression} 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 non-@code{nil},
+means to set the variable's value now, even if the variable's
+@code{defcustom} form has not been evaluated.  @var{request} is a list
+of features to be loaded immediately (@pxref{Named Features}).
+@var{comment} is a string describing the customization.
+@end defun
+
+@defun custom-set-faces &rest args
+This function installs the face customizations specified by
+@var{args}.  Each argument in @var{args} should have the form
+
+@example
+(@var{face} @var{spec} [@var{now} [@var{comment}]])
+@end example
+
+@noindent
+@var{face} 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 non-@code{nil}, 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.
+@end defun
+
+@node Custom Themes
+@section 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 @file{@var{foo}-theme.el}, where
+@var{foo} 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
+@code{provide-theme}.
+
+@defmac 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
+@kbd{?} (@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
+@code{changed} is a ``dummy theme'' used to store changes made outside
+of the Customize system.  If you specify either of these as the
+@var{theme} argument, @code{deftheme} signals an error.
+@end defmac
+
+@defmac provide-theme theme
+This macro declares that the theme named @var{theme} has been fully
+specified.
+@end defmac
+
+  In between @code{deftheme} and @code{provide-theme} are the Lisp
+forms specifying the theme settings---usually a call to
+@code{custom-theme-set-variables} and/or a call to
+@code{custom-theme-set-faces}:
+
+@defun 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
+
+@example
+(@var{var} @var{expression} [@var{now} [@var{request} [@var{comment}]]])
+@end example
+
+@noindent
+where the list entries have the same meanings as in
+@code{custom-set-variables}.  @xref{Applying Customizations}.
+@end defun
+
+@defun 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
+
+@example
+(@var{face} @var{spec} [@var{now} [@var{comment}]])
+@end example
+
+@noindent
+where the list entries have the same meanings as in
+@code{custom-set-faces}.  @xref{Applying Customizations}.
+@end 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.)
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index ee3ffd8d10c..cc48133113f 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -1885,7 +1885,7 @@ in all frames.  But you can also assign a face name a special set of
 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 @@ attributes in one frame (@pxref{Attribute Functions}).
 @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 value]@dots{}
-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
-@code{defgroup} 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 @@ Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun}
 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
+@cindex 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}
+@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
 @iftex
 (see the next section for details about face attributes).
 @end iftex
@@ -2022,14 +2019,22 @@ frame must match one of the @var{value}s specified for it in
   :group 'basic-faces)
 @end example
 
-  Internally, @code{defface} uses the symbol property
-@code{face-defface-spec} 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
-@code{face-documentation}.
+  Internally, Emacs stores the face's default specification in its
+@code{face-defface-spec} 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.
+@xref{Applying 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 non-@code{nil}, specifies the background type to use for
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index dc835347235..76397556b01 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -123,7 +123,7 @@ Cover art by Etienne Suvasa.
 * 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 @@ Writing Customization Definitions
 * 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 @@ Overlays
 
 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
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 12abc2fcd2b..83fbd02b16c 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1571,8 +1571,8 @@ rather than buffer-local.  It defaults to @code{nil}.
 
 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 @@ Fundamental mode; but it does not detect the creation of a new buffer
 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.
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 7c49c9e04a0..35ac7c20384 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -290,9 +290,9 @@ form to your init file:
 
 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
-@code{inhibit-startup-echo-area-message} 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
diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi
index df269868e09..45a0dee3b1c 100644
--- a/doc/lispref/vol1.texi
+++ b/doc/lispref/vol1.texi
@@ -141,7 +141,7 @@ Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}.
 * 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 @@ Writing Customization Definitions
 * 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 @@ Overlays
 
 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
diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi
index 2a2578158bf..01a3e3c129e 100644
--- a/doc/lispref/vol2.texi
+++ b/doc/lispref/vol2.texi
@@ -140,7 +140,7 @@ Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}.
 * 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 @@ Writing Customization Definitions
 * 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 @@ Overlays
 
 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