@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1997-2011 Free Software Foundation, Inc.
+@c Copyright (C) 1997-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/customize
@node Customization, Loading, Macros, Top
@section Common Item Keywords
@cindex customization keywords
- All kinds of customization declarations (for variables and groups, and
-for faces) accept keyword arguments for specifying various information.
-This section describes some keywords that apply to all kinds.
+ The customization declarations that we will describe in the next few
+sections (@code{defcustom}, @code{defgroup}, etc.) all accept keyword
+arguments for specifying various information. This section describes
+keywords that apply to all types of customization declarations.
All of these keywords, except @code{:tag}, can be used more than once
in a given item. Each use of the keyword has an independent effect.
for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
the Emacs manual which appears in the buffer as @samp{foo}.
-An item can have more than one external link; however, most items have
-none at all.
+You can use this keyword more than once, to add multiple links.
@item :load @var{file}
@kindex load@r{, customization keyword}
@kindex package-version@r{, customization keyword}
This keyword specifies that the item was first introduced in
@var{package} version @var{version}, or that its meaning or default
-value was changed in that version. The value of @var{package} is a
-symbol and @var{version} is a string.
+value was changed in that version. This keyword takes priority over
+@code{:version}.
-This keyword takes priority over @code{:version}.
-
-@var{package} should be the official name of the package, such as MH-E
-or Gnus. If the package @var{package} is released as part of Emacs,
-@var{package} and @var{version} should appear in the value of
+@var{package} should be the official name of the package, as a symbol
+(e.g.@: @code{MH-E}). @var{version} should be a string. If the
+package @var{package} is released as part of Emacs, @var{package} and
+@var{version} should appear in the value of
@code{customize-package-emacs-version-alist}.
@end table
@table @code
@item :prefix @var{prefix}
@kindex prefix@r{, @code{defgroup} keyword}
-If the name of an item in the group starts with @var{prefix}, then the
-tag for that item is constructed (by default) by omitting @var{prefix}.
-
-One group can have any number of prefixes.
+If the name of an item in the group starts with @var{prefix}, and the
+customizable variable @code{custom-unlispify-remove-prefixes} is
+non-@code{nil}, the item's tag will omit @var{prefix}. A group can
+have any number of prefixes.
@end table
@end defmac
- The prefix-discarding feature is currently turned off, which means
-that @code{:prefix} currently has no effect. We did this because we
-found that discarding the specified prefixes often led to confusing
-names for options. This happened because the people who wrote the
-@code{defgroup} definitions for various groups added @code{:prefix}
-keywords whenever they make logical sense---that is, whenever the
-variables in the library have a common prefix.
-
- In order to obtain good results with @code{:prefix}, it would be
-necessary to check the specific effects of discarding a particular
-prefix, given the specific items in a group and their names and
-documentation. If the resulting text is not clear, then @code{:prefix}
-should not be used in that case.
+@defopt custom-unlispify-remove-prefixes
+If this variable is non-@code{nil}, the prefixes specified by a
+group's @code{:prefix} keyword are omitted from tag names, whenever
+the user customizes the group.
- It should be possible to recheck all the customization groups, delete
-the @code{:prefix} specifications which give unclear results, and then
-turn this feature back on, if someone would like to do the work.
+The default value is @code{nil}, i.e.@: the prefix-discarding feature
+is disabled. This is because discarding prefixes often leads to
+confusing names for options and faces.
+@end defopt
@node Variable Definitions
@section Defining Customization Variables
@cindex define customization options
@cindex customization variables, how to define
- Use @code{defcustom} to declare user-customizable variables.
-
@defmac defcustom option standard doc [keyword value]@dots{}
-This macro declares @var{option} as a customizable @dfn{user option}.
-You should not quote @var{option}.
-
-This causes the function @code{user-variable-p} to return @code{t}
-when given @var{option} as an argument. @xref{Defining Variables}.
-The argument @var{doc} specifies the documentation string for the
-variable. (Note that there is no need to start @var{doc} with a
-@samp{*}.)
+This macro declares @var{option} as a user option (i.e.@: a
+customizable variable). You should not quote @var{option}.
The argument @var{standard} is an expression that specifies the
standard value for @var{option}. Evaluating the @code{defcustom} form
The expression @var{standard} can be evaluated at various other times,
too---whenever the customization facility needs to know @var{option}'s
standard value. So be sure to use an expression which is harmless to
-evaluate at any time. We recommend avoiding backquotes in
-@var{standard}, because they are not expanded when editing the value,
-so list values will appear to have the wrong structure.
+evaluate at any time.
-Every @code{defcustom} should specify @code{:group} at least once.
+The argument @var{doc} specifies the documentation string for the
+variable.
-If you specify the @code{:set} keyword, to make the variable take other
-special actions when set through the customization buffer, the
-variable's documentation string should tell the user specifically how
-to do the same job in hand-written Lisp code.
+Every @code{defcustom} should specify @code{:group} at least once.
When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
mode (@code{eval-defun}), a special feature of @code{eval-defun}
its value is void. (The same feature applies to @code{defvar}.)
@xref{Defining Variables}.
-If you put a @code{defcustom} in a file that is preloaded at dump time
-(@pxref{Building Emacs}), and the standard value installed for the
-variable at that time might not be correct, use
+If you put a @code{defcustom} in a pre-loaded Emacs Lisp file
+(@pxref{Building Emacs}), the standard value installed at dump time
+might be incorrect, e.g.@: because another variable that it depends on
+has not been assigned the right value yet. In that case, use
@code{custom-reevaluate-setting}, described below, to re-evaluate the
-standard value during or after Emacs startup.
+standard value after Emacs starts up.
@end defmac
@code{defcustom} accepts the following additional keywords:
the option as a Lisp variable). The default for @var{setfunction} is
@code{set-default}.
+If you specify this keyword, the variable's documentation string
+should describe how to do the same job in hand-written Lisp code.
+
@item :get @var{getfunction}
@kindex get@r{, @code{defcustom} keyword}
Specify @var{getfunction} as the way to extract the value of this
You have to really understand the workings of Custom to use
@code{:get} correctly. It is meant for values that are treated in
Custom as variables but are not actually stored in Lisp variables. It
-is almost surely a mistake to specify @code{getfunction} for a value
+is almost surely a mistake to specify @var{getfunction} for a value
that really is stored in a Lisp variable.
@item :initialize @var{function}
These functions behave like @code{custom-initialize-set}
(@code{custom-initialize-default}, respectively), but catch errors.
If an error occurs during initialization, they set the variable to
-@code{nil} using @code{set-default}, and throw no error.
-
-These two functions are only meant for options defined in pre-loaded
-files, where some variables or functions used to compute the option's
-value may not yet be defined. The option normally gets updated in
-@file{startup.el}, ignoring the previously computed value. Because of
-this typical usage, the value which these two functions compute
-normally only matters when, after startup, one unsets the option's
-value and then reevaluates the defcustom. By that time, the necessary
-variables and functions will be defined, so there will not be an error.
+@code{nil} using @code{set-default}, and signal no error.
+
+These functions are meant for options defined in pre-loaded files,
+where the @var{standard} expression may signal an error because some
+required variable or function is not yet defined. The value normally
+gets updated in @file{startup.el}, ignoring the value computed by
+@code{defcustom}. After startup, if one unsets the value and
+reevaluates the @code{defcustom}, the @var{standard} expression can be
+evaluated without error.
@end table
@item :risky @var{value}
@defun custom-reevaluate-setting symbol
This function re-evaluates the standard value of @var{symbol}, which
-should be a user option declared via @code{defcustom}. (If the
+should be a user option declared via @code{defcustom}. If the
variable was customized, this function re-evaluates the saved value
-instead.) This is useful for customizable options that are defined
-before their value could be computed correctly, such as variables
-defined in packages that are loaded at dump time, but depend on the
-run-time information. For example, the value could be a file whose
-precise name depends on the hierarchy of files when Emacs runs, or a
-name of a program that needs to be searched at run time.
-
-A good place to put calls to this function is in the function
-@code{command-line} that is run during startup (@pxref{Startup Summary})
-or in the various hooks it calls.
+instead. Then it sets the user option to that value (using the
+option's @code{:set} property if that is defined).
+
+This is useful for customizable options that are defined before their
+value could be computed correctly. For example, during startup Emacs
+calls this function for some user options that were defined in
+pre-loaded Emacs Lisp files, but whose initial values depend on
+information available only at run-time.
+@end defun
+
+@defun custom-variable-p arg
+This function returns non-@code{nil} if @var{arg} is a customizable
+variable. A customizable variable is either a variable that has a
+@code{standard-value} or @code{custom-autoload} property (usually
+meaning it was declared with @code{defcustom}), or an alias for
+another customizable variable.
+@end defun
+
+@defun user-variable-p arg
+This function is like @code{custom-variable-p}, except it also returns
+@code{t} if the first character of the variable's documentation string
+is the character @samp{*}. That is an obsolete way of indicating a
+user option, so for most purposes you may consider
+@code{user-variable-p} as equivalent to @code{custom-variable-p}.
@end defun
@node Customization Types
@node Simple Types
@subsection Simple Types
- This section describes all the simple customization types.
+ This section describes all the simple customization types. For
+several of these customization types, the customization widget
+provides inline completion with @kbd{C-M-i} or @kbd{M-@key{TAB}}.
@table @code
@item sexp
-The value may be any Lisp object that can be printed and read back. You
-can use @code{sexp} as a fall-back for any option, if you don't want to
-take the time to work out a more specific type to use.
+The value may be any Lisp object that can be printed and read back.
+You can use @code{sexp} as a fall-back for any option, if you don't
+want to take the time to work out a more specific type to use.
@item integer
-The value must be an integer, and is represented textually
-in the customization buffer.
+The value must be an integer.
@item number
-The value must be a number (floating point or integer), and is
-represented textually in the customization buffer.
+The value must be a number (floating point or integer).
@item float
-The value must be a floating point number, and is represented
-textually in the customization buffer.
+The value must be a floating point number.
@item string
-The value must be a string, and the customization buffer shows just the
-contents, with no delimiting @samp{"} characters and no quoting with
-@samp{\}.
+The value must be a string. The customization buffer shows the string
+without delimiting @samp{"} characters or @samp{\} quotes.
@item regexp
Like @code{string} except that the string must be a valid regular
buffer, rather than by showing the number.
@item file
-The value must be a file name, and you can do completion with
-@kbd{M-@key{TAB}}.
+The value must be a file name. The widget provides completion.
@item (file :must-match t)
-The value must be a file name for an existing file, and you can do
-completion with @kbd{M-@key{TAB}}.
+The value must be a file name for an existing file. The widget
+provides completion.
@item directory
-The value must be a directory name, and you can do completion with
-@kbd{M-@key{TAB}}.
+The value must be a directory name. The widget provides completion.
@item hook
-The value must be a list of functions (or a single function, but that is
-obsolete usage). This customization type is used for hook variables.
-You can use the @code{:options} keyword in a hook variable's
-@code{defcustom} to specify a list of functions recommended for use in
-the hook; see @ref{Variable Definitions}.
+The value must be a list of functions. This customization type is
+used for hook variables. You can use the @code{:options} keyword in a
+hook variable's @code{defcustom} to specify a list of functions
+recommended for use in the hook; @xref{Variable Definitions}.
@item symbol
The value must be a symbol. It appears in the customization buffer as
-the name of the symbol.
+the symbol name. The widget provides completion.
@item function
-The value must be either a lambda expression or a function name. When
-it is a function name, you can do completion with @kbd{M-@key{TAB}}.
+The value must be either a lambda expression or a function name. The
+widget provides completion for function names.
@item variable
-The value must be a variable name, and you can do completion with
-@kbd{M-@key{TAB}}.
+The value must be a variable name. The widget provides completion.
@item face
-The value must be a symbol which is a face name, and you can do
-completion with @kbd{M-@key{TAB}}.
+The value must be a symbol which is a face name. The widget provides
+completion.
@item boolean
The value is boolean---either @code{nil} or @code{t}. Note that by
@kbd{M-@key{TAB}}.
@item color
-The value must be a valid color name, and you can do completion with
-@kbd{M-@key{TAB}}. A sample is provided.
+The value must be a valid color name. The widget provides completion
+for color names, as well as a sample and a button for selecting a
+color name from a list of color names shown in a @samp{*Colors*}
+buffer.
@end table
@node Composite Types
symbol)} is a customization type which matches values such as
@code{("foo" . foo)}.
-In the customization buffer, the @sc{car} and the @sc{cdr} are
-displayed and edited separately, each according to the type
-that you specify for it.
+In the customization buffer, the @sc{car} and @sc{cdr} are displayed
+and edited separately, each according to their specified type.
@item (list @var{element-types}@dots{})
The value must be a list with exactly as many elements as the
The argument to the @code{:options} keywords should be a list of
specifications for reasonable keys in the alist. Ordinarily, they are
-simply atoms, which stand for themselves as. For example:
+simply atoms, which stand for themselves. For example:
@smallexample
:options '("foo" "bar" "baz")
"Alist of basic info about people.
Each element has the form (NAME AGE MALE-FLAG)."
:type '(alist :value-type (group integer boolean)))
-
-(defcustom pets '(("brian")
- ("dorith" "dog" "guppy")
- ("ken" "cat"))
- "Alist of people's pets.
-In an element (KEY . VALUE), KEY is the person's name,
-and the VALUE is a list of that person's pets."
- :type '(alist :value-type (repeat string)))
@end smallexample
@item (plist :key-type @var{key-type} :value-type @var{value-type})
defaults to @code{symbol} rather than @code{sexp}.
@item (choice @var{alternative-types}@dots{})
-The value must fit at least one of @var{alternative-types}.
-For example, @code{(choice integer string)} allows either an
-integer or a string.
+The value must fit one of @var{alternative-types}. For example,
+@code{(choice integer string)} allows either an integer or a string.
In the customization buffer, the user selects an alternative
using a menu, and can then edit the value in the usual way for that
@subsection Splicing into Lists
The @code{:inline} feature lets you splice a variable number of
-elements into the middle of a list or vector. You use it in a
-@code{set}, @code{choice} or @code{repeat} type which appears among the
-element-types of a @code{list} or @code{vector}.
-
- Normally, each of the element-types in a @code{list} or @code{vector}
-describes one and only one element of the list or vector. Thus, if an
-element-type is a @code{repeat}, that specifies a list of unspecified
-length which appears as one element.
-
- But when the element-type uses @code{:inline}, the value it matches is
-merged directly into the containing sequence. For example, if it
-matches a list with three elements, those become three elements of the
-overall sequence. This is analogous to using @samp{,@@} in the backquote
-construct.
+elements into the middle of a @code{list} or @code{vector}
+customization type. You use it by adding @code{:inline t} to a type
+specification which is contained in a @code{list} or @code{vector}
+specification.
+
+ Normally, each entry in a @code{list} or @code{vector} type
+specification describes a single element type. But when an entry
+contains @code{:inline t}, the value it matches is merged directly
+into the containing sequence. For example, if the entry matches a
+list with three elements, those become three elements of the overall
+sequence. This is analogous to @samp{,@@} in a backquote construct
+(@pxref{Backquote}).
For example, to specify a list whose first element must be @code{baz}
and whose remaining arguments should be zero or more of @code{foo} and
HCoop / bpt / emacs.git / blobdiff