procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation of the 'abbrev-suggest' feature

Browse source 
* lisp/abbrev.el (abbrev-suggest, abbrev-suggest-hint-threshold)
(abbrev-suggest-show-report): Improve wording of the doc strings.

* doc/emacs/abbrevs.texi (Abbrevs Suggestions): Fix the typo in
the node name.  Improve wording.
* doc/emacs/emacs.texi (Top): Add the new node in the @detailmenu
section.

* etc/NEWS: Improve wording of the NEWS entry for
'abbrev-suggest'.
This commit is contained in:
Eli Zaretskii 2020-09-27 08:57:17 +03:00
parent 768676f74f
commit c37370a7a0
4 changed files with 41 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
doc/emacs/abbrevs.texi
View file

@ -28,7 +28,7 @@ Automatic Typing}.
* Abbrev Concepts:: Fundamentals of defined abbrevs.
* Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
* Abbrevs Suggestions:: Get suggestions about defined abbrevs.
* Abbrevs Suggestions:: Get automatic suggestions about defined abbrevs.
* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
* Saving Abbrevs:: Saving the entire list of abbrevs for another session.
* Dynamic Abbrevs:: Abbreviations for words already in the buffer.
@ -224,34 +224,35 @@ changing this function you can make arbitrary changes to
the abbrev expansion. @xref{Abbrev Expansion,,, elisp, The Emacs Lisp
Reference Manual}.
@node Abbrev Suggestions
@section Abbrev Suggestions
@node Abbrevs Suggestions
@section Abbrevs Suggestions
You can get abbrev suggestions when you manually type text for which
there is currently an active defined abbrev. For example, if there is
an abbrev @samp{foo} with the expansion @samp{find outer otter}, and
you manually type @samp{find outer otter}, the abbrev suggestion
feature will notice this and show a hint in the echo area when you
have stopped typing.
you manually type @samp{find outer otter}, Emacs can notice this and
show a hint in the echo area when you have stopped typing.
@vindex abbrev-suggest
Enable the abbrev suggestion feature by setting
@code{abbrev-suggest} to @code{t}.
To enable the abbrev suggestion feature, customize the option
@code{abbrev-suggest} to a non-@code{nil} value.
@vindex abbrev-suggest-hint-threshold
Controls when to suggest an abbrev to the user. The variable
defines the number of characters that the user must save in order to
get a suggestion. For example, if the user types @samp{foo bar}
(seven characters) and there is an abbrev @samp{fubar} defined (five
characters), the user will not get any suggestion unless the threshold
is set to the number 2 or lower. With the default value 3, the user
would not get any suggestion, because the savings in using the abbrev
are not above the threshold. If you always want to get abbrev
suggestions, set this variable to 0.
The variable @code{abbrev-suggest-hint-threshold} controls when to
suggest an abbrev to the user. This variable defines the minimum
savings (in terms of the number of characters the user will not have
to type) required for Emacs to suggest using an abbrev. For example,
if the user types @samp{foo bar} (seven characters) and there is an
abbrev @samp{fubar} defined (five characters), the user will not get
any suggestion unless the threshold is set to the number 2 or lower.
With the default value 3, the user would not get any suggestion in
this example, because the savings in using the abbrev are below
the threshold. If you always want to get abbrev suggestions, set this
variable's value to zero.
@findex abbrev-suggest-show-report
The command @code{abbrev-suggest-show-report} can be used to show a
buffer with all abbrev suggestions from the current editing session.
The command @code{abbrev-suggest-show-report} displays a buffer with
all the abbrev suggestions shown during the current editing session.
This can be useful if you get several abbrev suggestions and don't
remember them all.

1
doc/emacs/emacs.texi
View file

@ -908,6 +908,7 @@ Abbrevs
* Abbrev Concepts:: Fundamentals of defined abbrevs.
* Defining Abbrevs:: Defining an abbrev, so it will expand when typed.
* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
* Abbrevs Suggestions:: Get automatic suggestions about defined abbrevs.
* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs.
* Saving Abbrevs:: Saving the entire list of abbrevs for another session.
* Dynamic Abbrevs:: Abbreviations for words already in the buffer.

10
etc/NEWS
View file

@ -1274,12 +1274,12 @@ of conditionals.
** Abbrev mode
+++
*** Abbrev can now suggest pre-existing abbrevs based on typed text.
*** Emacs can now suggest to use an abbrev based on text you type.
A new user option, 'abbrev-suggest', enables the new abbrev suggestion
feature. When enabled, if a user manually type a piece of text that
could have been written by using an abbrev, a hint will be displayed
in the echo area, mentioning the abbrev that could have been used
instead.
feature. When enabled, if a user manually types a piece of text that
could have saved enough typing by using an abbrev, a hint will be
displayed in the echo area, mentioning the abbrev that could have been
used instead.
* New Modes and Packages in Emacs 28.1

27
lisp/abbrev.el
View file

@ -825,22 +825,23 @@ see `define-abbrev' for details."
Takes no argument and should return the abbrev symbol if expansion took place.")
(defcustom abbrev-suggest nil
"Non-nil means suggest abbrevs to the user.
By enabling this option, if abbrev mode is enabled and if the
user has typed some text that exists as an abbrev, suggest to the
user to use the abbrev by displaying a message in the echo area."
"Non-nil means suggest using abbrevs to save typing.
When abbrev mode is active and this option is non-nil, Emacs will
suggest in the echo area to use an existing abbrev if doing so
will save enough typing. See `abbrev-suggest-hint-threshold' for
the definition of \"enough typing\"."
:type 'boolean
:version "28.1")
(defcustom abbrev-suggest-hint-threshold 3
"Threshold for when to inform the user that there is an abbrev.
The threshold is the number of characters that differ between the
length of the abbrev and the length of the expansion. The
thinking is that if the expansion is only one or a few characters
"Threshold for when to suggest to use an abbrev to save typing.
The threshold is the amount of typing, in terms of the number of
characters, that would be saved by using the abbrev. The
thinking is that if the expansion is only a few characters
longer than the abbrev, the benefit of informing the user is not
that big. If you always want to be informed, set this value to
`0' or less. This setting only applies if `abbrev-suggest' is
non-nil."
significant. If you always want to be informed about existing
abbrevs for the text you type, set this value to zero or less.
This setting only applies if `abbrev-suggest' is non-nil."
:type 'number
:version "28.1")
@ -945,7 +946,9 @@ typed."
total))
(defun abbrev-suggest-show-report ()
"Show the user a report of abbrevs he could have used."
"Show a buffer with the list of abbrevs you could have used.
This shows the abbrevs you've \"missed\" because you typed the
full text instead of the abbrevs that expand into that text."
(interactive)
(let ((totals (abbrev--suggest-get-totals))
(buf (get-buffer-create "*abbrev-suggest*")))