Subject: RE: [External] : Re: bug#78021: 30.1; Unclear sentence in (emacs)Matching

From: Drew Adams <[email-masked]>
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.