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

Previous Next

Full log

View this message in rfc822 format

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: 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

Previous Next

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