From: Eli Zaretskii Date: Sun, 27 Sep 2020 05:57:17 +0000 (+0300) Subject: Improve documentation of the 'abbrev-suggest' feature X-Git-Tag: emacs-28.0.90~5856 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=c37370a7a0f329d13cf00a06e446514be09a7bab;p=emacs.git Improve documentation of the 'abbrev-suggest' feature * 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'. --- diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi index 0dda977833f..e3766aae9e8 100644 --- a/doc/emacs/abbrevs.texi +++ b/doc/emacs/abbrevs.texi @@ -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. diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 6aed7bd92a5..566229b2f32 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -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. diff --git a/etc/NEWS b/etc/NEWS index 0cbbae41861..202cd689d33 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -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 diff --git a/lisp/abbrev.el b/lisp/abbrev.el index 75cc43941f4..dc52a220125 100644 --- a/lisp/abbrev.el +++ b/lisp/abbrev.el @@ -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*")))