[Emacs-diffs] /srv/bzr/emacs/trunk r107116: Update Customization chapter of Lisp manual.

[Chong Yidong]

------------------------------------------------------------
revno: 107116
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sun 2012-02-05 22:27:06 +0800
message:
  Update Customization chapter of Lisp manual.
  
  * doc/lispref/customize.texi (Common Keywords): Minor clarifications.
  Document custom-unlispify-remove-prefixes.
  (Variable Definitions): Backquotes in defcustom seem to work fine
  now.  Various other copyedits.
  (Simple Types): Copyedits.  Document color selector.
  (Composite Types): Copyedits.
  (Splicing into Lists): Clarifications.
modified:
  admin/FOR-RELEASE
  doc/lispref/ChangeLog
  doc/lispref/customize.texi

=== modified file 'admin/FOR-RELEASE'
--- a/admin/FOR-RELEASE 2012-02-05 06:44:47 +0000
+++ b/admin/FOR-RELEASE 2012-02-05 14:27:06 +0000
@@ -188,7 +188,7 @@
 commands.texi     
 compile.texi      
 control.texi      cyd
-customize.texi    
+customize.texi    cyd
 debugging.texi    
 display.texi      
 edebug.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-02-05 06:44:47 +0000
+++ b/doc/lispref/ChangeLog     2012-02-05 14:27:06 +0000
@@ -4,6 +4,9 @@
        Document custom-unlispify-remove-prefixes.
        (Variable Definitions): Backquotes in defcustom seem to work fine
        now.  Various other copyedits.
+       (Simple Types): Copyedits.  Document color selector.
+       (Composite Types): Copyedits.
+       (Splicing into Lists): Clarifications.
 
        * eval.texi (Backquote): Move from macros.texi.
 

=== modified file 'doc/lispref/customize.texi'
--- a/doc/lispref/customize.texi        2012-02-05 06:44:47 +0000
+++ b/doc/lispref/customize.texi        2012-02-05 14:27:06 +0000
@@ -519,30 +519,28 @@
 @node Simple Types
 @subsection Simple Types
 
-  This section describes all the simple customization types.
+  This section describes all the simple customization types.  For
+several of these customization types, the customization widget
+provides inline completion with @kbd{C-M-i} or @address@hidden
 
 @table @code
 @item sexp
-The value may be any Lisp object that can be printed and read back.  You
-can use @code{sexp} as a fall-back for any option, if you don't want to
-take the time to work out a more specific type to use.
+The value may be any Lisp object that can be printed and read back.
+You can use @code{sexp} as a fall-back for any option, if you don't
+want to take the time to work out a more specific type to use.
 
 @item integer
-The value must be an integer, and is represented textually
-in the customization buffer.
+The value must be an integer.
 
 @item number
-The value must be a number (floating point or integer), and is
-represented textually in the customization buffer.
+The value must be a number (floating point or integer).
 
 @item float
-The value must be a floating point number, and is represented
-textually in the customization buffer.
+The value must be a floating point number.
 
 @item string
-The value must be a string, and the customization buffer shows just the
-contents, with no delimiting @samp{"} characters and no quoting with
address@hidden
+The value must be a string.  The customization buffer shows the string
+without delimiting @samp{"} characters or @samp{\} quotes.
 
 @item regexp
 Like @code{string} except that the string must be a valid regular
@@ -554,39 +552,35 @@
 buffer, rather than by showing the number.
 
 @item file
-The value must be a file name, and you can do completion with
address@hidden@key{TAB}}.
+The value must be a file name.  The widget provides completion.
 
 @item (file :must-match t)
-The value must be a file name for an existing file, and you can do
-completion with @address@hidden
+The value must be a file name for an existing file.  The widget
+provides completion.
 
 @item directory
-The value must be a directory name, and you can do completion with
address@hidden@key{TAB}}.
+The value must be a directory name.  The widget provides completion.
 
 @item hook
-The value must be a list of functions (or a single function, but that is
-obsolete usage).  This customization type is used for hook variables.
-You can use the @code{:options} keyword in a hook variable's
address@hidden to specify a list of functions recommended for use in
-the hook; see @ref{Variable Definitions}.
+The value must be a list of functions.  This customization type is
+used for hook variables.  You can use the @code{:options} keyword in a
+hook variable's @code{defcustom} to specify a list of functions
+recommended for use in the hook; @xref{Variable Definitions}.
 
 @item symbol
 The value must be a symbol.  It appears in the customization buffer as
