diff lispref/customize.texi @ 21682:90da2489c498

*** empty log message ***

--- a/lispref/customize.texi	Mon Apr 20 17:37:53 1998 +0000
+++ b/lispref/customize.texi	Mon Apr 20 17:43:57 1998 +0000
@@ -6,30 +6,29 @@
 @node Customization, Loading, Macros, Top
 @chapter Writing Customization Definitions
 
-This chapter describes how to declare customization groups, variables,
-and faces.  We use the term @dfn{customization item} to include all
-three of those.  This has few examples, but please look at the file
-@file{cus-edit.el}, which contains many declarations you can learn from.
+  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}).
 
 @menu
 * Common Keywords::
 * Group Definitions::            
 * Variable Definitions::         
-* Face Definitions::             
 * Customization Types::
 @end menu
 
 @node Common Keywords
 @section Common Keywords for All Kinds of Items
 
-All three kinds of customization declarations (for groups, variables,
-and faces) accept keyword arguments for specifying various information.
-This section describes some keywords that apply to all three.
+  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.
 
-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.  The
-keyword @code{:tag} is an exception because any given item can only
-display one name item.
+  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.
+The keyword @code{:tag} is an exception because any given item can only
+display one name.
 
 @table @code
 @item :group @var{group}
@@ -49,6 +48,10 @@
 There are three alternatives you can use for @var{link-data}:
 
 @table @code
+@item :tag @var{name}
+Use @var{name}, a string, instead of the item's name, to label the item
+in customization menus and buffers.
+
 @item (custom-manual @var{info-node})
 Link to an Info node; @var{info-node} is a string which specifies the
 node name, as in @code{"(emacs)Top"}.  The link appears as
@@ -59,8 +62,8 @@
 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 URL.  The
-link appears in the customization buffer as @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}.
 @end table
 
 You can specify the text to use in the customization buffer by adding
@@ -84,30 +87,27 @@
 The most common reason to use @code{:require} is when a variable enables
 a feature such as a minor mode, and just setting the variable won't have
 any effect unless the code which implements the mode is loaded.
-
-@item :tag @var{name}
-Use @var{name}, a string, instead of the item's name, to label the item
-in customization menus and buffers.
 @end table
 
 @node Group Definitions
 @section Defining Custom Groups
 
-Each Emacs Lisp package should have one main customization group which
+  Each Emacs Lisp package should have one main customization group which
 contains all the options, faces and other groups in the package.  If the
 package has a small number of options and faces, use just one group and
 put everything in it.  When there are more than twelve or so options and
 faces, then you should structure them into subgroups, and put the
-subgroups under the package's main customization group.  It is ok to
-have some of the options and faces in the package's main group alongside
+subgroups under the package's main customization group.  It is OK to
+put some of the options and faces in the package's main group alongside
 the subgroups.
 
-The package's main or only group should be a member of one or more of
-the standard customization groups.  Type press @kbd{C-h p} to display a
-list of finder keywords; them choose some of them add your group to each
-of them, using the @code{:group} keyword.
+  The package's main or only group should be a member of one or more of
+the standard customization groups.  (To display the full list of them,
+use @kbd{M-x customize}.)  Choose one or more of them (but not too
+many), and add your group to each of them using the @code{:group}
+keyword.
 
-The way to declare new customization groups is with @code{defgroup}.
+  The way to declare new customization groups is with @code{defgroup}.
 
 @tindex defgroup
 @defmac defgroup group members doc [keyword value]...
@@ -116,9 +116,9 @@
 the documentation string for the group.
 
 The arguments @var{members} can be an alist whose elements specify
-members of the group; however, normally @var{members} is @code{nil}, and
-you specify the group's members by using the @code{:group} keyword when
-defining those members.
+customization items to be members of the group; however, normally
+@var{members} is @code{nil}, and you specify the group's members by
+using the @code{:group} keyword when defining those members.
 
 @ignore
 @code{(@var{name} @var{widget})}.  Here @var{name} is a symbol, and
@@ -139,40 +139,40 @@
 @end table
 @end defmac
 
-The @code{:prefix} 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 they say that there was a
-common prefix for the option names in a library.
+  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 is 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.
+  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.
 
-It should be possible to recheck all the customization groups, delete
+  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.
 
 @node Variable Definitions
 @section Defining Customization Variables
 
-  Use @code{defcustom} to declare user editable variables.
+  Use @code{defcustom} to declare user-editable variables.
 
 @tindex defcustom
