procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

New Lisp manual nodes, Applying Customizations and Custom Themes.

Browse source 
* 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.
This commit is contained in:
Chong Yidong 2012-04-12 22:50:58 +08:00
parent 893585f47b
commit 81927dd2a4
12 changed files with 230 additions and 62 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
doc/emacs/ChangeLog
View file

@ -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.

5
doc/emacs/custom.texi
View file

@ -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

10
doc/lispref/ChangeLog
View file

@ -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.

158
doc/lispref/customize.texi
View file

@ -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.)

59
doc/lispref/display.texi
View file

@ -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

6
doc/lispref/elisp.texi
View file

@ -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

6
doc/lispref/modes.texi
View file

@ -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.

6
doc/lispref/os.texi
View file

@ -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

6
doc/lispref/vol1.texi
View file

@ -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

6
doc/lispref/vol2.texi
View file

@ -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

4
lisp/ChangeLog
View file

@ -1,3 +1,7 @@
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.

21
lisp/custom.el
View file

@ -934,16 +934,21 @@ Each of the arguments in ARGS should be a list of this form:
(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.
EXP itself is saved unevaluated as SYMBOL property `saved-value' and
in SYMBOL's list property `theme-value' \(using `custom-push-theme')."
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