Improve documentation of 'electric-pair-mode'

* lisp/elec-pair.el (electric-pair-mode):
* doc/emacs/programs.texi (Matching): Document the operation of
electric-pair-mode when there's an active region.  (Bug#30502)

1 files changed, 11 insertions, 6 deletions

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index bafe5cc87be..b6bd173e4d9 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -877,12 +877,17 @@ or the last, non-whitespace position on the line.
 @cindex inserting matching parentheses
 @findex electric-pair-mode
   Electric Pair mode, a global minor mode, provides a way to easily
-insert matching delimiters.  Whenever you insert an opening delimiter,
-the matching closing delimiter is automatically inserted as well,
-leaving point between the two.  Conversely, when you insert a closing
-delimiter over an existing one, no inserting takes places and that
-position is simply skipped over.  These variables control additional
-features of Electric Pair mode:
+insert matching delimiters: parentheses, braces, brackets, etc.
+Whenever you insert an opening delimiter, the matching closing
+delimiter is automatically inserted as well, leaving point between the
+two.  Conversely, when you insert a closing delimiter over an existing
+one, no insertion takes places, and that position is simply skipped
+over.  If the region is active (@pxref{Mark}), insertion of a
+delimiter operates on the region: the characters in the region are
+enclosed in a pair of matching delimiters, leaving point after the
+delimiter you typed.
+
+These variables control additional features of Electric Pair mode:
 
 @itemize @bullet
 @item