-@defmac defcustom option value doc [keyword value]...
-Declare @var{option} as a customizable user option variable that
-defaults to @var{value}.  Do not quote @var{option}.  @var{value} should
-be an expression to compute the value; it will be be evaluated on more
+@defmac defcustom option default doc [keyword value]...
+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.
+
+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 be evaluated on more
 than one occasion.
 
-If @var{option} is void, @code{defcustom} initializes it to @var{value}.
-
-The argument @var{doc} specifies the documentation string for the variable.
-
 The following additional keywords are defined:
 
 @table @code
@@ -185,11 +185,10 @@
 Specify @var{list} as the list of reasonable values for use in this
 option.
 
-Currently this is meaningful only when type is @code{hook}.  The
-elements of @var{list} are functions that you might likely want to use
-as elements of the hook value.  The user is not actually restricted to
-using only these functions, 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.
 
 @item :version @var{version}
 This option specifies that the variable's default value was changed in
@@ -226,35 +225,47 @@
 
 @table @code
 @item custom-initialize-set
-Use the variable's @code{:set} function to initialize the variable.  Do
-not reinitialize it if it is already non-void.  This is the default
+Use the variable's @code{:set} function to initialize the variable, but
+do not reinitialize it if it is already non-void.  This is the default
 @code{:initialize} function.
 
 @item custom-initialize-default
-Always use @code{set-default} to initialize the variable, even if some
-other @code{:set} function has been specified.
+Like @code{custom-initialize-set}, but use the function
+@code{set-default} to set the variable, instead of the variable's
+@code{:set} function.  This is the usual choice for a variable whose
+@code{:set} function enables or disables a minor mode; with this choice,
+defining the variable will not call the minor mode function, but
+customizing the variable will do so.
 
 @item custom-initialize-reset
-Even if the variable is already non-void, reset it by calling the
-@code{:set} function using the current value (returned by the
-@code{:get} method).
+Always use the @code{:set} function to initialize the variable.  If the
+variable is already non-void, reset it by calling the @code{:set}
+function using the current value (returned by the @code{:get} method).
 
 @item custom-initialize-changed
-Like @code{custom-initialize-reset}, except use @code{set-default}
-(rather than the @code{:set} function) to initialize the variable if it
-is not bound and has not been set already.
+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
+@end table
+@end defmac
 
-@item :require @var{feature}
-If the user saves a customized value for this item, them Emacs should do
-@code{(require @var{feature})} after installing the saved value.
-
-The place to use this feature is for an option that turns on the
+  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
 check the value of the option, you still need to arrange for the package
