GNU bug report logs - #78021
30.1; Unclear sentence in (emacs)Matching

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 78021 in the body.
You can then email your comments to 78021 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: 30.1; Unclear sentence in (emacs)Matching
Date: Wed, 23 Apr 2025 22:42:49 +0000

In (emacs)Matching (not a great name for the node abbreviation, BTW),
this sentence is unclear:

  "Conversely, when you insert a closing delimiter over an existing one,
   No insertion takes places, and that position is simply skipped over."

What does it mean to insert a closing delimiter "over an existing one"?
No idea what this is trying to say, or why it's deemed the "converse" of
what happens when you insert an opening delimiter.

Presumably it should include something about what happens to the
"existing" closing delimiter, and something about point, if it hopes to
convey the converse behavior.

In GNU Emacs 30.1 (build 2, x86_64-w64-mingw32) of 2025-02-23 built on
 AVALON
Windowing system distributor 'Microsoft Corp.', version 10.0.26100
System Description: Microsoft Windows 10 Pro (v10.0.2009.26100.3775)

Configured using:
 'configure --with-modules --without-dbus --with-native-compilation=aot
 --without-compress-install --with-tree-sitter CFLAGS=-O2
 prefix=/g/rel/install/emacs-30.1'

Configured features:
ACL GIF GMP GNUTLS HARFBUZZ JPEG LCMS2 LIBXML2 MODULES NATIVE_COMP
NOTIFY W32NOTIFY PDUMPER PNG RSVG SOUND SQLITE3 THREADS TIFF
TOOLKIT_SCROLL_BARS TREE_SITTER WEBP XPM ZLIB

(NATIVE_COMP present but libgccjit not available)

Important settings:
  value of $LANG: ENU
  locale-coding-system: cp1252

Message #10 received at 78021-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 78021-done <at> debbugs.gnu.org
Subject: Re: bug#78021: 30.1; Unclear sentence in (emacs)Matching
Date: Thu, 24 Apr 2025 12:10:07 +0300

> Date: Wed, 23 Apr 2025 22:42:49 +0000
> From:  Drew Adams via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs <at> gnu.org>
> 
> In (emacs)Matching (not a great name for the node abbreviation, BTW),
> this sentence is unclear:
> 
>   "Conversely, when you insert a closing delimiter over an existing one,
>    No insertion takes places, and that position is simply skipped over."
> 
> What does it mean to insert a closing delimiter "over an existing one"?
> No idea what this is trying to say, or why it's deemed the "converse" of
> what happens when you insert an opening delimiter.
> 
> Presumably it should include something about what happens to the
> "existing" closing delimiter, and something about point, if it hopes to
> convey the converse behavior.

Thanks, I've fixed the wording on the emacs-30 branch.

Message #13 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Stephen Berman <stephen.berman <at> gmx.net>
To: 78021 <at> debbugs.gnu.org
Cc: eliz <at> gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#78021: 30.1; Unclear sentence in (emacs)Matching
Date: Fri, 25 Apr 2025 15:48:54 +0200

[Message part 1 (text/plain, inline)]

reopen 78021
thanks

