Merge from trunk.

12 files changed, 526 insertions, 193 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index fbdb6363b34..9fad60d2a8c 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,8 @@
+2012-11-16  Eli Zaretskii  <eliz@gnu.org>
+
+        * trouble.texi (Crashing): Add information about MS-Windows and
+        the emacs_backtrace.txt file.  (Bug#12908)
+
 2012-11-13  Chong Yidong  <cyd@gnu.org>
 
         * building.texi (Multithreaded Debugging): gdb-stopped-hooks is
diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi
index 1a891a62b33..705cd5a4bbe 100644
--- a/doc/emacs/trouble.texi
+++ b/doc/emacs/trouble.texi
@@ -282,18 +282,23 @@ itself, and the reserve supply may not be enough.
 @subsection When Emacs Crashes
 
 @cindex crash report
+@cindex backtrace
+@cindex @file{emacs_backtrace.txt} file, MS-Windows
   Emacs is not supposed to crash, but if it does, it produces a
 @dfn{crash report} prior to exiting.  The crash report is printed to
 the standard error stream.  If Emacs was started from a graphical
-desktop, the standard error stream is commonly redirected to a file
-such as @file{~/.xsession-errors}, so you can look for the crash
-report there.
+desktop on a GNU or Unix system, the standard error stream is commonly
+redirected to a file such as @file{~/.xsession-errors}, so you can
+look for the crash report there.  On MS-Windows, the crash report is
+written to a file named @file{emacs_backtrace.txt} in the current
+directory of the Emacs process, in addition to the standard error
+stream.
 
   The format of the crash report depends on the platform.  On some
 platforms, such as those using the GNU C Library, the crash report
 includes a @dfn{backtrace} describing the execution state prior to
 crashing, which can be used to help debug the crash.  Here is an
-example:
+example for a GNU system:
 
 @example
 Fatal error 11: Segmentation fault
@@ -320,22 +325,24 @@ backtrace with source-code line numbers:
 
 @example
 sed -n 's/.*\[\(.*\)]$/\1/p' @var{backtrace} |
-  addr2line -Cfip -e @var{bindir}/emacs
+  addr2line -Cfip -e @var{bindir}/@var{emacs-binary}
 @end example
 
 @noindent
 Here, @var{backtrace} is the name of a text file containing a copy of
-the backtrace, and @var{bindir} is the name of the directory that
-contains the Emacs executable.
+the backtrace, @var{bindir} is the name of the directory that
+contains the Emacs executable, and @var{emacs-binary} is the name of
+the Emacs executable file, normally @file{emacs} on GNU and Unix
+systems and @file{emacs.exe} on MS-Windows and MS-DOS.
 
 @cindex core dump
-  Optionally, Emacs can generate a @dfn{core dump} when it crashes.  A
-core dump is a file containing voluminous data about the state of the
-program prior to the crash, usually examined by loading it into a
-debugger such as GDB.  On many platforms, core dumps are disabled by
-default, and you must explicitly enable them by running the shell
-command @samp{ulimit -c unlimited} (e.g.@: in your shell startup
-script).
+  Optionally, Emacs can generate a @dfn{core dump} when it crashes, on
+systems that support core files.  A core dump is a file containing
+voluminous data about the state of the program prior to the crash,
+usually examined by loading it into a debugger such as GDB.  On many
+platforms, core dumps are disabled by default, and you must explicitly
+enable them by running the shell command @samp{ulimit -c unlimited}
+(e.g.@: in your shell startup script).
 
 @node After a Crash
 @subsection Recovery After a Crash
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 6d6ddf4da9a..8c1a863371b 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,35 @@
+2012-11-16  Martin Rudalics  <rudalics@gmx.at>
+
+        * windows.texi (Choosing Window): Rewrite description of
+        display-buffer-alist (Bug#12167).
+        (Display Action Functions): Mention inhibit-switch-frame.  Fix
+        description of display-buffer-below-selected.  Reorder actions.
+        Add example (Bug#12848).
+
+2012-11-16  Glenn Morris  <rgm@gnu.org>
+
+        * display.texi (Face Attributes): Fix :underline COLOR description.
+        (Attribute Functions): Update for set-face-underline rename.
+        Tweak descriptions of face-underline-p, face-inverse-video-p.
+
+        * keymaps.texi (Searching Keymaps, Tool Bar): Untabify examples,
+        so they align better in info.
+        (Active Keymaps, Searching Keymaps, Controlling Active Maps):
+        Document set-temporary-overlay-map.
+
+2012-11-15  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * keymaps.texi (Translation Keymaps): Add a subsection "Interaction
+        with normal keymaps".
+
+2012-11-15  Dmitry Antipov  <dmantipov@yandex.ru>
+
+        * internals.texi (Garbage Collection): Update descriptions
+        of vectorlike_header, garbage-collect and gc-cons-threshold.
+        (Object Internals): Explain Lisp_Object layout and the basics
+        of an internal type system.
+        (Buffer Internals): Update description of struct buffer.
+
 2012-11-13  Glenn Morris  <rgm@gnu.org>
 
         * variables.texi (Adding Generalized Variables):
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 68701a47126..9fedd162da6 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2009,12 +2009,11 @@ Don't underline.
 Underline with the foreground color of the face.
 
 @item @var{color}
-Underline in color @var{color}; which should be either a string
-specifying a color, or the symbol @code{foreground-color}, meaning the
-foreground color of the face.
+Underline in color @var{color}, a string specifying a color.
 
 @item @code{(:color @var{color} :style @var{style})}
-@var{color} is as described above.  Omitting the attribute
+@var{color} is either a string, or the symbol @code{foreground-color},
+meaning the foreground color of the face.  Omitting the attribute
 @code{:color} means to use the foreground color of the face.
 @var{style} should be a symbol @code{line} or @code{wave}, meaning to
 use a straight or wavy line.  Omitting the attribute @code{:style}
@@ -2404,7 +2403,7 @@ This sets the @code{:slant} attribute of @var{face} to @var{normal} if
 @var{italic-p} is @code{nil}, and to @var{italic} otherwise.
 @end defun
 
-@defun set-face-underline-p face underline &optional frame
+@defun set-face-underline face underline &optional frame
 This sets the @code{:underline} attribute of @var{face} to
 @var{underline}.
 @end defun
@@ -2467,12 +2466,16 @@ attribute of @var{face} is @code{italic} or @code{oblique}, and
 @code{nil} otherwise.
 @end defun
 
+@c Note the weasel words.  A face that inherits from an underlined
+@c face but does not specify :underline will return nil.
 @defun face-underline-p face &optional frame
-This function returns the @code{:underline} attribute of face @var{face}.
+This function returns non-@code{nil} if face @var{face} specifies
+a non-@code{nil} @code{:underline} attribute.
 @end defun
 
 @defun face-inverse-video-p face &optional frame
-This function returns the @code{:inverse-video} attribute of face @var{face}.
+This function returns non-@code{nil} if face @var{face} specifies
+a non-@code{nil} @code{:inverse-video} attribute.
 @end defun
 
 @node Displaying Faces
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index 1459f52d979..2a2846921c5 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -226,12 +226,11 @@ of 8k bytes, and small vectors are packed into blocks of 4k bytes).
   Beyond the basic vector, a lot of objects like window, buffer, and
 frame are managed as if they were vectors.  The corresponding C data
 structures include the @code{struct vectorlike_header} field whose
-@code{next} field points to the next object in the chain:
-@code{header.next.buffer} points to the next buffer (which could be
-a killed buffer), and @code{header.next.vector} points to the next
-vector in a free list.  If a vector is small (smaller than or equal to
-@code{VBLOCK_BYTES_MAX} bytes, see @file{alloc.c}), then
-@code{header.next.nbytes} contains the vector size in bytes.
+@code{size} member contains the subtype enumerated by @code{enum pvec_type}
+and an information about how many @code{Lisp_Object} fields this structure
+contains and what the size of the rest data is.  This information is
+needed to calculate the memory footprint of an object, and used
+by the vector allocation code while iterating over the vector blocks.
 
 @cindex garbage collection
   It is quite common to use some storage for a while, then release it
@@ -284,88 +283,147 @@ the amount of space in use.  (Garbage collection can also occur
 spontaneously if you use more than @code{gc-cons-threshold} bytes of
 Lisp data since the previous garbage collection.)
 
-@code{garbage-collect} returns a list containing the following
-information:
+@code{garbage-collect} returns a list with information on amount of space in
+use, where each entry has the form @samp{(@var{name} @var{size} @var{used})}
+or @samp{(@var{name} @var{size} @var{used} @var{free})}.  In the entry,
+@var{name} is a symbol describing the kind of objects this entry represents,
+@var{size} is the number of bytes used by each one, @var{used} is the number
+of those objects that were found live in the heap, and optional @var{free} is
+the number of those objects that are not live but that Emacs keeps around for
+future allocations.  So an overall result is:
 
 @example
-@group
-((@var{used-conses} . @var{free-conses})
- (@var{used-syms} . @var{free-syms})
-@end group
- (@var{used-miscs} . @var{free-miscs})
- @var{used-string-chars}
- @var{used-vector-slots}
- (@var{used-floats} . @var{free-floats})
- (@var{used-intervals} . @var{free-intervals})
- (@var{used-strings} . @var{free-strings}))
+((@code{conses} @var{cons-size} @var{used-conse} @var{free-conses})
+ (@code{symbols} @var{symbol-size} @var{used-symbols} @var{free-symbols})
+ (@code{miscs} @var{misc-size} @var{used-miscs} @var{free-miscs})
+ (@code{strings} @var{string-size} @var{used-strings} @var{free-strings})
+ (@code{string-bytes} @var{byte-size} @var{used-bytes})
+ (@code{vectors} @var{vector-size} @var{used-vectors})
+ (@code{vector-slots} @var{slot-size} @var{used-slots} @var{free-slots})
+ (@code{floats} @var{float-size} @var{used-floats} @var{free-floats})
+ (@code{intervals} @var{interval-size} @var{used-intervals} @var{free-intervals})
+ (@code{buffers} @var{buffer-size} @var{used-buffers})
+ (@code{heap} @var{unit-size} @var{total-size} @var{free-size}))
 @end example
 
 Here is an example:
 
 @example
-@group
 (garbage-collect)
-     @result{} ((106886 . 13184) (9769 . 0)
-                (7731 . 4651) 347543 121628
-                (31 . 94) (1273 . 168)
-                (25474 . 3569))
-@end group
+      @result{} ((conses 16 49126 8058) (symbols 48 14607 0)
+                 (miscs 40 34 56) (strings 32 2942 2607)
+                 (string-bytes 1 78607) (vectors 16 7247)
+                 (vector-slots 8 341609 29474) (floats 8 71 102)
+                 (intervals 56 27 26) (buffers 944 8)
+                 (heap 1024 11715 2678))
 @end example
 
-Here is a table explaining each element:
+Below is a table explaining each element.  Note that last @code{heap} entry
+is optional and present only if an underlying @code{malloc} implementation
+provides @code{mallinfo} function.
 
 @table @var
+@item cons-size
+Internal size of a cons cell, i.e.@: @code{sizeof (struct Lisp_Cons)}.
+
 @item used-conses
 The number of cons cells in use.
 
 @item free-conses
-The number of cons cells for which space has been obtained from the
-operating system, but that are not currently being used.
+The number of cons cells for which space has been obtained from
+the operating system, but that are not currently being used.
 
-@item used-syms
+@item symbol-size
+Internal size of a symbol, i.e.@: @code{sizeof (struct Lisp_Symbol)}.
+
+@item used-symbols
 The number of symbols in use.
 
-@item free-syms
-The number of symbols for which space has been obtained from the
-operating system, but that are not currently being used.
+@item free-symbols
+The number of symbols for which space has been obtained from
+the operating system, but that are not currently being used.
+
+@item misc-size
+Internal size of a miscellaneous entity, i.e.@:
+@code{sizeof (union Lisp_Misc)}, which is a size of the
+largest type enumerated in @code{enum Lisp_Misc_Type}.
 
 @item used-miscs
-The number of miscellaneous objects in use.  These include markers and
-overlays, plus certain objects not visible to users.
+The number of miscellaneous objects in use.  These include markers
+and overlays, plus certain objects not visible to users.
 
 @item free-miscs
 The number of miscellaneous objects for which space has been obtained
 from the operating system, but that are not currently being used.
 
-@item used-string-chars
-The total size of all strings, in characters.
+@item string-size
+Internal size of a string header, i.e.@: @code{sizeof (struct Lisp_String)}.
+
+@item used-strings
+The number of string headers in use.
+
+@item free-strings
+The number of string headers for which space has been obtained
+from the operating system, but that are not currently being used.
+
+@item byte-size
+This is used for convenience and equals to @code{sizeof (char)}.
+
+@item used-bytes
+The total size of all string data in bytes.
+
+@item vector-size
+Internal size of a vector header, i.e.@: @code{sizeof (struct Lisp_Vector)}.
 
-@item used-vector-slots
-The total number of elements of existing vectors.
+@item used-vectors
+The number of vector headers allocated from the vector blocks.
+
+@item slot-size
+Internal size of a vector slot, always equal to @code{sizeof (Lisp_Object)}.
+
+@item used-slots
+The number of slots in all used vectors.
+
+@item free-slots
+The number of free slots in all vector blocks.
+
+@item float-size
+Internal size of a float object, i.e.@: @code{sizeof (struct Lisp_Float)}.
+(Do not confuse it with the native platform @code{float} or @code{double}.)
 
 @item used-floats
 The number of floats in use.
 
 @item free-floats
-The number of floats for which space has been obtained from the
-operating system, but that are not currently being used.
+The number of floats for which space has been obtained from
+the operating system, but that are not currently being used.
+
+@item interval-size
+Internal size of an interval object, i.e.@: @code{sizeof (struct interval)}.
 
 @item used-intervals
-The number of intervals in use.  Intervals are an internal
-data structure used for representing text properties.
+The number of intervals in use.
 
 @item free-intervals
-The number of intervals for which space has been obtained
-from the operating system, but that are not currently being used.
+The number of intervals for which space has been obtained from
+the operating system, but that are not currently being used.
 
-@item used-strings
-The number of strings in use.
+@item buffer-size
+Internal size of a buffer, i.e.@: @code{sizeof (struct buffer)}.
+(Do not confuse with the value returned by @code{buffer-size} function.)
 
-@item free-strings
-The number of string headers for which the space was obtained from the
-operating system, but which are currently not in use.  (A string
-object consists of a header and the storage for the string text
-itself; the latter is only allocated when the string is created.)
+@item used-buffers
+The number of buffer objects in use.  This includes killed buffers
+invisible to users, i.e.@: all buffers in @code{all_buffers} list.
+
+@item unit-size
+The unit of heap space measurement, always equal to 1024 bytes.
+
+@item total-size
+Total heap size, in @var{unit-size} units.
+
+@item free-size
+Heap space which is not currently used, in @var{unit-size} units.
 @end table
 
 If there was overflow in pure space (@pxref{Pure Storage}),
@@ -388,23 +446,25 @@ careful writing them.
 @defopt gc-cons-threshold
 The value of this variable is the number of bytes of storage that must
 be allocated for Lisp objects after one garbage collection in order to
-trigger another garbage collection.  A cons cell counts as eight bytes,
-a string as one byte per character plus a few bytes of overhead, and so
-on; space allocated to the contents of buffers does not count.  Note
-that the subsequent garbage collection does not happen immediately when
-the threshold is exhausted, but only the next time the Lisp evaluator is
-called.
-
-The initial threshold value is 800,000.  If you specify a larger
-value, garbage collection will happen less often.  This reduces the
-amount of time spent garbage collecting, but increases total memory use.
-You may want to do this when running a program that creates lots of
-Lisp data.
-
-You can make collections more frequent by specifying a smaller value,
-down to 10,000.  A value less than 10,000 will remain in effect only
-until the subsequent garbage collection, at which time
-@code{garbage-collect} will set the threshold back to 10,000.
+trigger another garbage collection.  You can use the result returned by
+@code{garbage-collect} to get an information about size of the particular
+object type; space allocated to the contents of buffers does not count.
+Note that the subsequent garbage collection does not happen immediately
+when the threshold is exhausted, but only the next time the Lisp interpreter
+is called.
+
+The initial threshold value is @code{GC_DEFAULT_THRESHOLD}, defined in
+@file{alloc.c}.  Since it's defined in @code{word_size} units, the value
+is 400,000 for the default 32-bit configuration and 800,000 for the 64-bit
+one.  If you specify a larger value, garbage collection will happen less
+often.  This reduces the amount of time spent garbage collecting, but
+increases total memory use.  You may want to do this when running a program
+that creates lots of Lisp data.
+
+You can make collections more frequent by specifying a smaller value, down
+to 1/10th of @code{GC_DEFAULT_THRESHOLD}.  A value less than this minimum
+will remain in effect only until the subsequent garbage collection, at which
+time @code{garbage-collect} will set the threshold back to the minimum.
 @end defopt
 
 @defopt gc-cons-percentage
@@ -639,7 +699,12 @@ in the file @file{lisp.h}.)  If the primitive has no upper limit on
 the number of Lisp arguments, it must have exactly two C arguments:
 the first is the number of Lisp arguments, and the second is the
 address of a block containing their values.  These have types
-@code{int} and @w{@code{Lisp_Object *}} respectively.
+@code{int} and @w{@code{Lisp_Object *}} respectively.  Since 
+@code{Lisp_Object} can hold any Lisp object of any data type, you
+can determine the actual data type only at run time; so if you want
+a primitive to accept only a certain type of argument, you must check
+the type explicitly using a suitable predicate (@pxref{Type Predicates}).
+@cindex type checking internals
 
 @cindex @code{GCPRO} and @code{UNGCPRO}
 @cindex protect C variables from garbage collection
@@ -820,23 +885,70 @@ knows about it.
 @section Object Internals
 @cindex object internals
 
-@c FIXME Is this still true?  Does --with-wide-int affect anything?
-  GNU Emacs Lisp manipulates many different types of data.  The actual
-data are stored in a heap and the only access that programs have to it
-is through pointers.  Each pointer is 32 bits wide on 32-bit machines,
-and 64 bits wide on 64-bit machines; three of these bits are used for
-the tag that identifies the object's type, and the remainder are used
-to address the object.
-
-  Because Lisp objects are represented as tagged pointers, it is always
-possible to determine the Lisp data type of any object.  The C data type
-@code{Lisp_Object} can hold any Lisp object of any data type.  Ordinary
-variables have type @code{Lisp_Object}, which means they can hold any
-type of Lisp value; you can determine the actual data type only at run
-time.  The same is true for function arguments; if you want a function
-to accept only a certain type of argument, you must check the type
-explicitly using a suitable predicate (@pxref{Type Predicates}).
-@cindex type checking internals
+  Emacs Lisp provides a rich set of the data types.  Some of them, like cons
+cells, integers and stirngs, are common to nearly all Lisp dialects.  Some
+others, like markers and buffers, are quite special and needed to provide
+the basic support to write editor commands in Lisp.  To implement such
+a variety of object types and provide an efficient way to pass objects between
+the subsystems of an interpreter, there is a set of C data structures and
+a special type to represent the pointers to all of them, which is known as
+@dfn{tagged pointer}.
+
+  In C, the tagged pointer is an object of type @code{Lisp_Object}.  Any
+initialized variable of such a type always holds the value of one of the
+following basic data types: integer, symbol, string, cons cell, float,
+vectorlike or miscellaneous object.  Each of these data types has the
+corresponding tag value.  All tags are enumerated by @code{enum Lisp_Type}
+and placed into a 3-bit bitfield of the @code{Lisp_Object}.  The rest of the
+bits is the value itself.  Integer values are immediate, i.e.@: directly
+represented by those @dfn{value bits}, and all other objects are represented
+by the C pointers to a corresponding object allocated from the heap.  Width
+of the @code{Lisp_Object} is platform- and configuration-dependent: usually
+it's equal to the width of an underlying platform pointer (i.e.@: 32-bit on
+a 32-bit machine and 64-bit on a 64-bit one), but also there is a special
+configuration where @code{Lisp_Object} is 64-bit but all pointers are 32-bit.
+The latter trick was designed to overcome the limited range of values for
+Lisp integers on a 32-bit system by using 64-bit @code{long long} type for
+@code{Lisp_Object}.
+
+  The following C data structures are defined in @file{lisp.h} to represent
+the basic data types beyond integers:
+
+@table @code
+@item struct Lisp_Cons
+Cons cell, an object used to construct lists.
+
+@item struct Lisp_String
+String, the basic object to represent a sequence of characters.
+
+@item struct Lisp_Vector
+Array, a fixed-size set of Lisp objects which may be accessed by an index.
+
+@item struct Lisp_Symbol
+Symbol, the unique-named entity commonly used as an identifier.
+
+@item struct Lisp_Float
+Floating point value.
+
+@item union Lisp_Misc
+Miscellaneous kinds of objects which don't fit into any of the above.
+@end table
+
+  These types are the first-class citizens of an internal type system.
+Since the tag space is limited, all other types are the subtypes of either
+@code{Lisp_Vectorlike} or @code{Lisp_Misc}.  Vector subtypes are enumerated
+by @code{enum pvec_type}, and nearly all complex objects like windows, buffers,
+frames, and processes fall into this category.  The rest of special types,
+including markers and overlays, are enumerated by @code{enum Lisp_Misc_Type}
+and form the set of subtypes of @code{Lisp_Misc}.
+
+  Below there is a description of a few subtypes of @code{Lisp_Vectorlike}.
+Buffer object represents the text to display and edit.  Window is the part
+of display structure which shows the buffer or used as a container to
+recursively place other windows on the same frame.  (Do not confuse Emacs Lisp
+window object with the window as an entity managed by the user interface
+system like X; in Emacs terminology, the latter is called frame.)  Finally,
+process object is used to manage the subprocesses.
 
 @menu
 * Buffer Internals::    Components of a buffer structure.
