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

Previous Next

Full log

Message #39 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, 26 Apr 2025 11:29:15 +0300

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

> Second, in the first paragraphs of the patch I've tried to describe the
> default behavior concisely and completely; however, the sentence about
> the numeric prefix argument, which evidently comes from the
> documentation in master, is not suitable for emacs-30: the use of the
> prefix argument was added (together with its documentation) as a result
> of bug#72437 only to master.  If my doc changes for emacs-30 are
> acceptable, they should be added to master as well, but not merged,
> because of the prefix argument doc.  But in addition, in testing the use
> of the prefix argument I've encountered what seems like buggy behavior,
> one instance of which I pointed out above; I'm still investigating this
> and plan to file a bug report about it.  A doc patch for master should
> await the outcome of that.

You could either (a) install different changes on each branch, with
"Do not merge" in the log message of emacs-30 commit; or (b) install
only the change for emacs-30, wait for it to be merged, then install
followup changes on master.

> Third, concerning the user options, I think it's better not to use the
> phrase "when non-‘nil’", which is in all cases the default value: for
> electric-pair-preserve-balance, the behavior with that value was already
> described, so it's better (and more parsimonious) to focus on the
> behavior with the non-default value here; and for the other three
> options a user-defined function is also allowed as value, which of
> course is non-nil, but I don't think documenting this value is
> appropriate for the Emacs manual, so I think it's better just to say "by
> default".

The usual style in these cases is to describe the default behavior and
then tell what will happen if the value is customized to nil.  If the
default behavior was already described, you can describe only the
non-default one.

> +  Electric Pair mode is a minor mode that provides a way to easily
> +insert matching delimiters: parentheses, braces, brackets, quotes, etc.
> +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}.
> +
> +  When this mode is enabled and you type an opening delimiter, then by
> +default the matching closing delimiter is normally automatically
> +inserted as well, leaving point between the two.  However, if there is
> +an unmatched closing delimiter later in the buffer, then by default
> +typing an opening delimiter inserts just that character, in order to
> +balance opening and closing delimiters.

The repetition of "by default", let alone with "normally" in the same
sentence, gets in the way, and IMO adds no useful information.  I
suggest to drop those redundant words.

> +  This makes it unnecessary to type a closing delimiter, and doing so
> +normally simply inserts that character.

This sounds like a contradiction to me.  Would the below be accurate:

  This makes it unnecessary to type a closing delimiter in most
  cases.  (If you type it nonetheless, Emacs simply inserts that
  character.)

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

The "only white space" part is inaccurate, and only happens when
electric-pair-skip-whitespace is non-nil.  I think this subtle aspect
is best described where electric-pair-skip-whitespace is documented.
Here, I would only describe the behavior when inserting a closing
delimiter where there is one already.

> +@code{electric-pair-preserve-balance}, when set to @code{nil}, makes
> +typing an opening delimiter insert only that character, thus overriding
> +the default pairing logic of balancing the number of opening and closing
> +delimiters.

This sounds like disabling the main effect of the mode.  Is that
really correct?  If not, then the "default pairing logic of balancing
the number of opening and closing delimiters" should be described
first, to explain what does this option disable, exactly.

>  @vindex electric-pair-delete-adjacent-pairs
> -@code{electric-pair-delete-adjacent-pairs}, when non-@code{nil}, makes
> -backspacing between two adjacent delimiters also automatically delete
> -the closing delimiter.
> +@code{electric-pair-delete-adjacent-pairs}, by default, makes
> +backspacing between two adjacent delimiters delete not only the opening
> +delimiter but also the closing delimiter.

First, "backspacing" is an unfortunate wording, because someone might
interpret it as typing C-b.  I believe the intent is to deleting by
DEL instead.  Second, in my testing typing DEL on the opening
delimiter removes the closing delimiter only if there's _nothing_
between them.  If that is why you mean by "between two adjacent
delimiters", it should be clarified, because I didn't interpret it
that way.  And third, since this is the default behavior, documenting
this option should tell what happens in the non-default case.

>  @vindex electric-pair-open-newline-between-pairs
> -@code{electric-pair-open-newline-between-pairs}, when non-@code{nil},
> -makes inserting a newline between two adjacent pairs also
> -automatically open an extra newline after point.
> +@code{electric-pair-open-newline-between-pairs}, by default, makes
> +inserting a newline between two adjacent pairs also automatically open
> +an extra newline after point.

Some modes customize the default value of this option (for example, it
is nil in *scratch*), so "by default" is not accurate in this case.
Also, the same issue about "between two adjacent delimiters" happens
here as well: the additional newline is inserted only if there's
_nothing_ between the delimiters, not even white space.  And finally,
"open an extra newline" is confusing; I would instead say "inserts one
extra newline after point, moving the closing delimiter to a new line".

>  @vindex electric-pair-skip-whitespace
> -@code{electric-pair-skip-whitespace}, when non-@code{nil}, causes the minor
> -mode to skip whitespace forward before deciding whether to skip over
> -the closing delimiter.
> +@code{electric-pair-skip-whitespace}, by default, makes typing a closing
> +delimiter between matching delimiters of the same type behave as
> +described above.

The description of the default behavior is redundant and is best
omitted.

>                   You can set this option to additionally delete any
> +white space skipped over.

This "skipping over" part is "out of the blue": it is completely
unclear what it alludes to.  This should be explained before
describing the effect of the variable.

>                              You can also set it not to skip over the
> +following closing delimiter but simply insert a closing delimiter at
> +point (thus making the following delimiter unbalanced).

And here, it is unclear what does skipping whitespace have to do with
insertion of the closing delimiter.

Btw, I think the doc strings of these options need clarifications.
They make very little sense to me when I read them.

Thanks.

Previous Next

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