Updates to Macros and Customization chapters 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.

* doc/lispref/macros.texi (Expansion): Minor clarification.
(Backquote): Move node to eval.texi.
(Defining Macros): Move an example from Backquote node.
(Argument Evaluation): No need to mention Pascal.
(Indenting Macros): Add xref to Defining Macros.

* doc/lispref/eval.texi (Backquote): Move from macros.texi.

* lisp/custom.el (defcustom): Doc fix.

7 files changed, 194 insertions, 183 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 65740feeee5..bd7b27bbe60 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,18 @@
+2012-02-05  Chong Yidong  <cyd@gnu.org>
+
+        * customize.texi (Common Keywords): Minor clarifications.
+        Document custom-unlispify-remove-prefixes.
+        (Variable Definitions): Backquotes in defcustom seem to work fine
+        now.  Various other copyedits.
+
+        * eval.texi (Backquote): Move from macros.texi.
+
+        * macros.texi (Expansion): Minor clarification.
+        (Backquote): Move node to eval.texi.
+        (Defining Macros): Move an example from Backquote node.
+        (Argument Evaluation): No need to mention Pascal.
+        (Indenting Macros): Add xref to Defining Macros.
+
 2012-02-05  Glenn Morris  <rgm@gnu.org>
 
         * debugging.texi (Error Debugging): Mention debug-on-event default.
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 6d6c5df10ed..b8c30fff8ae 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -24,9 +24,10 @@ definitions---as well as face definitions (@pxref{Defining Faces}).
 @section Common Item Keywords
 
 @cindex customization keywords
-  All kinds of customization declarations (for variables and groups, and
-for faces) accept keyword arguments for specifying various information.
-This section describes some keywords that apply to all kinds.
+  The customization declarations that we will describe in the next few
+sections (@code{defcustom}, @code{defgroup}, etc.) all accept keyword
+arguments for specifying various information.  This section describes
+keywords that apply to all types of customization declarations.
 
   All of these keywords, except @code{:tag}, can be used more than once
 in a given item.  Each use of the keyword has an independent effect.
@@ -108,8 +109,7 @@ You can specify the text to use in the customization buffer by adding
 for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to
 the Emacs manual which appears in the buffer as @samp{foo}.
 
-An item can have more than one external link; however, most items have
-none at all.
+You can use this keyword more than once, to add multiple links.
 
 @item :load @var{file}
 @kindex load@r{, customization keyword}
@@ -136,14 +136,13 @@ version.  The value @var{version} must be a string.
 @kindex package-version@r{, customization keyword}
 This keyword specifies that the item was first introduced in
 @var{package} version @var{version}, or that its meaning or default
-value was changed in that version.  The value of @var{package} is a
-symbol and @var{version} is a string.
+value was changed in that version.  This keyword takes priority over
+@code{:version}.
 
-This keyword takes priority over @code{:version}.
-
-@var{package} should be the official name of the package, such as MH-E
-or Gnus.  If the package @var{package} is released as part of Emacs,
-@var{package} and @var{version} should appear in the value of
+@var{package} should be the official name of the package, as a symbol
+(e.g.@: @code{MH-E}).  @var{version} should be a string.  If the
+package @var{package} is released as part of Emacs, @var{package} and
+@var{version} should appear in the value of
 @code{customize-package-emacs-version-alist}.
 @end table
 
@@ -226,41 +225,31 @@ also use this keyword in @code{defgroup}:
 @table @code
 @item :prefix @var{prefix}
 @kindex prefix@r{, @code{defgroup} keyword}
-If the name of an item in the group starts with @var{prefix}, then the
-tag for that item is constructed (by default) by omitting @var{prefix}.
-
-One group can have any number of prefixes.
+If the name of an item in the group starts with @var{prefix}, and the
+customizable variable @code{custom-unlispify-remove-prefixes} is
+non-@code{nil}, the item's tag will omit @var{prefix}.  A group can
+have any number of prefixes.
 @end table
 @end defmac
 
