1 files changed, 52 insertions, 19 deletions
diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index fe3ee57ac0a..0056906e1f7 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -275,8 +275,10 @@ a non-@code{nil} value.  There is no need to rescan because of small
 changes in the text.
 
 @vindex imenu-auto-rescan-maxout
+@vindex imenu-max-index-time
   @code{imenu-auto-rescan} will be disabled in buffers that are larger
-than @code{imenu-auto-rescan-maxout} in bytes.
+than @code{imenu-auto-rescan-maxout} in bytes, and scanning is
+stopped if it takes more than @code{imenu-max-index-time} seconds.
 
 @vindex imenu-sort-function
   You can customize the way the menus are sorted by setting the
@@ -469,6 +471,23 @@ the function name.  This is normally done for macro definitions, using
 the @code{declare} construct.  @xref{Defining Macros,,, elisp, The
 Emacs Lisp Reference Manual}.
 
+  In Emacs Lisp, lists are usually indented as if they are
+function-like forms:
+
+@lisp
+(setq foo '(bar zot
+                gazonk))
+@end lisp
+
+  However, if you add a space after the opening parenthesis, this tells
+Emacs that it's a data list instead of a piece of code, and Emacs will
+then indent it like this:
+
+@lisp
+(setq foo '( bar zot
+             gazonk))
+@end lisp
+
 @node C Indent
 @subsection Commands for C Indentation
 
@@ -809,41 +828,55 @@ displayed.  The default is 102400.
 @cindex Show Paren mode
 @cindex highlighting matching parentheses
 @findex show-paren-mode
-  Show Paren mode, a global minor mode, provides a more powerful kind
+@findex show-paren-local-mode
+  Show Paren mode is a minor mode that provides a more powerful kind
 of automatic matching.  Whenever point is before an opening delimiter
 or after a closing delimiter, the delimiter, its matching delimiter,
 and optionally the text between them are highlighted.  To toggle Show
-Paren mode, type @kbd{M-x show-paren-mode}.  To customize it, type
-@kbd{M-x customize-group @key{RET} paren-showing}.  The customizable
-options which control the operation of this mode include:
+Paren mode globally, type @kbd{M-x show-paren-mode}.  To toggle it
+only in the current buffer, type @kbd{M-x show-paren-local-mode}.  To
+customize it, type @w{@kbd{M-x customize-group @key{RET} paren-showing}}.
+The customizable options which control the operation of this mode
+include:
 
 @itemize @bullet
 @item
 @vindex show-paren-highlight-openparen
 @code{show-paren-highlight-openparen} controls whether to highlight
-an open paren when point stands just before it, and hence its position
+an open paren when point is just before it, and hence its position
 is marked by the cursor anyway.  The default is non-@code{nil} (yes).
 
 @item
 @vindex show-paren-style
 @code{show-paren-style} controls whether just the two parens, or also
-the space between them get highlighted.  The valid options here are
+the text between them get highlighted.  The valid options here are
 @code{parenthesis} (show the matching paren), @code{expression}
 (highlight the entire expression enclosed by the parens), and
-@code{mixed} (highlight the matching paren if it is visible, the
-expression otherwise).
+@code{mixed} (highlight the matching paren if it is visible in the
+window, the expression otherwise).
 
 @item
 @vindex show-paren-when-point-inside-paren
 @code{show-paren-when-point-inside-paren}, when non-@code{nil}, causes
-highlighting also when point is on the inside of a parenthesis.
+highlighting also when point is inside of the parentheses.  The
+default is @code{nil}.
 
 @item
 @vindex show-paren-when-point-in-periphery
 @code{show-paren-when-point-in-periphery}, when non-@code{nil}, causes
-highlighting also when point is in whitespace at the beginning or end
-of a line, and there is a paren at, respectively, the first or last,
-or the last, non-whitespace position on the line.
+highlighting also when point is in whitespace at the beginning of a
+line and there is a paren at the first or last non-whitespace position
+on the line, or when point is at the end of a line and there is a
+paren at the last non-whitespace position on the line.
+
+@item
+@vindex show-paren-context-when-offscreen
+@code{show-paren-context-when-offscreen}, when non-@code{nil}, shows
+some context in the echo area when point is in a closing delimiter and
+the opening delimiter is offscreen.  The context is usually the line
+that contains the opening delimiter, except if the opening delimiter
+is on its own line, in which case the context includes the previous
+nonblank line.
 @end itemize
 
 @cindex Electric Pair mode
@@ -1098,13 +1131,13 @@ match the last comment before point in the buffer, and then does a
 expression that is the value of the variable @code{comment-start-skip}.
 Make sure this regexp does not match the null string.  It may match more
 than the comment starting delimiter in the strictest sense of the word;
-for example, in C mode the value of the variable is
+for example, in C mode the value of the variable could be
 @c This stops M-q from breaking the line inside that @code.
-@code{@w{"\\(//+\\|/\\*+\\)\\s *"}}, which matches extra stars and
-spaces after the @samp{/*} itself, and accepts C++ style comments
-also.  (Note that @samp{\\} is needed in Lisp syntax to include a
-@samp{\} in the string, which is needed to deny the first star its
-special meaning in regexp syntax.  @xref{Regexp Backslash}.)
+@code{@w{"/\\*+[ \t]*\\|//+[ \t]*"}}, which matches extra stars and
+spaces after the @samp{/*} itself, and accepts C++ style (@samp{//})
+comments also.  (Note that @samp{\\} is needed in Lisp syntax to
+include a @samp{\} in the string, which is needed to deny the first
+star its special meaning in regexp syntax.  @xref{Regexp Backslash}.)
 
 @vindex comment-start
 @vindex comment-end