@@ -912,12 +1024,8 @@ Some of the fields of @code{struct buffer} are:
 
 @table @code
 @item header
-A @code{struct vectorlike_header} structure where @code{header.next}
-points to the next buffer, in the chain of all buffers (including
-killed buffers).  This chain is used only for garbage collection, in
-order to collect killed buffers properly.  Note that vectors, and most
-kinds of objects allocated as vectors, are all on one chain, but
-buffers are on a separate chain of their own.
+A header of type @code{struct vectorlike_header} is common to all
+vectorlike objects.
 
 @item own_text
 A @code{struct buffer_text} structure that ordinarily holds the buffer
@@ -928,6 +1036,11 @@ A pointer to the @code{buffer_text} structure for this buffer.  In an
 ordinary buffer, this is the @code{own_text} field above.  In an
 indirect buffer, this is the @code{own_text} field of the base buffer.
 
+@item next
+A pointer to the next buffer, in the chain of all buffers, including
+killed buffers.  This chain is used only for allocation and garbage
+collection, in order to collect killed buffers properly.
+
 @item pt
 @itemx pt_byte
 The character and byte positions of point in a buffer.
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index f658f7e66fb..d01ecba4bed 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -664,7 +664,9 @@ additional active keymaps through the variable
 
   The highest precedence normal keymap comes from the @code{keymap}
 text or overlay property.  If that is non-@code{nil}, it is the first
