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.

1 files changed, 30 insertions, 3 deletions

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index bc8d39c974f..e6871e3ff34 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
+@kbd{M-x customize-group @key{RET} paren-showing}.  The customizable
+options which control the operation of this mode include:
+
+@itemize @bullet
+@item
+@code{show-paren-highlight-open-paren} 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 non-@code{nil} (yes).
+
+@item
+@code{show-paren-style} controls whether just the two parens, or also
+the space 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).
+
+@item
+@code{show-paren-when-point-inside-paren}, when non-@code{nil}, causes
+highlighting also when point is on the inside of a parenthesis.
+
+@item
+@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.
+@end itemize
 
 @cindex Electric Pair mode
 @cindex inserting matching parentheses