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)

2 files changed, 16 insertions, 8 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
diff --git a/lisp/elec-pair.el b/lisp/elec-pair.el
index af9a44c844c..97049a7d9d9 100644
--- a/lisp/elec-pair.el
+++ b/lisp/elec-pair.el
@@ -580,8 +580,11 @@ the mode if ARG is omitted or nil.
 
 Electric Pair mode is a global minor mode.  When enabled, typing
 an open parenthesis automatically inserts the corresponding
-closing parenthesis.  (Likewise for brackets, etc.). To toggle
-the mode in a single buffer, use `electric-pair-local-mode'."
+closing parenthesis, and vice versa.  (Likewise for brackets, etc.).
+If the region is active, the parentheses (brackets, etc.) are
+inserted around the region instead.
+
+To toggle the mode in a single buffer, use `electric-pair-local-mode'."
   :global t :group 'electricity
   (if electric-pair-mode
       (progn