mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2025-01-04 11:40:22 +00:00
Code Issues Releases Activity

Update Customization chapter of Lisp manual.

Browse Source 
* doc/lispref/customize.texi (Common Keywords): Minor clarifications.
Document custom-unlispify-remove-prefixes.
(Variable Definitions): Backquotes in defcustom seem to work fine
now.  Various other copyedits.
(Simple Types): Copyedits.  Document color selector.
(Composite Types): Copyedits.
(Splicing into Lists): Clarifications.
This commit is contained in:
Chong Yidong 2012-02-05 22:27:06 +08:00
parent eeb6cc88a9
commit e1161b06fc
3 changed files with 49 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
admin/FOR-RELEASE
View File

@ -188,7 +188,7 @@ buffers.texi
commands.texi
compile.texi
control.texi cyd
customize.texi
customize.texi cyd
debugging.texi
display.texi
edebug.texi

3
doc/lispref/ChangeLog
View File

@ -4,6 +4,9 @@
Document custom-unlispify-remove-prefixes.
(Variable Definitions): Backquotes in defcustom seem to work fine
now. Various other copyedits.
(Simple Types): Copyedits. Document color selector.
(Composite Types): Copyedits.
(Splicing into Lists): Clarifications.
* eval.texi (Backquote): Move from macros.texi.

106
doc/lispref/customize.texi
View File

@ -519,30 +519,28 @@ Introduction, widget, The Emacs Widget Library}, for details.
@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
@ -554,39 +552,35 @@ integer, but this type shows the value by inserting the character in the
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
@ -600,8 +594,10 @@ The value must be a coding-system name, and you can do completion with
@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
@ -635,9 +631,8 @@ its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string
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
@ -680,7 +675,7 @@ specified by the @code{:options} keyword argument.
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")
@ -753,14 +748,6 @@ key, using variations of this trick:
"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})
@ -770,9 +757,8 @@ that (i) the information is stored as a property list,
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
@ -964,20 +950,18 @@ whatever follows the last keyword-value pair.
@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}.
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 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.
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