man/custom.texi

[Luc Teirlinck]

Here is my patch to man/custom.texi making customize-browse more
prominent (by giving it a separate node) and adding some other remarks
about finding options.  (We discussed this before.)  I can install if
desired.

===File ~/man-custom.texi-diff==============================
*** custom.texi 12 Dec 2005 20:53:17 -0600      1.96
--- custom.texi 16 Dec 2005 20:06:24 -0600      
***************
*** 206,211 ****
--- 206,212 ----
  
  @menu
  * Groups: Customization Groups.   How options are classified in a structure.
+ * Browsing: Browsing Custom.   Browsing and searching for options and faces.
  * Changing a Variable::      How to edit a value and set an option.
  * Saving Customizations::    Specifying the file for saving customizations.
  * Face Customization::       How to edit the attributes of a face.
***************
*** 275,283 ****
  pertaining to that feature.  You can also go straight to a particular
  group by name, using the command @kbd{M-x customize-group}.
  
  @findex customize-browse
!   You can view the structure of customization groups on a larger scale
! with @kbd{M-x customize-browse}.  This command creates a special kind of
  customization buffer which shows only the names of the groups (and
  variables and faces), and their structure.
  
--- 276,288 ----
  pertaining to that feature.  You can also go straight to a particular
  group by name, using the command @kbd{M-x customize-group}.
  
+ @node Browsing Custom
+ @subsection Browsing and Searching for Options and Faces
  @findex customize-browse
! You can use @kbd{M-x customize} to browse the groups and options, but
! often @kbd{M-x customize-browse} is a more efficient alternative.
! That is because it lets you view the structure of customization groups
! on a larger scale.  This command creates a special kind of
  customization buffer which shows only the names of the groups (and
  variables and faces), and their structure.
  
***************
*** 291,296 ****
--- 296,308 ----
  that group and its contents, just that variable, or just that face.
  This is the way to set values in it.
  
+   If you can guess part of the name of the options you are interested
+ in, then sometimes @kbd{M-x customize-apropos} can be another useful
+ way to search for options.  However, unlike @code{customize} and
+ @code{customize-browse}, @code{customize-apropos} can only find
+ options that are loaded in the current Emacs session.  @xref{Specific
+ Customization,, Customizing Specific Items}.
+ 
  @node Changing a Variable
  @subsection Changing a Variable
  
***************
*** 627,633 ****
  customize-variable} and specify the variable name.  This sets up the
  customization buffer with just one variable---the one that you asked
  for.  Editing, setting and saving the value work as described above,
! but only for the specified variable.
  
  @findex customize-face
    Likewise, you can modify a specific face, chosen by name, using
--- 639,647 ----
  customize-variable} and specify the variable name.  This sets up the
  customization buffer with just one variable---the one that you asked
  for.  Editing, setting and saving the value work as described above,
! but only for the specified variable.  Minibuffer completion is very
! handy if you only know part of the name.  However, it only finds
! options that have been loaded in the current Emacs session.
  
  @findex customize-face
    Likewise, you can modify a specific face, chosen by name, using
***************
*** 638,652 ****
    You can also set up the customization buffer with a specific group,
  using @kbd{M-x customize-group}.  The immediate contents of the chosen
  group, including user options, faces, and other groups, all appear
! as well.  However, these subgroups' own contents are not included.
  
  @findex customize-apropos
    To control more precisely what to customize, you can use @kbd{M-x
  customize-apropos}.  You specify a regular expression as argument; then
! all options, faces and groups whose names match this regular expression
! are set up in the customization buffer.  If you specify an empty regular
! expression, this includes @emph{all} groups, options and faces (but
! that takes a long time).
  
  @findex customize-changed-options
    When you upgrade to a new Emacs version, you might want to customize
--- 652,667 ----
    You can also set up the customization buffer with a specific group,
  using @kbd{M-x customize-group}.  The immediate contents of the chosen
  group, including user options, faces, and other groups, all appear
! as well (even if not already loaded).  However, the subgroups' own
! contents are not included.
  
  @findex customize-apropos
    To control more precisely what to customize, you can use @kbd{M-x
  customize-apropos}.  You specify a regular expression as argument; then
! all @emph{loaded} options, faces and groups whose names match this
! regular expression are set up in the customization buffer.  If you
! specify an empty regular expression, this includes @emph{all} groups,
! options and faces (but that takes a long time).
  
  @findex customize-changed-options
    When you upgrade to a new Emacs version, you might want to customize
***************
*** 654,660 ****
  To do this, use @kbd{M-x customize-changed-options} and specify a
  previous Emacs version number using the minibuffer.  It creates a
  customization buffer which shows all the options (and groups) whose
! definitions have been changed since the specified version.
  
  @findex customize-saved
  @findex customize-customized
--- 669,676 ----
  To do this, use @kbd{M-x customize-changed-options} and specify a
  previous Emacs version number using the minibuffer.  It creates a
  customization buffer which shows all the options (and groups) whose
! definitions have been changed since the specified version.  (Not just
! those that are already loaded.)
  
  @findex customize-saved
  @findex customize-customized
============================================================