-the name of the symbol.
+the symbol name.  The widget provides completion.
 
 @item function
-The value must be either a lambda expression or a function name.  When
-it is a function name, you can do completion with @address@hidden
+The value must be either a lambda expression or a function name.  The
+widget provides completion for function names.
 
 @item variable
-The value must be a variable name, and you can do completion with
address@hidden@key{TAB}}.
+The value must be a variable name.  The widget provides completion.
 
 @item face
-The value must be a symbol which is a face name, and you can do
-completion with @address@hidden
+The value must be a symbol which is a face name.  The widget provides
+completion.
 
 @item boolean
 The value is boolean---either @code{nil} or @code{t}.  Note that by
@@ -600,8 +594,10 @@
 @address@hidden
 
 @item color
-The value must be a valid color name, and you can do completion with
address@hidden@key{TAB}}.  A sample is provided.
+The value must be a valid color name.  The widget provides completion
+for color names, as well as a sample and a button for selecting a
+color name from a list of color names shown in a @samp{*Colors*}
+buffer.
 @end table
 
 @node Composite Types
@@ -635,9 +631,8 @@
 symbol)} is a customization type which matches values such as
 @code{("foo" . foo)}.
 
-In the customization buffer, the @sc{car} and the @sc{cdr} are
-displayed and edited separately, each according to the type
-that you specify for it.
+In the customization buffer, the @sc{car} and @sc{cdr} are displayed
+and edited separately, each according to their specified type.
 
 @item (list @address@hidden)
 The value must be a list with exactly as many elements as the
@@ -680,7 +675,7 @@
 
 The argument to the @code{:options} keywords should be a list of
 specifications for reasonable keys in the alist.  Ordinarily, they are
-simply atoms, which stand for themselves as.  For example:
+simply atoms, which stand for themselves.  For example:
 
 @smallexample
 :options '("foo" "bar" "baz")
@@ -753,14 +748,6 @@
   "Alist of basic info about people.
 Each element has the form (NAME AGE MALE-FLAG)."
   :type '(alist :value-type (group integer boolean)))
-
-(defcustom pets '(("brian")
-                  ("dorith" "dog" "guppy")
-                  ("ken" "cat"))
-  "Alist of people's pets.
-In an element (KEY . VALUE), KEY is the person's name,
-and the VALUE is a list of that person's pets."
-  :type '(alist :value-type (repeat string)))
 @end smallexample
 
 @item (plist :key-type @var{key-type} :value-type @var{value-type})
@@ -770,9 +757,8 @@
 defaults to @code{symbol} rather than @code{sexp}.
 
 @item (choice @address@hidden)
-The value must fit at least one of @var{alternative-types}.
-For example, @code{(choice integer string)} allows either an
-integer or a string.
+The value must fit one of @var{alternative-types}.  For example,
address@hidden(choice integer string)} allows either an integer or a string.
 
 In the customization buffer, the user selects an alternative
 using a menu, and can then edit the value in the usual way for that
@@ -964,20 +950,18 @@
 @subsection Splicing into Lists
 
   The @code{:inline} feature lets you splice a variable number of
-elements into the middle of a list or vector.  You use it in a
address@hidden, @code{choice} or @code{repeat} type which appears among the
-element-types of a @code{list} or @code{vector}.
-
-  Normally, each of the element-types in a @code{list} or @code{vector}
-describes one and only one element of the list or vector.  Thus, if an
-element-type is a @code{repeat}, that specifies a list of unspecified
-length which appears as one element.
-
-  But when the element-type uses @code{:inline}, the value it matches is
-merged directly into the containing sequence.  For example, if it
-matches a list with three elements, those become three elements of the
-overall sequence.  This is analogous to using @samp{,@@} in the backquote
-construct.
+elements into the middle of a @code{list} or @code{vector}
+customization type.  You use it by adding @code{:inline t} to a type
+specification which is contained in a @code{list} or @code{vector}
+specification.
+
+  Normally, each entry in a @code{list} or @code{vector} type
+specification describes a single element type.  But when an entry
+contains @code{:inline t}, the value it matches is merged directly
+into the containing sequence.  For example, if the entry matches a
+list with three elements, those become three elements of the overall
+sequence.  This is analogous to @samp{,@@} in a backquote construct
+(@pxref{Backquote}).
 
   For example, to specify a list whose first element must be @code{baz}
 and whose remaining arguments should be zero or more of @code{foo} and