xemacs-beta: man/custom.texi comparison

comparison man/custom.texi @ 16:0293115a14e9 r19-15b91

Import from CVS: tag r19-15b91

author	cvs
date	Mon, 13 Aug 2007 08:49:20 +0200
parents
children	859a2309aef8

comparison

equal deleted inserted replaced

-:ad457d5f7d04
+:0293115a14e9
+\input texinfo.tex
+@c %**start of header
+@setfilename custom
+@settitle The Customization Library
+@iftex
+@afourpaper
+@headings double
+@end iftex
+@c %**end of header
+@node Top, Introduction, (dir), (dir)
+@comment  node-name,  next,  previous,  up
+@top The Customization Library
+Version: 1.20
+@menu
+* Introduction::
+* User Commands::
+* The Customization Buffer::
+* Declarations::
+* Utilities::
+* The Init File::
+* Wishlist::
+@end menu
+@node   Introduction, User Commands, Top, Top
+@comment  node-name,  next,  previous,  up
+@section Introduction
+This library allows customization of @dfn{user options}.  Currently two
+types of user options are supported, namely @dfn{variables} and
+@dfn{faces}.  Each user option can have four different values
+simultaneously:
+@table @dfn
+@item factory setting
+The value specified by the programmer.
+@item saved value
+The value saved by the user as the default for this variable.  This
+overwrites the factory setting when starting a new emacs.
+@item current value
+The value used by Emacs.  This will not be remembered next time you
+run Emacs.
+@item widget value
+The value entered by the user in a customization buffer, but not yet
+applied.
+@end table
+Variables also have a @dfn{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 @dfn{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.
+@node  User Commands, The Customization Buffer, Introduction, Top
+@comment  node-name,  next,  previous,  up
+@section User Commands
+The following commands will create a customization buffer:
+@table @code
+@item customize
+Create a customization buffer containing a specific group, by default
+the @code{emacs} group.
+@item customize-variable
+Create a customization buffer containing a single variable.
+@item customize-face
+Create a customization buffer containing a single face.
+@item customize-apropos
+Create a customization buffer containing all variables, faces, and
+groups that match a user specified regular expression.
+@end table
+@node The Customization Buffer, Declarations, User Commands, Top
+@comment  node-name,  next,  previous,  up
+@section 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:
+@table @dfn
+@item informative text
+where the normal editing commands are disabled.
+@item 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.
+@item buttons
+which can be activated by either pressing the @kbd{@key{ret}} while
+point is located on the text, or pushing @kbd{mouse-2} while the mouse
+pointer is above the tex.  Buttons are usually displayed in a bold
+font.
+@end table
+You can move to the next the next editable field or button by pressing
+@kbd{@key{tab}} or the previous with @kbd{M-@key{tab}}.  Some buttons
+have a small helpful message about their purpose, which will be
+displayed when you move to it with the @key{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::
+@end menu
+@node  The Introductory Text, The Customization Options, The Customization Buffer, The Customization Buffer
+@comment  node-name,  next,  previous,  up
+@subsection  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:
+@example
+This is a customization buffer.
+Push RET or click mouse-2 on the word _help_ for more information.
+@end example
+Rather boring.  It is mostly just informative text, but the word
+@samp{help} is a button that will bring up this document when
+activated.
+@node  The Customization Options, The Variable Options, The Introductory Text, The Customization Buffer
+@comment  node-name,  next,  previous,  up
+@subsection The Customization Options
+Each customization option looks similar to the following text:
+@example
+*** custom-background-mode: default
+State: this item is unchanged from its factory setting.
+[ ] [?] The brightness of the background.
+@end example
+The option contains the parts described below.
+@table @samp
+@item ***
+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 @samp{*}.  When they are
+expanded, the suboptions will be shown as @samp{**}.  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.
+@item 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.
+@item 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.
+@item 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.
+@item [ ]
+The magic button.  This is an abbreviated version of the state line.
+@item [?]
+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.
+@item The brightness of the background.
+This is a documentation string explaining the purpose of this particular
+customization option.
+@end table
+@node  The Variable Options, The Face Options, The Customization Options, The Customization Buffer
+@comment  node-name,  next,  previous,  up
+@subsection 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
+@ref{User Interface,,, widget, The Widget Library}, 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 @samp{( )}) it is in edit lisp
+mode, with square brackets (like @samp{[ ]}) it is normal edit mode.
+You can switch mode by activating the state button, and select either
+@samp{Edit} or @samp{Edit lisp} from the menu.
+You can change the state of the variable with the other menu items:
+@table @samp
+@item 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.
+@item 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.
+@item Reset
+If you have made some modifications and not yet applied them, you can
+undo the modification by activating this item.
+@item Reset to Saved
+Activating this item will reset the value of the variable to the last
+value you marked as permanent with `Save'.
+@item 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.
+@end table
+By default, the value of large or complicated variables are hidden.   You
+can show the value by clicking on the level button.
+@node  The Face Options, The Group Options, The Variable Options, The Customization Buffer
+@comment  node-name,  next,  previous,  up
+@subsection 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:
+@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]
+@end example
+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, @samp{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
+@samp{[INS]} and @samp{[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.
+@node  The Group Options, The State Button, The Face Options, The Customization Buffer
+@comment  node-name,  next,  previous,  up
+@subsection 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 @samp{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 @samp{Set} menu item on them as well.
+@node  The State Button, The Customization Buttons, The Group Options, The Customization Buffer
+@comment  node-name,  next,  previous,  up
+@subsection 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:
+@table @samp
+@item -
+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.
+@item *
+The value if this option has been modified in the buffer, but not yet
+applied.
+@item +
+The item has has been set by the user.
+@item :
+The current value of this option is different from the saved value.
+@item !
+The saved value of this option is different from the factory setting.
+@item @@
+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.
+@item SPC
+The factory setting is still in effect.
+@end table
+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).
+@node  The Customization Buttons,  , The State Button, The Customization Buffer
+@comment  node-name,  next,  previous,  up
+@subsection The Customization Buttons
+The last part of the customization buffer looks like this:
+@example
+[Set] [Save] [Reset]
+@end example
+Activating the @samp{[Set]}, @samp{[Save]}, or @samp{[Reset]}
+button will affect all modified customization items that are visible in
+the buffer.
+@node   Declarations, Utilities, The Customization Buffer, Top
+@comment  node-name,  next,  previous,  up
+@section Declarations
+@menu
+* Declaring Groups::
+* Declaring Variables::
+* Declaring Faces::
+@end menu
+All the customization declarations can be changes by keyword arguments.
+Groups, variables, and faces all share these common keywords:
+@table @code
+@item :group
+@var{value} should be a customization group.
+Add @var{symbol} to that group.
+@item :link
+@var{value} should be a widget type.
+Add @var{value} to the extrenal links for this customization option.
+Useful widget types include @code{custom-manual}, @code{info-link}, and
+@code{url-link}.
+@item :load
+Add @var{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 @code{load-library} unless
+present in @code{load-history}, or a symbol which will be loaded with
+@code{require}.
+@item :tag
+@var{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.
+@end table
+@node  Declaring Groups, Declaring Variables, Declarations, Declarations
+@comment  node-name,  next,  previous,  up
+@subsection Declaring Groups
+Use @code{defgroup} to declare new customization groups.
+@defun defgroup symbol members doc [keyword value]...
+Declare @var{symbol} as a customization group containing @var{members}.
+@var{symbol} does not need to be quoted.
+@var{doc} is the group documentation.
+@var{members} should be an alist of the form ((@var{name}
+@var{widget})...) where @var{name} is a symbol and @var{widget} is a
+widget for editing that symbol.  Useful widgets are
+@code{custom-variable} for editing variables, @code{custom-face} for
+editing faces, and @code{custom-group} for editing groups.@refill
+Internally, custom uses the symbol property @code{custom-group} to keep
+track of the group members, and @code{group-documentation} for the
+documentation string.
+The following additional @var{keyword}'s are defined:
+@table @code
+@item :prefix
+@var{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.
+@end table
+@end defun
+@node  Declaring Variables, Declaring Faces, Declaring Groups, Declarations
+@comment  node-name,  next,  previous,  up
+@subsection Declaring Variables
+Use @code{defcustom} to declare user editable variables.
+@defun defcustom symbol value doc [keyword value]...
+Declare @var{symbol} as a customizable variable that defaults to @var{value}.
+Neither @var{symbol} nor @var{value} needs to be quoted.
+If @var{symbol} is not already bound, initialize it to @var{value}.
+@var{doc} is the variable documentation.
+The following additional @var{keyword}'s are defined:
+@table @code
+@item :type
+@var{value} should be a widget type.
+@item :options
+@var{value} should be a list of possible members of the specified type.
+For hooks, this is a list of function names.
+@end table
+@xref{Sexp Types,,,widget,The Widget Library}, for information about
+widgets to use together with the @code{:type} keyword.
+@end defun
+Internally, custom uses the symbol property @code{custom-type} to keep
+track of the variables type, @code{factory-value} for the program
+specified default value, @code{saved-value} for a value saved by the
+user, and @code{variable-documentation} for the documentation string.
+Use @code{custom-add-option} to specify that a specific function is
+useful as an meber of a hook.
+@defun custom-add-option symbol option
+To the variable @var{symbol} add @var{option}.
+If @var{symbol} is a hook variable, @var{option} should be a hook
+member.  For other types variables, the effect is undefined."
+@end defun
+@node  Declaring Faces,  , Declaring Variables, Declarations
+@comment  node-name,  next,  previous,  up
+@subsection Declaring Faces
+Faces are declared with @code{defface}.
+@defun defface face spec doc [keyword value]...
+Declare @var{face} as a customizable face that defaults to @var{spec}.
+@var{face} does not need to be quoted.
+If @var{face} has been set with `custom-set-face', set the face attributes
+as specified by that function, otherwise set the face attributes
+according to @var{spec}.
+@var{doc} is the face documentation.
+@var{spec} should be an alist of the form @samp{((@var{display} @var{atts})...)}.
+@var{atts} is a list of face attributes and their values.  The possible
+attributes are defined in the variable `custom-face-attributes'.
+Alternatively, @var{atts} can be a face in which case the attributes of
+that face is used.
+The @var{atts} of the first entry in @var{spec} where the @var{display}
+matches the frame should take effect in that frame.  @var{display} can
+either be the symbol `t', which will match all frames, or an alist of
+the form @samp{((@var{req} @var{item}...)...)}@refill
+For the @var{display} to match a FRAME, the @var{req} property of the
+frame must match one of the @var{item}.  The following @var{req} are
+defined:@refill
+@table @code
+@item type
+(the value of (window-system))@br
+Should be one of @code{x} or @code{tty}.
+@item class
+(the frame's color support)@br
+Should be one of @code{color}, @code{grayscale}, or @code{mono}.
+@item background
+(what color is used for the background text)@br
+Should be one of @code{light} or @code{dark}.
+@end table
+Internally, custom uses the symbol property @code{factory-face} for the
+program specified default face properties, @code{saved-face} for
+properties saved by the user, and @code{face-documentation} for the
+documentation string.@refill
+@end defun
+@node  Utilities, The Init File, Declarations, Top
+@comment  node-name,  next,  previous,  up
+@section Utilities
+These utilities can come in handy when adding customization support.
+@deffn Widget custom-manual
+Widget type for specifying the info manual entry for a customization
+option.  It takes one argument, an info address.
+@end deffn
+@defun custom-add-to-group group member widget
+To existing @var{group} add a new @var{member} of type @var{widget},
+If there already is an entry for that member, overwrite it.
+@end defun
+@defun custom-add-link symbol widget
+To the custom option @var{symbol} add the link @var{widget}.
+@end defun
+@defun custom-add-load symbol load
+To the custom option @var{symbol} add the dependency @var{load}.
+@var{load} should be either a library file name, or a feature name.
+@end defun
+@defun custom-menu-create symbol &optional name
+Create menu for customization group @var{symbol}.
+If optional @var{name} is given, use that as the name of the menu.
+Otherwise make up a name from @var{symbol}.
+The menu is in a format applicable to @code{easy-menu-define}.
+@end defun
+@node  The Init File, Wishlist, Utilities, Top
+@comment  node-name,  next,  previous,  up
+@section The Init File
+When you save the customizations, call to @code{custom-set-variables},
+@code{custom-set-faces} are inserted into the file specified by
+@code{custom-file}.  By default @code{custom-file} is your @file{.emacs}
+file.  The two functions will initialize variables and faces as you have
+specified.
+@node  Wishlist,  , The Init File, Top
+@comment  node-name,  next,  previous,  up
+@section Wishlist
+@itemize @bullet
+@item
+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 @samp{Factory} menu item.
+@item
+We need @strong{much} better support for keyboard operations in the
+customize buffer.
+@item
+Support real specifiers under XEmacs.
+@item
+Integrate with @file{w3} so you can customization buffers with much
+better formatting.  I'm thinking about adding a <custom>name</custom>
+tag.
+@item
+Add an `examples' section, with explained examples of custom type
+definitions.
+@item
+Support undo using lmi's @file{gnus-undo.el}.
+@item
+Make it possible to append to `choice', `radio', and `set' options.
+@end itemize
+@contents
+@bye

Mercurial > hg > xemacs-beta

comparison man/custom.texi @ 16:0293115a14e9 r19-15b91