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

Previous Next

Full log

Message #51 received at 78021 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stephen Berman <stephen.berman <at> gmx.net>
Cc: 78021 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#78021: 30.1; Unclear sentence in (emacs)Matching
Date: Sat, 03 May 2025 12:38:43 +0300

> From: Stephen Berman <stephen.berman <at> gmx.net>
> Cc: 78021 <at> debbugs.gnu.org,  drew.adams <at> oracle.com
> Date: Tue, 29 Apr 2025 12:13:28 +0200
> 
> On Sat, 26 Apr 2025 11:29:15 +0300 Eli Zaretskii <eliz <at> gnu.org> wrote:
> 
> >> From: Stephen Berman <stephen.berman <at> gmx.net>
> >> Cc: eliz <at> gnu.org,  drew.adams <at> oracle.com
> >> 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.

Previous Next

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