--- a/man/custom.texi	Mon Aug 13 09:38:27 2007 +0200
+++ b/man/custom.texi	Mon Aug 13 09:39:39 2007 +0200
@@ -9,442 +9,11 @@
 @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
-
-@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,
+This manual 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.
 
@@ -453,6 +22,9 @@
 * 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.
@@ -479,9 +51,9 @@
 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. 
 
@@ -511,9 +83,9 @@
 @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.
 
@@ -527,7 +99,7 @@
 The following additional @var{keyword}'s are defined:
 
 @table @code
-@item :type	
+@item :type     
 @var{value} should be a widget type.
 
 @item :options
@@ -594,9 +166,9 @@
 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}.
 
@@ -646,9 +218,9 @@
 
 @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
@@ -662,7 +234,7 @@
 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
 
@@ -694,7 +266,7 @@
 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
 
@@ -705,7 +277,7 @@
 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
 
@@ -714,7 +286,7 @@
 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.
@@ -750,7 +322,8 @@
 @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
@@ -793,14 +366,25 @@
 Detect when faces have been changed outside customize.
 
 @item
-Activate mouse help in Emacs by default.
-
-@item
-Group members should be sorted, groups last.
+Enable mouse help in Emacs by default.
 
 @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