This is Info file ../info/customize, produced by Makeinfo version 1.68
from the input file customize.texi.

Distribution
************

Copyright (C) 1997 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the same conditions as for modified
versions.


File: customize,  Node: Top,  Next: Common Keywords,  Up: (dir)

Declarations
************

   This section describes how to declare customization groups,
variables, and faces.  We use the term "customization item" to include
all three of those.  This has few examples, but please look at the file
`cus-edit.el', which contains many declarations you can learn from.

* Menu:

* Common Keywords::
* Declaring Groups::
* Declaring Variables::
* Declaring Faces::
* Customization Types::


File: customize,  Node: Common Keywords,  Next: Declaring Groups,  Prev: Top,  Up: Top

Common Keywords for All Kinds of Items
**************************************

   All the customization declarations accept keyword arguments for
specifying various information.  This section describes some keywords
that apply to all three kinds of customization items (groups, variables,
and faces).

   Most of these keywords can be used more than once in a given item.
Each use of the keyword has an independent effect.  The only keyword
which cannot meaningfully be used more than once is `:tag'--because
only one name is displayed for a given item.

`:group GROUP'
     Put this customization item in group GROUP.  When you use `:group'
     in a `defgroup', it makes one group within another.

     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 go overboard with this!

`:link 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 LINK-DATA:

    `(custom-manual INFO-NODE)'
          Link to an Info node; INFO-NODE is a string which specifies
          the node name, as in `"(emacs)Top"'.  The link appears as
          `[manual]' in the customization buffer.

    `(info-link INFO-NODE)'
          Like `custom-manual' except that the link appears in the
          customization buffer with the Info node name.

    `(url-link URL)'
          Link to a web page; URL is a string which specifies the URL.
          The link appears in the customization buffer as URL.

     You can specify the text to use in the customization buffer by
     adding `:tag NAME' after the first element of the LINK-DATA; for
     example, `(info-link :tag "foo" "(emacs)Top")' makes a link to the
     Emacs manual which appears in the buffer as `foo'.

     An item can have more than one external link; most items have none
     at all.

`:load FILE'
     Load file FILE (a string) before displaying this customization
     item.  Loading is done with `load-library', and only if the file is
     not already loaded.

`:require FEATURE'
     Require feature FEATURE (a symbol) when installing a value for
     this item (an option or a face) that was saved using the
     customization feature.  This is done by calling `require'.

     The most common reason to use `:require' is when a variable enables
     a feature, such as a minor mode, and it won't have any effect
     unless the code which implements the mode is loaded.

`:tag NAME'
     Use NAME, a string, instead of the item's name, to label the item
     in customization menus and buffers.


File: customize,  Node: Declaring Groups,  Next: Declaring Variables,  Prev: Common Keywords,  Up: Top

Declaring Groups
****************

   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 the subgroups.

   The package's main or only group should be a member of one or more of
the standard customization groups.  Type press `C-h p' to display a
list of finder keywords; them choose some of them add your group to each
of them, using the `:group' keyword.

   The way to declare new customization groups is with `defgroup'.

 - Function: defgroup GROUP MEMBERS DOC [KEYWORD VALUE]...
     Declare GROUP as a customization group containing MEMBERS.  Do not
     quote the symbol GROUP.  The argument DOC specifies the
     documentation string for the group.

     The arguments MEMBERS can be an alist whose elements specify
     members of the group; however, normally MEMBERS is `nil', and you
     specify the group's members by using the `:group' keyword when
     defining those members.

     In addition to the common keywords (*note Common Keywords::.), you
     can use this keyword in `defgroup':

    `:prefix PREFIX'
          If the name of an item in the group starts with PREFIX, then
          the tag for that item is constructed (by default) by omitting
          PREFIX.

          One group can have any number of prefixes.

   The `:prefix' feature is currently turned off, which means that
`: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 `defgroup'
definitions for various groups added `: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.

   In order to obtain good results with `: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 `:prefix' should not be used in that
case.

   It should be possible to recheck all the customization groups, delete
