[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master c37370a: Improve documentation of the 'abbrev-suggest' feature
From: |
Eli Zaretskii |
Subject: |
master c37370a: Improve documentation of the 'abbrev-suggest' feature |
Date: |
Sun, 27 Sep 2020 02:00:15 -0400 (EDT) |
branch: master
commit c37370a7a0f329d13cf00a06e446514be09a7bab
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>
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'.
---
doc/emacs/abbrevs.texi | 39 ++++++++++++++++++++-------------------
doc/emacs/emacs.texi | 1 +
etc/NEWS | 10 +++++-----
lisp/abbrev.el | 27 +++++++++++++++------------
4 files changed, 41 insertions(+), 36 deletions(-)
diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi
index 0dda977..e3766aa 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 6aed7bd..566229b 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 0cbbae4..202cd68 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 75cc439..dc52a22 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*")))
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- master c37370a: Improve documentation of the 'abbrev-suggest' feature,
Eli Zaretskii <=