xemacs-beta: man/custom.texi comparison

comparison man/custom.texi @ 155:43dd3413c7c7 r20-3b4

Import from CVS: tag r20-3b4

author	cvs
date	Mon, 13 Aug 2007 09:39:39 +0200
parents	25f70ba0133c
children	28f395d8dc7a

comparison

equal deleted inserted replaced

-:94141801dd7e
+:43dd3413c7c7
 @afourpaper
 @headings double
 @end iftex
 @c %**end of header
-@node Top, Introduction, (dir), (dir)
+@node Top, Declaring Groups, (dir), (dir)
 @comment  node-name,  next,  previous,  up
 @top The Customization Library
-Version: 1.98
+This manual describes how to declare customization groups, variables,
-@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 standard 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 standard 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 the @code{emacs} group.
-@item customize-group
-Create a customization buffer containing a specific 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.
-@item customize-saved
-Create a customization buffer containing all variables and faces that
-have been saved with customize.
-@item customize-customized
-Create a customization buffer containing all variables and faces that
-have been customized but not saved.
-@end table
-You can also set variables without creating a customization buffer.
-@deffn Command customize-set-variable var val
-Set the default for @var{variable} to @var{value}.
-@var{value} is a Lisp object.
-If @var{variable} has a @code{custom-set} property, that is used for setting
-@var{variable}, otherwise @code{set-default} is used.
-The @code{customized-value} property of the @var{variable} will be set
-to a list with a quoted @var{value} as its sole list member.
-If @var{variable} has a @code{variable-interactive} property, that is
-used as if it were the arg to `interactive' (which see) to interactively
-read the value.
-If @var{variable} has a @code{custom-type} property, it must be a widget
-and the @code{:prompt-value} property of that widget will be used for
-reading the value.
-@end deffn
-All variables that have been set either from a customization buffer or
-with @code{customize-set-variable} can be saved with the command
-@code{custom-save-customized}.
-@deffn Command custom-save-customized
-Save all variables that have been set with customize in this session.
-@end deffn
-@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 Buttons::
-* The Customization Options::
-* The Variable Options::
-* The Face Options::
-* The Group Options::
-* The State Button::
-@end menu
-@node  The Introductory Text, The Customization Buttons, 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 Buttons, The Customization Options, The Introductory Text, The Customization Buffer
-@comment  node-name,  next,  previous,  up
-@subsection The Customization Buttons
-The next part of the customization buffer looks like this:
-@example
-[Set] [Save] [Reset] [Done]
-@end example
-Activating the @samp{[Set]}, @samp{[Save]}, or @samp{[Reset]}
-button will affect all modified customization items that are visible in
-the buffer.  @samp{[Done]} will bury the buffer.
-@node  The Customization Options, The Variable Options, The Customization Buttons, 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 standard setting.
-[?] The brightness of the background.
-@end example
-The option contains the parts described below.
-@table @samp
-@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 standard 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 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 (e.g. 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
-description.  It will end with @samp{(lisp)} in lisp 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 Standard 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 change this with the @samp{Hide} and @samp{Show} entries in the
-state menu.
-@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.  You do this by
-activating `Edit All' in the state menu.
-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)
-State: this item is unchanged from its standard setting.
-Face used when the customize item is invalid.
-[INS] [DEL] Display: [ ] Type: [ ] X [ ] PM [ ] Win32 [ ] DOS [ ] 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 what window system the device belongs to, 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 those listed.
-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.
-Faces usually start out hidden, activate the @samp{State} button to show
-them.
-@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
-asterisks before the name of the group.
-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 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.
-There is an optional `magic button' that holds the same information in a
-more compact form.  The magic button contain a character inside the
-brackets (in edit mode) or parentheses (in lisp mode).
-@defopt custom-magic-show-button
-Show a magic button indicating the state of each customization option.
-@end defopt
-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 standard setting.
-@item @@
-The standard 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 standard 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   Declarations, Utilities, The Customization Buffer, Top
-@comment  node-name,  next,  previous,  up
-@section Declarations
-This section describes how to declare customization groups, variables,
 and faces.  It doesn't contain any examples, but please look at the file
 @file{cus-edit.el} which contains many declarations you can learn from.
 @menu
 * Declaring Groups::
 * Declaring Variables::
 * Declaring Faces::
 * Usage for Package Authors::
+* Utilities::
+* The Init File::
+* Wishlist::
 @end menu
 All the customization declarations can be changes by keyword arguments.
 Groups, variables, and faces all share these common keywords:
 @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
+@node Declaring Groups, Declaring Variables, Top, Top
 @comment  node-name,  next,  previous,  up
-@subsection Declaring Groups
+@section 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}.
 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
+@node Declaring Variables, Declaring Faces, Declaring Groups, Top
 @comment  node-name,  next,  previous,  up
-@subsection Declaring Variables
+@section 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}.
 @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.
 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, Usage for Package Authors, Declaring Variables, Declarations
+@node Declaring Faces, Usage for Package Authors, Declaring Variables, Top
 @comment  node-name,  next,  previous,  up
-@subsection Declaring Faces
+@section Declaring Faces
 Faces are declared with @code{defface}.
 @defun defface face spec doc [keyword value]...
 properties saved by the user, and @code{face-documentation} for the
 documentation string.@refill
 @end defun
-@node Usage for Package Authors,  , Declaring Faces, Declarations
+@node Usage for Package Authors, Utilities, Declaring Faces, Top
 @comment  node-name,  next,  previous,  up
-@subsection Usage for Package Authors
+@section 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
 more of the standard customization groups.  There exists a group for
 each @emph{finder} keyword.  Press @kbd{C-c p} to see a list of finder
 keywords, and add you group to each of them, using the @code{:group}
 keyword.
-@node  Utilities, The Init File, Declarations, Top
+@node  Utilities, The Init File, Usage for Package Authors, Top
 @comment  node-name,  next,  previous,  up
 @section Utilities
 These utilities can come in handy when adding customization support.
 If optional @var{name} is given, use that as the name of the menu.
 Otherwise the menu will be named `Customize'.
 The menu is in a format applicable to @code{easy-menu-define}.
 @end defun
