GNU bug report logs - #55527
28.1; Clearer abbrev docstrings

Previous Next

Package: emacs;

Reported by: Howard Melman <hmelman <at> gmail.com>

Date: Thu, 19 May 2022 18:33:01 UTC

Severity: normal

Found in version 28.1

Done: Eli Zaretskii <eliz <at> gnu.org>

Bug is archived. No further changes may be made.

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 55527 in the body.
You can then email your comments to 55527 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to bug-gnu-emacs <at> gnu.org:
bug#55527; Package emacs. (Thu, 19 May 2022 18:33:01 GMT) Full text and rfc822 format available.

Acknowledgement sent to Howard Melman <hmelman <at> gmail.com>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs <at> gnu.org. (Thu, 19 May 2022 18:33:01 GMT) Full text and rfc822 format available.

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

From: Howard Melman <hmelman <at> gmail.com>
To: GNU Emacs <bug-gnu-emacs <at> gnu.org>
Subject: 28.1; Clearer abbrev docstrings
Date: Thu, 19 May 2022 14:32:44 -0400
When using abbrev commands I'm always confused by which 
is the abbrev and which is the expansion.  I think there are a 
few reasons for this.

I know that the manual defines "abbrev" as the short name, but given
it's the package and feature name I also think of it as an overused
term for the pairing of an abbreviation and its expansion.  With this
confusion some of the prompts and command names are easily read as
ambiguous.  (I'll talk about the global forms here but they all apply
to the mode-specific forms too.)

First off, I don't define abbrevs frequently enough to
remember their bindings, so I usually use M-x.  The names of
the commands add-global-abbrev and inverse-add-global-abbrev
also don't resolve the ambiguity, since all they say is one
is the inverse of the other.  I know these are very old
commands, but a clearer alias of the latter could be one of:

    add-global-expansion
    add-global-abbrev-expansion
    add-global-expansion-of-abbrev

I use marginalia so I see annotations when using M-x which
include the first line of the commands' docstring.  The
first line of the docstrings for add-global-abbrev and
inverse-add-global-abbrev don't help me too much.  They are
currently:

    Define global (all modes) abbrev for last word(s) before point.
    Define last word before point as a global (mode-independent) abbrev.

and I find I have to think hard to resolve which is which. I
think these would be clearer:

    Use word(s) before point as the expansion of a new global abbrev.
    Use word before point as the abbreviation of a new global abbrev.

