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

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: Howard Melman <hmelman <at> gmail.com>
Cc: 55527 <at> debbugs.gnu.org
Subject: 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?

Previous Next

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