This is Info file ../info/custom.info, produced by Makeinfo-1.64 from
the input file custom.texi.


File: custom.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

The Customization Library
*************************

   Version: 1.67

* Menu:

* Introduction::
* User Commands::
* The Customization Buffer::
* Declarations::
* Utilities::
* The Init File::
* Wishlist::


File: custom.info,  Node: Introduction,  Next: User Commands,  Prev: Top,  Up: Top

Introduction
============

   This library allows customization of "user options".  Currently two
types of user options are supported, namely "variables" and "faces".
Each user option can have four different values simultaneously:
"factory setting"
     The value specified by the programmer.

"saved value"
     The value saved by the user as the default for this variable.  This
     overwrites the factory setting when starting a new emacs.

"current value"
     The value used by Emacs.  This will not be remembered next time you
     run Emacs.

"widget value"
     The value entered by the user in a customization buffer, but not
     yet applied.

   Variables also have a "type", which specifies what kind of values
the variable can hold, and how the value is presented in a customization
buffer.  By default a variable can hold any valid expression, but the
programmer can specify a more limited type when declaring the variable.

   The user options are organized in a number of "groups".  Each group
can contain a number user options, as well as other groups.  The groups
allows the user to concentrate on a specific part of emacs.


File: custom.info,  Node: User Commands,  Next: The Customization Buffer,  Prev: Introduction,  Up: Top

User Commands
=============

   The following commands will create a customization buffer:

`customize'
     Create a customization buffer containing a specific group, by
     default the `emacs' group.

`customize-variable'
     Create a customization buffer containing a single variable.

`customize-face'
     Create a customization buffer containing a single face.

`customize-apropos'
     Create a customization buffer containing all variables, faces, and
     groups that match a user specified regular expression.


File: custom.info,  Node: The Customization Buffer,  Next: Declarations,  Prev: User Commands,  Up: Top

The Customization Buffer.
=========================

   The customization buffer allows the user to make temporary or
permanent changes to how specific aspects of emacs works, by setting
and editing user options.

   The customization buffer contains three types of text:

"informative text"
     where the normal editing commands are disabled.

"editable fields"
     where you can edit with the usual emacs commands.  Editable fields
     are usually displayed with a grey background if your terminal
     supports colors, or an italic font otherwise.

"buttons"
     which can be activated by either pressing the `ret' while point is
     located on the text, or pushing `mouse-2' while the mouse pointer
     is above the tex.  Buttons are usually displayed in a bold font.

   You can move to the next the next editable field or button by
pressing `tab' or the previous with `M-tab'.  Some buttons have a small
helpful message about their purpose, which will be displayed when you
move to it with the tab key.

   The buffer is divided into three part, an introductory text, a list
of customization options, and a line of customization buttons.  Each
part will be described in the following.

* Menu:

* The Introductory Text::
* The Customization Options::
* The Variable Options::
* The Face Options::
* The Group Options::
* The State Button::
* The Customization Buttons::


File: custom.info,  Node: The Introductory Text,  Next: The Customization Options,  Prev: The Customization Buffer,  Up: The Customization Buffer

The Introductory Text
---------------------

   The start of the buffer contains a short explanation of what it is,
and how to get help.  It will typically look like this:

     This is a customization buffer.
     Push RET or click mouse-2 on the word _help_ for more information.

   Rather boring.  It is mostly just informative text, but the word
`help' is a button that will bring up this document when activated.


File: custom.info,  Node: The Customization Options,  Next: The Variable Options,  Prev: The Introductory Text,  Up: The Customization Buffer

The Customization Options
-------------------------

   Each customization option looks similar to the following text:

      *** custom-background-mode: default
      State: this item is unchanged from its factory setting.
      [ ] [?] The brightness of the background.

   The option contains the parts described below.

`***'
     The Level Button.  The customization options in the buffer are
     organized in a hierarchy, which is indicated by the number of
     stars in the level button.  The top level options will be shown as
     `*'.  When they are expanded, the suboptions will be shown as
     `**'.  The example option is thus a subsuboption.

     Activating the level buttons will toggle between hiding and
     exposing the content of that option.  The content can either be
     the value of the option, as in this example, or a list of
     suboptions.

