X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/a9f0a989a17f47f9d25b7a426b4e82a8ff684ee4..7cb668991105849ed4561b102d8550ff7f519583:/lispref/customize.texi

diff --git a/lispref/customize.texi b/lispref/customize.texi
index dffd3de49a..2ce5f5ed4a 100644
--- a/lispref/customize.texi
+++ b/lispref/customize.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1997, 1998 Free Software Foundation, Inc. 
+@c Copyright (C) 1997, 1998, 1999, 2000 Free Software Foundation, Inc. 
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/customize
 @node Customization, Loading, Macros, Top
@@ -19,7 +19,7 @@ definitions---as well as face definitions (@pxref{Defining Faces}).
 @end menu
 
 @node Common Keywords
-@section Common Keywords for All Kinds of Items
+@section Common Item Keywords
 
   All kinds of customization declarations (for variables and groups, and
 for faces) accept keyword arguments for specifying various information.
@@ -31,8 +31,8 @@ The keyword @code{:tag} is an exception because any given item can only
 display one name.
 
 @table @code
-@item :tag @var{name}
-Use @var{name}, a string, instead of the item's name, to label the item
+@item :tag @var{label}
+Use @var{label}, a string, instead of the item's name, to label the item
 in customization menus and buffers.
 
 @item :group @var{group}
@@ -42,7 +42,7 @@ Put this customization item in group @var{group}.  When you use
 
 If you use this keyword more than once, you can put a single item into
 more than one group.  Displaying any of those groups will show this
-item.  Be careful not to overdo this!
+item.  Please don't overdo this, since the result would be annoying.
 
 @item :link @var{link-data}
 Include an external link after the documentation string for this item.
@@ -64,6 +64,10 @@ in the customization buffer with the Info node name.
 @item (url-link @var{url})
 Link to a web page; @var{url} is a string which specifies the @sc{url}.
 The link appears in the customization buffer as @var{url}.
+
+@item (emacs-commentary-link @var{library})
+Link to the commentary section of a library; @var{library} is a string
+which specifies the library name.
 @end table
 
 You can specify the text to use in the customization buffer by adding
@@ -110,10 +114,10 @@ keyword.
   The way to declare new customization groups is with @code{defgroup}.
 
 @defmac defgroup group members doc [keyword value]...
-@tindex defgroup
 Declare @var{group} as a customization group containing @var{members}.
 Do not quote the symbol @var{group}.  The argument @var{doc} specifies
-the documentation string for the group.
+the documentation string for the group.  It should not start with a
+@samp{*} as in @code{defcustom}; that convention is for variables only.
 
 The argument @var{members} is a list specifying an initial set of
 customization items to be members of the group.  However, most often
@@ -126,8 +130,20 @@ is a symbol, and @var{widget} is a widget type for editing that symbol.
 Useful widgets are @code{custom-variable} for a variable,
 @code{custom-face} for a face, and @code{custom-group} for a group.
 
+When a new group is introduced into Emacs, use this keyword in
+@code{defgroup}:
+
+@table @code
+@item :version @var{version}
+This option specifies that the group was first introduced in Emacs
+version @var{version}.  The value @var{version} must be a string.
+@end table
+
+Tag the group with a version like this when it is introduced, rather
+than the individual members (@pxref{Variable Definitions}).
+
 In addition to the common keywords (@pxref{Common Keywords}), you can
-use this keyword in @code{defgroup}:
+also use this keyword in @code{defgroup}:
 
 @table @code
 @item :prefix @var{prefix}
@@ -162,17 +178,25 @@ turn this feature back on, if someone would like to do the work.
   Use @code{defcustom} to declare user-editable variables.
 
 @defmac defcustom option default doc [keyword value]...
-@tindex defcustom
 Declare @var{option} as a customizable user option variable.  Do not
 quote @var{option}.  The argument @var{doc} specifies the documentation
-string for the variable.
+string for the variable; it should normally start with a @samp{*}.  This
+marks the variable, for other purposes, as one that users may want to
+customize.
 
 If @var{option} is void, @code{defcustom} initializes it to
 @var{default}.  @var{default} should be an expression to compute the
 value; be careful in writing it, because it can be evaluated on more
 than one occasion.
 
-The following additional keywords are accepted:
+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}
+arranges to set the variable unconditionally, without testing whether
+its value is void.  (The same feature applies to @code{defvar}.)
+@xref{Defining Variables}.
+@end defmac
+
+  @code{defcustom} accepts the following additional keywords:
 
 @table @code
 @item :type @var{type}
@@ -182,12 +206,12 @@ values are legitimate, and how to display the value.
 
 @item :options @var{list}
 Specify @var{list} as the list of reasonable values for use in this
-option.
+option.  The user is not restricted to using only these values, but they
+are offered as convenient alternatives.
 
