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

Version: 0.9

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.

default value
     The value specified 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.

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 contaning a single face.

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

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

Here should be a description of how to use a customization buffer. For now, try to press C-h m in the buffer, or read widget (The Widget Library).

The interface will change, as it currently stinks.  Here is some hints about how to use it though:

  * Groups and user option start on a new line, and look like this name:.  If you move point above to the name and press RET, or move the mouse pointer above it and press mouse-2, you will be presented with a menu.  I call this the tag menu below.

  * For groups and faces, you need to activate Toggle Hide from the tag menu to be able to see the content.

  * After editing a variable or face, you must activate Apply for the setting to take effect, and Set Default for marking the widget value as the new default value.

  * After setting new default values with Set Default, you must activate the Save button in the bottom of the screen to save the new defaults.  Otherwise the new defaults will be silently forgotten.

  * Pushing Save is a no-op unless you have activated Set Default for some user option.

  * The face widget never attempts to display the current value of a face.  Instead it allows you to specify how the face should be initialized.  This is done with a list of display and attributes pairs, where the first display that matches a frame specify the attributes to use for that frame.

     A display can either match all frames, or only frames with a given type, class, and background.  The checkbox before each of these display parameters determine whether the parameter will be checked.  If the checkbox before Type is unchecked, the display will match all types of frames.  If it is checked, it will match the type of frames specified on the rest of the line.

     The attributes are specified next.  Each attribute line begins with a checkbox, if that checkbox is unchecked the face will not affect that particular attribute on the screen, otherwise the face will force the the text to have the value for attribute specified after the attrbute name.  This means that an attribute like bold in effect have three states: If the first checkmark is unchecked, the face will not affect the boldness of the text.  If the first checkmark is checked, but the second is unchecked, the text will be forced to be unbold.  If both checkmarks are checked, the text will be forced to be bold.

     Think about this, and mail me a suggestion for how to make the face widget more intuitive.

Declaring Groups
================

Use defgroup to declare new customization groups.

 -- Function: defgroup symbol members [keyword value]... doc
     Declare SYMBOL as a customization group containing MEMBERS. SYMBOL does not need to be quoted.

     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.

     DOC is the group documentation.

     The following KEYWORD's are defined:

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

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

Declaring Variables
===================

Use defcustom to declare user editable variables.

 -- Function: defcustom symbol [keyword value]... doc
     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 KEYWORD's are defined:

     :type
          VALUE should be a sexp widget.

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

     See widget (The Widget Library), 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, default-value for a user specified default value, and variable-documentation for the documentation string.

Declaring Faces
===============

Faces are declared with defface.

 -- Function: defface FACE SPEC [KEYWORD VALUE]... DOC

     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.

     The following KEYWORD's are defined:

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

     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, default-face for a user specified default properties, and face-documentation for the documentation string.

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.  The two functions will initialize variables and faces as you have specified.

Wishlist
========

  * The names of the menu items for the custom-variable, custom-face, and custom-group tags should be rethought. Some of the actions may be better placed as buttons in the buffer.

  * The menu items above 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.

  * There should be buttons that will apply, set, reset, etc. all the relevant widgets in a customize buffer.

  * There should be a menu in the customize buffer.

  * The group widget should allow you to apply, set, reset, etc. all the relevant members of the group.

  * There should be a function to create a customize menu from a group.

  * There should be a `Help | Customize' entry in the menu bar with a user specified number of levels of submenus.

  * It would be nice if one could set simple variables directly from the menu.

  * Support real specifiers under XEmacs.

  * customize-apropos should only match user options that has either been declared with this library, or variables whose documentation start with *.  With an prefix argument, also match all variables that has a documentation string.

  * If there is only one line of documentation, the Documentation tag-menu items should go from `first line only' to `none' without going over `full'.  I.e. it should have two states instead of three.

  * custom-face should display the face-documentation property.

  * custom-face, custom-variable, and custom-group should be derived from a common custom widget.

  * Integrate with w3 so you can customization buffers with much better formatting.  I'm thinking about adding a <custom>name</custom> tag.