GNU bug report logs - #50303
Add interlinks to docstrings of inverse abbrev

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: Juri Linkov <juri <at> linkov.net>
Cc: 50303 <at> debbugs.gnu.org
Subject: bug#50303: Add interlinks to docstrings of inverse abbrev
Date: Tue, 31 Aug 2021 22:03:04 +0300

> From: Juri Linkov <juri <at> linkov.net>
> Cc: 50303 <at> debbugs.gnu.org
> Date: Tue, 31 Aug 2021 21:11:05 +0300
> 
> >> +You can also use the opposite command `inverse-add-mode-abbrev'.
> >
> > Thanks, but I think "you can also use" is not the best text here.  It
> > could be interpreted to mean that the other command does something
> > similar, which is not true, and contradicts the "opposite" part.
> > This makes the text confusing.
> >
> > How about saying explicitly what that command does.  For example:
> >
> >   To define expansion for the word at point, use `inverse-add-mode-abbrev'.
> >
> > And similarly for the other doc strings.
> 
> The intention was to indicate that these are opposite commands.

I understand.  But "opposite" is not well-defined in this case (it
could be a command that UN-defines an abbrev, for instance), and
therefore requires a long explanation:

> A good explanation is in (info "(emacs) Defining Abbrevs"):
> 
>      ‘C-x a i g’ (‘inverse-add-global-abbrev’) and ‘C-x a i l’
>   (‘inverse-add-mode-abbrev’) perform the opposite task: if the abbrev
>   text is already in the buffer, you use these commands to define an
>   abbrev by specifying the expansion in the minibuffer.  These commands
>   will expand the abbrev text used for the definition.
> 
> Also to reduce confusion, to explicitly mention what another command does:
> 
> 1. the abbrev is in the buffer, read the expansion from the minibuffer
> 2. the expansion is in the buffer, read the abbrev from the minibuffer
> 
> So maybe this patch is better:

If you like what the manual says, why not say in the doc string what
the manual says, or some simple variant of that?  I doubt that you'll
be able to come up with a significantly shorter description that is
still clear enough.

Thanks.

Previous Next

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