-Currently this is meaningful only when the type is @code{hook}.  In that
-case, the elements of @var{list} should be functions that are useful as
-elements of the hook value.  The user is not restricted to using only
-these functions, but they are offered as convenient alternatives.
+This is meaningful only for certain types, currently including
+@code{hook}, @code{plist} and @code{alist}.  See the definition of the
+individual types for a description of how to use @code{:options}.
 
 @item :version @var{version}
 This option specifies that the variable was first introduced, or its
@@ -247,8 +271,14 @@ Use the @code{:set} function to initialize the variable, if it is
 already set or has been customized; otherwise, just use
 @code{set-default}.
 @end table
+
+@item :set-after @var{variables}
+When setting variables according to saved customizations, make sure to
+set the variables @var{variables} before this one; in other words, delay
+setting this variable until after those others have been handled.  Use
+@code{:set-after} if setting this variable won't work properly unless
+those other variables already have their intended values.
 @end table
-@end defmac
 
   The @code{:require} option is useful for an option that turns on the
 operation of a certain feature.  Assuming that the package is coded to
@@ -258,7 +288,7 @@ Keywords}.  Here is an example, from the library @file{paren.el}:
 
 @example
 (defcustom show-paren-mode nil
-  "Toggle Show Paren mode@enddots{}"
+  "Toggle Show Paren mode..."
   :set (lambda (symbol value)
          (show-paren-mode (or value 0)))
   :initialize 'custom-initialize-default
@@ -267,17 +297,26 @@ Keywords}.  Here is an example, from the library @file{paren.el}:
   :require 'paren)
 @end example
 
-@ignore
-Use @code{custom-add-option} to specify that a specific function is
-useful as an member of a hook.
+If a customization item has a type such as @code{hook} or @code{alist},
+which supports @code{:options}, you can add additional options to the
+item, outside the @code{defcustom} declaration, by calling
+@code{custom-add-option}.  For example, if you define a function
+@code{my-lisp-mode-initialization} intended to be called from
+@code{emacs-lisp-mode-hook}, you might want to add that to the list of
+options for @code{emacs-lisp-mode-hook}, but not by editing its
+definition.   You can do it thus:
+
+@example
+(custom-add-option 'emacs-lisp-mode-hook
+                   'my-lisp-mode-initialization)
+@end example
 
 @defun custom-add-option symbol option
-To the variable @var{symbol} add @var{option}.
+To the customization @var{symbol}, add @var{option}.
 
-If @var{symbol} is a hook variable, @var{option} should be a hook
-member.  For other types variables, the effect is undefined."
+The precise effect of adding @var{option} depends on the customization
+type of @var{symbol}.
 @end defun
-@end ignore
 
 Internally, @code{defcustom} uses the symbol property
 @code{standard-value} to record the expression for the default value,
@@ -372,9 +411,130 @@ The value must be a directory name, and you can do completion with
 @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{:option} in the @code{defcustom} for a hook
-variable to specify functions recommended for use in the hook;
-see @ref{Variable Definitions}.
+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}.
+
+@item alist
+The value must be a list of cons-cells, the @sc{car} of each cell
+representing a key, and the @sc{cdr} of the same cell representing an
+associated value.  The user can add and delete key/value pairs, and
+edit both the key and the value of each pair.
+
+You can specify the key and value types like this:
+
+@smallexample
+(alist :key-type @var{key-type} :value-type @var{value-type})
+@end smallexample
+
+@noindent
+where @var{key-type} and @var{value-type} are customization type
+specifications.  The default key type is @code{sexp}, and the default
+value type is @code{sexp}.
+
+The user can add any key matching the specified key type, but you can
+give some keys a preferential treatment by specifying them with the
+@code{:options} (see @ref{Variable Definitions}).  The specified keys
+will always be shown in the customize buffer (together with a suitable
+value), with a checkbox to include or exclude or disable the key/value
+pair from the alist.  The user will not be able to edit the keys
+specified by the @code{:options} keyword argument.
+
+The argument to the @code{:options} keywords should be a list of option
+specifications.  Ordinarily, the options are simply atoms, which are the
+specified keys.  For example:
+
+@smallexample
+:options '("foo" "bar" "baz")
+@end smallexample
+
+@noindent
+specifies that there are three ``known'' keys, namely @code{"foo"},
+@code{"bar"} and @code{"baz"}, which will always be shown first.
+
+You may want to restrict the value type for specific keys, for example,
+the value associated with the @code{"bar"} key can only be an integer.
+You can specify this by using a list instead of an atom in the option
+specification.  The first element will specify the key, like before,
+while the second element will specify the value type.
+
+@smallexample
+:options '("foo" ("bar" integer) "baz")
+@end smallexample
+
+Finally, you may want to change how the key is presented.  By default,
+the key is simply shown as a @code{const}, since the user cannot change
+the special keys specified with the @code{:options} keyword.  However,
+you may want to use a more specialized type for presenting the key, like
+@code{function-item} if you know it is a symbol with a function binding.
+This is done by using a customization type specification instead of a
+symbol for the key.
+
+@smallexample
+:options '("foo" ((function-item some-function) integer) "baz")
+@end smallexample
+
+Many alists use lists with two elements, instead of cons cells.  For
+example,
+
+@smallexample
+(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
+  "Each element is a list of the form (KEY VALUE).")
+@end smallexample
+
+@noindent
+instead of 
+
+@smallexample
+(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
+  "Each element is a cons-cell (KEY . VALUE).")
+@end smallexample
+
+Because of the way lists are implemented on top of cons cells, you can
+treat @code{list-alist} in the example above as a cons cell alist, where
+the value type is a list with a single element containing the real
+value.
+
+@smallexample
+(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
+  "Each element is a list of the form (KEY VALUE)."
+  :type '(alist :value-type (group integer)))
+@end smallexample
+
+The @code{group} widget is used here instead of @code{list} only because
+the formatting is better suited for the purpose.
+
+Similarily, you can have alists with more values associated with each
+key, using variations of this trick:
+
+@smallexample
+(defcustom person-data '(("brian"  50 t) 
+                         ("dorith" 55 nil)
+                         ("ken"    52 t))
+  "Alist of basic info about people.
+Each element has the form (NAME AGE MALE-FLAG)."
+  :type '(alist :value-type (group age 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
+The @code{plist} custom type is similar to the @code{alist} (see above),
+except that the information is stored as a property list, i.e. a list of
+this form:
+
+@smallexample
+(@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{})
+@end smallexample
+
+The default @code{:key-type} for @code{plist} is @code{symbol},
+rather than @code{sexp}.
 
 @item symbol
 The value must be a symbol.  It appears in the customization buffer as
@@ -398,6 +558,14 @@ using @code{choice} and @code{const} together (see the next section),
 you can specify that the value must be @code{nil} or @code{t}, but also
 specify the text to describe each value in a way that fits the specific
 meaning of the alternative.
+
+@item coding-system
+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,
 @end table
 
 @node Composite Types
@@ -507,6 +675,30 @@ For example,
         (const :tag "Ask" foo))
 @end example
 