the `:prefix' specifications which give unclear results, and then turn
this feature back on, if someone would like to do the work.


File: customize,  Node: Declaring Variables,  Next: Declaring Faces,  Prev: Declaring Groups,  Up: Top

Declaring Variables
*******************

   Use `defcustom' to declare user editable variables.

 - Function: defcustom OPTION VALUE DOC [KEYWORD VALUE]...
     Declare OPTION as a customizable user option variable that
     defaults to VALUE.  Do not quote OPTION.  VALUE should be an
     expression to compute the value; it will be be evaluated on more
     than one occasion.

     If OPTION is void, `defcustom' initializes it to VALUE.

     The argument DOC specifies the documentation string for the
     variable.

     The following additional keywords are defined:

    `:type TYPE'
          Use TYPE as the data type for this option.  It specifies which
          values are legitimate, and how to display the value.  *Note
          Customization Types::, for more information.

    `:options LIST'
          Specify LIST as the list of reasonable values for use in this
          option.

          Currently this is meaningful only when type is `hook'.  The
          elements of 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.

    `:set SETFUNCTION'
          Specify SETFUNCTION as the way to change the value of this
          option.  The function SETFUNCTION should take two arguments,
          a symbol and the new value, and should do whatever is
          necessary to update the value properly for this option (which
          may not mean simply setting the option as a Lisp variable).
          The default for SETFUNCTION is `set-default'.

    `:get GETFUNCTION'
          Specify GETFUNCTION as the way to extract the value of this
          option.  The function GETFUNCTION should take one argument, a
          symbol, and should return the "current value" for that symbol
          (which need not be the symbol's Lisp value).  The default is
          `default-value'.

    `:initialize FUNCTION'
          FUNCTION should be a function used to initialize the variable
          when the `defcustom' is evaluated.  It should take two
          arguments, the symbol and value.  Here are some predefined
          functions meant for use in this way:

         `custom-initialize-set'
               Use the variable's `:set' function to initialize the
               variable.  Do not reinitialize it if it is already
               non-void.  This is the default `:initialize' function.

         `custom-initialize-default'
               Always use `set-default' to initialize the variable,
               even if some other `:set' function has been specified.

         `custom-initialize-reset'
               Even if the variable is already non-void, reset it by
               calling the `:set' function using the current value
               (returned by the `:get' method).

         `custom-initialize-changed'
               Like `custom-initialize-reset', except use `set-default'
               (rather than the `:set' function) to initialize the
               variable if it is not bound and has not been set already.

    `:require FEATURE'
          If the user saves a customized value for this item, them
          Emacs should do `(require FEATURE)' after installing the
          saved value.

          The place to use this feature is 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
          `:require' is for.

   Internally, `defcustom' uses the symbol property `standard-value' to
record the expression for the default value, and `saved-value' to
record the value saved by the user with the customization buffer.  The
`saved-value' property is actually a list whose car is an expression
which evaluates to the value.


File: customize,  Node: Declaring Faces,  Next: Customization Types,  Prev: Declaring Variables,  Up: Top

Declaring Faces
***************

   Faces are declared with `defface'.

 - Function: defface FACE SPEC DOC [KEYWORD VALUE]...
     Declare FACE as a customizable face that defaults according to
     SPEC.  Do not quote the symbol FACE.

     DOC is the face documentation.

     SPEC should be an alist whose elements have the form `(DISPLAY
     ATTS)' (see below).  When `defface' executes, it defines the face
     according to SPEC, then uses any customizations saved in the
     `.emacs' file to override that specification.

     In each element of SPEC, ATTS is a list of face attributes and
     their values.  The possible attributes are defined in the variable
     `custom-face-attributes'.

     The DISPLAY part of an element of SPEC determines which frames the
     element applies to.  If more than one element of SPEC matches a
     given frame, the first matching element is the only one used for
     that frame.

     If DISPLAY is `t' in a SPEC element, that element matches all
     frames.  (This means that any subsequent elements of SPEC are
     never used.)

     Alternatively, DISPLAY can be an alist whose elements have the
     form `(CHARACTERISTIC VALUE...)'.  Here CHARACTERISTIC specifies a
     way of classifying frames, and the VALUEs are possible
     classifications which DISPLAY should apply to.  Here are the
     possible values of CHARACTERISTIC:

    `type'
          The kind of window system the frame uses--either `x', `pc'
          (for the MS-DOS console), `w32' (for MS Windows 9X/NT), or
          `tty'.

    `class'
          What kinds of colors the frame supports--either `color',
          `grayscale', or `mono'.

    `background'
          The kind of background-- either `light' or `dark'.

     If an element of DISPLAY specifies more than one VALUE for a given
     CHARACTERISTIC, any of those values is acceptable.  If an element
     of DISPLAY has elements for more than one CHARACTERISTIC, then
     EACH characteristic of the frame must match one of the values
     specified for it.

   Internally, `defface' uses the symbol property `face-defface-spec'
to record the face attributes specified in `defface', `saved-face' for
the attributes saved by the user with the customization buffer, and
`face-documentation' for the documentation string.


File: customize,  Node: Customization Types,  Prev: Declaring Faces,  Up: Top

Customization Types
*******************

   When you define a user option with `defcustom', you must specify its
"customization type".  That is a Lisp object which indictaes (1) which
values are legitimate and (2) how to display the value in the
customization buffer for editing.

   You specify the customization type in `defcustom' with the `:type'
keyword.  The argument of `:type' is evaluated; since types that vary
at run time are rarely useful, normally it is a quoted constant.  For
example:

     (defcustom diff-command "diff"
       "*The command to use to run diff."
       :type 'string
       :group 'diff)

   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 "simple types".

   In between the type symbol and its arguments, you can optionally
write keyword-value pairs.  *Note 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 `string' as the customization type.  But `(string)'
would mean the same thing.

* Menu:

* Simple Types::
* Composite Types::
* Splicing into Lists::
* Type Keywords::


File: customize,  Node: Simple Types,  Next: Composite Types,  Up: Customization Types

Simple Types
============

   This section describes all the simple customization types.

`sexp'
     The value may be any Lisp object that can be printed and read
     back.  You can use `sexp' as a fall-back for any option, if you
     don't want to take the time to work out a more specific type to
     use.

`integer'
     The value must be an integer, and is represented textually in the
     customization buffer.

`number'
     The value must be a number, and is represented textually in the
     customization buffer.

`string'
     The value must be a string, and the customization buffer shows
     just the contents, with no `"' characters or quoting with `\'.

`regexp'
     The value must be a string which is a valid regular expression.

`character'
     The value must be a character code.  A character code is actually
     an integer, but this type shows the value by inserting the
     character in the buffer, rather than by showing the number.

`file'
     The value must be a file name, and you can do completion with
     `M-<TAB>'.

`(file :must-match t)'
     The value must be a file name for an existing file, and you can do
     completion with `M-<TAB>'.

`directory'
     The value must be a directory name, and you can do completion with
     `M-<TAB>'.

`symbol'
     The value must be a symbol.  It appears in the customization
     buffer as the name of the symbol.

`function'
     The value must be either a lambda expression or a function name.
     When it is a function name, you can do completion with `M-<TAB>'.

`variable'
     The value must be a variable name, and you can do completion with
     `M-<TAB>'.

`boolean'
     The value is boolean--either `nil' or `t'.


File: customize,  Node: Composite Types,  Next: Splicing into Lists,  Prev: Simple Types,  Up: Customization Types

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:

`(restricted-sexp :match-alternatives CRITERIA)'
     The value may be any Lisp object that satisfies one of CRITERIA.
     CRITERIA should be a list, and each elements should be one of
     these possibilities:

        * A predicate--that is, a function of one argument that returns
          non-`nil' if the argument fits a certain type.  This means
          that objects of that type are acceptable.

        * A quoted constant--that is, `'OBJECT'.  This means that
          OBJECT is an acceptable value.

     For example,

          (restricted-sexp :match-alternatives (integerp 't 'nil))

     allows integers, `t' and `nil' as legitimate values.

     The customization buffer shows all legitimate values using their
     read syntax, and the user edits them textually.

`(cons CAR-TYPE CDR-TYPE)'
     The value must be a cons cell, its CAR must fit CAR-TYPE, and its
     CDR must fit CDR-TYPE.  For example, `(const string symbol)' is a
     customization type which matches values such as `("foo" . foo)'.

     In the customization buffeer, the CAR and the CDR are displayed
     and edited separately, each according to the type that you specify
     for it.

`(list ELEMENT-TYPES...)'
     The value must be a list with exactly as many elements as the
     ELEMENT-TYPES you have specified; and each element must fit the
     corresponding ELEMENT-TYPE.

     For example, `(list integer string function)' describes a list of
     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 separately, according to the type specified for it.

`(vector ELEMENT-TYPES...)'
     Like `list' except that the value must be a vector instead of a
     list.  The elements work the same as in `list'.

`(choice ALTERNATIVE-TYPES...)'
     The value must fit at least one of ALTERNATIVE-TYPES.  For
     example, `(choice integer string)' allows either an integer or a
     string.

     In the customization buffer, the user selects one of the
     alternatives using a menu, and can then edit the value in the
     usual way for that alternative.

     Normally the strings in this menu are determined automatically
     from the choices; however, you can specify different strings for
     the menu by including the `:tag' keyword in the alternatives.  For
     example, if an integer stands for a number of spaces, while a
     string is text to use verbatim, you might write the customization
     type this way,

          (choice (integer :tag "Number of spaces")
                  (string :tag "Literal text"))

     so that the menu offers `Number of spaces' and `Literal Text'.

`(const VALUE)'
     The value must be VALUE--nothing else is allowed.

     The main use of `const' is inside of `choice'.  For example,
     `(choice integer (const nil))' allows either an integer or `nil'.
     `:tag' is often used with `const'.

`(function-item FUNCTION)'
     Like `const', but used for values which are functions.  This
     displays the documentation string of the function FUNCTION as well
     as its name.

`(variable-item VARIABLE)'
     Like `const', but used for values which are variable names.  This
     displays the documentation string of the variable VARIABLE as well
     as its name.

`(set ELEMENTS...)'
     The value must be a list and each element of the list must be one
     of the ELEMENTS specified.  This appears in the customization
     buffer as a checklist.

`(repeat ELEMENT-TYPE)'
     The value must be a list and each element of the list must fit the
     type ELEMENT-TYPE.  This appears in the customization buffer as a
     list of elements, with `[INS]' and `[DEL]' buttons for adding more
     elements or removing elements.


File: customize,  Node: Splicing into Lists,  Next: Type Keywords,  Prev: Composite Types,  Up: Customization Types

Splicing into Lists
===================

   The `:inline' feature lets you splice a variable number of elements
into the middle of a list or vector.  You use it in a `set', `choice'
or `repeat' type which appears among the element-types of a `list' or
`vector'.

   Normally, each of the element-types in a `list' or `vector'
describes one and only one element of the list or vector.  Thus, if an
element-type is a `repeat', that specifies a list of unspecified length
which appears as one element.

   But when the element-type uses `:inline', the value it matches is
merged directly into the containing sequence.  For example, if it
matches a list with three elements, those become three elements of the
overall sequence.  This is analogous to using `,@' in the backquote
construct.

   For example, to specify a list whose first element must be `t' and
whose remaining arguments should be zero or more of `foo' and `bar',
use this customization type:

     (list (const t) (set :inline t foo bar))

This matches values such as `(t)', `(t foo)', `(t bar)' and `(t foo
bar)'.

   When the element-type is a `choice', you use `:inline' not in the
`choice' itself, but in (some of) the alternatives of the `choice'.
For example, to match a list which must start with a file name,
followed either by the symbol `t' or two strings, use this
customization type:

     (list file
           (choice (const t)
                   (list :inline t string string)))

If the user chooses the first alternative in the choice, then the
overall list has two elements and the second element is `t'.  If the
user chooses the second alternative, then the overall list has three
elements and the second and third must be strings.


File: customize,  Node: Type Keywords,  Prev: Splicing into Lists,  Up: Customization Types

Type Keywords
=============

   You can specify keyword-argument pairs in a customization type after
the type name symbol.  Here are the keywords you can use, and their
meanings:

`:value DEFAULT'
     This is used for a type that appears as an alternative inside of
     `: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 DEFAULT.

`:format FORMAT-STRING'
     This string will be inserted in the buffer to represent the value
     corresponding to the type.  The following `%' escapes are available
     for use in FORMAT-STRING:

    `%{SAMPLE%}'
          Show SAMPLE in a special face specified by `:sample-face'.

    `%v'
          Substitute the item's value.  How the value is represented
          depends on the kind of item, and (for variables) on the
          customization type.

    `%d'
          Substitute the item's documentation string.

    `%h'
          Like `%d', but if the documentation string is more than one
          line, add an active field to control whether to show all of
          it or just the first line.

    `%t'
          Substitute the tag here.  You specify the tag with the `:tag'
          keyword.

    `%%'
          Display a literal `%'.

`:button-face FACE'
     Use face FACE for text displayed with `%[...%]'.

`:button-prefix'
`:button-suffix'
     These specify the text to display before and after a button.  Each
     can be:

    `nil'
          No text is inserted.

    a string
          The string is inserted literally.

    a symbol
          The symbol's value is used.

`:doc DOC'
     Use DOC as the documentation string for this item.

`:tag TAG'
     Use TAG (a string) as the tag for this item.

`:help-echo MOTION-DOC'
     When you move to this item with `widget-forward' or
     `widget-backward', it will display the string MOTION-DOC in the
     echo area.

`:match FUNCTION'
     Specify how to decide whether a value matches the type.  FUNCTION
     should be a function that accepts two arguments, a widget and a
     value; it should return non-`nil' if the value is acceptable.



Tag Table:
Node: Top754
Node: Common Keywords1242
Node: Declaring Groups4093
Node: Declaring Variables6839
Node: Declaring Faces10897
Node: Customization Types13321
Node: Simple Types14788
Node: Composite Types16590
Node: Splicing into Lists20705
Node: Type Keywords22537

End Tag Table