-  The prefix-discarding feature is currently turned off, which means
-that @code{:prefix} currently has no effect.  We did this because we
-found that discarding the specified prefixes often led to confusing
-names for options.  This happened because the people who wrote the
-@code{defgroup} definitions for various groups added @code{:prefix}
-keywords whenever they make logical sense---that is, whenever the
-variables in the library have a common prefix.
-
-  In order to obtain good results with @code{:prefix}, it would be
-necessary to check the specific effects of discarding a particular
-prefix, given the specific items in a group and their names and
-documentation.  If the resulting text is not clear, then @code{:prefix}
-should not be used in that case.
+@defopt custom-unlispify-remove-prefixes
+If this variable is non-@code{nil}, the prefixes specified by a
+group's @code{:prefix} keyword are omitted from tag names, whenever
+the user customizes the group.
 
-  It should be possible to recheck all the customization groups, delete
-the @code{:prefix} specifications which give unclear results, and then
-turn this feature back on, if someone would like to do the work.
+The default value is @code{nil}, i.e.@: the prefix-discarding feature
+is disabled.  This is because discarding prefixes often leads to
+confusing names for options and faces.
+@end defopt
 
 @node Variable Definitions
 @section Defining Customization Variables
 @cindex define customization options
 @cindex customization variables, how to define
 
-  Use @code{defcustom} to declare user-customizable variables.
-
 @defmac defcustom option standard doc [keyword value]@dots{}
-This macro declares @var{option} as a customizable @dfn{user option}.
-You should not quote @var{option}.
+This macro declares @var{option} as a user option (i.e.@: a
+customizable variable).  You should not quote @var{option}.
 
 The argument @var{standard} is an expression that specifies the
 standard value for @var{option}.  Evaluating the @code{defcustom} form
@@ -275,31 +264,25 @@ cases applies, @code{defcustom} installs the result of evaluating
 The expression @var{standard} can be evaluated at various other times,
 too---whenever the customization facility needs to know @var{option}'s
 standard value.  So be sure to use an expression which is harmless to
-evaluate at any time.  We recommend avoiding backquotes in
-@var{standard}, because they are not expanded when editing the value,
-so list values will appear to have the wrong structure.
+evaluate at any time.
 
 The argument @var{doc} specifies the documentation string for the
 variable.
 
 Every @code{defcustom} should specify @code{:group} at least once.
 
-If you specify the @code{:set} keyword, to make the variable take other
-special actions when set through the customization buffer, the
-variable's documentation string should tell the user specifically how
-to do the same job in hand-written Lisp code.
-
 When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
 mode (@code{eval-defun}), a special feature of @code{eval-defun}
 arranges to set the variable unconditionally, without testing whether
 its value is void.  (The same feature applies to @code{defvar}.)
 @xref{Defining Variables}.
 
-If you put a @code{defcustom} in a file that is preloaded at dump time
-(@pxref{Building Emacs}), and the standard value installed for the
-variable at that time might not be correct, use
+If you put a @code{defcustom} in a pre-loaded Emacs Lisp file
+(@pxref{Building Emacs}), the standard value installed at dump time
+might be incorrect, e.g.@: because another variable that it depends on
+has not been assigned the right value yet.  In that case, use
 @code{custom-reevaluate-setting}, described below, to re-evaluate the
-standard value during or after Emacs startup.
+standard value after Emacs starts up.
 @end defmac
 
   @code{defcustom} accepts the following additional keywords:
@@ -330,6 +313,9 @@ the value properly for this option (which may not mean simply setting
 the option as a Lisp variable).  The default for @var{setfunction} is
 @code{set-default}.
 
+If you specify this keyword, the variable's documentation string
+should describe how to do the same job in hand-written Lisp code.
+
 @item :get @var{getfunction}
 @kindex get@r{, @code{defcustom} keyword}
 Specify @var{getfunction} as the way to extract the value of this
