5 files changed, 71 insertions, 23 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 7eb75ceac55..6d6ddf4da9a 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,18 @@
+2012-11-13  Glenn Morris  <rgm@gnu.org>
+
+        * variables.texi (Adding Generalized Variables):
+        At least mention gv-define-expander and gv-letplace.
+
+        * debugging.texi (Error Debugging): Mention debug-on-message.
+        (Using Debugger): Mention debugger-bury-or-kill.
+
+        * control.texi (Signaling Errors):
+        * debugging.texi (Error Debugging):
+        * errors.texi (Standard Errors): Add user-error.
+
+        * variables.texi (Adding Generalized Variables):
+        Use standard formatting for common lisp note about setf functions.
+
 2012-11-10  Martin Rudalics  <rudalics@gmx.at>
 
         * elisp.texi (Top): Add Recombining Windows to menu.
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index cf393b59c49..489e5cc5b22 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -824,6 +824,19 @@ The function @code{signal} never returns.
 @end example
 @end defun
 
+@cindex user errors, signaling
+@defun user-error format-string &rest args
+This function behaves exactly like @code{error}, except that it uses
+the error symbol @code{user-error} rather than @code{error}.  As the
+name suggests, this is intended to report errors on the part of the
+user, rather than errors in the code itself.  For example,
+if you try to use the command @code{Info-history-back} (@kbd{l}) to
+move back beyond the start of your Info browsing history, Emacs
+signals a @code{user-error}.  Such errors do not cause entry to the
+debugger, even when @code{debug-on-error} is non-@code{nil}.
+@xref{Error Debugging}.
+@end defun
+
 @cindex CL note---no continuable errors
 @quotation
 @b{Common Lisp note:} Emacs Lisp has nothing like the Common Lisp
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 2226db942d1..11532b19781 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -117,12 +117,12 @@ has any of those condition symbols, or if the error message matches
 any of the regular expressions, then that error does not enter the
 debugger.
 
-The normal value of this variable lists several errors that happen
-often during editing but rarely result from bugs in Lisp programs.
-However, ``rarely'' is not ``never''; if your program fails with an
-error that matches this list, you may try changing this list to debug
-the error.  The easiest way is usually to set
-@code{debug-ignored-errors} to @code{nil}.
+The normal value of this variable includes @code{user-error}, as well
+as several errors that happen often during editing but rarely result
+from bugs in Lisp programs.  However, ``rarely'' is not ``never''; if
+your program fails with an error that matches this list, you may try
+changing this list to debug the error.  The easiest way is usually to
+set @code{debug-ignored-errors} to @code{nil}.
 @end defopt
 
 @defopt eval-expression-debug-on-error
@@ -163,6 +163,14 @@ supported values correspond to the signals @code{SIGUSR1} and
 @code{inhibit-quit} is set and Emacs is not otherwise responding.
 @end defopt
 
+@cindex message, finding what causes a particular message
+@defvar debug-on-message
+If you set @code{debug-on-message} to a regular expression,
+Emacs will enter the debugger if it displays a matching message in the
+echo area.  For example, this can be useful when trying to find the
+cause of a particular message.
+@end defvar
+
   To debug an error that happens during loading of the init
 file, use the option @samp{--debug-init}.  This binds
 @code{debug-on-error} to @code{t} while loading the init file, and
@@ -314,6 +322,7 @@ is a message describing the reason that the debugger was invoked (such
 as the error message and associated data, if it was invoked due to an
 error).
 
+@vindex debugger-bury-or-kill
   The backtrace buffer is read-only and uses a special major mode,
 Debugger mode, in which letters are defined as debugger commands.  The
 usual Emacs editing commands are available; thus, you can switch windows
@@ -322,8 +331,12 @@ switch buffers, visit files, or do any other sort of editing.  However,
 the debugger is a recursive editing level (@pxref{Recursive Editing})
 and it is wise to go back to the backtrace buffer and exit the debugger
 (with the @kbd{q} command) when you are finished with it.  Exiting
-the debugger gets out of the recursive edit and kills the backtrace
-buffer.
+the debugger gets out of the recursive edit and buries the backtrace
+buffer.  (You can customize what the @kbd{q} command does with the
+backtrace buffer by setting the variable @code{debugger-bury-or-kill}.
+For example, set it to @code{kill} if you prefer to kill the buffer
+rather than bury it.  Consult the variable's documentation for more
+possibilities.)
 
   When the debugger has been entered, the @code{debug-on-error}
 variable is temporarily set according to
diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi
index a57f74d6c86..b92fd9ed665 100644
--- a/doc/lispref/errors.texi
+++ b/doc/lispref/errors.texi
@@ -172,6 +172,9 @@ The message is @samp{Text is read-only}.  This is a subcategory of
 @item undefined-color
 The message is @samp{Undefined color}.  @xref{Color Names}.
 
+@item user-error
+The message is the empty string.  @xref{Signaling Errors}.
+
 @item void-function
 The message is @samp{Symbol's function definition is void}.
 @xref{Function Cells}.
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index c8451527d4f..dfde3c45c04 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -2133,20 +2133,24 @@ set.  An example of using this macro is:
 @end example
 @end defmac
 
-@c FIXME?  Not sure what, if anything, to say about this.
-@ignore
-@defmac gv-define-expander name handler
-This is the most general way to define a new @code{setf} expansion.
-@end defmac
-@end ignore
+@findex gv-define-expander
+@findex gv-letplace
+@c FIXME?  Not sure what or how much to say about these.
+@c See cl.texi for an example of using gv-letplace.
+For more control over the expansion, see the macro @code{gv-define-expander}.
+The macro @code{gv-letplace} can be useful in defining macros that
+perform similarly to @code{setf}; for example, the @code{incf} macro
+of Common Lisp.  Consult the source file @file{gv.el} for more details.
 
 @cindex CL note---no @code{setf} functions
-Common Lisp defines another way to specify the @code{setf} behavior of
-a function, namely ``@code{setf} functions'', whose names are lists
-@code{(setf @var{name})} rather than symbols.  For example,
-@code{(defun (setf foo) @dots{})} defines the function that is used
-when @code{setf} is applied to @code{foo}.  Emacs does not support
-this.  It is a compile-time error to use @code{setf} on a form that
-has not already had an appropriate expansion defined.  In Common Lisp,
-this is not an error since the function @code{(setf @var{func})} might
-be defined later.
+@quotation
+@b{Common Lisp note:} Common Lisp defines another way to specify the
+@code{setf} behavior of a function, namely ``@code{setf} functions'',
+whose names are lists @code{(setf @var{name})} rather than symbols.
+For example, @code{(defun (setf foo) @dots{})} defines the function
+that is used when @code{setf} is applied to @code{foo}.  Emacs does
+not support this.  It is a compile-time error to use @code{setf} on a
+form that has not already had an appropriate expansion defined.  In
+Common Lisp, this is not an error since the function @code{(setf
+@var{func})} might be defined later.
+@end quotation