Subject: bug#78021: 30.1; Unclear sentence in (emacs)Matching

From: Stephen Berman <[email-masked]>
Date: Tue, 29 Apr 2025 12:13:28 +0200

(Sorry for the delayed reply.)

On Sat, 26 Apr 2025 11:29:15 +0300 Eli Zaretskii <[email-masked]> wrote:

>> From: Stephen Berman <[email-masked]>
>> Cc: [email-masked],  [email-masked]
>> Date: Fri, 25 Apr 2025 15:48:54 +0200
>> 
>> I've attached a patch for emacs-30 and have several remarks concerning
>> it.  First, regarding my first point above, since the parent node
>> already says "The major mode controls which delimiters are significant
>> [...]", I now think there is no need to reiterate it here.
>
> I think it is still a good idea to mention that.  The manual is not
> always read in the logical order of the chapters and sections.  In
> fact, in most cases people are supposed to use Info-index to land
> directly on this text and read it without reading the parent section.
[...]

Thanks for you're detailed critique of my patch; I agree with almost all
of your points, and in the attached patch tried to take them into
account.  I also spent some time trying to better understand the effect
of the user options mentioned in this node (there are other user options
in electric-pair.el but they require writing Lisp, which I suppose is
why weren't documented in the Emacs manual, and I don't think they
should be added).  This has resulted in (I hope) more accurate and
clearer, but also longer, descriptions.  If you find them too long or
still not clear enough, I welcome suggestions to improve them.  For this
reason I haven't yet tried to improve the doc strings of the options,
and would also welcome suggestions for these (in particular, for the
first line of each option).

Steve Berman
diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 820a772104e..7cd57584061 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -1063,52 +1063,96 @@ Matching
 @cindex Electric Pair mode
 @cindex inserting matching parentheses
 @findex electric-pair-mode
-  Electric Pair mode, a global minor mode, provides a way to easily
-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.
-However, if you insert a closing delimiter where one already exists
-(probably a mistake, since typing the opening delimiter inserted the
-closing one for you), Emacs simply moves point to after the closing
-delimiter, skipping the insertion.  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.  If you provide a prefix
-argument when inserting a delimiter, the numeric value of that prefix
-argument specifies the number of pairs to insert.
-
-These variables control additional features of Electric Pair mode:
+  Electric Pair mode is a minor mode that provides a way to easily
+insert pairs of matching delimiters: parentheses, braces, brackets,
+quotes, etc. (what counts as matching delimiters depends on the major
+mode).  To toggle Electric Pair mode globally, type @kbd{M-x
+electric-pair-mode}.  To toggle it only in the current buffer, type
+@kbd{M-x electric-pair-local-mode}.
+
+  When this mode is enabled, typing an opening delimiter inserts both
+that character and, immediately following it, the matching closing
+delimiter, leaving point between the two.  This makes it unnecessary to
+type a matching closing delimiter in most cases.  If you type one
+nonetheless, Emacs simply inserts that character, unless point is
+immediately before a closing delimiter of the same type; in that case,
+point moves to immediately after the closing delimiter and no additional
+closing delimiter is inserted.  Thus, typing the sequence <opening
+delimiter>, <matching closing delimiter> is a perhaps more convenient
+alternative to the sequence <opening delimiter>, @kbd{C-f}.
+
+  With an active region (@pxref{Mark}), Electric Pair mode operates
+differently: inserting either an opening or a closing delimiter encloses
+the characters in the region within the resulting pair of matching
+delimiters, leaving point after the delimiter you typed (this
+facilitates continuing to type either before the text following the
+opening delimiter or after the closing delimiter).
+
+  There are several user options for modifying the behavior of Electric
+Pair mode:
 
 @itemize @bullet
 @item
 @vindex electric-pair-preserve-balance
-@code{electric-pair-preserve-balance}, when non-@code{nil}, makes the
-default pairing logic balance out the number of opening and closing
-delimiters.
+@code{electric-pair-preserve-balance}, when non-@code{nil} (the
+default), makes typing a delimiter preserve the balance between opening
+and closing delimiters.  Thus, if there is an unmatched closing
+delimiter of the same type later in the buffer, then only the opening
+delimiter gets inserted (and not a matching closing delimiter
+immediately following it); likewise, if there is an unmatched opening
+delimiter, then typing a closing delimiter of the same type later in the
+buffer inserts this character even when the following character is
+another closing delimiter of the same type.
+
+  When set to @code{nil}, typing an opening delimiter inserts only this
+character, but only when point is either immediately before or
+immediately after an opening delimiter of the same type, or immediately
+before a letter or digit; in all other positions inserting an opening
+delimiter automatically inserts a matching closing delimiter immediately
+following it, even if there is an unmatched closing delimiter of the
+same type later in the buffer.  And typing a closing delimiter
+immediately before another closing delimiter of the same type does not
+insert that character but moves point as described above, even when
+there is an unmatched opening delimiter of the same type earlier in the
+buffer.
+
+  With an active region, the effect of inserting a delimiter is as
+described above regardless of the value of this variable.
 
 @item
 @vindex electric-pair-delete-adjacent-pairs
-@code{electric-pair-delete-adjacent-pairs}, when non-@code{nil}, makes
-backspacing between two adjacent delimiters also automatically delete
-the closing delimiter.
+@code{electric-pair-delete-adjacent-pairs}, when non-@code{nil} (the
+default), makes deleting an opening delimiter by typing the @key{DEL}
+key (which is normally the @key{BACKSPACE} key) automatically also
+delete an immediately following closing delimiter (but not if there are
+any characters---including just whitespace---between the matching
+delimiters).  When set to @code{nil}, typing @key{BACKSPACE} deletes
+only the opening delimiter.  (Typing @key{BACKSPACE} to delete a closing
+delimiter always deletes only this character.)
 
 @item
 @vindex electric-pair-open-newline-between-pairs
-@code{electric-pair-open-newline-between-pairs}, when non-@code{nil},
-makes inserting a newline between two adjacent pairs also
-automatically open an extra newline after point.
+When @code{electric-pair-open-newline-between-pairs} is non-@code{nil}
+(the default) and point is between an opening delimiter and an
+immediately following closing delimiter, then typing a newline
+automatically inserts an extra newline after point (possibly indenting
+the empty line point is on, depending on the major mode).  When set to
+@code{nil}, typing a newline insert only one newline before point, as
+usual.
 
 @item
 @vindex electric-pair-skip-whitespace
-@code{electric-pair-skip-whitespace}, when non-@code{nil}, causes the minor
-mode to skip whitespace forward before deciding whether to skip over
-the closing delimiter.
+When @code{electric-pair-skip-whitespace} has its default non-@code{nil}
+value and point is separated from a closing delimiter only by
+whitespace, then typing a closing delimiter of the same type does not
+insert that character but instead moves point to immediately after the
+already present closing delimiter.  You can also set this option to
+additionally delete any white space that point moves over.  When set to
+@code{nil}, typing a closing delimiter simply inserts that character
+(thus making the following closing delimiter of the same type
+unbalanced).
 @end itemize
 
-To toggle Electric Pair mode, type @kbd{M-x electric-pair-mode}.  To
-toggle the mode in a single buffer, use @kbd{M-x
-electric-pair-local-mode}.
-
 @node Comments
 @section Manipulating Comments
 @cindex comments