@@ -341,7 +327,7 @@ value).  The default is @code{default-value}.
 You have to really understand the workings of Custom to use
 @code{:get} correctly.  It is meant for values that are treated in
 Custom as variables but are not actually stored in Lisp variables.  It
-is almost surely a mistake to specify @code{getfunction} for a value
+is almost surely a mistake to specify @var{getfunction} for a value
 that really is stored in a Lisp variable.
 
 @item :initialize @var{function}
@@ -380,16 +366,15 @@ already set or has been customized; otherwise, just use
 These functions behave like @code{custom-initialize-set}
 (@code{custom-initialize-default}, respectively), but catch errors.
 If an error occurs during initialization, they set the variable to
-@code{nil} using @code{set-default}, and throw no error.
-
-These two functions are only meant for options defined in pre-loaded
-files, where some variables or functions used to compute the option's
-value may not yet be defined.  The option normally gets updated in
-@file{startup.el}, ignoring the previously computed value.  Because of
-this typical usage, the value which these two functions compute
-normally only matters when, after startup, one unsets the option's
-value and then reevaluates the defcustom.  By that time, the necessary
-variables and functions will be defined, so there will not be an error.
+@code{nil} using @code{set-default}, and signal no error.
+
+These functions are meant for options defined in pre-loaded files,
+where the @var{standard} expression may signal an error because some
+required variable or function is not yet defined.  The value normally
+gets updated in @file{startup.el}, ignoring the value computed by
+@code{defcustom}.  After startup, if one unsets the value and
+reevaluates the @code{defcustom}, the @var{standard} expression can be
+evaluated without error.
 @end table
 
 @item :risky @var{value}
@@ -457,18 +442,16 @@ is an expression that evaluates to the value.
 
 @defun custom-reevaluate-setting symbol
 This function re-evaluates the standard value of @var{symbol}, which
-should be a user option declared via @code{defcustom}.  (If the
+should be a user option declared via @code{defcustom}.  If the
 variable was customized, this function re-evaluates the saved value
-instead.)  This is useful for customizable options that are defined
-before their value could be computed correctly, such as variables
-defined in packages that are loaded at dump time, but depend on the
-run-time information.  For example, the value could be a file whose
-precise name depends on the hierarchy of files when Emacs runs, or a
-name of a program that needs to be searched at run time.
-
-A good place to put calls to this function is in the function
-@code{command-line} that is run during startup (@pxref{Startup Summary})
-or in the various hooks it calls.
+instead.  Then it sets the user option to that value (using the
+option's @code{:set} property if that is defined).
+
+This is useful for customizable options that are defined before their
+value could be computed correctly.  For example, during startup Emacs
+calls this function for some user options that were defined in
+pre-loaded Emacs Lisp files, but whose initial values depend on
+information available only at run-time.
 @end defun
 
 @defun custom-variable-p arg
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index b4692cd33ce..f69823101d0 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -374,6 +374,7 @@ Evaluation
 * Forms::                   How various sorts of objects are evaluated.
 * Quoting::                 Avoiding evaluation (to put constants in
                               the program).
+* Backquote::               Easier construction of list structure.
 * Eval::                    How to invoke the Lisp interpreter explicitly.
 
 Kinds of Forms
@@ -482,7 +483,6 @@ Macros
 * Expansion::               How, when and why macros are expanded.
 * Compiling Macros::        How macros are expanded by the compiler.
 * Defining Macros::         How to write a macro definition.
-* Backquote::               Easier construction of list structure.
 * Problems with Macros::    Don't evaluate the macro arguments too many times.
                               Don't hide the user's variables.
 * Indenting Macros::        Specifying how to indent macro calls.
diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index e81efd10892..cb3a4c54fac 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -23,6 +23,7 @@ function @code{eval}.
 * Intro Eval::  Evaluation in the scheme of things.
 * Forms::       How various sorts of objects are evaluated.
 * Quoting::     Avoiding evaluation (to put constants in the program).
+* Backquote::   Easier construction of list structure.
 * Eval::        How to invoke the Lisp interpreter explicitly.
 @end menu
 
@@ -579,6 +580,96 @@ Functions}), which causes an anonymous lambda expression written in Lisp
 to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
 only part of a list, while computing and substituting other parts.
 
