Patch by Martin.Lorentzson@telia.com.

[bpt/emacs.git] / lispref / customize.texi

diff --git a/lispref/customize.texi b/lispref/customize.texi
index 0da420c..97d26c7 100644 (file)
--- a/lispref/customize.texi
+++ b/lispref/customize.texi
@@ -130,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}
@@ -165,17 +177,22 @@ 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]...
+@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
-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.
+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
-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}
@@ -351,6 +368,9 @@ equivalent to @code{(string)}.
 * 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
 
@@ -620,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}.
 
-@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.
@@ -647,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}.
 
+@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.