(view-todo): New function.

[gnu-emacs] / lispref / customize.texi

diff --git a/lispref/customize.texi b/lispref/customize.texi
index b43610764185316d620255f5b20890e0da5aa99b..1a5ba1577899d9c21e6a3db8cc4ace3a0e5a85e1 100644 (file)
--- 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 -*-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
 @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
 @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.
 
   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
 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}
 in customization menus and buffers.
 
 @item :group @var{group}


@@ -42,14 +42,14 @@ 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
 
 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.
 This is a sentence containing an active field which references some
 other documentation.
 
 
 @item :link @var{link-data}
 Include an external link after the documentation string for this item.
 This is a sentence containing an active field which references some
 other documentation.
 

-There are three alternatives you can use for @var{link-data}:
+There are four alternatives you can use for @var{link-data}:

 
 @table @code
 @item (custom-manual @var{info-node})
 
 @table @code
 @item (custom-manual @var{info-node})


@@ -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 (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
 @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]...
   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
 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
 
 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.
 
 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
 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}
 
 @table @code
 @item :prefix @var{prefix}


@@ -161,16 +177,28 @@ turn this feature back on, if someone would like to do the work.
 
   Use @code{defcustom} to declare user-editable variables.
 
 
   Use @code{defcustom} to declare user-editable variables.
 

-@defmac defcustom option default doc [keyword value]...
-@tindex defcustom
+@defmac defcustom option default doc [keyword value]@dots{}

 Declare @var{option} as a customizable user option variable.  Do not
 quote @var{option}.  The argument @var{doc} specifies the documentation
 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 often start with a @samp{*} to mark
+it as a @dfn{user option} (@pxref{Defining Variables}).  Do not start
+the documentation string with @samp{*} for options which cannot or
+normally should not be set with @code{set-variable}; examples of the
+former are global minor mode options such as
+@code{global-font-lock-mode} and examples of the latter are hooks.

 
 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
 
 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.
+than one occasion.  You should normally avoid using backquotes in
+@var{default} because they are not expanded when editing the value,
+causing list values to appear to have the wrong structure.
+
+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:
 @end defmac
 
   @code{defcustom} accepts the following additional keywords:


@@ -248,6 +276,13 @@ 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
 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
 
   The @code{:require} option is useful for an option that turns on the
 @end table
 
   The @code{:require} option is useful for an option that turns on the


@@ -258,7 +293,7 @@ Keywords}.  Here is an example, from the library @file{paren.el}:
 
 @example
 (defcustom show-paren-mode nil
 
 @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
   :set (lambda (symbol value)
          (show-paren-mode (or value 0)))
   :initialize 'custom-initialize-default


@@ -277,7 +312,8 @@ options for @code{emacs-lisp-mode-hook}, but not by editing its
 definition.   You can do it thus:
 
 @example
 definition.   You can do it thus:
 
 @example

-(custom-add-option 'emacs-lisp-mode-hook 'my-lisp-mode-initialization)
+(custom-add-option 'emacs-lisp-mode-hook
+                   'my-lisp-mode-initialization)

 @end example
 
 @defun custom-add-option symbol option
 @end example
 
 @defun custom-add-option symbol option


@@ -332,6 +368,9 @@ equivalent to @code{(string)}.
 * Type Keywords::
 @end menu
 
 * Type Keywords::
 @end menu
 

+All customization types are implemented as widgets; see @ref{Top, ,
+Introduction, widget, The Emacs Widget Library} for details.
+

 @node Simple Types
 @subsection Simple Types
 
 @node Simple Types
 @subsection Simple Types
 


@@ -385,17 +424,16 @@ You can use the @code{:options} keyword in a hook variable's
 the hook; see @ref{Variable Definitions}.
 
 @item alist
 the hook; see @ref{Variable Definitions}.
 
 @item alist

-The value must be a list of cons-cells, the car of each cell
-representing a key, and the cdr of the same cell representing and
-associated value.  The use can add and a delete key/value pairs, and
+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:
 
 edit both the key and the value of each pair.
 
 You can specify the key and value types like this:
 

-@example
-(alist :key-type @var{key-type}
-       :value-type @var{value-type})
-@end example
+@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
 
 @noindent
 where @var{key-type} and @var{value-type} are customization type


@@ -414,9 +452,9 @@ 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:
 
 specifications.  Ordinarily, the options are simply atoms, which are the
 specified keys.  For example:
 

-@example
+@smallexample

 :options '("foo" "bar" "baz")
 :options '("foo" "bar" "baz")

-@end example
+@end smallexample

 
 @noindent
 specifies that there are three ``known'' keys, namely @code{"foo"},
 
 @noindent
 specifies that there are three ``known'' keys, namely @code{"foo"},


@@ -428,9 +466,9 @@ 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.
 
 specification.  The first element will specify the key, like before,
 while the second element will specify the value type.
 

-@example
+@smallexample

 :options '("foo" ("bar" integer) "baz")
 :options '("foo" ("bar" integer) "baz")

-@end example
+@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
 
 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


@@ -440,36 +478,36 @@ you may want to use a more specialized type for presenting the key, like
 This is done by using a customization type specification instead of a
 symbol for the key.
 
 This is done by using a customization type specification instead of a
 symbol for the key.
 

-@example
+@smallexample

 :options '("foo" ((function-item some-function) integer) "baz")
 :options '("foo" ((function-item some-function) integer) "baz")

-@end example
+@end smallexample

 
 

-Many alist uses lists with two elements, instead of cons cells.  For
+Many alists use lists with two elements, instead of cons cells.  For

 example,
 
 example,
 

-@example
+@smallexample

 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
   "Each element is a list of the form (KEY VALUE).")
 (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
   "Each element is a list of the form (KEY VALUE).")

-@end example
+@end smallexample

 
 @noindent
 instead of 
 
 
 @noindent
 instead of 
 

-@example
+@smallexample

 (defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
   "Each element is a cons-cell (KEY . VALUE).")
 (defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
   "Each element is a cons-cell (KEY . VALUE).")

-@end example
+@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.
 
 
 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.
 

-@example
+@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)))
 (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 example
+@end smallexample

 
 The @code{group} widget is used here instead of @code{list} only because
 the formatting is better suited for the purpose.
 
 The @code{group} widget is used here instead of @code{list} only because
 the formatting is better suited for the purpose.


@@ -477,28 +515,31 @@ 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:
 
 Similarily, you can have alists with more values associated with each
 key, using variations of this trick:
 

-@example
+@smallexample

 (defcustom person-data '(("brian"  50 t) 
                          ("dorith" 55 nil)
                          ("ken"    52 t))
 (defcustom person-data '(("brian"  50 t) 
                          ("dorith" 55 nil)
                          ("ken"    52 t))

-  "Alist of people, each element has the form (NAME AGE MALE)."
+  "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"))
   :type '(alist :value-type (group age boolean)))
 
 (defcustom pets '(("brian") 
                   ("dorith" "dog" "guppy")
                   ("ken" "cat"))