-@node  The Init File, Wishlist, Utilities, Top
+@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.  If you use another file, you must explicitly load it yourself.
 The two functions will initialize variables and faces as you have
 specified.
-@node  Wishlist,  , The Init File, Top
+@node Wishlist,  , The Init File, Top
 @comment  node-name,  next,  previous,  up
 @section Wishlist
 @itemize @bullet
 @item
 Better support for keyboard operations in the customize buffer.
 @item
-Integrate with @file{w3} so you can customization buffers with much
+Integrate with @file{w3} so you can get 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.
 @item
 item in XEmacs.  This is like the *Completions* buffer in XEmacs.
 Suggested by Jens Lautenbacher
 @samp{<jens@@lemming0.lem.uni-karlsruhe.de>}.@refill
 @item
-Empty customization groups should start open (harder than it looks).
+Explain why it is necessary that all choices have differnet default
+values.
 @item
 Make it possible to include a comment/remark/annotation when saving an
 option.
 @item
 Detect when faces have been changed outside customize.
 @item
-Activate mouse help in Emacs by default.
+Enable mouse help in Emacs by default.
-@item
-Group members should be sorted, groups last.
 @item
 Add an easy way to display the standard settings when an item is modified.
+@item
+Option or command to create new buffer instead of expanding a group
+inline.
+@item
+See if it is feasible to scan files for customization information
+instead of loading them,
+@item
+Add hint message when user push a non-pushable tag.
+Suggest that the user unhide if hidden, and edit the value directly
+otherwise.
 @end itemize
 @contents
 @bye

Mercurial > hg > xemacs-beta

comparison man/custom.texi @ 155:43dd3413c7c7 r20-3b4