-keymap to be processed, in normal circumstances.
+keymap to be processed, in normal circumstances.  Next comes
+any keymap added by the function @code{set-temporary-overlay-map}.
+@xref{Controlling Active Maps}.
 
   However, there are also special ways for programs to substitute
 other keymaps for some of those.  The variable
@@ -753,12 +755,13 @@ them:
      (overriding-local-map
       (@var{find-in} overriding-local-map))
      ((or (@var{find-in} (get-char-property (point) 'keymap))
-          (@var{find-in-any} emulation-mode-map-alists)
-          (@var{find-in-any} minor-mode-overriding-map-alist)
-          (@var{find-in-any} minor-mode-map-alist)
-          (if (get-text-property (point) 'local-map)
-              (@var{find-in} (get-char-property (point) 'local-map))
-            (@var{find-in} (current-local-map))))))
+          (@var{find-in} @var{temp-map})
+          (@var{find-in-any} emulation-mode-map-alists)
+          (@var{find-in-any} minor-mode-overriding-map-alist)
+          (@var{find-in-any} minor-mode-map-alist)
+          (if (get-text-property (point) 'local-map)
+              (@var{find-in} (get-char-property (point) 'local-map))
+            (@var{find-in} (current-local-map))))))
     (@var{find-in} (current-global-map)))
 @end lisp
 
@@ -770,7 +773,8 @@ Lookup}.)  If the key sequence starts with a mouse event, or a
 symbolic prefix event followed by a mouse event, that event's position
 is used instead of point and the current buffer.  Mouse events on an
 embedded string use non-@code{nil} text properties from that string
-instead of the buffer.
+instead of the buffer.  @var{temp-map} is a pseudo variable that
+represents the effect of a @code{set-temporary-overlay-map} call.
 
   When a match is found (@pxref{Key Lookup}), if the binding in the
 keymap is a function, the search is over.  However if the keymap entry
@@ -950,6 +954,21 @@ are used before @code{minor-mode-map-alist} and
 @code{minor-mode-overriding-map-alist}.
 @end defvar
 
+@defun set-temporary-overlay-map keymap &optional keep
+This function adds @var{keymap} as a temporary keymap that takes
+precedence over most other keymaps.  It does not take precedence over
+the ``overriding'' maps (see above); and unlike them, if no match for
+a key is found in @var{keymap}, the search continues.
+
+Normally, @var{keymap} is used only once.  If the optional argument
+@var{pred} is @code{t}, the map stays active if a key from @var{keymap}
+is used.  @var{pred} can also be a function of no arguments: if it returns
+non-@code{nil} then @var{keymap} stays active.
+
+For a pseudo-Lisp description of exactly how and when this keymap applies,
+@pxref{Searching Keymaps}.
+@end defun
+
 @node Key Lookup
 @section Key Lookup
 @cindex key lookup
@@ -1540,14 +1559,11 @@ sequence, to translate certain event sequences into others.
 being read, as it is read, against @code{input-decode-map}, then
 @code{local-function-key-map}, and then against @code{key-translation-map}.
 
-@defvar input-decode-map
-This variable holds a keymap that describes the character sequences sent
-by function keys on an ordinary character terminal.  This keymap has the
-same structure as other keymaps, but is used differently: it specifies
-translations to make while reading key sequences, rather than bindings
-for key sequences.
+These keymaps have the same structure as other keymaps, but they are used
+differently: they specify translations to make while reading key sequences,
+rather than bindings for key sequences.
 
-If @code{input-decode-map} ``binds'' a key sequence @var{k} to a vector
+If one of these keymaps ``binds'' a key sequence @var{k} to a vector
 @var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
 key sequence, it is replaced with the events in @var{v}.
 
@@ -1562,6 +1578,10 @@ Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c
 this back into @kbd{C-c @key{PF1}}, which it returns as the vector
 @code{[?\C-c pf1]}.
 
+@defvar input-decode-map
+This variable holds a keymap that describes the character sequences sent
+by function keys on an ordinary character terminal.
+
 The value of @code{input-decode-map} is usually set up automatically
 according to the terminal's Terminfo or Termcap entry, but sometimes
 those need help from terminal-specific Lisp files.  Emacs comes with
@@ -1636,8 +1656,6 @@ to turn the character that follows into a Hyper character:
   (let ((symbol (if (symbolp e) e (car e))))
     (setq symbol (intern (concat string
                                  (symbol-name symbol))))
-@end group
-@group
     (if (symbolp e)
         symbol
       (cons symbol (cdr e)))))