`custom-background-mode'
     This is the tag of the the option.  The tag is a name of a
     variable, a face, or customization group.  Activating the tag has
     an effect that depends on the exact type of the option.  In this
     particular case, activating the tag will bring up a menu that will
     allow you to choose from the three possible values of the
     `custom-background-mode' variable.

`default'
     After the tag, the options value is shown.  Depending on its type,
     you may be able to edit the value directly.  If an option should
     contain a file name, it is displayed in an editable field, i.e.
     you can edit it using the standard emacs editing commands.

`State: this item is unchanged from its factory setting.'
     The state line.  This line will explain the state of the option,
     e.g. whether it is currently hidden, or whether it has been
     modified or not.  Activating the button will allow you to change
     the state, e.g. set or reset the changes you have made.  This is
     explained in detail in the following sections.

`[ ]'
     The magic button.  This is an abbreviated version of the state
     line.

`[?]'
     The documentation button.  If the documentation is more than one
     line, this button will be present.  Activating the button will
     toggle whether the complete documentation is shown, or only the
     first line.

`The brightness of the background.'
     This is a documentation string explaining the purpose of this
     particular customization option.


File: custom.info,  Node: The Variable Options,  Next: The Face Options,  Prev: The Customization Options,  Up: The Customization Buffer

The Variable Options
--------------------

   The most common customization options are emacs lisp variables.  The
actual editing of these variables depend on what type values the
variable is expected to contain.  For example, a lisp variable whose
value should be a string will typically be represented with an editable
text field in the buffer, where you can change the string directly.  If
the value is a list, each item in the list will be presented in the
buffer buffer on a separate line, with buttons to insert new items in
the list, or delete existing items from the list.  You may want to see
*Note User Interface: (widget)User Interface, where some examples of
editing are discussed.

   You can either choose to edit the value directly, or edit the lisp
value for that variable.  The lisp value is a lisp expression that will
be evaluated when you start emacs.  The result of the evaluation will
be used as the initial value for that variable.  Editing the lisp value
is for experts only, but if the current value of the variable is of a
wrong type (i.e. a symbol where a string is expected), the `edit lisp'
mode will always be selected.

   You can see what mode is currently selected by looking at the state
