[Emacs-diffs] Changes to emacs/lispref/customize.texi,v

[Eli Zaretskii]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Eli Zaretskii <eliz>    06/11/27 07:28:16

Index: customize.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/customize.texi,v
retrieving revision 1.61
retrieving revision 1.62
diff -u -b -r1.61 -r1.62
--- customize.texi      16 Aug 2006 05:10:55 -0000      1.61
+++ customize.texi      27 Nov 2006 07:28:16 -0000      1.62
@@ -7,6 +7,7 @@
 @node Customization, Loading, Macros, Top
 @chapter Writing Customization Definitions
 
address@hidden customization definitions
   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
@@ -23,6 +24,7 @@
 @node Common Keywords
 @section Common Item Keywords
 
address@hidden customization keywords
   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.
@@ -34,6 +36,7 @@
 
 @table @code
 @item :tag @var{label}
address@hidden address@hidden, customization keyword}
 Use @var{label}, a string, instead of the item's name, to label the
 item in customization menus and buffers.  @strong{Don't use a tag
 which is substantially different from the item's real name; that would
@@ -45,6 +48,7 @@
   :tag "Cursor In Non-selected Windows"
 @end example
 
address@hidden address@hidden, customization keyword}
 @item :group @var{group}
 Put this customization item in group @var{group}.  When you use
 @code{:group} in a @code{defgroup}, it makes the new group a subgroup of
@@ -55,6 +59,7 @@
 item.  Please don't overdo this, since the result would be annoying.
 
 @item :link @var{link-data}
address@hidden address@hidden, customization keyword}
 Include an external link after the documentation string for this item.
 This is a sentence containing an active field which references some
 other documentation.
@@ -114,11 +119,13 @@
 none at all.
 
 @item :load @var{file}
address@hidden address@hidden, customization keyword}
 Load file @var{file} (a string) before displaying this customization
 item.  Loading is done with @code{load-library}, and only if the file is
 not already loaded.
 
 @item :require @var{feature}
address@hidden address@hidden, customization keyword}
 Execute @code{(require '@var{feature})} when your saved customizations
 set the value of this item.  @var{feature} should be a symbol.
 
@@ -127,11 +134,13 @@
 any effect unless the code which implements the mode is loaded.
 
 @item :version @var{version}
address@hidden address@hidden, customization keyword}
 This option specifies that the item was first introduced in Emacs
 version @var{version}, or that its default value was changed in that
 version.  The value @var{version} must be a string.
 
 @item :package-version '(@var{package} . @var{version})
address@hidden address@hidden, customization keyword}
 This option specifies that the item was first introduced in
 @var{package} version @var{version}, or that its meaning or default
 value was changed in that version.  The value of @var{package} is a
@@ -179,6 +188,7 @@
 @node Group Definitions
 @section Defining Custom Groups
 
address@hidden custom groups, how to define
   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
@@ -221,6 +231,7 @@
 
 @table @code
 @item :prefix @var{prefix}
address@hidden address@hidden, @code{defgroup} keyword}
 If the name of an item in the group starts with @var{prefix}, then the
 tag for that item is constructed (by default) by omitting @var{prefix}.
 
@@ -249,6 +260,8 @@
 @node Variable Definitions
 @section Defining Customization Variables
 
address@hidden customization variables, how to define
address@hidden declare user-editable variables
   Use @code{defcustom} to declare user-editable variables.
 
 @defmac defcustom option standard doc [keyword address@hidden
@@ -297,6 +310,7 @@
 @xref{Customization Types}, for more information.
 
 @item :options @var{list}
address@hidden address@hidden, @code{defcustom} keyword}
 Specify @var{list} as the list of reasonable values for use in this
 option.  The user is not restricted to using only these values, but they
 are offered as convenient alternatives.
@@ -306,6 +320,7 @@
 individual types for a description of how to use @code{:options}.
 
 @item :set @var{setfunction}
address@hidden address@hidden, @code{defcustom} keyword}
 Specify @var{setfunction} as the way to change the value of this
 option.  The function @var{setfunction} should take two arguments, a
 symbol (the option name) and the new value, and should do whatever is
@@ -314,6 +329,7 @@
 @var{setfunction} is @code{set-default}.
 
 @item :get @var{getfunction}
address@hidden address@hidden, @code{defcustom} keyword}
 Specify @var{getfunction} as the way to extract the value of this
 option.  The function @var{getfunction} should take one argument, a
 symbol, and should return whatever customize should use as the
@@ -327,6 +343,7 @@
 that really is stored in a Lisp variable.
 
 @item :initialize @var{function}
address@hidden address@hidden, @code{defcustom} keyword}
 @var{function} should be a function used to initialize the variable
 when the @code{defcustom} is evaluated.  It should take two arguments,
 the option name (a symbol) and the value.  Here are some predefined
@@ -374,6 +391,7 @@
 @end table
 
 @item :set-after @var{variables}
address@hidden address@hidden, @code{defcustom} keyword}
 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
@@ -425,11 +443,13 @@
 @node Customization Types
 @section Customization Types
 
address@hidden customization types
   When you define a user option with @code{defcustom}, you must specify
 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.
 
address@hidden address@hidden, @code{defcustom} keyword}
   You specify the customization type in @code{defcustom} with the
 @code{:type} keyword.  The argument of @code{:type} is evaluated, but
 only once when the @code{defcustom} is executed, so it isn't useful
@@ -905,10 +925,12 @@
 @code{choice}.
 
 @item :match-alternatives @var{criteria}
address@hidden address@hidden, customization keyword}
 Use @var{criteria} to match possible values.  This is used only in
 @code{restricted-sexp}.
 
 @item :args @var{argument-list}
address@hidden address@hidden, customization keyword}
 Use the elements of @var{argument-list} as the arguments of the type
 construct.  For instance, @code{(const :args (foo))} is equivalent to
 @code{(const foo)}.  You rarely need to write @code{:args} explicitly,
@@ -986,6 +1008,7 @@
 essential to specify a valid default with @code{:value}.
 
 @item :format @var{format-string}
address@hidden address@hidden, customization keyword}
 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}:
@@ -1024,14 +1047,18 @@
 @end table
 
 @item :action @var{action}
address@hidden address@hidden, customization keyword}
 Perform @var{action} if the user clicks on a button.
 
 @item :button-face @var{face}
address@hidden address@hidden, customization keyword}
 Use the face @var{face} (a face name or a list of face names) for button
 text displayed with @address@hidden
 
 @item :button-prefix @var{prefix}
 @itemx :button-suffix @var{suffix}
address@hidden address@hidden, customization keyword}
address@hidden address@hidden, customization keyword}
 These specify the text to display before and after a button.
 Each can be:
 
@@ -1051,6 +1078,7 @@
 that corresponds to this type.
 
 @item :doc @var{doc}
address@hidden address@hidden, customization keyword}
 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}
@@ -1061,6 +1089,7 @@
 @code{:choice} type or the parts of some other composite type.
 
 @item :help-echo @var{motion-doc}
address@hidden address@hidden, customization keyword}
 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.  In addition, @var{motion-doc} is used as the mouse
@@ -1069,6 +1098,7 @@
 argument, the widget.
 
 @item :match @var{function}
address@hidden address@hidden, customization keyword}
 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 address@hidden if