+@noindent
+describes a variable for which @code{t} means yes, @code{nil} means no,
+and @code{foo} means ``ask.''
+
+@item (other @var{value})
+This alternative can match any Lisp value, but if the user chooses this
+alternative, that selects the value @var{value}.
+
+The main use of @code{other} is as the last element of @code{choice}.
+For example,
+
+@example
+(choice (const :tag "Yes" t)
+        (const :tag "No" nil)
+        (other :tag "Ask" foo))
+@end example
+
+@noindent
+describes a variable for which @code{t} means yes, @code{nil} means no,
+and anything else means ``ask.''  If the user chooses @samp{Ask} from
+the menu of alternatives, that specifies the value @code{foo}; but any
+other value (not @code{t}, @code{nil} or @code{foo}) displays as
+@samp{Ask}, just like @code{foo}.
+
 @item (function-item @var{function})
 Like @code{const}, but used for values which are functions.  This
 displays the documentation string as well as the function name.
@@ -519,10 +711,35 @@ displays the documentation string as well as the variable name.  The
 documentation string is either the one you specify with @code{:doc}, or
 @var{variable}'s own documentation string.
 
-@item (set @var{elements}@dots{})
-The value must be a list and each element of the list must be one of the
-@var{elements} specified.  This appears in the customization buffer as a
-checklist.
+@item (set @var{types}@dots{})
+The value must be a list, and each element of the list must match one of
+the @var{types} specified.
+
+This appears in the customization buffer as a checklist, so that each of
+@var{types} may have either one corresponding element or none.  It is
+not possible to specify two different elements that match the same one
+of @var{types}.  For example, @code{(set integer symbol)} allows one
+integer and/or one symbol in the list; it does not allow multiple
+integers or multiple symbols.  As a result, it is rare to use
+nonspecific types such as @code{integer} in a @code{set}.
+
+Most often, the @var{types} in a @code{set} are @code{const} types, as
+shown here:
+
+@example
+(set (const :bold) (const :italic))
+@end example
+
+Sometimes they describe possible elements in an alist:
+
+@example
+(set (cons :tag "Height" (const height) integer)
+     (cons :tag "Width" (const width) integer))
+@end example
+
+@noindent
+That lets the user specify a height value optionally
+and a width value optionally.
 
 @item (repeat @var{element-type})
 The value must be a list and each element of the list must fit the type
@@ -677,8 +894,11 @@ provide more information about the meanings of alternatives inside a
 
 @item :help-echo @var{motion-doc}
 When you move to this item with @code{widget-forward} or
-@code{widget-backward}, it will display the string @var{motion-doc}
-in the echo area.
+@code{widget-backward}, it will display the string @var{motion-doc} in
+the echo area.  In addition, @var{motion-doc} is used as the mouse
+@code{help-echo} string and may actually be a function or form evaluated
+to yield a help string as for @code{help-echo} text properties.
+@c @xref{Text help-echo}.
 
 @item :match @var{function}
 Specify how to decide whether a value matches the type.  The