button.  If it uses parenthesises (like `( )') it is in edit lisp mode,
with square brackets (like `[ ]') it is normal edit mode.  You can
switch mode by activating the state button, and select either `Edit' or
`Edit lisp' from the menu.

   You can change the state of the variable with the other menu items:

`Set'
     When you have made your modifications in the buffer, you need to
     activate this item to make the modifications take effect.  The
     modifications will be forgotten next time you run emacs.

`Save'
     Unless you activate this item instead!  This will mark the
     modification as permanent, i.e. the changes will be remembered in
     the next emacs session.

`Reset'
     If you have made some modifications and not yet applied them, you
     can undo the modification by activating this item.

`Reset to Saved'
     Activating this item will reset the value of the variable to the
     last value you marked as permanent with `Save'.

`Reset to Factory Settings'
     Activating this item will undo all modifications you have made, and
     reset the value to the initial value specified by the program
     itself.

   By default, the value of large or complicated variables are hidden.
You can show the value by clicking on the level button.


File: custom.info,  Node: The Face Options,  Next: The Group Options,  Prev: The Variable Options,  Up: The Customization Buffer

The Face Options
----------------

   A face is an object that controls the appearance of some buffer text.
The face has a number of possible attributes, such as boldness,
foreground color, and more.  For each attribute you can specify whether
this attribute is controlled by the face, and if so, what the value is.
For example, if the attribute bold is not controlled by a face, using
that face on some buffer text will not affect its boldness.  If the bold
attribute is controlled by the face, it can be turned either on or of.

   It is possible to specify that a face should have different
attributes on different device types.  For example, a face may make
text red on a color device, and bold on a monochrome device.

   The way this is presented in the customization buffer is to have a
list of display specifications, and for each display specification a
list of face attributes.  For each face attribute, there is a checkbox
specifying whether this attribute has effect and what the value is.
Here is an example:

      *** custom-invalid-face: (sample)
      [ ] Face used when the customize item is invalid.
      [INS] [DEL] Display: [ ] Type: [ ] X [ ] TTY
                           [X] Class: [X] Color [ ] Grayscale [ ] Monochrome
                           [ ] Background: [ ] Light [ ] Dark
                  Attributes: [ ] Bold: off
                              [ ] Italic: off
                              [ ] Underline: off
                              [X] Foreground: yellow (sample)
                              [X] Background: red (sample)
                              [ ] Stipple:
      [INS] [DEL] Display: all
                  Attributes: [X] Bold: on
                              [X] Italic: on
                              [X] Underline: on
                              [ ] Foreground: default (sample)
                              [ ] Background: default (sample)
                              [ ] Stipple:
      [INS]

   This has two display specifications.  The first will match all color
displays, independently on whether the device is X11 or a tty, and
whether background color is dark or light.  For devices matching this
specification, `custom-invalid-face' will force text to be displayed in
yellow on red, but leave all other attributes alone.

   The second display will simply match everything.  Since the list is
prioritised, this means that it will match all non-color displays.  For
these, the face will not affect the foreground or background color, but
force the font to be both bold, italic, and underline.

   You can add or delete display specifications by activating the
`[INS]' and `[DEL]' buttons, and modify them by clicking on the check
boxes.  The first checkbox in each line in the display specification is
special.  It specify whether this particular property will even be
relevant.  By not checking the box in the first display, we match all
device types, also device types other than X11 and tty, for example
ms-windows, nextstep, and mac os.

   After modifying the face, you can activate the state button to make
the changes take effect.  The menu items in the state button menu is
similar to the state menu items for variables described in the previous
section.


File: custom.info,  Node: The Group Options,  Next: The State Button,  Prev: The Face Options,  Up: The Customization Buffer

The Group Options
-----------------

   Since Emacs has approximately a zillion configuration options, they
have been organized in groups.  Each group can contain other groups,
thus creating a customization hierarchy.  The nesting of the
customization within the visible part of this hierarchy is indicated by
the number of stars in the level button.

   Since there is really no customization needed for the group itself,
the menu items in the groups state button will affect all modified group
members recursively.  Thus, if you activate the `Set' menu item, all
variables and faces that have been modified and belong to that group
will be applied.  For those members that themselves are groups, it will
work as if you had activated the `Set' menu item on them as well.


File: custom.info,  Node: The State Button,  Next: The Customization Buttons,  Prev: The Group Options,  Up: The Customization Buffer

The State Line and The Magic Button
-----------------------------------

   The state line has two purposes.  The first is to hold the state
menu, as described in the previous sections.  The second is to indicate
the state of each customization item.

   For the magic button, this is done by the character inside the
brackets.  The following states have been defined, the first that
applies to the current item will be used:

`-'
     The option is currently hidden.  For group options that means the
     members are not shown, for variables and faces that the value is
     not shown.  You cannot perform any of the state change operations
     on a hidden customization option.

`*'
     The value if this option has been modified in the buffer, but not
     yet applied.

`+'
     The item has has been set by the user.

`:'
     The current value of this option is different from the saved value.

`!'
     The saved value of this option is different from the factory
     setting.

`@'
     The factory setting of this option is not known.  This occurs when
     you try to customize variables or faces that have not been
     explicitly declared as customizable.

`SPC'
     The factory setting is still in effect.

   For non-hidden group options, the state shown is the most severe
state of its members, where more severe means that it appears earlier
in the list above (except hidden members, which are ignored).


File: custom.info,  Node: The Customization Buttons,  Prev: The State Button,  Up: The Customization Buffer

The Customization Buttons
-------------------------

   The last part of the customization buffer looks like this:

     [Set] [Save] [Reset] [Done]

   Activating the `[Set]', `[Save]', or `[Reset]' button will affect
all modified customization items that are visible in the buffer.
`[Done]' will bury the buffer.


File: custom.info,  Node: Declarations,  Next: Utilities,  Prev: The Customization Buffer,  Up: Top

Declarations
============

* Menu:

* Declaring Groups::
* Declaring Variables::
* Declaring Faces::
* Usage for Package Authors::

   All the customization declarations can be changes by keyword
arguments.  Groups, variables, and faces all share these common
keywords:

`:group'
     VALUE should be a customization group.  Add SYMBOL to that group.

`:link'
     VALUE should be a widget type.  Add VALUE to the extrenal links
     for this customization option.  Useful widget types include
     `custom-manual', `info-link', and `url-link'.

`:load'
     Add VALUE to the files that should be loaded nefore displaying
     this customization option.  The value should be iether a string,
     which should be a string which will be loaded with `load-library'
     unless present in `load-history', or a symbol which will be loaded
     with `require'.

`:tag'
     VALUE should be a short string used for identifying the option in
     customization menus and buffers.  By default the tag will be
     automatically created from the options name.


File: custom.info,  Node: Declaring Groups,  Next: Declaring Variables,  Prev: Declarations,  Up: Declarations

Declaring Groups
----------------

   Use `defgroup' to declare new customization groups.

 - Function: defgroup SYMBOL MEMBERS DOC [KEYWORD VALUE]...
     Declare SYMBOL as a customization group containing MEMBERS.
     SYMBOL does not need to be quoted.

     DOC is the group documentation.

     MEMBERS should be an alist of the form ((NAME WIDGET)...) where
     NAME is a symbol and WIDGET is a widget for editing that symbol.
     Useful widgets are `custom-variable' for editing variables,
     `custom-face' for editing faces, and `custom-group' for editing
     groups.

     Internally, custom uses the symbol property `custom-group' to keep
     track of the group members, and `group-documentation' for the
     documentation string.

     The following additional KEYWORD's are defined:

    `:prefix'
          VALUE should be a string.  If the string is a prefix for the
          name of a member of the group, that prefix will be ignored
          when creating a tag for that member.


File: custom.info,  Node: Declaring Variables,  Next: Declaring Faces,  Prev: Declaring Groups,  Up: Declarations

Declaring Variables
-------------------

   Use `defcustom' to declare user editable variables.

 - Function: defcustom SYMBOL VALUE DOC [KEYWORD VALUE]...
     Declare SYMBOL as a customizable variable that defaults to VALUE.
     Neither SYMBOL nor VALUE needs to be quoted.  If SYMBOL is not
     already bound, initialize it to VALUE.

     DOC is the variable documentation.

     The following additional KEYWORD's are defined:

    `:type'
          VALUE should be a widget type.

    `:options'
          VALUE should be a list of possible members of the specified
          type.  For hooks, this is a list of function names.

     *Note Sexp Types: (widget)Sexp Types, for information about
     widgets to use together with the `:type' keyword.

   Internally, custom uses the symbol property `custom-type' to keep
track of the variables type, `factory-value' for the program specified
default value, `saved-value' for a value saved by the user, and
`variable-documentation' for the documentation string.

   Use `custom-add-option' to specify that a specific function is
useful as an meber of a hook.

 - Function: custom-add-option SYMBOL OPTION
     To the variable SYMBOL add OPTION.

     If SYMBOL is a hook variable, OPTION should be a hook member.  For
     other types variables, the effect is undefined."


File: custom.info,  Node: Declaring Faces,  Next: Usage for Package Authors,  Prev: Declaring Variables,  Up: Declarations

Declaring Faces
---------------

   Faces are declared with `defface'.

 - Function: defface FACE SPEC DOC [KEYWORD VALUE]...
     Declare FACE as a customizable face that defaults to SPEC.  FACE
     does not need to be quoted.

     If FACE has been set with `custom-set-face', set the face
     attributes as specified by that function, otherwise set the face
     attributes according to SPEC.

     DOC is the face documentation.

     SPEC should be an alist of the form `((DISPLAY ATTS)...)'.

     ATTS is a list of face attributes and their values.  The possible
     attributes are defined in the variable `custom-face-attributes'.
     Alternatively, ATTS can be a face in which case the attributes of
     that face is used.

     The ATTS of the first entry in SPEC where the DISPLAY matches the
     frame should take effect in that frame.  DISPLAY can either be the
     symbol `t', which will match all frames, or an alist of the form
     `((REQ ITEM...)...)'

     For the DISPLAY to match a FRAME, the REQ property of the frame
     must match one of the ITEM.  The following REQ are defined:

    `type'
          (the value of (window-system))
          Should be one of `x' or `tty'.

    `class'
          (the frame's color support)
          Should be one of `color', `grayscale', or `mono'.

    `background'
          (what color is used for the background text)
          Should be one of `light' or `dark'.

     Internally, custom uses the symbol property `factory-face' for the
     program specified default face properties, `saved-face' for
     properties saved by the user, and `face-doc-string' for the
     documentation string.



File: custom.info,  Node: Usage for Package Authors,  Prev: Declaring Faces,  Up: Declarations

Usage for Package Authors
-------------------------

   The recommended usage for the author of a typical emacs lisp package
is to create one group identifying the package, and make all user
options and faces members of that group.  If the package has more than
around 20 such options, they should be divided into a number of
subgroups, with each subgroup being member of the top level group.

   The top level group for the package should itself be member of one or
more of the standard customization groups.  There exists a group for
each *finder* keyword.  Press `C-c p' to see a list of finder keywords,
and add you group to each of them, using the `:group' keyword.


File: custom.info,  Node: Utilities,  Next: The Init File,  Prev: Declarations,  Up: Top

Utilities
=========

   These utilities can come in handy when adding customization support.

 - Widget: custom-manual
     Widget type for specifying the info manual entry for a
     customization option.  It takes one argument, an info address.

 - Function: custom-add-to-group GROUP MEMBER WIDGET
     To existing GROUP add a new MEMBER of type WIDGET, If there
     already is an entry for that member, overwrite it.

 - Function: custom-add-link SYMBOL WIDGET
     To the custom option SYMBOL add the link WIDGET.

 - Function: custom-add-load SYMBOL LOAD
     To the custom option SYMBOL add the dependency LOAD.  LOAD should
     be either a library file name, or a feature name.

 - Function: custom-menu-create SYMBOL &optional NAME
     Create menu for customization group SYMBOL.  If optional NAME is
     given, use that as the name of the menu.  Otherwise make up a name
     from SYMBOL.  The menu is in a format applicable to
     `easy-menu-define'.


File: custom.info,  Node: The Init File,  Next: Wishlist,  Prev: Utilities,  Up: Top

The Init File
=============

   When you save the customizations, call to `custom-set-variables',
`custom-set-faces' are inserted into the file specified by
`custom-file'.  By default `custom-file' is your `.emacs' file.  If you
use another file, you must explicitly load it yourself.  The two
functions will initialize variables and faces as you have specified.


File: custom.info,  Node: Wishlist,  Prev: The Init File,  Up: Top

Wishlist
========

   * The menu items should be grayed out when the information is
     missing.  I.e. if a variable doesn't have a factory setting, the
     user should not be allowed to select the `Factory' menu item.

   * We need *much* better support for keyboard operations in the
     customize buffer.

   * Integrate with `w3' so you can customization buffers with much
     better formatting.  I'm thinking about adding a
     <custom>name</custom> tag.  The latest w3 have some support for
     this, so come up with a convincing example.

   * Add an `examples' section, with explained examples of custom type
     definitions.

   * Support selectable color themes.  I.e., change many faces by
     setting one variable.

   * There should be a way to see only the "current" display when
     editing a face, and that should be "on" by default.

   * Support undo using lmi's `gnus-undo.el'.

   * Make it possible to append to `choice', `radio', and `set' options.

   * Ask whether set or modified variables should be saved in
     `kill-buffer-hook'.

     Ditto for `kill-emacs-query-functions'.

   * Command to check if there are any customization options that does
     not belong to an existing group.

   * Optionally disable the point-cursor and instead highlight the
     selected item in XEmacs.  This is like the *Completions* buffer in
     XEmacs.  Suggested by Jens Lautenbacher
     `<jens@lemming0.lem.uni-karlsruhe.de>'.



Tag Table:
Node: Top99
Node: Introduction386
Node: User Commands1616
Node: The Customization Buffer2246
Node: The Introductory Text3736
Node: The Customization Options4305
Node: The Variable Options6862
Node: The Face Options9501
Node: The Group Options12870
Node: The State Button13771
Node: The Customization Buttons15333
Node: Declarations15760
Node: Declaring Groups16915
Node: Declaring Variables18034
Node: Declaring Faces19479
Node: Usage for Package Authors21273
Node: Utilities22043
Node: The Init File23103
Node: Wishlist23555

End Tag Table