+@node Backquote
+@section Backquote
+@cindex backquote (list substitution)
+@cindex ` (list substitution)
+@findex `
+
+  @dfn{Backquote constructs} allow you to quote a list, but
+selectively evaluate elements of that list.  In the simplest case, it
+is identical to the special form @code{quote}
+@iftex
+@end iftex
+@ifnottex
+(described in the previous section; @pxref{Quoting}).
+@end ifnottex
+For example, these two forms yield identical results:
+
+@example
+@group
+`(a list of (+ 2 3) elements)
+     @result{} (a list of (+ 2 3) elements)
+@end group
+@group
+'(a list of (+ 2 3) elements)
+     @result{} (a list of (+ 2 3) elements)
+@end group
+@end example
+
+@findex , @r{(with backquote)}
+  The special marker @samp{,} inside of the argument to backquote
+indicates a value that isn't constant.  The Emacs Lisp evaluator
+evaluates the argument of @samp{,}, and puts the value in the list
+structure:
+
+@example
+@group
+`(a list of ,(+ 2 3) elements)
+     @result{} (a list of 5 elements)
+@end group
+@end example
+
+@noindent
+Substitution with @samp{,} is allowed at deeper levels of the list
+structure also.  For example:
+
+@example
+@group
+`(1 2 (3 ,(+ 4 5)))
+     @result{} (1 2 (3 9))
+@end group
+@end example
+
+@findex ,@@ @r{(with backquote)}
+@cindex splicing (with backquote)
+  You can also @dfn{splice} an evaluated value into the resulting list,
+using the special marker @samp{,@@}.  The elements of the spliced list
+become elements at the same level as the other elements of the resulting
+list.  The equivalent code without using @samp{`} is often unreadable.
+Here are some examples:
+
+@example
+@group
+(setq some-list '(2 3))
+     @result{} (2 3)
+@end group
+@group
+(cons 1 (append some-list '(4) some-list))
+     @result{} (1 2 3 4 2 3)
+@end group
+@group
+`(1 ,@@some-list 4 ,@@some-list)
+     @result{} (1 2 3 4 2 3)
+@end group
+
+@group
+(setq list '(hack foo bar))
+     @result{} (hack foo bar)
+@end group
+@group
+(cons 'use
+  (cons 'the
+    (cons 'words (append (cdr list) '(as elements)))))
+     @result{} (use the words foo bar as elements)
+@end group
+@group
+`(use the words ,@@(cdr list) as elements)
+     @result{} (use the words foo bar as elements)
+@end group
+@end example
+
+
 @node Eval
 @section Eval
 
diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi
index 3804d963108..dca88d2b7c7 100644
--- a/doc/lispref/macros.texi
+++ b/doc/lispref/macros.texi
@@ -27,7 +27,6 @@ instead.  @xref{Inline Functions}.
 * Expansion::               How, when and why macros are expanded.
 * Compiling Macros::        How macros are expanded by the compiler.
 * Defining Macros::         How to write a macro definition.
-* Backquote::               Easier construction of list structure.
 * Problems with Macros::    Don't evaluate the macro arguments too many times.
                               Don't hide the user's variables.
 * Indenting Macros::        Specifying how to indent macro calls.
@@ -78,10 +77,9 @@ to the argument values from the macro call, or to a list of them in the
 case of a @code{&rest} argument.  And the macro body executes and
 returns its value just as a function body does.
 
-  The second crucial difference between macros and functions is that the
-value returned by the macro body is not the value of the macro call.
-Instead, it is an alternate expression for computing that value, also
-known as the @dfn{expansion} of the macro.  The Lisp interpreter
+  The second crucial difference between macros and functions is that
+the value returned by the macro body is an alternate Lisp expression,
+also known as the @dfn{expansion} of the macro.  The Lisp interpreter
 proceeds to evaluate the expansion as soon as it comes back from the
 macro.
 
@@ -221,7 +219,26 @@ any @code{interactive} declaration is ignored since macros cannot be
 called interactively.
 @end defspec
 
-  The body of the macro definition can include a @code{declare} form,
+  Macros often need to construct large list structures from a mixture
+of constants and nonconstant parts.  To make this easier, use the
+@samp{`} syntax (@pxref{Backquote}).  For example:
+
+@example
+@example
+@group
+(defmacro t-becomes-nil (variable)
+  `(if (eq ,variable t)
+       (setq ,variable nil)))
+@end group
+
+@group
+(t-becomes-nil foo)
+     @equiv{} (if (eq foo t) (setq foo nil))
+@end group
+@end example
+@end example
+
+  The body of a macro definition can include a @code{declare} form,
 which can specify how @key{TAB} should indent macro calls, and how to
 step through them for Edebug.
 
@@ -259,107 +276,11 @@ without evaluating any @var{specs}.
 has no effect on how the macro expands, on what the macro means in the
 program.  It only affects the secondary features listed above.
 
-@node Backquote
-@section Backquote
-@cindex backquote (list substitution)
-@cindex ` (list substitution)
-@findex `
-
-  Macros often need to construct large list structures from a mixture of
-constants and nonconstant parts.  To make this easier, use the @samp{`}
-syntax (usually called @dfn{backquote}).
-
-  Backquote allows you to quote a list, but selectively evaluate
-elements of that list.  In the simplest case, it is identical to the
-special form @code{quote} (@pxref{Quoting}).  For example, these
-two forms yield identical results:
-
-@example
-@group
-`(a list of (+ 2 3) elements)
-     @result{} (a list of (+ 2 3) elements)
-@end group
-@group
-'(a list of (+ 2 3) elements)
-     @result{} (a list of (+ 2 3) elements)
-@end group
-@end example
-
-@findex , @r{(with backquote)}
-The special marker @samp{,} inside of the argument to backquote
-indicates a value that isn't constant.  Backquote evaluates the
-argument of @samp{,} and puts the value in the list structure:
-
-@example
-@group
-(list 'a 'list 'of (+ 2 3) 'elements)
-     @result{} (a list of 5 elements)
-@end group
-@group
-`(a list of ,(+ 2 3) elements)
-     @result{} (a list of 5 elements)
-@end group
-@end example
-
-  Substitution with @samp{,} is allowed at deeper levels of the list
-structure also.  For example:
-
-@example
-@group
-(defmacro t-becomes-nil (variable)
-  `(if (eq ,variable t)
-       (setq ,variable nil)))
-@end group
-
-@group
-(t-becomes-nil foo)
-     @equiv{} (if (eq foo t) (setq foo nil))
-@end group
-@end example
-
-@findex ,@@ @r{(with backquote)}
-@cindex splicing (with backquote)
-  You can also @dfn{splice} an evaluated value into the resulting list,
-using the special marker @samp{,@@}.  The elements of the spliced list
-become elements at the same level as the other elements of the resulting
-list.  The equivalent code without using @samp{`} is often unreadable.
-Here are some examples:
-
-@example
-@group
-(setq some-list '(2 3))
-     @result{} (2 3)
-@end group
-@group
-(cons 1 (append some-list '(4) some-list))
-     @result{} (1 2 3 4 2 3)
-@end group
-@group
-`(1 ,@@some-list 4 ,@@some-list)
-     @result{} (1 2 3 4 2 3)
-@end group
-
-@group
-(setq list '(hack foo bar))
-     @result{} (hack foo bar)
-@end group
-@group
-(cons 'use
-  (cons 'the
-    (cons 'words (append (cdr list) '(as elements)))))
-     @result{} (use the words foo bar as elements)
-@end group
-@group
-`(use the words ,@@(cdr list) as elements)
-     @result{} (use the words foo bar as elements)
-@end group
-@end example
-
 @node Problems with Macros
 @section Common Problems Using Macros
 
-  The basic facts of macro expansion have counterintuitive consequences.
-This section describes some important consequences that can lead to
+  Macro expansion can have counterintuitive consequences.  This
+section describes some important consequences that can lead to
 trouble, and rules to follow to avoid trouble.
 
 @menu
@@ -407,9 +328,8 @@ program is actually run.
 
   When defining a macro you must pay attention to the number of times
 the arguments will be evaluated when the expansion is executed.  The
-following macro (used to facilitate iteration) illustrates the problem.
-This macro allows us to write a simple ``for'' loop such as one might
-find in Pascal.
+following macro (used to facilitate iteration) illustrates the
+problem.  This macro allows us to write a ``for'' loop construct.
 
 @findex for
 @smallexample
@@ -683,9 +603,9 @@ either.
 @node Indenting Macros
 @section Indenting Macros
 
-  You can use the @code{declare} form in the macro definition to
-specify how to @key{TAB} should indent calls to the macro.  You
-write it like this:
+  Within a macro definition, you can use the @code{declare} form
+(@pxref{Defining Macros}) to specify how to @key{TAB} should indent
+calls to the macro.  An indentation specifiction is written like this:
 
 @example
 (declare (indent @var{indent-spec}))
@@ -715,6 +635,7 @@ the line uses the standard pattern.
 @var{symbol} should be a function name; that function is called to
 calculate the indentation of a line within this expression.  The
 function receives two arguments:
+
 @table @asis
 @item @var{state}
 The value returned by @code{parse-partial-sexp} (a Lisp primitive for
@@ -723,6 +644,7 @@ beginning of this line.
 @item @var{pos}
 The position at which the line being indented begins.
 @end table
+
 @noindent
 It should return either a number, which is the number of columns of
 indentation for that line, or a list whose car is such a number.  The
diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi
index 4a48536f5f3..0f4a4447ed3 100644
--- a/doc/lispref/vol1.texi
+++ b/doc/lispref/vol1.texi
@@ -390,6 +390,7 @@ Evaluation
 * Forms::                   How various sorts of objects are evaluated.
 * Quoting::                 Avoiding evaluation (to put constants in
                               the program).
+* Backquote::               Easier construction of list structure.
 * Eval::                    How to invoke the Lisp interpreter explicitly.
 
 Kinds of Forms
@@ -501,7 +502,6 @@ Macros
 * Expansion::               How, when and why macros are expanded.
 * Compiling Macros::        How macros are expanded by the compiler.
 * Defining Macros::         How to write a macro definition.
-* Backquote::               Easier construction of list structure.
 * Problems with Macros::    Don't evaluate the macro arguments too many times.
                               Don't hide the user's variables.
 * Indenting Macros::        Specifying how to indent macro calls.
diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi
index 961b3225823..241728fd1d2 100644
--- a/doc/lispref/vol2.texi
+++ b/doc/lispref/vol2.texi
@@ -389,6 +389,7 @@ Evaluation
 * Forms::                   How various sorts of objects are evaluated.
 * Quoting::                 Avoiding evaluation (to put constants in
                               the program).
+* Backquote::               Easier construction of list structure.
 * Eval::                    How to invoke the Lisp interpreter explicitly.
 
 Kinds of Forms
@@ -500,7 +501,6 @@ Macros
 * Expansion::               How, when and why macros are expanded.
 * Compiling Macros::        How macros are expanded by the compiler.
 * Defining Macros::         How to write a macro definition.
-* Backquote::               Easier construction of list structure.
 * Problems with Macros::    Don't evaluate the macro arguments too many times.
                               Don't hide the user's variables.
 * Indenting Macros::        Specifying how to indent macro calls.