(In light of the posts related to this bug on emacs-devel, included
below for convenience, I've reopened this bug and am following up here.)

On Thu, 24 Apr 2025 18:30:37 +0300 Eli Zaretskii <eliz <at> gnu.org> wrote:

>> From: Stephen Berman <stephen.berman <at> gmx.net>
>> Cc: Eli Zaretskii <eliz <at> gnu.org>
>> Date: Thu, 24 Apr 2025 16:15:16 +0200
>> 
>> On Thu, 24 Apr 2025 05:08:40 -0400 (EDT) Eli Zaretskii <eliz <at> gnu.org> wrote:
>> 
>> > branch: emacs-30
>> > commit a975232c0fd7bbcce39f904518bd068a879ea4f0
>> > Author: Eli Zaretskii <eliz <at> gnu.org>
>> > Commit: Eli Zaretskii <eliz <at> gnu.org>
>> >
>> >     ; * doc/emacs/programs.texi (Matching): Fix wording (bug#78021).
>> > ---
>> >  doc/emacs/programs.texi | 25 ++++++++++++++-----------
>> >  1 file changed, 14 insertions(+), 11 deletions(-)
>> >
>> > diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
>> > index e155092676b..820a772104e 100644
>> > --- a/doc/emacs/programs.texi
>> > +++ b/doc/emacs/programs.texi
>> > @@ -960,11 +960,11 @@ argument specifies the number of levels to go down.
>> >  
>> >  @node Matching
>> >  @subsection Matching Parentheses
>> > -@cindex matching parentheses
>> > +@cindex matching, parentheses and other paired delimiters
>> >  @cindex parentheses, displaying matches
>> >  
>> > -  Emacs has a number of @dfn{parenthesis matching} features, which
>> > -make it easy to see how and whether parentheses (or other delimiters)
>> > +  Emacs has a number of @dfn{parenthesis matching} features, which make
>> > +it easy to see how and whether parentheses (or other paired delimiters)
>> >  match up.
>> >  
>> >    Whenever you type a self-inserting character that is a closing
>> > @@ -1065,14 +1065,17 @@ nonblank line.
>> >  @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.  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.
>> > +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:
>>   
>> I think the documentation of Electric Pair mode (both before and after
>> the change), is incomplete or inaccurate in several respects:
>> 
>> - What counts as paired delimiters can vary with the mode (e.g.,
>>   emacs-lisp-mode includes ` and ', and latex-mode includes $).
>> 
>> - Whether typing an opening delimiter automatically inserts the matching
>>   closing delimiter depends both on the presence or absence of a
>>   following unmatched closing delimiter as well as on the value of
>>   electric-pair-preserve-balance.
>> 
>> - Unless the region is active (see below), typing a closing delimiter
>>   anywere (not just where a closing delimiter already is) does not
>>   insert the matching opening delimiter but is just like typing a
>>   non-delimiter self-inserting character.
>> 
>> - With a numeric prefix argument N, typing an opening delimiter normally
>>   (but see below) inserts N nested (not sequential) paired delimiters
>>   and leaves point directly after the innermost opening delimiter, while
>>   typing a closing delimiter inserts N nested paired delimiters only
>>   with an active region, leaving point directly after the outermost
>>   closing delimiter.  If there is an unmatched closing delimiter, then
>>   typing the opening delimiter with a numeric prefix argument inserts
>>   just N copies of the opening delimiter, not N nested paired delimiters
>>   (even if electric-pair-preserve-balance is non-nil, which might be
>>   considered a bug).
>> 
>> - The user option electric-pair-preserve-balance only affects the
>>   behavior of opening delimiters (I haven't yet tested the other
>>   Electric Pair mode user options).
>> 
>> Should the documentation be amended accordingly?
>
> I think so, but please try to be as concise as possible, and secondary
> details could be omitted entirely.  I wouldn't want to have this node
> bloated too much because of this minor feature.
>
> For example, your first point could be addressed by adding just this:
>
>   What counts as paired delimiters depends on the major mode.
>
> Thanks.

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.

Second, in the first paragraphs of the patch I've tried to describe the
default behavior concisely and completely; however, the sentence about
the numeric prefix argument, which evidently comes from the
documentation in master, is not suitable for emacs-30: the use of the
prefix argument was added (together with its documentation) as a result
of bug#72437 only to master.  If my doc changes for emacs-30 are
acceptable, they should be added to master as well, but not merged,
because of the prefix argument doc.  But in addition, in testing the use
of the prefix argument I've encountered what seems like buggy behavior,
one instance of which I pointed out above; I'm still investigating this
and plan to file a bug report about it.  A doc patch for master should
await the outcome of that.

Third, concerning the user options, I think it's better not to use the
phrase "when non-‘nil’", which is in all cases the default value: for
electric-pair-preserve-balance, the behavior with that value was already
described, so it's better (and more parsimonious) to focus on the
behavior with the non-default value here; and for the other three
options a user-defined function is also allowed as value, which of
course is non-nil, but I don't think documenting this value is
appropriate for the Emacs manual, so I think it's better just to say "by
default".

Finally, in the description of electric-pair-preserve-balance the
penultimate parenthetical sentence seems like a rather shamefaced
admission of a bug.  Indeed, it does strike me as a bug, and I have a
simple fix that makes setting this option to nil have the same effect
with an active region as without, according to my initial testing.  I
will file a bug report and include the patch.  If the maintainers agree
that this is a bug and that the patch fixes it, then the parenthetical
sentence can be removed.  But whether that goes only for master or also
for emacs-30 is also for the maintainers to decide.

Steve Berman

[Message part 2 (text/x-patch, attachment)]

Message #18 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stephen Berman <stephen.berman <at> gmx.net>, "78021 <at> debbugs.gnu.org"
 <78021 <at> debbugs.gnu.org>
Cc: "eliz <at> gnu.org" <eliz <at> gnu.org>
Subject: RE: [External] : Re: bug#78021: 30.1; Unclear sentence in
 (emacs)Matching
Date: Fri, 25 Apr 2025 15:51:31 +0000

I don't have Eli's fix, to compare, and I can't
follow your diff wrt the text I see in Emacs 30,
so I can't tell what, in your suggested text, you
think actually responds to _this_ bug, which I
filed.

This bug is only about this existing text, which
I can't fathom (and "places" should be "place"):

  "Conversely, when you insert a closing delimiter
   over an existing one, no insertion takes places,
   and that position is simply skipped over."

(And the node-name abbreviation shouldn't just be
"Matching".  There are lots of kinds of matching
in Emacs; please don't hijack that term for this.)

If you fix this bug, then fine.  But please make
your other changes independently of this bug fix.
Or at least make very clear what part of your fix
actually corresponds to fixing this bug.  Thx.

Message #21 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Stephen Berman <stephen.berman <at> gmx.net>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: "eliz <at> gnu.org" <eliz <at> gnu.org>,
 "78021 <at> debbugs.gnu.org" <78021 <at> debbugs.gnu.org>
Subject: Re: [External] : Re: bug#78021: 30.1; Unclear sentence in
 (emacs)Matching
Date: Fri, 25 Apr 2025 18:30:28 +0200

On Fri, 25 Apr 2025 15:51:31 +0000 Drew Adams <drew.adams <at> oracle.com> wrote:

> I don't have Eli's fix, to compare, 

I included the diff of his fix in my post, so I wonder why you can't see
it there; I also see it in the mailing list archive:

https://lists.gnu.org/archive/html/bug-gnu-emacs/2025-04/msg01589.html

But I will quote from his fix below for your convenience.

>                                     and I can't
> follow your diff wrt the text I see in Emacs 30,

This is because my diff was against the current emacs-30 branch, which
contains Eli's changes.  But again, you should be able to see his diff
at the above URL (and in my post).

> so I can't tell what, in your suggested text, you
> think actually responds to _this_ bug, which I
> filed.
>
> This bug is only about this existing text, which
> I can't fathom (and "places" should be "place"):
>
>   "Conversely, when you insert a closing delimiter
>    over an existing one, no insertion takes places,
>    and that position is simply skipped over."
>
> (And the node-name abbreviation shouldn't just be
> "Matching".  There are lots of kinds of matching
> in Emacs; please don't hijack that term for this.)
>
> If you fix this bug, then fine.  But please make
> your other changes independently of this bug fix.
> Or at least make very clear what part of your fix
> actually corresponds to fixing this bug.  Thx.

Here is Eli's clarification of the bit you found wanting:

   "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."

And here is my reformulation, which includes a more complete description
of the behavior, which I think is needed to understand the
functionality:

   "However, if you type a closing delimiter at a buffer position
   between matching delimiters of the same type with only white space
   between the delimiters, then by default Emacs simply moves point to
   after the closing delimiter and does not insert another one."

But I also made numerous other changes in this documentation, for
reasons I listed in my emacs-devel post, which is included in the post
you replied to and should be readable at the URL I provided above.
Admittedly, my other changes widen the scope of your bug report, but I
took that to be legitimate, since it's still about clarifying the
documentation of Electric Pair mode.  If you disagree, then I apologize
for hijacking your bug report (though I don't see it that way), but at
this point I would rather not open a new bug report and repeat
everything there; I hope you can accept that.

Steve Berman

Message #24 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: "eliz <at> gnu.org" <eliz <at> gnu.org>,
 "78021 <at> debbugs.gnu.org" <78021 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#78021: 30.1; Unclear sentence in
 (emacs)Matching
Date: Fri, 25 Apr 2025 17:05:19 +0000

> > This bug is only about this existing text, which
> > I can't fathom (and "places" should be "place"):
> >
> >   "Conversely, when you insert a closing delimiter
> >    over an existing one, no insertion takes places,
> >    and that position is simply skipped over."
> >
> > (And the node-name abbreviation shouldn't just be
> > "Matching".  There are lots of kinds of matching
> > in Emacs; please don't hijack that term for this.)
> >
> > If you fix this bug, then fine.  But please make
> > your other changes independently of this bug fix.
> > Or at least make very clear what part of your fix
> > actually corresponds to fixing this bug.  Thx.
> 
> Here is Eli's clarification of the bit you found wanting:
> 
>    "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."
> 
> And here is my reformulation, which includes a more complete description
> of the behavior, which I think is needed to understand the
> functionality:
> 
>    "However, if you type a closing delimiter at a buffer position
>    between matching delimiters of the same type with only white space
>    between the delimiters, then by default Emacs simply moves point to
>    after the closing delimiter and does not insert another one."

"Matching" delimiters implies matching delimiters of
the same type, no?

Not clear enough:

"with only white space between the delimiters".
Only whitespace between which delimiters?  There are 
presumably at least 3 delimiters in this scenario, one
opening and two closing.

Not clear enough:

"to after the closing delimiter".
Which closing delimiter?  Immediately after it?
If not, where after it?

> But I also made numerous other changes in this documentation, for
> reasons I listed in my emacs-devel post, which is included in the post
> you replied to and should be readable at the URL I provided above.
> Admittedly, my other changes widen the scope of your bug report, but I
> took that to be legitimate, since it's still about clarifying the
> documentation of Electric Pair mode.  If you disagree, then I apologize
> for hijacking your bug report (though I don't see it that way), but at
> this point I would rather not open a new bug report and repeat
> everything there; I hope you can accept that.

I don't intend to review all of your proposed text.
I'll review the text that fixes the bug I filed.

And please change the name of the node (the name
used by `g' etc.) from just "Matching" to something
else, preferably something that indicates it's
about matching delimiters.  That too is part of
this bug/enhancement request.

Thanks for working on this.  And thank you for
providing the proposed text (for the part concerning
this bug).  When reviewing doc changes we shouldn't
have to decipher a diff or apply it.

Message #27 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 78021 <at> debbugs.gnu.org, stephen.berman <at> gmx.net
Subject: Re: [External] : Re: bug#78021: 30.1; Unclear sentence in
 (emacs)Matching
Date: Fri, 25 Apr 2025 21:31:22 +0300

> From: Drew Adams <drew.adams <at> oracle.com>
> CC: "eliz <at> gnu.org" <eliz <at> gnu.org>
> Date: Fri, 25 Apr 2025 15:51:31 +0000
> 
> I don't have Eli's fix, to compare, and I can't
> follow your diff wrt the text I see in Emacs 30,
> so I can't tell what, in your suggested text, you
> think actually responds to _this_ bug, which I
> filed.
> 
> This bug is only about this existing text, which
> I can't fathom (and "places" should be "place"):
> 
>   "Conversely, when you insert a closing delimiter
>    over an existing one, no insertion takes places,
>    and that position is simply skipped over."
> 
> (And the node-name abbreviation shouldn't just be
> "Matching".  There are lots of kinds of matching
> in Emacs; please don't hijack that term for this.)
> 
> If you fix this bug, then fine.  But please make
> your other changes independently of this bug fix.
> Or at least make very clear what part of your fix
> actually corresponds to fixing this bug.  Thx.

The original bug was already fixed.  Stephen reopened it, but the
changes he suggests to install have nothing to do with the original
report.

Message #30 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Stephen Berman <stephen.berman <at> gmx.net>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: "eliz <at> gnu.org" <eliz <at> gnu.org>,
 "78021 <at> debbugs.gnu.org" <78021 <at> debbugs.gnu.org>
Subject: Re: [External] : Re: bug#78021: 30.1; Unclear sentence in
 (emacs)Matching
Date: Fri, 25 Apr 2025 20:33:17 +0200

On Fri, 25 Apr 2025 17:05:19 +0000 Drew Adams <drew.adams <at> oracle.com> wrote:

>> > This bug is only about this existing text, which
>> > I can't fathom (and "places" should be "place"):
>> >
>> >   "Conversely, when you insert a closing delimiter
>> >    over an existing one, no insertion takes places,
>> >    and that position is simply skipped over."
>> >
>> > (And the node-name abbreviation shouldn't just be
>> > "Matching".  There are lots of kinds of matching
>> > in Emacs; please don't hijack that term for this.)
>> >
>> > If you fix this bug, then fine.  But please make
>> > your other changes independently of this bug fix.
>> > Or at least make very clear what part of your fix
>> > actually corresponds to fixing this bug.  Thx.
>> 
>> Here is Eli's clarification of the bit you found wanting:
>> 
>>    "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."
>> 
>> And here is my reformulation, which includes a more complete description
>> of the behavior, which I think is needed to understand the
>> functionality:
>> 
>>    "However, if you type a closing delimiter at a buffer position
>>    between matching delimiters of the same type with only white space
>>    between the delimiters, then by default Emacs simply moves point to
>>    after the closing delimiter and does not insert another one."
>
> "Matching" delimiters implies matching delimiters of
> the same type, no?

Yes, but the point is that matching delimiters must also be of the same
type as the closing delimiter that is typed in the region that the
matching delimiters surround; e.g., if you type ")", the matching
delimiters must "(" and ")", not "[" and "]".

> Not clear enough:
>
> "with only white space between the delimiters".
> Only whitespace between which delimiters?  There are 
> presumably at least 3 delimiters in this scenario, one
> opening and two closing.

The scenario is like this: "some text (     ) more text", and the user
types ")" somewhere between the pair of parens.  If you can think of a
clearer way of describing this just as briefly, I would be grateful (Eli
requested that the node should not become much longer).

> Not clear enough:
>
> "to after the closing delimiter".
> Which closing delimiter?

The one in the text scenario given above, which is the only actual
closing delimiter character in the text -- the "other closing delimiter"
is still just the key being typed, but the character is not inserted (as
the description says).  Here, too, I would welcome a clearer but just as
brief description.

>                           Immediately after it?
> If not, where after it?

Yes, immediately or directly after it.  Perhaps adding one of those
words would be acceptable.

>> But I also made numerous other changes in this documentation, for
>> reasons I listed in my emacs-devel post, which is included in the post
>> you replied to and should be readable at the URL I provided above.
>> Admittedly, my other changes widen the scope of your bug report, but I
>> took that to be legitimate, since it's still about clarifying the
>> documentation of Electric Pair mode.  If you disagree, then I apologize
>> for hijacking your bug report (though I don't see it that way), but at
>> this point I would rather not open a new bug report and repeat
>> everything there; I hope you can accept that.
>
> I don't intend to review all of your proposed text.
> I'll review the text that fixes the bug I filed.
>
> And please change the name of the node (the name
> used by `g' etc.) from just "Matching" to something
> else, preferably something that indicates it's
> about matching delimiters.  That too is part of
> this bug/enhancement request.

Making such a change is the maintainers' prerogative; the (cogent)
argument against such a change is that, being a long-standing node name,
changing it could well break references in external info files or other
formats derived from them, like web pages.

> Thanks for working on this.  And thank you for
> providing the proposed text (for the part concerning
> this bug).  When reviewing doc changes we shouldn't
> have to decipher a diff or apply it.

Since dealing with diffs is standard fare here, and they are generally
required by those who decide whether to accept the changes, and those
who install the changes to the source repository, I don't think it's
unduly burdensome on other interested participants to expect them to be
able to deal with them too.

Steve Berman

Message #33 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Stephen Berman <stephen.berman <at> gmx.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 78021 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: [External] : Re: bug#78021: 30.1; Unclear sentence in
 (emacs)Matching
Date: Fri, 25 Apr 2025 21:16:46 +0200

On Fri, 25 Apr 2025 21:31:22 +0300 Eli Zaretskii <eliz <at> gnu.org> wrote:

>> From: Drew Adams <drew.adams <at> oracle.com>
>> CC: "eliz <at> gnu.org" <eliz <at> gnu.org>
>> Date: Fri, 25 Apr 2025 15:51:31 +0000
>> 
>> I don't have Eli's fix, to compare, and I can't
>> follow your diff wrt the text I see in Emacs 30,
>> so I can't tell what, in your suggested text, you
>> think actually responds to _this_ bug, which I
>> filed.
>> 
>> This bug is only about this existing text, which
>> I can't fathom (and "places" should be "place"):
>> 
>>   "Conversely, when you insert a closing delimiter
>>    over an existing one, no insertion takes places,
>>    and that position is simply skipped over."
>> 
>> (And the node-name abbreviation shouldn't just be
>> "Matching".  There are lots of kinds of matching
>> in Emacs; please don't hijack that term for this.)
>> 
>> If you fix this bug, then fine.  But please make
>> your other changes independently of this bug fix.
>> Or at least make very clear what part of your fix
>> actually corresponds to fixing this bug.  Thx.
>
> The original bug was already fixed.  Stephen reopened it, but the
> changes he suggests to install have nothing to do with the original
> report.

I respectfully disagree, and in my first reply to Drew tried to explain
why I felt it was legitimate to add to this bug.  But if you want a new
bug report for my proposed changes, then I'll make one and close this
one again.

Steve Berman

Message #36 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: "eliz <at> gnu.org" <eliz <at> gnu.org>,
 "78021 <at> debbugs.gnu.org" <78021 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#78021: 30.1; Unclear sentence in
 (emacs)Matching
Date: Fri, 25 Apr 2025 20:23:34 +0000

> > Not clear enough:
> > "with only white space between the delimiters".
> > Only whitespace between which delimiters?  There are
> > presumably at least 3 delimiters in this scenario, one
> > opening and two closing.
> 
> The scenario is like this: "some text (     ) more text", and the user
> types ")" somewhere between the pair of parens.  If you can think of a
> clearer way of describing this just as briefly, I would be grateful (Eli
> requested that the node should not become much longer).
> 
> > Not clear enough:
> > "to after the closing delimiter".
> > Which closing delimiter?
> 
> The one in the text scenario given above, which is the only actual
> closing delimiter character in the text -- the "other closing delimiter"
> is still just the key being typed, but the character is not inserted (as
> the description says).  Here, too, I would welcome a clearer but just as
> brief description.
> 
> >                           Immediately after it?
> > If not, where after it?
> 
> Yes, immediately or directly after it.  Perhaps adding one of those
> words would be acceptable.

Quite complicated.  Maybe should include an illustration.

  However, if you try to insert a closing delimiter between
  a matching pair of the same type, which are not separated
  or are separated only by whitespace, then there's no
  insertion and point is moved immediately after the closing
  delimiter.  For example, if you try to insert `)' at | then
  for `(|)' the result is `()|', and for `(    |  )' the
  result is `(      )|'.

Or maybe:

  However, if only whitespace (or nothing) is delimited, and
  you try to insert a closing delimiter of the same type
  between the delimiters, it's not inserted.  Instead, point
  is put immediately after the closing delimiter.  For example... 

But a reasonable question is why?  Why is that the chosen
behavior?  And why is delimited whitespace special here?
Explaining _why_ would itself take readers a long way toward
understanding _what_ the behavior is.  IOW, start by saying
what the problem is that this behavior tries to solve.

> > And please change the name of the node (the name
> > used by `g' etc.) from just "Matching" to something
> > else, preferably something that indicates it's
> > about matching delimiters.  That too is part of
> > this bug/enhancement request.
> 
> Making such a change is the maintainers' prerogative; the (cogent)
> argument against such a change is that, being a long-standing node name,
> changing it could well break references in external info files or other
> formats derived from them, like web pages.

If that's a concern then the old node name could presumably
still be respected for a while, as an (unadvertised) alias.

But yes, it would have been better to think more about the
node name at the outset.  The key terms in this are "paired"
and "delimiters".

There can be different ways that a pair of delimiters match
each other.  What's important is that there's some way that
they're defined as a matching _pair_.

And an ordered pair, at that.  `(' matches `)' that follows
it, but it doesn't match `)' that precedes it, etc.  (Dunno
what the case is for bidirectional text.)

Matching isn't even a great term to introduce for this, IMO.
In one sense `)' matches `)'; in another sense `)' matches `('.

> > Thanks for working on this.  And thank you for
> > providing the proposed text (for the part concerning
> > this bug).  When reviewing doc changes we shouldn't
> > have to decipher a diff or apply it.
> 
> Since dealing with diffs is standard fare here, and they are generally
> required by those who decide whether to accept the changes, and those
> who install the changes to the source repository, I don't think it's
> unduly burdensome on other interested participants to expect them to be
> able to deal with them too.

I do think so.  Ordinary users of all stripes are encouraged
to file bug reports and enhancement requests.  They shouldn't
need to access texi sources or be familiar with diffs or
patches.  Especially for doc changes.  Just tossing them a
patch discourages such participation.

I write technical docs.  There's no way we would expect our
reviewers to fiddle with source input (XML) to the doc process
or diffs/patches, even though they're all competent software
people.  Reviewing doc is about reading text, and preferably
doing so in context.

Think about this: Surely you didn't _write_ your improved
text in the form of a diff.  You wrote it as ordinary text,
and you probably did so reading the surrounding context as
ordinary text.  And even if you didn't, mere mortals would.

Message #39 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: 78021 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#78021: 30.1; Unclear sentence in (emacs)Matching
Date: Sat, 26 Apr 2025 11:29:15 +0300

> From: Stephen Berman <stephen.berman <at> gmx.net>
> Cc: eliz <at> gnu.org,  drew.adams <at> oracle.com
> 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.

> Second, in the first paragraphs of the patch I've tried to describe the
> default behavior concisely and completely; however, the sentence about
> the numeric prefix argument, which evidently comes from the
> documentation in master, is not suitable for emacs-30: the use of the
> prefix argument was added (together with its documentation) as a result
> of bug#72437 only to master.  If my doc changes for emacs-30 are
> acceptable, they should be added to master as well, but not merged,
> because of the prefix argument doc.  But in addition, in testing the use
> of the prefix argument I've encountered what seems like buggy behavior,
> one instance of which I pointed out above; I'm still investigating this
> and plan to file a bug report about it.  A doc patch for master should
> await the outcome of that.

You could either (a) install different changes on each branch, with
"Do not merge" in the log message of emacs-30 commit; or (b) install
only the change for emacs-30, wait for it to be merged, then install
followup changes on master.

> Third, concerning the user options, I think it's better not to use the
> phrase "when non-‘nil’", which is in all cases the default value: for
> electric-pair-preserve-balance, the behavior with that value was already
> described, so it's better (and more parsimonious) to focus on the
> behavior with the non-default value here; and for the other three
> options a user-defined function is also allowed as value, which of
> course is non-nil, but I don't think documenting this value is
> appropriate for the Emacs manual, so I think it's better just to say "by
> default".

The usual style in these cases is to describe the default behavior and
then tell what will happen if the value is customized to nil.  If the
default behavior was already described, you can describe only the
non-default one.

> +  Electric Pair mode is a minor mode that provides a way to easily
> +insert matching delimiters: parentheses, braces, brackets, quotes, etc.
> +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 and you type an opening delimiter, then by
> +default the matching closing delimiter is normally automatically
> +inserted as well, leaving point between the two.  However, if there is
> +an unmatched closing delimiter later in the buffer, then by default
> +typing an opening delimiter inserts just that character, in order to
> +balance opening and closing delimiters.

The repetition of "by default", let alone with "normally" in the same
sentence, gets in the way, and IMO adds no useful information.  I
suggest to drop those redundant words.

> +  This makes it unnecessary to type a closing delimiter, and doing so
> +normally simply inserts that character.

This sounds like a contradiction to me.  Would the below be accurate:

  This makes it unnecessary to type a closing delimiter in most
  cases.  (If you type it nonetheless, Emacs simply inserts that
  character.)

>                                          However, if you type a closing
> +delimiter at a buffer position between matching delimiters of the same
> +type with only white space between the delimiters, then by default Emacs
> +simply moves point to after the closing delimiter and does not insert
> +another one.

The "only white space" part is inaccurate, and only happens when
electric-pair-skip-whitespace is non-nil.  I think this subtle aspect
is best described where electric-pair-skip-whitespace is documented.
Here, I would only describe the behavior when inserting a closing
delimiter where there is one already.

> +@code{electric-pair-preserve-balance}, when set to @code{nil}, makes
> +typing an opening delimiter insert only that character, thus overriding
> +the default pairing logic of balancing the number of opening and closing
> +delimiters.

This sounds like disabling the main effect of the mode.  Is that
really correct?  If not, then the "default pairing logic of balancing
the number of opening and closing delimiters" should be described
first, to explain what does this option disable, exactly.

>  @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}, by default, makes
> +backspacing between two adjacent delimiters delete not only the opening
> +delimiter but also the closing delimiter.

First, "backspacing" is an unfortunate wording, because someone might
interpret it as typing C-b.  I believe the intent is to deleting by
DEL instead.  Second, in my testing typing DEL on the opening
delimiter removes the closing delimiter only if there's _nothing_
between them.  If that is why you mean by "between two adjacent
delimiters", it should be clarified, because I didn't interpret it
that way.  And third, since this is the default behavior, documenting
this option should tell what happens in the non-default case.

>  @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.
> +@code{electric-pair-open-newline-between-pairs}, by default, makes
> +inserting a newline between two adjacent pairs also automatically open
> +an extra newline after point.

Some modes customize the default value of this option (for example, it
is nil in *scratch*), so "by default" is not accurate in this case.
Also, the same issue about "between two adjacent delimiters" happens
here as well: the additional newline is inserted only if there's
_nothing_ between the delimiters, not even white space.  And finally,
"open an extra newline" is confusing; I would instead say "inserts one
extra newline after point, moving the closing delimiter to a new line".

>  @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.
> +@code{electric-pair-skip-whitespace}, by default, makes typing a closing
> +delimiter between matching delimiters of the same type behave as
> +described above.

The description of the default behavior is redundant and is best
omitted.

>                   You can set this option to additionally delete any
> +white space skipped over.

This "skipping over" part is "out of the blue": it is completely
unclear what it alludes to.  This should be explained before
describing the effect of the variable.

>                              You can also set it not to skip over the
> +following closing delimiter but simply insert a closing delimiter at
> +point (thus making the following delimiter unbalanced).

And here, it is unclear what does skipping whitespace have to do with
insertion of the closing delimiter.

Btw, I think the doc strings of these options need clarifications.
They make very little sense to me when I read them.

Thanks.

Message #42 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Stephen Berman <stephen.berman <at> gmx.net>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: "eliz <at> gnu.org" <eliz <at> gnu.org>,
 "78021 <at> debbugs.gnu.org" <78021 <at> debbugs.gnu.org>
Subject: Re: [External] : Re: bug#78021: 30.1; Unclear sentence in
 (emacs)Matching
Date: Tue, 29 Apr 2025 12:13:05 +0200

(Sorry for the delayed reply.)

On Fri, 25 Apr 2025 20:23:34 +0000 Drew Adams <drew.adams <at> oracle.com> wrote:

>> > Not clear enough:
>> > "with only white space between the delimiters".
>> > Only whitespace between which delimiters?  There are
>> > presumably at least 3 delimiters in this scenario, one
>> > opening and two closing.
>> 
>> The scenario is like this: "some text (     ) more text", and the user
>> types ")" somewhere between the pair of parens.  If you can think of a
>> clearer way of describing this just as briefly, I would be grateful (Eli
>> requested that the node should not become much longer).
>> 
>> > Not clear enough:
>> > "to after the closing delimiter".
>> > Which closing delimiter?
>> 
>> The one in the text scenario given above, which is the only actual
>> closing delimiter character in the text -- the "other closing delimiter"
>> is still just the key being typed, but the character is not inserted (as
>> the description says).  Here, too, I would welcome a clearer but just as
>> brief description.
>> 
>> >                           Immediately after it?
>> > If not, where after it?
>> 
>> Yes, immediately or directly after it.  Perhaps adding one of those
>> words would be acceptable.
>
> Quite complicated.  Maybe should include an illustration.
>
>   However, if you try to insert a closing delimiter between
>   a matching pair of the same type, which are not separated
>   or are separated only by whitespace, then there's no
>   insertion and point is moved immediately after the closing
>   delimiter.  For example, if you try to insert `)' at | then
>   for `(|)' the result is `()|', and for `(    |  )' the
>   result is `(      )|'.
>
> Or maybe:
>
>   However, if only whitespace (or nothing) is delimited, and
>   you try to insert a closing delimiter of the same type
>   between the delimiters, it's not inserted.  Instead, point
>   is put immediately after the closing delimiter.  For example... 
>
> But a reasonable question is why?  Why is that the chosen
> behavior?  And why is delimited whitespace special here?
> Explaining _why_ would itself take readers a long way toward
> understanding _what_ the behavior is.  IOW, start by saying
> what the problem is that this behavior tries to solve.

Thanks for the suggestions, which in principle I agree with.  However,
this is starting to sound like a project more appropriate for a separate
Info manual for Electric Pair mode, which I don't want to undertake,
because I have neither enough familiarity with the code nor the time to
familiarize myself with it and then satisfactorily document it.  I'm
already finding it hard than I thought it would be to make the necessary
relatively small doc changes suitable for the Emacs manual.

[...]
>> > Thanks for working on this.  And thank you for
>> > providing the proposed text (for the part concerning
>> > this bug).  When reviewing doc changes we shouldn't
>> > have to decipher a diff or apply it.
>> 
>> Since dealing with diffs is standard fare here, and they are generally
>> required by those who decide whether to accept the changes, and those
>> who install the changes to the source repository, I don't think it's
>> unduly burdensome on other interested participants to expect them to be
>> able to deal with them too.
>
> I do think so.  Ordinary users of all stripes are encouraged
> to file bug reports and enhancement requests.  They shouldn't
> need to access texi sources or be familiar with diffs or
> patches.  Especially for doc changes.  Just tossing them a
> patch discourages such participation.
>
> I write technical docs.  There's no way we would expect our
> reviewers to fiddle with source input (XML) to the doc process
> or diffs/patches, even though they're all competent software
> people.  Reviewing doc is about reading text, and preferably
> doing so in context.
>
> Think about this: Surely you didn't _write_ your improved
> text in the form of a diff.  You wrote it as ordinary text,
> and you probably did so reading the surrounding context as
> ordinary text.  And even if you didn't, mere mortals would.

Of course I didn't write the diff by hand, but I did make changes
directly in the .texi file and then the easiest and quickest way (for
me) to see the changes in context, and present them to others, is to
generate a diff.  To extract plain text out that is an added burden for
me (granted, probably in most cases only a small one).  But I shouldn't
have presumed to judge what is burdensome for others.

Steve Berman

Message #45 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Stephen Berman <stephen.berman <at> gmx.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 78021 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#78021: 30.1; Unclear sentence in (emacs)Matching
Date: Tue, 29 Apr 2025 12:13:28 +0200

[Message part 1 (text/plain, inline)]

(Sorry for the delayed reply.)

On Sat, 26 Apr 2025 11:29:15 +0300 Eli Zaretskii <eliz <at> gnu.org> wrote:

>> From: Stephen Berman <stephen.berman <at> gmx.net>
>> Cc: eliz <at> gnu.org,  drew.adams <at> oracle.com
>> 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

[Message part 2 (text/x-patch, attachment)]

Message #48 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: "eliz <at> gnu.org" <eliz <at> gnu.org>,
 "78021 <at> debbugs.gnu.org" <78021 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#78021: 30.1; Unclear sentence in
 (emacs)Matching
Date: Tue, 29 Apr 2025 17:16:47 +0000

> > I do think so.  Ordinary users of all stripes are encouraged
> > to file bug reports and enhancement requests.  They shouldn't
> > need to access texi sources or be familiar with diffs or
> > patches.  Especially for doc changes.  Just tossing them a
> > patch discourages such participation.
> >
> > I write technical docs.  There's no way we would expect our
> > reviewers to fiddle with source input (XML) to the doc process
> > or diffs/patches, even though they're all competent software
> > people.  Reviewing doc is about reading text, and preferably
> > doing so in context.
> >
> > Think about this: Surely you didn't _write_ your improved
> > text in the form of a diff.  You wrote it as ordinary text,
> > and you probably did so reading the surrounding context as
> > ordinary text.  And even if you didn't, mere mortals would.
> 
> Of course I didn't write the diff by hand, but I did make changes
> directly in the .texi file and then the easiest and quickest way (for
> me) to see the changes in context, and present them to others, is to
> generate a diff.  To extract plain text out that is an added burden for
> me (granted, probably in most cases only a small one).  But I shouldn't
> have presumed to judge what is burdensome for others.

Too burdensome for me, to deal with the diff.  And I don't
want to have to track down the current doc state that it
applies against, and use the patch to create the new doc
state from that, to be reviewed.

Message #51 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: 78021 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#78021: 30.1; Unclear sentence in (emacs)Matching
Date: Sat, 03 May 2025 12:38:43 +0300

> From: Stephen Berman <stephen.berman <at> gmx.net>
> Cc: 78021 <at> debbugs.gnu.org,  drew.adams <at> oracle.com
> Date: Tue, 29 Apr 2025 12:13:28 +0200
> 
> On Sat, 26 Apr 2025 11:29:15 +0300 Eli Zaretskii <eliz <at> gnu.org> wrote:
> 
> >> From: Stephen Berman <stephen.berman <at> gmx.net>
> >> Cc: eliz <at> gnu.org,  drew.adams <at> oracle.com
> >> 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).

Thanks, see a few minor comments below.

> +  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
           ^^^^
Please use "etc.@:" there, to indicate that it is not the end of a
sentence.

> +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}.

These are long commands, so I suggest to wrap them in @w{..}, to avoud
breaking them between two lines.

> +  With an active region, the effect of inserting a delimiter is as
> +described above regardless of the value of this variable.

I'd rephrase:

  If there is an active region, this variable has no effect.

> +@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
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A cross-reference to "DEL Does Not Delete" would be useful here.

Message #54 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Stephen Berman <stephen.berman <at> gmx.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 78021 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#78021: 30.1; Unclear sentence in (emacs)Matching
Date: Sun, 04 May 2025 00:31:08 +0200

On Sat, 03 May 2025 12:38:43 +0300 Eli Zaretskii <eliz <at> gnu.org> wrote:

>> From: Stephen Berman <stephen.berman <at> gmx.net>
>> Cc: 78021 <at> debbugs.gnu.org,  drew.adams <at> oracle.com
>> Date: Tue, 29 Apr 2025 12:13:28 +0200
>> 
>> On Sat, 26 Apr 2025 11:29:15 +0300 Eli Zaretskii <eliz <at> gnu.org> wrote:
>> 
>> >> From: Stephen Berman <stephen.berman <at> gmx.net>
>> >> Cc: eliz <at> gnu.org,  drew.adams <at> oracle.com
>> >> 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).
>
> Thanks, see a few minor comments below.

Thanks, I've made the changes you suggested.  If that now completes this
revision of the Electric Pair mode documentation for the Emacs manual,
should I go ahead and install it to emacs-30, or would you prefer to
wait for improvements to the corresponding doc strings in
electric-pair.el, and have all the doc changes installed as one
changeset?  If the latter, I'll make a patch for review as soon as I
can.

Steve Berman

Message #57 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: 78021 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#78021: 30.1; Unclear sentence in (emacs)Matching
Date: Sun, 04 May 2025 08:05:23 +0300

> From: Stephen Berman <stephen.berman <at> gmx.net>
> Cc: 78021 <at> debbugs.gnu.org,  drew.adams <at> oracle.com
> Date: Sun, 04 May 2025 00:31:08 +0200
> 
> Thanks, I've made the changes you suggested.  If that now completes this
> revision of the Electric Pair mode documentation for the Emacs manual,
> should I go ahead and install it to emacs-30, or would you prefer to
> wait for improvements to the corresponding doc strings in
> electric-pair.el, and have all the doc changes installed as one
> changeset?  If the latter, I'll make a patch for review as soon as I
> can.

I'd prefer a single patch with all the documentation changes for this
mode.

Thanks.

Message #60 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Stephen Berman <stephen.berman <at> gmx.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 78021 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#78021: 30.1; Unclear sentence in (emacs)Matching
Date: Thu, 08 May 2025 17:47:46 +0200

[Message part 1 (text/plain, inline)]

On Sun, 04 May 2025 08:05:23 +0300 Eli Zaretskii <eliz <at> gnu.org> wrote:

>> From: Stephen Berman <stephen.berman <at> gmx.net>
>> Cc: 78021 <at> debbugs.gnu.org,  drew.adams <at> oracle.com
>> Date: Sun, 04 May 2025 00:31:08 +0200
>> 
>> Thanks, I've made the changes you suggested.  If that now completes this
>> revision of the Electric Pair mode documentation for the Emacs manual,
>> should I go ahead and install it to emacs-30, or would you prefer to
>> wait for improvements to the corresponding doc strings in
>> electric-pair.el, and have all the doc changes installed as one
>> changeset?  If the latter, I'll make a patch for review as soon as I
>> can.
>
> I'd prefer a single patch with all the documentation changes for this
> mode.

I've now finished the patch and attached it.  On rereading my changes
for the Emacs manual I realized that my use of the terms "matching" and
"of the same type" was confusing (and confused); Drew drew attention to
that upthread but I misconstrued it then.  I've adjusted the text
accordingly (mainly in the description of
`electric-pair-preserve-balance') and also replaced the infelicitous
"unmatched" with "unpaired".  In electric-pair.el I tried to clarify and
improve not just the doc strings of the user options documented in the
manual but also a number of others that I found unclear.  I also added
text to the Commentary section, corrected several typos and in one case
reformatted overlong lines of code.

If you agree with these changes I'll push them to emacs-30, using the
ChangeLog entry below as the commit message.

Steve Berman

Improve Electric Pair mode documentation (bug#78021)

* doc/emacs/programs.texi (Matching): Clarify and improve
documentation of Electric Pair mode.

* lisp/elec-pair.el: Improve description in header line.  Add text
and a reference to the Emacs user manual in the Commentary section.
(electric-pair-skip-self, electric-pair-inhibit-predicate)
(electric-pair-preserve-balance)
(electric-pair-delete-adjacent-pairs)
(electric-pair-open-newline-between-pairs)
(electric-pair-skip-whitespace)
(electric-pair-skip-whitespace-function)
(electric-pair-analyze-conversion)
(electric-pair--skip-whitespace)
(electric-pair-text-syntax-table, electric-pair-syntax-info)
(electric-pair--insert, electric-pair--syntax-ppss)
(electric-pair--balance-info)
(electric-pair-inhibit-if-helps-balance)
(electric-pair-skip-if-helps-balance)
(electric-pair-open-newline-between-pairs-psif)
(electric-pair-mode): Clarify and improve doc strings and some comments.
(electric-pair-post-self-insert-function): Restructure doc string
to shorten overlong first line, and reformat overlong lines of code.

[Message part 2 (text/x-patch, attachment)]

Message #63 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: 78021 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#78021: 30.1; Unclear sentence in (emacs)Matching
Date: Sat, 10 May 2025 13:58:44 +0300

> From: Stephen Berman <stephen.berman <at> gmx.net>
> Cc: 78021 <at> debbugs.gnu.org,  drew.adams <at> oracle.com
> Date: Thu, 08 May 2025 17:47:46 +0200
> 
> > I'd prefer a single patch with all the documentation changes for this
> > mode.
> 
> I've now finished the patch and attached it.  On rereading my changes
> for the Emacs manual I realized that my use of the terms "matching" and
> "of the same type" was confusing (and confused); Drew drew attention to
> that upthread but I misconstrued it then.  I've adjusted the text
> accordingly (mainly in the description of
> `electric-pair-preserve-balance') and also replaced the infelicitous
> "unmatched" with "unpaired".  In electric-pair.el I tried to clarify and
> improve not just the doc strings of the user options documented in the
> manual but also a number of others that I found unclear.  I also added
> text to the Commentary section, corrected several typos and in one case
> reformatted overlong lines of code.
> 
> If you agree with these changes I'll push them to emacs-30, using the
> ChangeLog entry below as the commit message.

Thanks, LGTM, but please make sure the first line of a doc string is
always a single complete sentence.  I've seen it be only party of a
sentence in two functions: electric-pair-post-self-insert-function and
electric-pair-open-newline-between-pairs-psif.

Message #66 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Stephen Berman <stephen.berman <at> gmx.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 78021 <at> debbugs.gnu.org
Subject: Re: bug#78021: 30.1; Unclear sentence in (emacs)Matching
Date: Sat, 10 May 2025 14:44:48 +0200

On Sat, 10 May 2025 13:58:44 +0300 Eli Zaretskii <eliz <at> gnu.org> wrote:

>> From: Stephen Berman <stephen.berman <at> gmx.net>
>> Cc: 78021 <at> debbugs.gnu.org,  drew.adams <at> oracle.com
>> Date: Thu, 08 May 2025 17:47:46 +0200
>> 
>> > I'd prefer a single patch with all the documentation changes for this
>> > mode.
>> 
>> I've now finished the patch and attached it.  On rereading my changes
>> for the Emacs manual I realized that my use of the terms "matching" and
>> "of the same type" was confusing (and confused); Drew drew attention to
>> that upthread but I misconstrued it then.  I've adjusted the text
>> accordingly (mainly in the description of
>> `electric-pair-preserve-balance') and also replaced the infelicitous
>> "unmatched" with "unpaired".  In electric-pair.el I tried to clarify and
>> improve not just the doc strings of the user options documented in the
>> manual but also a number of others that I found unclear.  I also added
>> text to the Commentary section, corrected several typos and in one case
>> reformatted overlong lines of code.
>> 
>> If you agree with these changes I'll push them to emacs-30, using the
>> ChangeLog entry below as the commit message.
>
> Thanks, LGTM, but please make sure the first line of a doc string is
> always a single complete sentence.  I've seen it be only party of a
> sentence in two functions: electric-pair-post-self-insert-function and
> electric-pair-open-newline-between-pairs-psif.

I think they are complete sentences (checkdoc did not complain about
them), though a bit terse:

  (defun electric-pair-post-self-insert-function ()
    "Do main work for `electric-pair-mode'.
  
  (defun electric-pair-open-newline-between-pairs-psif ()
    "Honor `electric-pair-open-newline-between-pairs'.

Do you prefer the following reformulations instead?

  (defun electric-pair-post-self-insert-function ()
    "Do the main work of `electric-pair-mode'.
  
  (defun electric-pair-open-newline-between-pairs-psif ()
    "Act on the value of `electric-pair-open-newline-between-pairs'.

On the other hand, checkdoc did notice something I missed (I should have
run it before posting my patch, mea culpa): that the symbol `text-mode'
in the doc string of `electric-pair--with-syntax' was not quoted, so
I've now fixed that.  In addition, checkdoc noticed that seven defuns
lack doc strings, which I had decided not to add: they are either
internal functions (electric-pair--with-syntax,
electric-pair--with-syntax-1, electric-pair--insert) or default values
of defcustoms (electric-pair-conservative-inhibit,
electric-pair-default-skip-self, electric-pair-default-inhibit), which
are adequately documented, or self-explanatory
(electric-pair-will-use-region).  Is that ok or would you rather that
these functions also have doc strings?

Steve Berman

Message #69 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: 78021 <at> debbugs.gnu.org
Subject: Re: bug#78021: 30.1; Unclear sentence in (emacs)Matching
Date: Sat, 10 May 2025 15:49:38 +0300

> From: Stephen Berman <stephen.berman <at> gmx.net>
> Cc: 78021 <at> debbugs.gnu.org
> Date: Sat, 10 May 2025 14:44:48 +0200
> 
> On Sat, 10 May 2025 13:58:44 +0300 Eli Zaretskii <eliz <at> gnu.org> wrote:
> 
> > Thanks, LGTM, but please make sure the first line of a doc string is
> > always a single complete sentence.  I've seen it be only party of a
> > sentence in two functions: electric-pair-post-self-insert-function and
> > electric-pair-open-newline-between-pairs-psif.
> 
> I think they are complete sentences (checkdoc did not complain about
> them), though a bit terse:

Sorry, you are right, I've misread the diffs.

Message #74 received at 78021-done <at> debbugs.gnu.org (full text, mbox):

From: Stephen Berman <stephen.berman <at> gmx.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 78021-done <at> debbugs.gnu.org
Subject: Re: bug#78021: 30.1; Unclear sentence in (emacs)Matching
Date: Sat, 10 May 2025 16:33:59 +0200

On Sat, 10 May 2025 15:49:38 +0300 Eli Zaretskii <eliz <at> gnu.org> wrote:

>> From: Stephen Berman <stephen.berman <at> gmx.net>
>> Cc: 78021 <at> debbugs.gnu.org
>> Date: Sat, 10 May 2025 14:44:48 +0200
>> 
>> On Sat, 10 May 2025 13:58:44 +0300 Eli Zaretskii <eliz <at> gnu.org> wrote:
>> 
>> > Thanks, LGTM, but please make sure the first line of a doc string is
>> > always a single complete sentence.  I've seen it be only party of a
>> > sentence in two functions: electric-pair-post-self-insert-function and
>> > electric-pair-open-newline-between-pairs-psif.
>> 
>> I think they are complete sentences (checkdoc did not complain about
>> them), though a bit terse:
>
> Sorry, you are right, I've misread the diffs.

Ok, thanks.  I've now pushed the changes to emacs-30 as commit
bb735331650 and I'm (re)closing the bug.  When these changes have been
merged to master, they'll overwrite the sentence in the manual about
using a prefix argument, so I'll put it back then.

Steve Berman

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.