7 files changed, 204 insertions, 105 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index bd7b27bbe60..a172f82d2e5 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,9 +1,38 @@
+2012-02-07  Glenn Morris  <rgm@gnu.org>
+
+        * modes.texi (Defining Minor Modes):
+        Expand on args of defined minor modes.
+
+2012-02-07  Chong Yidong  <cyd@gnu.org>
+
+        * variables.texi (Creating Buffer-Local): Minor clarification
+        to buffer-local-variables doc (Bug#10715).
+
+2012-02-07  Glenn Morris  <rgm@gnu.org>
+
+        * display.texi (ImageMagick Images): General update.
+        Move most details of imagemagick-render-type to the variable's doc.
+
+2012-02-06  Glenn Morris  <rgm@gnu.org>
+
+        * keymaps.texi (Tool Bar): Mention separators.
+        (Inheritance and Keymaps):
+        Mention make-composed-keymap and multiple inheritance.
+
+        * modes.texi (Running Hooks): Mention run-hook-wrapped.
+
+        * control.texi (Handling Errors):
+        Mention condition-case-no-debug and with-demoted-errors.
+
 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.
+        (Simple Types): Copyedits.  Document color selector.
+        (Composite Types): Copyedits.
+        (Splicing into Lists): Clarifications.
 
         * eval.texi (Backquote): Move from macros.texi.
 
diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 0511f21007d..3673f753a0a 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -891,9 +891,8 @@ establishing an error handler, with the special form
 
 @noindent
 This deletes the file named @var{filename}, catching any error and
-returning @code{nil} if an error occurs@footnote{
-Actually, you should use @code{ignore-errors} in such a simple case;
-see below.}.
+returning @code{nil} if an error occurs.  (You can use the macro
+@code{ignore-errors} for a simple case like this; see below.)
 
   The @code{condition-case} construct is often used to trap errors that
 are predictable, such as failure to open a file in a call to
@@ -949,6 +948,13 @@ The effect of @code{debug} here is only to prevent
 given error will invoke the debugger only if @code{debug-on-error} and
 the other usual filtering mechanisms say it should.  @xref{Error Debugging}.
 
+@defmac condition-case-no-debug var protected-form handlers@dots{}
+The macro @code{condition-case-no-debug} provides another way to
+handle debugging of such forms.  It behaves exactly like
+@code{condition-case}, unless the variable @code{debug-on-error} is
+non-@code{nil}, in which case it does not handle any errors at all.
+@end defmac
+
   Once Emacs decides that a certain handler handles the error, it
 returns control to that handler.  To do so, Emacs unbinds all variable
 bindings made by binding constructs that are being exited, and
@@ -1122,6 +1128,13 @@ Here's the example at the beginning of this subsection rewritten using
 @end smallexample
 @end defmac
 
+@defmac with-demoted-errors body@dots{}
+This macro is like a milder version of @code{ignore-errors}.  Rather
+than suppressing errors altogether, it converts them into messages.
+Use this form around code that is not expected to signal errors,
+but should be robust if one does occur.  Note that this macro
+uses @code{condition-case-no-debug} rather than @code{condition-case}.
+@end defmac
 
 @node Error Symbols
 @subsubsection Error Symbols and Condition Names
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index b8c30fff8ae..4c3adee0db5 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -519,30 +519,28 @@ Introduction, widget, The Emacs Widget Library}, for details.
 @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 @kbd{M-@key{TAB}}.
 
 @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
-@samp{\}.
+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 @@ integer, but this type shows the value by inserting the character in the
 buffer, rather than by showing the number.
 
 @item file
