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

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

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

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