From e1161b06fc12499f9990fc23a915d75bb8866cd2 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sun, 5 Feb 2012 22:27:06 +0800 Subject: [PATCH] Update Customization chapter of Lisp manual. * 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. --- admin/FOR-RELEASE | 2 +- doc/lispref/ChangeLog | 3 ++ doc/lispref/customize.texi | 108 +++++++++++++++++++-------------------------- 3 files changed, 50 insertions(+), 63 deletions(-) diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE index 74a758826a1..379363252b2 100644 --- a/admin/FOR-RELEASE +++ b/admin/FOR-RELEASE @@ -188,7 +188,7 @@ buffers.texi commands.texi compile.texi control.texi cyd -customize.texi +customize.texi cyd debugging.texi display.texi edebug.texi diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index bd7b27bbe60..85dc017d7f5 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -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. diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index b8c30fff8ae..4c3adee0db5 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -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}. - - 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 -- 2.11.4.GIT