-The value must be a file name, and you can do completion with
-@kbd{M-@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 @kbd{M-@key{TAB}}.
+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
-@kbd{M-@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
-@code{defcustom} 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 @kbd{M-@key{TAB}}.
+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
-@kbd{M-@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 @kbd{M-@key{TAB}}.
+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 @@ The value must be a coding-system name, and you can do completion with
 @kbd{M-@key{TAB}}.
 
 @item color
-The value must be a valid color name, and you can do completion with
-@kbd{M-@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 @@ its @sc{cdr} must fit @var{cdr-type}.  For example, @code{(cons string
 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 @var{element-types}@dots{})
 The value must be a list with exactly as many elements as the
@@ -680,7 +675,7 @@ specified by the @code{:options} keyword argument.
 
 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 @@ key, using variations of this trick:
   "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 @@ that (i) the information is stored as a property list,
 defaults to @code{symbol} rather than @code{sexp}.
 
 @item (choice @var{alternative-types}@dots{})
-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,
+@code{(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 @@ whatever follows the last keyword-value pair.
 @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
-@code{set}, @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
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index e97e6c264a3..d5870fd3abb 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -4527,30 +4527,51 @@ specifying the bounding box of the PostScript image, analogous to the
 support, you can use the ImageMagick library to load many image formats.
 
 @findex imagemagick-types
+@findex imagemagick-register-types
 The function @code{imagemagick-types} returns a list of image file
 extensions that your installation of ImageMagick supports.  To enable
 support, you must call the function @code{imagemagick-register-types}.
+This enables Emacs to visit these file types in @code{image-mode}
+(@pxref{File Conveniences,,, emacs, The GNU Emacs Manual}).
+If your Emacs was not compiled with ImageMagick support, then
+@code{imagemagick-types} will be undefined and
+@code{imagemagick-register-types} will do nothing.
 
 @vindex imagemagick-types-inhibit
 The variable @code{imagemagick-types-inhibit} specifies a list of
-image types that you do @emph{not} want ImageMagick to handle.  There
-may be overlap between image loaders in your Emacs installation, and
-you may prefer to use a different one for a given image type (which
-@c FIXME how is this priority determined?
-loader will be used in practice depends on the priority of the loaders).
-@c FIXME why are these uppercase when image-types is lower-case?
-@c FIXME what are the possible options?  Are these actually file extensions?
-For example, if you never want to use the ImageMagick loader to use
+image types that you do @emph{not} want ImageMagick to handle.  It is
+a list of symbols, each of which has the same name as one of the
+format tags used internally by ImageMagick (i.e., as
+@code{imagemagick-types} returns).  ImageMagick has a very broad
+definition of what an image is, for example it includes such file
+types as C files and HTML files.  It is not appropriate to treat these
+as images in Emacs.  You can add any other ImageMagick type that you
+wish to this list.
+@ignore
+@c I don't know what this means.  I suspect it means eg loading jpg
+@c images via libjpeg or ImageMagick.  But it doesn't work.
+@c If you don't have libjpeg support compiled in, you cannot
+@c view jpeg images, even if you have imagemagick support:
+@c http://debbugs.gnu.org/9045
+@c And if you have both compiled in, then you always get
+@c the libjpeg version:
+@c http://debbugs.gnu.org/10746
+There may be overlap between image loaders in your Emacs installation,
+and you may prefer to use a different one for a given image type
+(which loader will be used in practice depends on the priority of the
+loaders).  
+For example, if you never want to use the ImageMagick loader to view
 JPEG files, add @code{JPG} to this list.
+@end ignore
+Note that ImageMagick often distinguishes between several different
+types of a particular format (e.g., @code{JPG}, @code{JPEG},
+@code{PJPEG}, etc.), and you may need to add all versions to this
+list.
 
+@c Not sure this should even be in the manual at all.
 @vindex imagemagick-render-type
-You can set the variable @code{imagemagick-render-type} to choose
-between screen render methods for the ImageMagick loader.  The options
-are: @code{0}, a conservative method which works with older
-@c FIXME details of this "newer method"?
-@c Presumably it is faster but may be less "robust"?
-ImageMagick versions (it is a bit slow, but robust); and @code{1},
-a newer ImageMagick method.
+If you wish to experiment with the performance of the ImageMagick
+loader, see the variable @code{imagemagick-render-type}.
 
 Images loaded with ImageMagick support a few new display specifications:
 
@@ -4565,10 +4586,11 @@ aspect ratio may not be preserved.
 Specifies a rotation angle in degrees.
 
 @item :index
-Specifies which image to view inside an image bundle file format, such
-as TIFF or DJVM.  You can use the @code{image-metadata} function to
-retrieve the total number of images in an image bundle (this is
-similar to how GIF files work).
+@c Doesn't work: http://debbugs.gnu.org/7978
+This has the same meaning as it does for GIF images (@pxref{GIF Images}),
+i.e. it specifies which image to view inside an image bundle file format
+such as DJVM.  You can use the @code{image-metadata} function to
+retrieve the total number of images in an image bundle.
 @end table
 
 
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 8e03ade285f..a8528a548fc 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -432,6 +432,34 @@ for every numeric character code without modifier bits, even if it is
 @code{nil}, so these character's bindings are never inherited from
 the parent keymap.
 
+@cindex keymap inheritance from multiple maps
+  Sometimes you want to make a keymap that inherits from more than one
+map.  You can use the function @code{make-composed-keymap} for this.
+
+@defun make-composed-keymap maps &optional parent
+This function returns a new keymap composed of the existing keymap(s)
+@var{maps}, and optionally inheriting from a parent keymap
+@var{parent}.  @var{maps} can be a single keymap or a list of more
+than one.  When looking up a key in the resulting new map, Emacs
+searches in each of the @var{maps}, and then in @var{parent}, stopping
+at the first match.  A @code{nil} binding in any one of @var{maps}
+overrides any binding in @var{parent}, but not a non-@code{nil} binding
+in any other of the @var{maps}.
+@end defun
+
+@noindent For example, here is how Emacs sets the parent of
+@code{help-mode-map}, such that it inherits from both
+@code{button-buffer-map} and @code{special-mode-map}:
+
+@example
+(defvar help-mode-map
+  (let ((map (make-sparse-keymap)))
+    (set-keymap-parent map (make-composed-keymap button-buffer-map
+                                                 special-mode-map))
+    ... map) ... )
+@end example
+
+
 @node Prefix Keys
 @section Prefix Keys
 @cindex prefix key
@@ -2318,7 +2346,7 @@ The various toolkits with which you can build Emacs do not all support
 the same set of features for menus.  Some code works as expected with
 one toolkit, but not under another.
 
-One example is menu actions or buttons in a top-level menu-bar.  The
+One example is menu actions or buttons in a top-level menu bar.  The
 following works with the Lucid toolkit or on MS Windows, but not with
 GTK or Nextstep, where clicking on the item has no effect.
 
@@ -2658,6 +2686,15 @@ The @code{:rtl} property specifies an alternative image to use for
 right-to-left languages.  Only the Gtk+ version of Emacs supports this
 at present.
 
+Like the menu bar, the tool bar can display separators (@pxref{Menu
+Separators}).  Tool bar separators are vertical rather than
+horizontal, though, and only a single style is supported.  Separators
+are represented in the tool bar keymap in the same way as for the
+menu bar, i.e. using a @code{(menu-item "--"}) entry.  The Gtk+ and
+Nextstep tool bars render separators natively, otherwise Emacs selects
+a separator image that is appropriate for the display.  Note that tool
+bar separators do not support any properties, such as @code{:visible}.
+
 The default tool bar is defined so that items specific to editing do not
 appear for major modes whose command symbol has a @code{mode-class}
 property of @code{special} (@pxref{Major Mode Conventions}).  Major
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 638ab89e37f..052fd037167 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -163,6 +163,14 @@ A wrapper-hook also allows for a hook function to completely replace the
 default definition (by not calling @var{fun}).
 @end defmac
 
+@defun run-hook-wrapped hook wrap-function &rest args
+This function is similar to @code{run-hook-with-args-until-success}.
+Like that function, it runs the functions on the abnormal hook
+@code{hook}, stopping at the first one that returns non-@code{nil}.
+Instead of calling the hook functions directly, though, it actually
+calls @code{wrap-function} with arguments @code{fun} and @code{args}.
+@end defun
+
 @node Setting Hooks
 @subsection Setting Hooks
 
@@ -1372,11 +1380,21 @@ implementing a mode in one self-contained definition.
 @defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{}
 This macro defines a new minor mode whose name is @var{mode} (a
 symbol).  It defines a command named @var{mode} to toggle the minor
-mode, with @var{doc} as its documentation string.  By default, it also
-defines a variable named @var{mode}, which is set to @code{t} or
-@code{nil} by enabling or disabling the mode.  The variable is
-initialized to @var{init-value}.  Except in unusual circumstances (see
-below), this value must be @code{nil}.
+mode, with @var{doc} as its documentation string.
+
+The toggle command takes one optional (prefix) argument.
+If called interactively with no argument it toggles the mode on or off.
+A positive prefix argument enables the mode, any other prefix argument
+disables it.  From Lisp, an argument of @code{toggle} toggles the mode,
+whereas an omitted or @code{nil} argument enables the mode.
+This makes it easy to enable the minor mode in a major mode hook, for example.
+If @var{doc} is nil, the macro supplies a default documentation string
+explaining the above.
+
+By default, it also defines a variable named @var{mode}, which is set to
+@code{t} or @code{nil} by enabling or disabling the mode.  The variable
+is initialized to @var{init-value}.  Except in unusual circumstances
+(see below), this value must be @code{nil}.
 
 The string @var{lighter} says what to display in the mode line
 when the mode is enabled; if it is @code{nil}, the mode is not displayed
@@ -1470,9 +1488,10 @@ for this macro.
 @smallexample
 (define-minor-mode hungry-mode
   "Toggle Hungry mode.
-With no argument, this command toggles the mode.
-Non-null prefix argument turns on the mode.
-Null prefix argument turns off the mode.
+Interactively with no argument, this command toggles the mode.
+A positive prefix argument enables the mode, any other prefix
+argument disables it.  From Lisp, argument omitted or nil enables
+the mode, `toggle' toggles the state.
 
 When Hungry mode is enabled, the control delete key
 gobbles all preceding whitespace except the last.
@@ -1501,13 +1520,7 @@ minor modes don't need any.
 @smallexample
 (define-minor-mode hungry-mode
   "Toggle Hungry mode.
-With no argument, this command toggles the mode.
-Non-null prefix argument turns on the mode.
-Null prefix argument turns off the mode.
-
-When Hungry mode is enabled, the control delete key
-gobbles all preceding whitespace except the last.
-See the command \\[hungry-electric-delete]."
+...rest of documentation as before..."
  ;; The initial value.
  :init-value nil
  ;; The indicator for the mode line.
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index bdb16cd10a8..ab3a4edc0ac 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1317,11 +1317,12 @@ value (@pxref{Default Value}) of @var{variable} instead.
 
 @defun buffer-local-variables &optional buffer
 This function returns a list describing the buffer-local variables in
-buffer @var{buffer}.  (If @var{buffer} is omitted, the current buffer is
-used.)  It returns an association list (@pxref{Association Lists}) in
-which each element contains one buffer-local variable and its value.
-However, when a variable's buffer-local binding in @var{buffer} is void,
-then the variable appears directly in the resulting list.
+buffer @var{buffer}.  (If @var{buffer} is omitted, the current buffer
+is used.)  Normally, each list element has the form
+@w{@code{(@var{sym} . @var{val})}}, where @var{sym} is a buffer-local
+variable (a symbol) and @var{val} is its buffer-local value.  But when
+a variable's buffer-local binding in @var{buffer} is void, its list
+element is just @var{sym}.
 
 @example
 @group