-to be loaded.  That is what @code{:require} is for.
-@end table
-@end defmac
+to be loaded.  You can do that with @code{:require}.  @xref{Common
+Keywords}.  Here is an example, from the library @file{paren.el}:
+
+@example
+(defcustom show-paren-mode nil
+  "Toggle Show Paren mode@enddots{}"
+  :set (lambda (symbol value)
+	 (show-paren-mode (or value 0)))
+  :initialize 'custom-initialize-default
+  :type 'boolean
+  :group 'paren-showing
+  :require 'paren)
+@end example
 
 @ignore
 Use @code{custom-add-option} to specify that a specific function is
@@ -274,103 +285,37 @@
 customization buffer.  The @code{saved-value} property is actually a
 list whose car is an expression which evaluates to the value.
 
-@node Face Definitions
-@section Defining Faces
-
-Faces are declared with @code{defface}.
-
-@tindex defface
-@defmac defface face spec doc [keyword value]... 
-Declare @var{face} as a customizable face that defaults according to
-@var{spec}.  Do not quote the symbol @var{face}.
-
-@var{doc} is the face documentation.
-
-@var{spec} should be an alist whose elements have the form
-@code{(@var{display} @var{atts})} (see below).  When @code{defface}
-executes, it defines the face according to @var{spec}, then uses any
-customizations saved in the @file{.emacs} file to override that
-specification.
-
-In each element of @var{spec}, @var{atts} is a list of face attributes
-and their values.  The possible attributes are defined in the variable
-@code{custom-face-attributes}.
-
-The @var{display} part of an element of @var{spec} determines which
-frames the element applies to.  If more than one element of @var{spec}
-matches a given frame, the first matching element is the only one used
-for that frame.
-
-If @var{display} is @code{t} in a @var{spec} element, that element
-matches all frames.  (This means that any subsequent elements of
-@var{spec} are never used.)
-
-Alternatively, @var{display} can be an alist whose elements have the
-form @code{(@var{characteristic} @var{value}@dots{})}.  Here
-@var{characteristic} specifies a way of classifying frames, and the
-@var{value}s are possible classifications which @var{display} should
-apply to.  Here are the possible values of @var{characteristic}:
-
-@table @code
-@item type
-The kind of window system the frame uses---either @code{x}, @code{pc}
-(for the MS-DOS console), @code{w32} (for MS Windows 9X/NT), or
-@code{tty}.
-
-@item class
-What kinds of colors the frame supports---either @code{color},
-@code{grayscale}, or @code{mono}.
-
-@item background
-The kind of background--- either @code{light} or @code{dark}.
-@end table
-
-If an element of @var{display} specifies more than one
-@var{value} for a given @var{characteristic}, any of those values
-is acceptable.  If an element of @var{display} has elements for
-more than one @var{characteristic}, then @var{each} characteristic
-of the frame must match one of the values specified for it.
-@end defmac
-
-Internally, @code{defface} uses the symbol property
-@code{face-defface-spec} to record the face attributes specified in
-@code{defface}, @code{saved-face} for the attributes saved by the user
-with the customization buffer, and @code{face-documentation} for the
-documentation string.
-
 @node Customization Types
 @section Customization Types
 
   When you define a user option with @code{defcustom}, you must specify
-its @dfn{customization type}.  That is a Lisp object which indictaes (1)
+its @dfn{customization type}.  That is a Lisp object which describes (1)
 which values are legitimate and (2) how to display the value in the
 customization buffer for editing.
 
   You specify the customization type in @code{defcustom} with the
 @code{:type} keyword.  The argument of @code{:type} is evaluated; since
-types that vary at run time are rarely useful, normally it is a quoted
+types that vary at run time are rarely useful, normally you use a quoted
 constant.  For example:
 
 @example
 (defcustom diff-command "diff"
   "*The command to use to run diff."
-  :type 'string
+  :type '(string)
   :group 'diff)
 @end example
 
-  In general, a customization type appears is a list whose first element
-is a symbol, one of the customization type names defined in the
-following sections.  After this symbol come a number of arguments,
-depending on the symbol.  Some of the type symbols do not use any
-arguments; those are called @dfn{simple types}.
+  In general, a customization type is a list whose first element is a
+symbol, one of the customization type names defined in the following
+sections.  After this symbol come a number of arguments, depending on
+the symbol.  Between the type symbol and its arguments, you can
+optionally write keyword-value pairs (@pxref{Type Keywords}).
 
-  In between the type symbol and its arguments, you can optionally
-write keyword-value pairs.  @xref{Type Keywords}.
-
-  For a simple type, if you do not use any keyword-value pairs, you can
-omit the parentheses around the type symbol.  The above example does
-this, using just @code{string} as the customization type.
-But @code{(string)} would mean the same thing.
+  Some of the type symbols do not use any arguments; those are called
+@dfn{simple types}.  For a simple type, if you do not use any
+keyword-value pairs, you can omit the parentheses around the type
+symbol.  For example just @code{string} as a customization type is
+equivalent to @code{(string)}.
 
 @menu
 * Simple Types::
@@ -400,10 +345,12 @@
 
 @item string
 The value must be a string, and the customization buffer shows just the
-contents, with no @samp{"} characters or quoting with @samp{\}.
+contents, with no delimiting @samp{"} characters and no quoting with
+@samp{\}.
 
 @item regexp
-The value must be a string which is a valid regular expression.
+Like @code{string} except that the string must be a valid regular
+expression.
 
 @item character
 The value must be a character code.  A character code is actually an
@@ -435,15 +382,19 @@
 @kbd{M-@key{TAB}}.
 
 @item boolean
-The value is boolean---either @code{nil} or @code{t}.
+The value is boolean---either @code{nil} or @code{t}.  Note that by
+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.
 @end table
 
 @node Composite Types
 @subsection Composite Types
 
   When none of the simple types is appropriate, you can use composite
-types, which build from simple types.  Here are several ways of doing
-that:
+types, which build new types from other types.  Here are several ways of
+doing that:
 
 @table @code
 @item (restricted-sexp :match-alternatives @var{criteria})
@@ -459,7 +410,7 @@
 
 @item
 A quoted constant---that is, @code{'@var{object}}.  This means that
-@var{object} is an acceptable value.
+@var{object} itself is an acceptable value.
 @end itemize
 
 For example,
@@ -480,7 +431,7 @@
 symbol)} is a customization type which matches values such as
 @code{("foo" . foo)}.
 
-In the customization buffeer, the @sc{car} and the @sc{cdr} are
+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.
 
@@ -493,7 +444,7 @@
 three elements; the first element must be an integer, the second a
 string, and the third a function.
 
-In the customization buffeer, the each element is displayed and edited
+In the customization buffer, the each element is displayed and edited
 separately, according to the type specified for it.
 
 @item (vector @var{element-types}@dots{})
@@ -523,22 +474,37 @@
 @noindent
 so that the menu offers @samp{Number of spaces} and @samp{Literal Text}.
 
+In any alternative for which @code{nil} is not a valid value, other than
+a @code{const}, you should specify a valid default for that alternative
+using the @code{:value} keyword.  @xref{Type Keywords}.
+
 @item (const @var{value})
 The value must be @var{value}---nothing else is allowed.
 
 The main use of @code{const} is inside of @code{choice}.  For example,
 @code{(choice integer (const nil))} allows either an integer or
-@code{nil}.  @code{:tag} is often used with @code{const}.
+@code{nil}.
+
+@code{:tag} is often used with @code{const}, inside of @code{choice}.
+For example,
+
+@smallexample
+(choice (const :tag "Yes" t)
+        (const :tag "No" nil)
+        (const :tag "Ask" foo))
+@end smallexample
 
 @item (function-item @var{function})
 Like @code{const}, but used for values which are functions.  This
-displays the documentation string of the function @var{function}
-as well as its name.
+displays the documentation string as well as the function name.
+The documentation string is either the one you specify with
+@code{:doc}, or @var{function}'s own documentation string.
 
 @item (variable-item @var{variable})
 Like @code{const}, but used for values which are variable names.  This
-displays the documentation string of the variable @var{variable} as well
-as its name.
+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
@@ -611,20 +577,22 @@
 @table @code
 @item :value @var{default}
 This is used for a type that appears as an alternative inside of
-@code{:choice}; it specifies the default value to use, at first, if and
+@code{choice}; it specifies the default value to use, at first, if and
 when the user selects this alternative with the menu in the
 customization buffer.
 
 Of course, if the actual value of the option fits this alternative, it
 will appear showing the actual value, not @var{default}.
 
+If @code{nil} is not a valid value for the alternative, then it is
+essential to specify a valid default with @code{:value}.
+
 @item :format @var{format-string}
 This string will be inserted in the buffer to represent the value
 corresponding to the type.  The following @samp{%} escapes are available
 for use in @var{format-string}:
 
 @table @samp
-@ignore
 @item %[@var{button}%]
 Display the text @var{button} marked as a button.  The @code{:action}
 attribute specifies what the button will do if the user invokes it;
@@ -632,8 +600,7 @@
 the button appears in, and the event.
 
 There is no way to specify two different buttons with different
-actions; but perhaps there is no need for one.
-@end ignore
+actions.
 
 @item %@{@var{sample}%@}
 Show @var{sample} in a special face specified by @code{:sample-face}.
@@ -658,11 +625,15 @@
 Display a literal @samp{%}. 
 @end table
 
-@item :button-face @var{face}
-Use face @var{face} for text displayed with @samp{%[@dots{}%]}.
+@item :action @var{action}
+Perform @var{action} if the user clicks on a button.
 
-@item :button-prefix
-@itemx :button-suffix
+@item :button-face @var{face}
+Use the face @var{face} (a face name or a list of face names) for button
+text displayed with @samp{%[@dots{}%]}.
+
+@item :button-prefix @var{prefix}
+@itemx :button-suffix @var{suffix}
 These specify the text to display before and after a button.
 Each can be:
 
@@ -677,11 +648,19 @@
 The symbol's value is used.
 @end table
 
-@item :doc @var{doc}
-Use @var{doc} as the documentation string for this item.
+@item :tag @var{tag}
+Use @var{tag} (a string) as the tag for the value (or part of the value)
+that corresponds to this type.
 
-@item :tag @var{tag}
-Use @var{tag} (a string) as the tag for this item.
+@item :doc @var{doc}
+Use @var{doc} as the documentation string for this value (or part of the
+value) that corresponds to this type.  In order for this to work, you
+must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
+in that value.
+
+The usual reason to specify a documentation string for a type is to
+provide more information about the meanings of alternatives inside a
+@code{:choice} type or the parts of some other composite type.
 
 @item :help-echo @var{motion-doc}
 When you move to this item with @code{widget-forward} or
@@ -689,9 +668,10 @@
 in the echo area.
 
 @item :match @var{function}
-Specify how to decide whether a value matches the type.  @var{function}
-should be a function that accepts two arguments, a widget and a value;
-it should return non-@code{nil} if the value is acceptable.
+Specify how to decide whether a value matches the type.  The
+corresponding value, @var{function}, should be a function that accepts
+two arguments, a widget and a value; it should return non-@code{nil} if
+the value is acceptable.
 
 @ignore
 @item :indent @var{columns}