+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.
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
+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.
@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
@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
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.)
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.
@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
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
: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
* 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.
* 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
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
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
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.
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
* 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.
* 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
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
* 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.
* 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
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
+2012-04-12 Chong Yidong <cyd@gnu.org>
+
+ * custom.el (custom-theme-set-variables): Doc fix.
+
2012-04-12 Glenn Morris <rgm@gnu.org>
* international/mule.el (set-auto-coding-for-load): Doc fix.
(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.
+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').
-REQUEST is a list of features we must require in order to
-handle SYMBOL properly.
-COMMENT is a comment string about SYMBOL.
+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).
-EXP itself is saved unevaluated as SYMBOL property `saved-value' and
-in SYMBOL's list property `theme-value' \(using `custom-push-theme')."
+COMMENT is a comment string about SYMBOL."
(custom-check-theme theme)
;; Process all the needed autoloads before anything else, so that the
projects / emacs.git / commitdiff