[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#50303: Add interlinks to docstrings of inverse abbrev
From: |
Eli Zaretskii |
Subject: |
bug#50303: Add interlinks to docstrings of inverse abbrev |
Date: |
Tue, 31 Aug 2021 22:03:04 +0300 |
> From: Juri Linkov <juri@linkov.net>
> Cc: 50303@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.