GNU bug report logs -
#78021
30.1; Unclear sentence in (emacs)Matching
Previous Next
Reported by: Drew Adams <drew.adams <at> oracle.com>
Date: Wed, 23 Apr 2025 22:44:03 UTC
Severity: normal
Found in version 30.1
Done: Stephen Berman <stephen.berman <at> gmx.net>
Bug is archived. No further changes may be made.
Full log
Message #42 received at 78021 <at> debbugs.gnu.org (full text, mbox):
(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
This bug report was last modified 107 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.