-  "Alist where the KEY is a person, and the VALUE is a list of pets."
+  "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)))
   :type '(alist :value-type (repeat string)))

-@end example
+@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:
 
 
 @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:
 

-@example
+@smallexample

 (@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{})
 (@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{})

-@end example
+@end smallexample

 
 The default @code{:key-type} for @code{plist} is @code{symbol},
 rather than @code{sexp}.
 
 The default @code{:key-type} for @code{plist} is @code{symbol},
 rather than @code{sexp}.


@@ -525,6 +566,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.
 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
 @end table
 
 @node Composite Types


@@ -591,7 +640,7 @@ separately, according to the type specified for it.
 Like @code{list} except that the value must be a vector instead of a
 list.  The elements work the same as in @code{list}.
 
 Like @code{list} except that the value must be a vector instead of a
 list.  The elements work the same as in @code{list}.
 

-@item (choice @var{alternative-types}...)
+@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 at least one of @var{alternative-types}.
 For example, @code{(choice integer string)} allows either an
 integer or a string.


@@ -618,6 +667,13 @@ 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}.
 
 a @code{const}, you should specify a valid default for that alternative
 using the @code{:value} keyword.  @xref{Type Keywords}.
 

+@item (radio @var{element-types}@dots{})
+This is similar to @code{choice}, except that the choices are displayed
+using `radio buttons' rather than a menu.  This has the advantage of
+displaying documentation for the choices when applicable and so is often
+a good choice for a choice between constant functions
+(@code{function-item} customization types).
+

 @item (const @var{value})
 The value must be @var{value}---nothing else is allowed.
 
 @item (const @var{value})
 The value must be @var{value}---nothing else is allowed.
 


@@ -853,8 +909,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
 
 @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
 
 @item :match @var{function}
 Specify how to decide whether a value matches the type.  The


@@ -884,20 +943,20 @@ the item itself, the second argument is the item that was changed, and
 the third argument is the event leading to the change, if any.
 
 @item :menu-tag
 the third argument is the event leading to the change, if any.
 
 @item :menu-tag

-Tag used in the menu when the widget is used as an option in a
+A tag used in the menu when the widget is used as an option in a

 @code{menu-choice} widget.
 
 @item :menu-tag-get
 @code{menu-choice} widget.
 
 @item :menu-tag-get

-Function used for finding the tag when the widget is used as an option
+A function used for finding the tag when the widget is used as an option

 in a @code{menu-choice} widget.  By default, the tag used will be either the
 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
 representation of the @code{:value} property if not.
 
 @item :validate
 in a @code{menu-choice} widget.  By default, the tag used will be either the
 @code{:menu-tag} or @code{:tag} property if present, or the @code{princ}
 representation of the @code{:value} property if not.
 
 @item :validate

-A function which takes a widget as an argument, and return nil if the
-widgets current value is valid for the widget.  Otherwise, it should
-return the widget containing the invalid data, and set that widgets
-@code{:error} property to a string explaining the error.
+A function which takes a widget as an argument, and return @code{nil}
+if the widget's current value is valid for the widget.  Otherwise, it
+should return the widget containing the invalid data, and set that
+widget's @code{:error} property to a string explaining the error.

 
 You can use the function @code{widget-children-validate} for this job;
 it tests that all children of @var{widget} are valid.
 
 You can use the function @code{widget-children-validate} for this job;
 it tests that all children of @var{widget} are valid.