[Emacs-diffs] emacs-25 6d4ae9d: Add documentation for changes to Show Paren mode.

[Alan Mackenzie]

branch: emacs-25
commit 6d4ae9d33870c3024845b06cfb2fae2a225a0bbc
Author: Alan Mackenzie <address@hidden>
Commit: Alan Mackenzie <address@hidden>

    Add documentation for changes to Show Paren mode.
    
    * lisp/paren.el (show-paren-highlight-openparen): Enhance doc string.
    
    * doc/emacs/programs.texi (Matching): Add descriptions of some pertinent 
user
    options, including the new show-paren-when-point-inside-paren and
    show-paren-when-point-in-periphery.
    
    * etc/NEWS (.. Specialized Modes ...): Add an entry for Show Paren mode.
    Move an entry on pcase to the Lisp Changes section.
---
 doc/emacs/programs.texi |   33 ++++++++++++++++++++++++++++++---
 etc/NEWS                |    7 +++++++
 lisp/paren.el           |    5 ++++-
 3 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index bc8d39c..e6871e3 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -833,9 +833,36 @@ displayed.  The default is 102400.
 @findex show-paren-mode
   Show Paren mode, a global minor mode, provides a more powerful kind
 of automatic matching.  Whenever point is before an opening delimiter
-or after a closing delimiter, both that delimiter and its opposite
-delimiter are highlighted.  To toggle Show Paren mode, type @kbd{M-x
-show-paren-mode}.
+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
address@hidden customize-group @key{RET} paren-showing}.  The customizable
+options which control the operation of this mode include:
+
address@hidden @bullet
address@hidden
address@hidden controls whether to highlight
+an open paren when point stands just before it, and hence its position
+is marked by the cursor anyway.  The default is address@hidden (yes).
+
address@hidden
address@hidden controls whether just the two parens, or also
+the space between them get highlighted.  The valid options here are
address@hidden (show the matching paren), @code{expression}
+(highlight the entire expression enclosed by the parens), and
address@hidden (highlight the matching paren if it is visible, the
+expression otherwise).
+
address@hidden
address@hidden, when address@hidden, causes
+highlighting also when point is on the inside of a parenthesis.
+
address@hidden
address@hidden, when address@hidden, 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.
address@hidden itemize
 
 @cindex Electric Pair mode
 @cindex inserting matching parentheses
diff --git a/etc/NEWS b/etc/NEWS
index a09db164..4c5ce3e 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -623,6 +623,13 @@ invalid certificates are marked in red.
 *** text/html messages that contain inline image parts will be
 transformed into multipart/related messages before sending.
 
++++
+** In Show Paren Mode, a parenthesis can be highlighted when point
+stands inside it, and certain parens can be highlighted when point is
+at BOL or EOL, or in whitespace there.  To enable these, customize,
+respectively, show-paren-when-point-inside-paren or
+show-paren-when-point-in-periphery.
+
 ** pcase
 *** New UPatterns `quote', `app', `cl-struct', and `eieio'.
 *** New UPatterns can be defined with `pcase-defmacro'.
diff --git a/lisp/paren.el b/lisp/paren.el
index 30314c2..5825d6a 100644
--- a/lisp/paren.el
+++ b/lisp/paren.el
@@ -87,7 +87,10 @@ whitespace there."
   'show-paren-mismatch "22.1")
 
 (defcustom show-paren-highlight-openparen t
-  "Non-nil turns on openparen highlighting when matching forward."
+  "Non-nil turns on openparen highlighting when matching forward.
+When nil, and point stands just before an open paren, the paren
+is not highlighted, the cursor being regarded as adequate to mark
+its position."
   :type 'boolean)
 
 (defvar show-paren--idle-timer nil)