[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to emacs/lispref/customize.texi,v
From: |
Eli Zaretskii |
Subject: |
[Emacs-diffs] Changes to emacs/lispref/customize.texi,v |
Date: |
Mon, 27 Nov 2006 07:28:16 +0000 |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] Changes to emacs/lispref/customize.texi,v,
Eli Zaretskii <=