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

Copyright © 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.

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.

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.

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 (see 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.

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. See 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.

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.

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.  See 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.

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.

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.

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.

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.