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

From: Stephen Berman <[email-masked]>
Date: Sun, 04 May 2025 00:31:08 +0200

On Sat, 03 May 2025 12:38:43 +0300 Eli Zaretskii <[email-masked]> wrote:

>> From: Stephen Berman <[email-masked]>
>> Cc: [email-masked],  [email-masked]
>> Date: Tue, 29 Apr 2025 12:13:28 +0200
>> 
>> 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).
>
> 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