The latter could also be this (though it's 70 chars long):

    Define word before point as a global abbrev, prompt for its expansion.

FWIW I do wish the documentation used "abbreviation" when it refers to
the abbrev so that "abbrev" could refer to the pair of "abbreviation"
and "expansion" or to the feature name.  Even if it did this
occasionally I think it would help.

Then, if I do pick one of the commands the prompts don't
give me confidence I chose the right one.  These are the
interactive prompts for add-global-abbrev and
inverse-add-global-abbrev:

	Global abbrev for "foo":
	Global expansion for "foo":

The latter is fine but the first confuses me (particularly
when defining one word expansions), I think these would be
clearer as:

	Global abbrev for expansion "foo":
	Global expansion of abbrev "foo":

(I'm not sure if "of" or "for" read better in either of the above).
Or even better:

	Global abbrev to expand to "foo":
	Expand global abbrev "foo" to:

Finally define-abbrev has an argument "name" that I find too generic
and a docstring first line I find awkward.  Perhaps change this:

	(defun define-abbrev (table name expansion &optional hook &rest props)
	  "Define an abbrev in TABLE named NAME, to expand to EXPANSION and call HOOK.

to this:

	(defun define-abbrev (table abbrev expansion &optional hook &rest props)
	  "Define in TABLE an ABBREV and its EXPANSION and optionally a HOOK.

(and of course the two uses of the variable name in the
function which I think will read much clearer.)

Howard




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55527; Package emacs. (Thu, 19 May 2022 18:53:01 GMT) Full text and rfc822 format available.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Howard Melman <hmelman <at> gmail.com>
Cc: 55527 <at> debbugs.gnu.org
Subject: Re: bug#55527: 28.1; Clearer abbrev docstrings
Date: Thu, 19 May 2022 21:52:27 +0300
> From: Howard Melman <hmelman <at> gmail.com>
> Date: Thu, 19 May 2022 14:32:44 -0400
> 
>     Define global (all modes) abbrev for last word(s) before point.
>     Define last word before point as a global (mode-independent) abbrev.
> 
> and I find I have to think hard to resolve which is which. I
> think these would be clearer:
> 
>     Use word(s) before point as the expansion of a new global abbrev.

"Use" is ambiguous, because it may be interpreted as "expand it now".
"Define" is better.  So I would suggest

  Define a global abbrev that expands into word(s) preceding point.

>     Use word before point as the abbreviation of a new global abbrev.

"Abbreviation of a new abbrev" is confusing.  I don't actually
understand what's wrong with the original one, viz.:

  Define last word before point as a global (mode-independent) abbrev.

>     Define word before point as a global abbrev, prompt for its expansion.
> 
> FWIW I do wish the documentation used "abbreviation" when it refers to
> the abbrev so that "abbrev" could refer to the pair of "abbreviation"
> and "expansion" or to the feature name.

That'd be counter-productive, because it will cause these doc strings
become longer and more confusing.

> 	Global abbrev for "foo":
> 	Global expansion for "foo":
> 
> The latter is fine but the first confuses me (particularly
> when defining one word expansions), I think these would be
> clearer as:
> 
> 	Global abbrev for expansion "foo":
> 	Global expansion of abbrev "foo":

Is that really more clear?  I would say

  Global abbrev that expands into "foo":
  Expansion for a global abbrev "foo":

But I'm not sure we can make these prompts so much longer than the
original ones without overflowing the minibuffer into a second line,
which is a disadvantage.

> 	(defun define-abbrev (table name expansion &optional hook &rest props)
> 	  "Define an abbrev in TABLE named NAME, to expand to EXPANSION and call HOOK.
> 
> to this:
> 
> 	(defun define-abbrev (table abbrev expansion &optional hook &rest props)
> 	  "Define in TABLE an ABBREV and its EXPANSION and optionally a HOOK.

This loses the explanation of what is HOOK, and is also a very awkward
sentence that I think will be hard on non-native English speakers.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55527; Package emacs. (Thu, 19 May 2022 19:31:02 GMT) Full text and rfc822 format available.

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

From: Howard Melman <hmelman <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#55527: 28.1; Clearer abbrev docstrings
Date: Thu, 19 May 2022 15:30:18 -0400
Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Howard Melman <hmelman <at> gmail.com>
>>     Use word(s) before point as the expansion of a new global abbrev.
>
> "Use" is ambiguous, because it may be interpreted as "expand it now".
> "Define" is better.  So I would suggest
>
>   Define a global abbrev that expands into word(s) preceding point.

I think that's good.

>>     Use word before point as the abbreviation of a new global abbrev.
>
> "Abbreviation of a new abbrev" is confusing.  I don't actually
> understand what's wrong with the original one, viz.:
>
>   Define last word before point as a global (mode-independent) abbrev.

Because I'm not sure if the word will be used as the abbrev
or the expansion.

>>     Define word before point as a global abbrev, prompt for its expansion.

The above makes it clear, what do you think of it?

>> 	Global abbrev for "foo":
>> 	Global expansion for "foo":
>>
>> The latter is fine but the first confuses me (particularly
>> when defining one word expansions), I think these would be
>> clearer as:
>>
>> 	Global abbrev for expansion "foo":
>> 	Global expansion of abbrev "foo":
>
> Is that really more clear?

I think so, because both make it clear what "foo" will be
used for.

> I would say
>
>   Global abbrev that expands into "foo":
>   Expansion for a global abbrev "foo":

Those would be fine with me.

> But I'm not sure we can make these prompts so much longer than the
> original ones without overflowing the minibuffer into a second line,
> which is a disadvantage.

I tend to use very short abbrevs that expand into longer
words, so it wouldn't be a problem for me.  For those that
expand them to something longer, these aren't that much
longer prompts so the window they would break (expansions
long enough to break but short enough not be broken before)
doesn't seem large to me.

>> 	(defun define-abbrev (table name expansion &optional hook &rest props)
>> 	  "Define an abbrev in TABLE named NAME, to expand to EXPANSION and call HOOK.
>>
>> to this:
>>
>> 	(defun define-abbrev (table abbrev expansion &optional hook &rest props)
>> 	  "Define in TABLE an ABBREV and its EXPANSION and optionally a HOOK.
>
> This loses the explanation of what is HOOK, and is also a very awkward
> sentence that I think will be hard on non-native English
> speakers.

I'm not sure that "call HOOK" is an "explanation".  I
already assumed a "hook" would be called and I was confused
when it would be called.  I think mine makes it slightly
clearer that it's associated with the persisted definition
rather than called when the define-abbrev is called.

And while I agree "Define in TABLE" is a little (not very)
awkward, I think it's less awkard than the original, where
NAME could be the name of the abbrev or of the TABLE.

Also the original was 75 chars long and mine fits in the
recommendated 67 character length.

Maybe someone has a better suggestion, but I think changing
"name" to "abbrev" is worth doing.

Also I think the docstring should say define-abbrev returns
"name" (hopefully changed to "abbrev").

Howard





Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55527; Package emacs. (Thu, 19 May 2022 19:48:01 GMT) Full text and rfc822 format available.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Howard Melman <hmelman <at> gmail.com>
Cc: 55527 <at> debbugs.gnu.org
Subject: Re: bug#55527: 28.1; Clearer abbrev docstrings
Date: Thu, 19 May 2022 22:46:51 +0300
> From: Howard Melman <hmelman <at> gmail.com>
> Date: Thu, 19 May 2022 15:30:18 -0400
> 
> > I don't actually understand what's wrong with the original one,
> > viz.:
> >
> >   Define last word before point as a global (mode-independent) abbrev.
> 
> Because I'm not sure if the word will be used as the abbrev
> or the expansion.

If you add the expansion part, the line becomes too long, though:

  Define last word before point as expansion of a global (mode-independent) abbrev.

> > I would say
> >
> >   Global abbrev that expands into "foo":
> >   Expansion for a global abbrev "foo":
> 
> Those would be fine with me.
> 
> > But I'm not sure we can make these prompts so much longer than the
> > original ones without overflowing the minibuffer into a second line,
> > which is a disadvantage.
> 
> I tend to use very short abbrevs that expand into longer
> words, so it wouldn't be a problem for me.

The problem in the first prompt is with "foo": it could be arbitrarily
long.  And in the second prompt you are supposed to type the
expansion, which again can be long.

> >> 	(defun define-abbrev (table abbrev expansion &optional hook &rest props)
> >> 	  "Define in TABLE an ABBREV and its EXPANSION and optionally a HOOK.
> >
> > This loses the explanation of what is HOOK, and is also a very awkward
> > sentence that I think will be hard on non-native English
> > speakers.
> 
> I'm not sure that "call HOOK" is an "explanation".  I
> already assumed a "hook" would be called and I was confused
> when it would be called.

It will be called, but by whom and when?




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55527; Package emacs. (Thu, 19 May 2022 20:39:02 GMT) Full text and rfc822 format available.

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

From: Howard Melman <hmelman <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#55527: 28.1; Clearer abbrev docstrings
Date: Thu, 19 May 2022 16:38:42 -0400
Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Howard Melman <hmelman <at> gmail.com>
>> Date: Thu, 19 May 2022 15:30:18 -0400
>>
>> > I don't actually understand what's wrong with the original one,
>> > viz.:
>> >
>> >   Define last word before point as a global (mode-independent) abbrev.
>>
>> Because I'm not sure if the word will be used as the abbrev
>> or the expansion.
>
> If you add the expansion part, the line becomes too long, though:
>
>   Define last word before point as expansion of a global (mode-independent) abbrev.

I think you can loose the "mode-independent" part, as global
covers that pretty clearly, how about:

   Define last word before point as expansion of a global abbrev.

>> > I would say
>> >
>> >   Global abbrev that expands into "foo":
>> >   Expansion for a global abbrev "foo":
>>
>> Those would be fine with me.
>>
>> > But I'm not sure we can make these prompts so much longer than the
>> > original ones without overflowing the minibuffer into a second line,
>> > which is a disadvantage.
>>
>> I tend to use very short abbrevs that expand into longer
>> words, so it wouldn't be a problem for me.
>
> The problem in the first prompt is with "foo": it could be arbitrarily
> long.  And in the second prompt you are supposed to type the
> expansion, which again can be long.

Yes but I'm adding about 10 characters to the prompt, so
once you get to "arbitrarily long", 10 characters only
affects so many of them :)

>> >> 	(defun define-abbrev (table abbrev expansion &optional hook &rest props)
>> >> 	  "Define in TABLE an ABBREV and its EXPANSION and optionally a HOOK.
>> >
>> > This loses the explanation of what is HOOK, and is also a very awkward
>> > sentence that I think will be hard on non-native English
>> > speakers.
>>
>> I'm not sure that "call HOOK" is an "explanation".  I
>> already assumed a "hook" would be called and I was confused
>> when it would be called.
>
> It will be called, but by whom and when?

Yes that was *my* point.  The original says:

Define an abbrev in TABLE named NAME, to expand to EXPANSION and call HOOK.

which to me doesn't answer "by whom and when" and I think is
actually less clear than my rewording.  Perhaps better is:

  Define in TABLE an ABBREV and its EXPANSION and optionally its HOOK.

I don't think it's at all obvious how the original clauses
relate to each other (thankfully the full docstring is much
clearer) but as you brought up non-native english speakers I
would think the original is also difficult for them.

-- 

Howard





Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55527; Package emacs. (Fri, 20 May 2022 05:49:01 GMT) Full text and rfc822 format available.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Howard Melman <hmelman <at> gmail.com>
Cc: 55527 <at> debbugs.gnu.org
Subject: Re: bug#55527: 28.1; Clearer abbrev docstrings
Date: Fri, 20 May 2022 08:48:28 +0300
> From: Howard Melman <hmelman <at> gmail.com>
> Date: Thu, 19 May 2022 16:38:42 -0400
> 
> > If you add the expansion part, the line becomes too long, though:
> >
> >   Define last word before point as expansion of a global (mode-independent) abbrev.
> 
> I think you can loose the "mode-independent" part, as global
> covers that pretty clearly, how about:
> 
>    Define last word before point as expansion of a global abbrev.

No, "global" doesn't explain itself in this case, because we aren't
talking about a minor mode.  So I'd rather lose "a" or even replace
"of a" with "for".  We could also lose "last".

> > It will be called, but by whom and when?
> 
> Yes that was *my* point.  The original says:
> 
> Define an abbrev in TABLE named NAME, to expand to EXPANSION and call HOOK.
> 
> which to me doesn't answer "by whom and when"

Yes, it does: the abbrev you define will call HOOK at the time of the
expansion.  That's what the sentence says.

>   Define in TABLE an ABBREV and its EXPANSION and optionally its HOOK.

"Define in TABLE" is awkward (or even incorrect) English.  OTOH,
"optionally" is redundant, so maybe if we lose it, we could reword the
sentence to be more correct English-wise.

> I don't think it's at all obvious how the original clauses
> relate to each other (thankfully the full docstring is much
> clearer) but as you brought up non-native english speakers I
> would think the original is also difficult for them.

The comparison is always relative, not absolute.  And if the full doc
string makes things clear, it's fine.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55527; Package emacs. (Fri, 20 May 2022 07:52:01 GMT) Full text and rfc822 format available.

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

From: Juri Linkov <juri <at> linkov.net>
To: Howard Melman <hmelman <at> gmail.com>
Cc: 55527 <at> debbugs.gnu.org
Subject: Re: bug#55527: 28.1; Clearer abbrev docstrings
Date: Fri, 20 May 2022 10:41:56 +0300
> When using abbrev commands I'm always confused by which 
> is the abbrev and which is the expansion.  I think there are a 
> few reasons for this.

The unhelpful abbrev docstrings and prompts is a known problem.
Recently I tried to ameliorate this problem by adding these new sections
to the docstrings:

  See also ‘inverse-add-global-abbrev’, which performs the opposite task:
  if the abbrev text is already in the buffer, use this command to
  define an abbrev by specifying the expansion in the minibuffer.

and

  See also ‘add-global-abbrev’, which performs the opposite task:
  if the expansion is already in the buffer, use this command
  to define an abbrev by specifying the abbrev in the minibuffer.

So every time I use this feature, I have to consult these parts
of docstrings to recall what these commands do.

> I think these would be clearer:
>
>     Use word(s) before point as the expansion of a new global abbrev.
>     Use word before point as the abbreviation of a new global abbrev.
>
> [...]
>
> 	Global abbrev for expansion "foo":
> 	Global expansion of abbrev "foo":

Thanks, these and other such changes would be much of help.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55527; Package emacs. (Fri, 20 May 2022 13:13:01 GMT) Full text and rfc822 format available.

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

From: Howard Melman <hmelman <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#55527: 28.1; Clearer abbrev docstrings
Date: Fri, 20 May 2022 09:12:20 -0400
Juri Linkov <juri <at> linkov.net> writes:

> The unhelpful abbrev docstrings and prompts is a known problem.

Thanks for saying so, I wasn't sure if I was the only one
confused by them.

> Recently I tried to ameliorate this problem by adding
> these new sections to the docstrings:

I saw these were added 9 months ago and they are indeed
helpful, thanks.

>> I think these would be clearer:
>>
>>     Use word(s) before point as the expansion of a new global abbrev.
>>     Use word before point as the abbreviation of a new global abbrev.
>>
>> [...]
>>
>> 	Global abbrev for expansion "foo":
>> 	Global expansion of abbrev "foo":
>
> Thanks, these and other such changes would be much of help.

Thanks for the confirmation.

-- 

Howard





Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55527; Package emacs. (Fri, 20 May 2022 13:36:02 GMT) Full text and rfc822 format available.

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

From: Howard Melman <hmelman <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#55527: 28.1; Clearer abbrev docstrings
Date: Fri, 20 May 2022 09:35:43 -0400
Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Howard Melman <hmelman <at> gmail.com>
>>
>> > If you add the expansion part, the line becomes too long, though:
>> >
>> >   Define last word before point as expansion of a global (mode-independent) abbrev.
>>
>> I think you can loose the "mode-independent" part, as global
>> covers that pretty clearly, how about:
>>
>>    Define last word before point as expansion of a global abbrev.
>
> No, "global" doesn't explain itself in this case, because we aren't
> talking about a minor mode.  So I'd rather lose "a" or even replace
> "of a" with "for".  We could also lose "last".

To kind of prove my point, we've confused the docstrings of
the two commands :) The command that only uses the last word
(as opposed to possibly several words) of the buffer text
uses that word as the abbrev not the expansion.

Maybe we could go this route (here are possible docstrings for both):

    Define abbrev for all modes that expands to word(s) before point.
    Define word before point as abbrev for all modes, prompt for expansion.

The last is slightly long at 71 chars.

>> > It will be called, but by whom and when?
>>
>> Yes that was *my* point.  The original says:
>>
>> Define an abbrev in TABLE named NAME, to expand to EXPANSION and call HOOK.
>>
>> which to me doesn't answer "by whom and when"
>
> Yes, it does: the abbrev you define will call HOOK at the time of the
> expansion.  That's what the sentence says.

The sentence does not say "at the time of expansion" that would be clear.
Instead the sentence has a clause "and call HOOK" without an
oxford comma, so it's not clear where the clause attaches to.  It's also 75
chars long.

>>   Define in TABLE an ABBREV and its EXPANSION and optionally its HOOK.
>
> "Define in TABLE" is awkward (or even incorrect) English.  OTOH,
> "optionally" is redundant, so maybe if we lose it, we could reword the
> sentence to be more correct English-wise.

I wasn't clear on the conventions of including optional
arguments in the first line of a docstring.  The existing
string includes the optional HOOK but not PROPS.  The HOOK
is optional and in Emacs itself only used by mail
abbrevs. My choice would be to leave HOOK out of the first
line.  But if it must be in there, how about:

    In TABLE, define an ABBREV, its EXPANSION, and optionally its HOOK.

If you don't care for this, then I'd be fine with just
changing the argument NAME to ABBREV so the simplest change
would be:

    Define an abbrev in TABLE named ABBREV, to expand to EXPANSION and call HOOK.

Though now it's 77 chars, up from 75.

-- 

Howard





Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55527; Package emacs. (Fri, 20 May 2022 16:00:02 GMT) Full text and rfc822 format available.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Howard Melman <hmelman <at> gmail.com>
Cc: 55527 <at> debbugs.gnu.org
Subject: Re: bug#55527: 28.1; Clearer abbrev docstrings
Date: Fri, 20 May 2022 18:59:09 +0300
> From: Howard Melman <hmelman <at> gmail.com>
> Date: Fri, 20 May 2022 09:35:43 -0400
> 
> >>    Define last word before point as expansion of a global abbrev.
> >
> > No, "global" doesn't explain itself in this case, because we aren't
> > talking about a minor mode.  So I'd rather lose "a" or even replace
> > "of a" with "for".  We could also lose "last".
> 
> To kind of prove my point, we've confused the docstrings of
> the two commands :) The command that only uses the last word
> (as opposed to possibly several words) of the buffer text
> uses that word as the abbrev not the expansion.

Is that relevant for the "global" issue to which I responded?

> Maybe we could go this route (here are possible docstrings for both):
> 
>     Define abbrev for all modes that expands to word(s) before point.
>     Define word before point as abbrev for all modes, prompt for expansion.
> 
> The last is slightly long at 71 chars.

I don't see why these are better.  And we almost never mention the
prompt in the first line of a doc string, unless there's nothing more
important to say there (which isn't the case here).

> >> Define an abbrev in TABLE named NAME, to expand to EXPANSION and call HOOK.
> >>
> >> which to me doesn't answer "by whom and when"
> >
> > Yes, it does: the abbrev you define will call HOOK at the time of the
> > expansion.  That's what the sentence says.
> 
> The sentence does not say "at the time of expansion" that would be clear.

Not explicitly, but that's implied quite clearly.  And given the
screen estate constraints, we cannot do much better, except in the
following parts of the doc string.

> Instead the sentence has a clause "and call HOOK" without an
> oxford comma, so it's not clear where the clause attaches to.

I won't object to adding a comma.  But I'm not sure it is needed,
since "expand and call" both allude to the abbrev.

> >>   Define in TABLE an ABBREV and its EXPANSION and optionally its HOOK.
> >
> > "Define in TABLE" is awkward (or even incorrect) English.  OTOH,
> > "optionally" is redundant, so maybe if we lose it, we could reword the
> > sentence to be more correct English-wise.
> 
> I wasn't clear on the conventions of including optional
> arguments in the first line of a docstring.  The existing
> string includes the optional HOOK but not PROPS.  The HOOK
> is optional and in Emacs itself only used by mail
> abbrevs. My choice would be to leave HOOK out of the first
> line.  But if it must be in there, how about:
> 
>     In TABLE, define an ABBREV, its EXPANSION, and optionally its HOOK.

The convention is that we don't have to mention optional arguments,
but we can if that's possible and important.

> If you don't care for this, then I'd be fine with just
> changing the argument NAME to ABBREV so the simplest change
> would be:
> 
>     Define an abbrev in TABLE named ABBREV, to expand to EXPANSION and call HOOK.

Why not

  Define ABBREV in TABLE, to expand into EXPANSION and call HOOK.

?




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55527; Package emacs. (Fri, 20 May 2022 17:05:02 GMT) Full text and rfc822 format available.

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

From: Howard Melman <hmelman <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 55527 <at> debbugs.gnu.org
Subject: Re: bug#55527: 28.1; Clearer abbrev docstrings
Date: Fri, 20 May 2022 13:03:43 -0400

> On May 20, 2022, at 11:59 AM, Eli Zaretskii <eliz <at> gnu.org> wrote:
> 
>> From: Howard Melman <hmelman <at> gmail.com>
>> Date: Fri, 20 May 2022 09:35:43 -0400
>> 
>>>>   Define last word before point as expansion of a global abbrev.
>>> 
>>> No, "global" doesn't explain itself in this case, because we aren't
>>> talking about a minor mode.  So I'd rather lose "a" or even replace
>>> "of a" with "for".  We could also lose "last".
>> 
>> To kind of prove my point, we've confused the docstrings of
>> the two commands :) The command that only uses the last word
>> (as opposed to possibly several words) of the buffer text
>> uses that word as the abbrev not the expansion.
> 
> Is that relevant for the "global" issue to which I responded?

It's relevant to this bug report.

> 
>> Maybe we could go this route (here are possible docstrings for both):
>> 
>>    Define abbrev for all modes that expands to word(s) before point.
>>    Define word before point as abbrev for all modes, prompt for expansion.
>> 
>> The last is slightly long at 71 chars.
> 
> I don't see why these are better.  

To the point above, these make it explict which part of the abbrev the
text before point will be used for.  

> And we almost never mention the
> prompt in the first line of a doc string, unless there's nothing more
> important to say there (which isn't the case here).

Given that just "abbrev" is somewhat ambiguous (and apparently not
just to me) it was a way to mention that the word before point isn't
used as the expansion.  I'm open to another construction that does this.

> 
>>>> Define an abbrev in TABLE named NAME, to expand to EXPANSION and call HOOK.
>>>> 
>>>> which to me doesn't answer "by whom and when"
>>> 
>>> Yes, it does: the abbrev you define will call HOOK at the time of the
>>> expansion.  That's what the sentence says.
>> 
>> The sentence does not say "at the time of expansion" that would be clear.
> 
> Not explicitly, but that's implied quite clearly.  And given the
> screen estate constraints, we cannot do much better, except in the
> following parts of the doc string.
> 
>> Instead the sentence has a clause "and call HOOK" without an
>> oxford comma, so it's not clear where the clause attaches to.
> 
> I won't object to adding a comma.  But I'm not sure it is needed,
> since "expand and call" both allude to the abbrev.
> 
>>>>  Define in TABLE an ABBREV and its EXPANSION and optionally its HOOK.
>>> 
>>> "Define in TABLE" is awkward (or even incorrect) English.  OTOH,
>>> "optionally" is redundant, so maybe if we lose it, we could reword the
>>> sentence to be more correct English-wise.
>> 
>> I wasn't clear on the conventions of including optional
>> arguments in the first line of a docstring.  The existing
>> string includes the optional HOOK but not PROPS.  The HOOK
>> is optional and in Emacs itself only used by mail
>> abbrevs. My choice would be to leave HOOK out of the first
>> line.  But if it must be in there, how about:
>> 
>>    In TABLE, define an ABBREV, its EXPANSION, and optionally its HOOK.
> 
> The convention is that we don't have to mention optional arguments,
> but we can if that's possible and important.
> 
>> If you don't care for this, then I'd be fine with just
>> changing the argument NAME to ABBREV so the simplest change
>> would be:
>> 
>>    Define an abbrev in TABLE named ABBREV, to expand to EXPANSION and call HOOK.
> 
> Why not
> 
>  Define ABBREV in TABLE, to expand into EXPANSION and call HOOK.

I'm fine with that, but the variables are not in the order they are called
which I know is usually desired.

Howard





Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55527; Package emacs. (Sat, 21 May 2022 07:24:02 GMT) Full text and rfc822 format available.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Howard Melman <hmelman <at> gmail.com>
Cc: 55527 <at> debbugs.gnu.org
Subject: Re: bug#55527: 28.1; Clearer abbrev docstrings
Date: Sat, 21 May 2022 10:23:22 +0300
I've now improved the doc strings and prompts, on the release branch,
per this discussion.

Any more issues, or can we close this?

Thanks.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55527; Package emacs. (Sat, 21 May 2022 13:42:02 GMT) Full text and rfc822 format available.

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

From: Howard Melman <hmelman <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 55527 <at> debbugs.gnu.org
Subject: Re: bug#55527: 28.1; Clearer abbrev docstrings
Date: Sat, 21 May 2022 09:41:41 -0400
On May 21, 2022, at 3:23 AM, Eli Zaretskii <eliz <at> gnu.org> wrote:
> 
> I've now improved the doc strings and prompts, on the release branch,
> per this discussion.
> 
> Any more issues, or can we close this?

I think the new prompts will be very helpful.

I think the new use of "abbreviation" in the inverse- flavor of the
commands will help.

For the non-inverse commands I'd love to see the "word(s)"
construction retained as it jumps out when skimming the docstring and
is a bit more accurate.  So how about:

  (defun add-mode-abbrev (arg)
  "Define a mode-specific abbrev which expands into the word(s) before point.

  (defun add-global-abbrev (arg)
  "Define a global (all modes) abbrev which expands into word(s) before point.

Howard





Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55527; Package emacs. (Sat, 21 May 2022 14:11:02 GMT) Full text and rfc822 format available.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Howard Melman <hmelman <at> gmail.com>
Cc: 55527 <at> debbugs.gnu.org
Subject: Re: bug#55527: 28.1; Clearer abbrev docstrings
Date: Sat, 21 May 2022 17:09:59 +0300
> From: Howard Melman <hmelman <at> gmail.com>
> Date: Sat, 21 May 2022 09:41:41 -0400
> Cc: 55527 <at> debbugs.gnu.org
> 
> For the non-inverse commands I'd love to see the "word(s)"
> construction retained as it jumps out when skimming the docstring and
> is a bit more accurate.  So how about:
> 
>   (defun add-mode-abbrev (arg)
>   "Define a mode-specific abbrev which expands into the word(s) before point.
> 
>   (defun add-global-abbrev (arg)
>   "Define a global (all modes) abbrev which expands into word(s) before point.

This is IMO a tradeoff for the worse: it makes the first line less
clear on behalf of including information that is non-essential.

In many commands, we describe in the first line what the command does
by default, and defer the description of what ARG does to the body of
the doc string.  A random example:

  (transpose-chars ARG)

  Interchange characters around point, moving forward one character.
  With prefix arg ARG, effect is to take character before point
  and drag it forward past ARG other characters (backward if ARG negative).

add-mode-abbrev and add-global-abbrev are the main user-level entry
points into this facility, so IMO it is much more important to have
the first line be as self-explanatory as possible than to describe in
it some optional features.  After all, most users will invoke these
commands through their key bindings, thus without any prefix arg.
Moreover, some values of the prefix have the effect that isn't
captured by saying "word(s)", and I see no reason to consider those
effects less important than the effect of a positive ARG.

So I'd prefer to keep the new doc strings as they are.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55527; Package emacs. (Sat, 21 May 2022 17:51:02 GMT) Full text and rfc822 format available.

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

From: Howard Melman <hmelman <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 55527 <at> debbugs.gnu.org
Subject: Re: bug#55527: 28.1; Clearer abbrev docstrings
Date: Sat, 21 May 2022 13:49:48 -0400
On May 21, 2022, at 10:09 AM, Eli Zaretskii <eliz <at> gnu.org> wrote:
> 
>> From: Howard Melman <hmelman <at> gmail.com>
>> Date: Sat, 21 May 2022 09:41:41 -0400
>> Cc: 55527 <at> debbugs.gnu.org
>> 
>> For the non-inverse commands I'd love to see the "word(s)"
>> construction retained as it jumps out when skimming the docstring and
>> is a bit more accurate.  So how about:
>> 
>>  (defun add-mode-abbrev (arg)
>>  "Define a mode-specific abbrev which expands into the word(s) before point.
>> 
>>  (defun add-global-abbrev (arg)
>>  "Define a global (all modes) abbrev which expands into word(s) before point.
> 
> This is IMO a tradeoff for the worse: it makes the first line less
> clear on behalf of including information that is non-essential.
> 

> In many commands, we describe in the first line what the command does
> by default, and defer the description of what ARG does to the body of
> the doc string.  A random example:
> 
>  (transpose-chars ARG)
> 
>  Interchange characters around point, moving forward one character.
>  With prefix arg ARG, effect is to take character before point
>  and drag it forward past ARG other characters (backward if ARG negative).

The existing docstrings for these commands had "word(s)" in them
and I don't think that's what made them unclear.  I also think it's a
common case to define an abbrev for a multi-word expansion.

I count about 80 first line docstrings in Emacs lisp code that use a "(s)" construct.
  
But looking at forward-word's docstring for inspiration, how about this:

    "Define a mode-specific abbrev which expands into ARG words before point.
    "Define a global (all modes) abbrev which expands into ARG words before point.

I think using ARG as above includes the common case of an expansion
being more than one word and defers the less common uses of
a zero or negative arg to the docstring body.  I think too that an ARG 
of zero is unclear so the user would read the body.  A negative ARG would
often reverse direction so perhaps it's unintuitive, but I think that's the case
if ARG is mentioned in the first line or not.

Also, I see now that the inverse- versions of these command treat a 
negative argument as reversing the direction to find the word to use
as the abbreviation but the (old and new) docstrings fails to mention 
this.  I'm not sure if that's intentional or not (IMO it's an odd use case).

Howard





Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55527; Package emacs. (Sat, 21 May 2022 18:07:02 GMT) Full text and rfc822 format available.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Howard Melman <hmelman <at> gmail.com>
Cc: 55527 <at> debbugs.gnu.org
Subject: Re: bug#55527: 28.1; Clearer abbrev docstrings
Date: Sat, 21 May 2022 21:06:01 +0300
> From: Howard Melman <hmelman <at> gmail.com>
> Date: Sat, 21 May 2022 13:49:48 -0400
> Cc: 55527 <at> debbugs.gnu.org
> 
> The existing docstrings for these commands had "word(s)" in them
> and I don't think that's what made them unclear.  I also think it's a
> common case to define an abbrev for a multi-word expansion.

I disagree, and let's leave it at that.

> Also, I see now that the inverse- versions of these command treat a 
> negative argument as reversing the direction to find the word to use
> as the abbreviation but the (old and new) docstrings fails to mention 
> this.  I'm not sure if that's intentional or not (IMO it's an odd use case).

This is unrelated.  The effect of negative argument was implied; I've
now made it explicit.

Our disagreement aside, are there any other issues left?




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#55527; Package emacs. (Sat, 21 May 2022 18:27:01 GMT) Full text and rfc822 format available.

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

From: Howard Melman <hmelman <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 55527 <at> debbugs.gnu.org
Subject: Re: bug#55527: 28.1; Clearer abbrev docstrings
Date: Sat, 21 May 2022 14:26:29 -0400

> On May 21, 2022, at 2:06 PM, Eli Zaretskii <eliz <at> gnu.org> wrote:
> 
>> From: Howard Melman <hmelman <at> gmail.com>
>> Date: Sat, 21 May 2022 13:49:48 -0400
>> Cc: 55527 <at> debbugs.gnu.org
>> 
>> The existing docstrings for these commands had "word(s)" in them
>> and I don't think that's what made them unclear.  I also think it's a
>> common case to define an abbrev for a multi-word expansion.
> 
> I disagree, and let's leave it at that.
> 
>> Also, I see now that the inverse- versions of these command treat a 
>> negative argument as reversing the direction to find the word to use
>> as the abbreviation but the (old and new) docstrings fails to mention 
>> this.  I'm not sure if that's intentional or not (IMO it's an odd use case).
> 
> This is unrelated.  The effect of negative argument was implied; I've
> now made it explicit.
> 
> Our disagreement aside, are there any other issues left?

Nope.  Thanks.

Howard



Reply sent to Eli Zaretskii <eliz <at> gnu.org>:
You have taken responsibility. (Sat, 21 May 2022 18:47:02 GMT) Full text and rfc822 format available.

Notification sent to Howard Melman <hmelman <at> gmail.com>:
bug acknowledged by developer. (Sat, 21 May 2022 18:47:02 GMT) Full text and rfc822 format available.

Message #58 received at 55527-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Howard Melman <hmelman <at> gmail.com>
Cc: 55527-done <at> debbugs.gnu.org
Subject: Re: bug#55527: 28.1; Clearer abbrev docstrings
Date: Sat, 21 May 2022 21:46:08 +0300
> From: Howard Melman <hmelman <at> gmail.com>
> Date: Sat, 21 May 2022 14:26:29 -0400
> Cc: 55527 <at> debbugs.gnu.org
> 
> 
> 
> > Our disagreement aside, are there any other issues left?
> 
> Nope.  Thanks.

Great, thanks.  So I'm closing this bug.




bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Sun, 19 Jun 2022 11:24:06 GMT) Full text and rfc822 format available.

This bug report was last modified 1 year and 283 days ago.

Previous Next


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