Improve documentation of Show Paren mode

* doc/emacs/programs.texi (Matching): Improve wording and
indexing.  (Bug#29381)

1 files changed, 17 insertions, 13 deletions

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 522c092c3b3..37a15b6d5f6 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -809,42 +809,46 @@ 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 toggle it in single
-buffer, type @kbd{M-x show-paren-local-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.
 @end itemize
 
 @cindex Electric Pair mode