@@ -1647,10 +1665,30 @@ to turn the character that follows into a Hyper character:
 @end example
 
   If you have enabled keyboard character set decoding using
-@code{set-keyboard-coding-system}, decoding is done after the
-translations listed above.  @xref{Terminal I/O Encoding}.  However, in
-future Emacs versions, character set decoding may be done at an
-earlier stage.
+@code{set-keyboard-coding-system}, decoding is done before the
+translations listed above.  @xref{Terminal I/O Encoding}.
+
+@subsection Interaction with normal keymaps
+
+The end of a key sequence is detected when that key sequence either is bound
+to a command, or when Emacs determines that no additional event can lead
+to a sequence that is bound to a command.
+
+This means that, while @code{input-decode-map} and @code{key-translation-map}
+apply regardless of whether the original key sequence would have a binding, the
+presence of such a binding can still prevent translation from taking place.
+For example, let us return to our VT100 example above and add a binding for
+@kbd{C-c @key{ESC}} to the global map; now when the user hits @kbd{C-c
+@key{PF1}} Emacs will fail to decode @kbd{C-c @key{ESC} O P} into @kbd{C-c
+@key{PF1}} because it will stop reading keys right after @kbd{C-x @key{ESC}},
+leaving @kbd{O P} for later.  This is in case the user really hit @kbd{C-c
+@key{ESC}}, in which case Emacs should not sit there waiting for the next key
+to decide whether the user really pressed @kbd{@key{ESC}} or @kbd{@key{PF1}}.
+
+For that reason, it is better to avoid binding commands to key sequences where
+the end of the key sequence is a prefix of a key translation.  The main such
+problematic suffixes/prefixes are @kbd{@key{ESC}}, @kbd{M-O} (which is really
+@kbd{@key{ESC} O}) and @kbd{M-[} (which is really @kbd{@key{ESC} [}).
 
 @node Key Binding Commands
 @section Commands for Binding Keys
@@ -2629,8 +2667,8 @@ By default, the global map binds @code{[tool-bar]} as follows:
 
 @example
 (global-set-key [tool-bar]
-                `(menu-item ,(purecopy "tool bar") ignore
-                            :filter tool-bar-make-keymap))
+                `(menu-item ,(purecopy "tool bar") ignore
+                            :filter tool-bar-make-keymap))
 @end example
 
 @noindent
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index bb02b1d54fd..efbfebc670f 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -1055,7 +1055,7 @@ including the space earlier stolen from @code{W3}.
 @end smallexample
 
 @noindent
-This can be counterintutive, in particular if @code{W4} were used for
+This can be counterintuitive, in particular if @code{W4} were used for
 displaying a buffer only temporarily (@pxref{Temporary Displays}), and
 you want to continue working with the initial layout.
 
@@ -1766,6 +1766,7 @@ Like @code{switch-to-buffer}, this function updates the buffer list
 unless @var{norecord} is non-@code{nil}.
 @end deffn
 
+
 @node Choosing Window
 @section Choosing a Window for Display
 
@@ -1851,10 +1852,14 @@ default value is empty, i.e. @code{(nil . nil)}.
 @end defvar
 
 @defopt display-buffer-alist
-The value of this option is an alist mapping regular expressions to
-display actions.  If the name of the buffer passed to
-@code{display-buffer} matches a regular expression in this alist, then
-@code{display-buffer} uses the corresponding display action.
+The value of this option is an alist mapping conditions to display
+actions.  Each condition may be either a regular expression matching a
+buffer name or a function that takes two arguments - a buffer name and
+the @var{action} argument passed to @code{display-buffer}.  If the name
+of the buffer passed to @code{display-buffer} either matches a regular
+expression in this alist or the function specified by a condition
+returns non-@code{nil}, then @code{display-buffer} uses the
+corresponding display action to display the buffer.
 @end defopt
 
 @defopt display-buffer-base-action
@@ -1868,6 +1873,7 @@ This display action specifies the fallback behavior for
 @code{display-buffer} if no other display actions are given.
 @end defvr
 
+
 @node Display Action Functions
 @section Action Functions for @code{display-buffer}
 
@@ -1911,8 +1917,9 @@ normally searches just the selected frame; however, if the variable
 @code{pop-up-frames} is non-@code{nil}, it searches all frames on the
 current terminal.  @xref{Choosing Window Options}.
 
-If this function chooses a window on another frame, it makes that
-frame visible and raises it if necessary.
+If this function chooses a window on another frame, it makes that frame
+visible and, unless @var{alist} contains an @code{inhibit-switch-frame}
+entry (@pxref{Choosing Window Options}), raises that frame if necessary.
 @end defun
 
 @defun display-buffer-pop-up-frame buffer alist
@@ -1976,16 +1983,12 @@ reason (e.g. if there is just one frame and it has an
 @code{unsplittable} frame parameter; @pxref{Buffer Parameters}).
 @end defun
 
-@defun display-buffer-use-some-window buffer alist
-This function tries to display @var{buffer} by choosing an existing
-window and displaying the buffer in that window.  It can fail if all
-windows are dedicated to another buffer (@pxref{Dedicated Windows}).
-@end defun
-
 @defun display-buffer-below-selected buffer alist
 This function tries to display @var{buffer} in a window below the
-selected window.  This means to either split the selected window or
-reuse the window below the selected one.
+selected window.  This means to either split the selected window or use
+the window below the selected one.  If it does create a new window, it
+will also adjust its size provided @var{alist} contains a suitable
+@code{window-height} or @code{window-width} entry, see above.
 @end defun
 
 @defun display-buffer-in-previous-window buffer alist
@@ -2001,6 +2004,83 @@ specified by that entry will override any other window found by the
 methods above, even if that window never showed @var{buffer} before.
 @end defun
 
+@defun display-buffer-use-some-window buffer alist
+This function tries to display @var{buffer} by choosing an existing
+window and displaying the buffer in that window.  It can fail if all
+windows are dedicated to another buffer (@pxref{Dedicated Windows}).
+@end defun
+
+To illustrate the use of action functions, consider the following
+example.
+
+@example
+@group
+(display-buffer
+ (get-buffer-create "*foo*")
+ '((display-buffer-reuse-window
+    display-buffer-pop-up-window
+    display-buffer-pop-up-frame)
+   (reusable-frames . 0)
+   (window-height . 10) (window-width . 40)))
+@end group
+@end example
+
+@noindent
+Evaluating the form above will cause @code{display-buffer} to proceed as
+follows: If `*foo*' already appears on a visible or iconified frame, it
+will reuse its window.  Otherwise, it will try to pop up a new window
+or, if that is impossible, a new frame.  If all these steps fail, it
+will try to use some existing window.
+
+   Furthermore, @code{display-buffer} will try to adjust a reused window
+(provided `*foo*' was put by @code{display-buffer} there before) or a
+popped-up window as follows: If the window is part of a vertical
+combination, it will set its height to ten lines.  Note that if, instead
+of the number ``10'', we specified the function
+@code{fit-window-to-buffer}, @code{display-buffer} would come up with a
+one-line window to fit the empty buffer.  If the window is part of a
+horizontal combination, it sets its width to 40 columns.  Whether a new
+window is vertically or horizontally combined depends on the shape of
+the window split and the values of
+@code{split-window-preferred-function}, @code{split-height-threshold}
+and @code{split-width-threshold} (@pxref{Choosing Window Options}).
+
+   Now suppose we combine this call with a preexisting setup for
+`display-buffer-alist' as follows.
+
+@example
+@group
+(let ((display-buffer-alist
+       (cons
+        '("\\*foo\\*"
+          (display-buffer-reuse-window display-buffer-below-selected)
+          (reusable-frames)
+          (window-height . 5))
+        display-buffer-alist)))
+  (display-buffer
+   (get-buffer-create "*foo*")
+   '((display-buffer-reuse-window
+      display-buffer-pop-up-window
+      display-buffer-pop-up-frame)
+     (reusable-frames . 0)
+     (window-height . 10) (window-width . 40))))
+@end group
+@end example
+
+@noindent
+Evaluating this form will cause @code{display-buffer} to first try
+reusing a window showing @code{*foo*} on the selected frame.
+If no such window exists, it will try to split the selected window or,
+if that is impossible, use the window below the selected window.
+
+   If there's no window below the selected one, or the window below the
+selected one is dedicated to its buffer, @code{display-buffer} will
+proceed as described in the previous example.  Note, however, that when
+it tries to adjust the height of any reused or popped-up window, it will
+in any case try to set its number of lines to ``5'' since that value
+overrides the corresponding specification in the @var{action} argument
+of @code{display-buffer}.
+
 
 @node Choosing Window Options
 @section Additional Options for Displaying Buffers
@@ -2343,7 +2423,7 @@ buffer previously shown no longer exists, this function calls
 @code{switch-to-prev-buffer} (@pxref{Window History}) to show some other
 buffer instead.
 
-The optional argument @var{bury-or-kill} specifes how to deal with
+The optional argument @var{bury-or-kill} specifies how to deal with
 @var{window}'s buffer.  The following values are handled:
 
 @table @code
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 7322613e0db..b31b67b5d84 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,14 @@
+2012-11-16  Glenn Morris  <rgm@gnu.org>
+
+        * cl.texi (Function Bindings): Clarify that cl-flet is lexical.
+        (Obsolete Macros): Move example here from Function Bindings.
+
+        * erc.texi: Use @code{nil} rather than just "nil".
+        (Modules): Undocument obsolete "hecomplete".
+        Add "notifications".
+        (Connecting): Add brief section on passwords.
+        (Options): Make a start by adding erc-hide-list, erc-lurker-hide-list.
+
 2012-11-13  Glenn Morris  <rgm@gnu.org>
 
         * flymake.texi (Customizable variables)
diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index a50be1027f3..beefa3e9c40 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -1292,28 +1292,14 @@ it were a @code{cl-defun} form.  The function @var{name} is defined
 accordingly for the duration of the body of the @code{cl-flet}; then
 the old function definition, or lack thereof, is restored.
 
-You can use @code{cl-flet} to disable or modify the behavior of a
-function in a temporary fashion.  (Compare this with the idea
-of advising functions.
+You can use @code{cl-flet} to disable or modify the behavior of
+functions (including Emacs primitives) in a temporary, localized fashion.
+(Compare this with the idea of advising functions.
 @xref{Advising Functions,,,elisp,GNU Emacs Lisp Reference Manual}.)
-This will even work on Emacs primitives, although note that some calls
-to primitive functions internal to Emacs are made without going
-through the symbol's function cell, and so will not be affected by
-@code{cl-flet}.  For example,
-
-@example
-(cl-flet ((message (&rest args) (push args saved-msgs)))
-    (do-something))
-@end example
 
-This code attempts to replace the built-in function @code{message}
-with a function that simply saves the messages in a list rather
-than displaying them.  The original definition of @code{message}
-will be restored after @code{do-something} exits.  This code will
-work fine on messages generated by other Lisp code, but messages
-generated directly inside Emacs will not be caught since they make
-direct C-language calls to the message routines rather than going
-through the Lisp @code{message} function.
+The bindings are lexical in scope.  This means that all references to
+the named functions must appear physically within the body of the
+@code{cl-flet} form.
 
 Functions defined by @code{cl-flet} may use the full Common Lisp
 argument notation supported by @code{cl-defun}; also, the function
@@ -1321,7 +1307,8 @@ body is enclosed in an implicit block as if by @code{cl-defun}.
 @xref{Program Structure}.
 
 Note that the @file{cl.el} version of this macro behaves slightly
-differently.  @xref{Obsolete Macros}.
+differently.  In particular, its binding is dynamic rather than
+lexical.  @xref{Obsolete Macros}.
 @end defmac
 
 @defmac cl-labels (bindings@dots{}) forms@dots{}
@@ -4863,6 +4850,25 @@ time before Emacs had lexical binding).  The result is
 that @code{flet} affects indirect calls to a function as well as calls
 directly inside the @code{flet} form itself.
 
+This will even work on Emacs primitives, although note that some calls
+to primitive functions internal to Emacs are made without going
+through the symbol's function cell, and so will not be affected by
+@code{flet}.  For example,
+
+@example
+(flet ((message (&rest args) (push args saved-msgs)))
+  (do-something))
+@end example
+
+This code attempts to replace the built-in function @code{message}
+with a function that simply saves the messages in a list rather
+than displaying them.  The original definition of @code{message}
+will be restored after @code{do-something} exits.  This code will
+work fine on messages generated by other Lisp code, but messages
+generated directly inside Emacs will not be caught since they make
+direct C-language calls to the message routines rather than going
+through the Lisp @code{message} function.
+
 @c Bug#411.
 Note that many primitives (e.g.@: @code{+}) have special byte-compile
 handling.  Attempts to redefine such functions using @code{flet} will
diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi
index 378180bef31..834d2ea844d 100644
--- a/doc/misc/erc.texi
+++ b/doc/misc/erc.texi
@@ -390,11 +390,6 @@ Complete nicknames and commands (programmable)
 @item fill
 Wrap long lines
 
-@cindex modules, hecomplete
-@item hecomplete
-Complete nicknames and commands (old).  This is the old module---you
-might prefer the ``completion'' module instead.
-
 @cindex modules, identd
 @item identd
 Launch an identd server on port 8113
@@ -427,6 +422,11 @@ Don't display non-IRC commands after evaluation
 @item notify
 Notify when the online status of certain users changes
 
+@cindex modules, notifications
+@item notifications
+Send you a notification when you get a private message,
+or your nickname is mentioned
+
 @cindex modules, page
 @item page
 Process CTCP PAGE requests from IRC
@@ -530,7 +530,7 @@ parameters.
 @defun erc-compute-server &optional server
 Return an IRC server name.
 
-This tries a number of increasingly more default methods until a non-nil
+This tries a number of increasingly more default methods until a non-@code{nil}
 value is found.
 
 @itemize @bullet
@@ -542,7 +542,7 @@ value is found.
 
 @end defun
 
-@defopt erc-server nil
+@defopt erc-server
 IRC server to use if one is not provided.
 @end defopt
 
@@ -551,7 +551,7 @@ IRC server to use if one is not provided.
 @defun erc-compute-port &optional port
 Return a port for an IRC server.
 
-This tries a number of increasingly more default methods until a non-nil
+This tries a number of increasingly more default methods until a non-@code{nil}
 value is found.
 
 @itemize @bullet
@@ -574,7 +574,7 @@ This can be either a string or a number.
 Return user's IRC nick.
 
 This tries a number of increasingly more default methods until a
-non-nil value is found.
+non-@code{nil} value is found.
 
 @itemize
 @item @var{nick} (the argument passed to this function)
@@ -598,19 +598,43 @@ The string to append to the nick if it is already in use.
 @end defopt
 
 @defopt erc-try-new-nick-p
-If the nickname you chose isn't available, and this option is non-nil,
+If the nickname you chose isn't available, and this option is non-@code{nil},
 ERC should automatically attempt to connect with another nickname.
 
 You can manually set another nickname with the /NICK command.
 @end defopt
 
+@subheading Password
+@cindex password
+
+@defopt erc-prompt-for-password
+If non-@code{nil} (the default), @kbd{M-x erc} prompts for a password.
+@end defopt
+
+If you prefer, you can set this option to @code{nil} and use the
+@code{auth-source} mechanism to store your password.  For instance, if
+you use @file{~/.authinfo} as your auth-source backend, then put
+something like the following in that file:
+
+@example
+machine irc.example.net login "#fsf" password sEcReT
+@end example
+
+@noindent
+ERC also consults @code{auth-source} to find any channel keys required
+for the channels that you wish to autojoin, as specified by the
+variable @code{erc-autojoin-channels-alist}.
+
+For more details, @pxref{Top,,auth-source, auth, Emacs auth-source Library}.
+
+
 @subheading Full name
 
 @defun erc-compute-full-name &optional full-name
 Return user's full name.
 
 This tries a number of increasingly more default methods until a
-non-nil value is found.
+non-@code{nil} value is found.
 
 @itemize @bullet
 @item @var{full-name} (the argument passed to this function)
@@ -713,10 +737,24 @@ stuff, to the current ERC buffer."
 @c PRE5_4: (Node) Document every ERC option (module options go in
 @c previous chapter)
 
-This section has not yet been written.  For now, the easiest way to
-check out the available options for ERC is to do
+This section is extremely incomplete.  For now, the easiest way to
+check out all the available options for ERC is to do
 @kbd{M-x customize-group erc RET}.
 
+@defopt erc-hide-list
+If non, @code{nil}, this is a list of IRC message types to hide, e.g.
+
+@example
+(setq erc-hide-list '("JOIN" "PART" "QUIT"))
+@end example
+@end defopt
+
+@defopt erc-lurker-hide-list
+Like @code{erc-hide-list}, but only applies to messages sent by
+lurkers.  The function @code{erc-lurker-p} determines whether a given
+nickname is considerd a lurker.
+@end defopt
+
 
 @node Getting Help and Reporting Bugs
 @chapter Getting Help and Reporting Bugs
diff --git a/doc/misc/ses.texi b/doc/misc/ses.texi
index 5de87a2f1c7..cccd74dec0f 100644
--- a/doc/misc/ses.texi
+++ b/doc/misc/ses.texi
@@ -482,9 +482,9 @@ show column letters again.
 Pops up a menu to set the current row as the header, or revert to
 column letters.
 @item M-x ses-rename-cell
-@findex ses-rename-cell 
-Rename a cell from a standard A1-like name to any 
-string. 
+@findex ses-rename-cell
+Rename a cell from a standard A1-like name to any
+string.
 @item M-x ses-repair-cell-reference-all
 @findex ses-repair-cell-reference-all
 When you interrupt a cell formula update by clicking @kbd{C-g}, then
@@ -606,15 +606,15 @@ instance @code{(ses-range A1 A4 _ "empty")} will do the same as
 are empty. Similarly, @code{(ses-range A1 A4 _ )} will do the same as
 @code{(list A1 0 A3 0)}.
 @item >v
-When order matters, list cells by reading cells rowwise from top left
+When order matters, list cells by reading cells row-wise from top left
 to bottom right. This flag is provided for completeness only as it is
 the default reading order.
 @item <v
-List cells by reading cells rowwise from top right to bottom left.
+List cells by reading cells row-wise from top right to bottom left.
 @item v>
-List cells by reading cells columnwise from top left to bottom right.
+List cells by reading cells column-wise from top left to bottom right.
 @item v<
-List cells by reading cells columnwise from top right to bottom left.
+List cells by reading cells column-wise from top right to bottom left.
 @item v
 A short hand for @code{v>}.
 @item ^
diff --git a/doc/misc/url.texi b/doc/misc/url.texi
index fdb3ab452f2..90ab7f5554f 100644
--- a/doc/misc/url.texi
+++ b/doc/misc/url.texi
@@ -346,7 +346,7 @@ To use this function, you must @code{(require 'url-queue)}.
 The value of this option is an integer specifying the maximum number
 of concurrent @code{url-queue-retrieve} network processes.  If the
 number of @code{url-queue-retrieve} calls is larger than this number,
-later ones are queued until ealier ones are finished.
+later ones are queued until earlier ones are finished.
 @end defopt
 
 @vindex url-queue-timeout