branch: externals/hyperbole
commit 987433ee1d697eb9ebf8a12870207b0f1e8e234d
Author: Bob Weiner <r...@gnu.org>
Commit: Bob Weiner <r...@gnu.org>
Update doc to new minibuffer argument handling including Vertico
---
ChangeLog | 9 ++++++++-
DEMO | 23 +++++++++++++++------
man/hkey-help.txt | 3 ++-
man/hyperbole.texi | 59 ++++++++++++++++++++++++++++++++++++------------------
4 files changed, 67 insertions(+), 27 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index f5fdf1595c..4bcc0b5c87 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+* DEMO (Completion Selection):
+ man/hkey-help.txt:
+ man/hyperbole.texi (Smart Key Argument Selection): Update to new minibuffer
+ argument handling including Vertico support.
+
2023-07-05 Bob Weiner <r...@gnu.org>
* hpath.el (hpath:markdown-section-pattern, hpath:outline-section-pattern): Fix
@@ -8,7 +13,9 @@
* hyperbole.el (hyperb:init): Activate 'vertico-mouse-mode' when
'vertico-mode' is used so that the Action Key properly selects completions
- from the candidate list.
+ from the candidate list. Since Vertico displays completions automatically,
+ must initialize this before Vertico is invoked so cannot wait until a Smart
+ Mouse Key is first pressed.
hargs.el (hargs:select-p):
(hargs:at-p): When 'hargs:reading-type' is nil, rather than a
string, return a list of (completion-so-far exact-completion-match),
diff --git a/DEMO b/DEMO
index 5c6191fd2f..d09fa39973 100644
--- a/DEMO
+++ b/DEMO
@@ -1060,12 +1060,23 @@ Try that one by pressing between the square brackets.
** Completion Selection
-Often when Emacs or Hyperbole prompts for an argument in the minibuffer, a
-list of possible argument completions is available by pressing {?}. A single
-Action Key press on any of these completions inserts it into the minibuffer
-for your inspection. A second press on the same completion causes it to be
-used as the argument value and any succeeding argument prompt is then
-displayed. Test this technique with a {C-x C-f} (find-file) and then a {?}.
+Often when Emacs or Hyperbole prompts for an argument in the
+minibuffer, a list of possible argument completions is available by
+pressing {?} or automatically displayed. A single Action Key press on
+any of these completions inserts it into the minibuffer for your
+inspection. A second press on the same completion uses it as the
+argument value and moves on to any next minibuffer argument prompt.
+Test this technique with a {C-x C-f} (find-file) and then a {?}.
+
+Within the minibuffer itself, the Smart Keys are also
+context-sensitive. A press of the Action Key at the end of the
+argument line tries to accept the argument and when successful, exits
+the minibuffer. A press of the Assist Key at the end of the argument
+line displays matching completions for times when they are not
+automatically displayed or need updating. A press of the Action or
+Assist Key on part of the argument, deletes from point to the end of
+the line, expanding the set of available completions and redisplaying
+them.
** Hyperbole Source Buttons
diff --git a/man/hkey-help.txt b/man/hkey-help.txt
index f32ae91bed..bac0b5aef9 100644
--- a/man/hkey-help.txt
+++ b/man/hkey-help.txt
@@ -8,7 +8,8 @@ Hyperbole
Reading argument
1st press at an arg value Copies value to minibuffer <- same
2nd press at an arg value Uses value as argument <- same
- In minibuffer Accepts minibuffer arg Completion help
+ In minibuffer at eol Accepts minibuffer arg List completions
+ In minibuffer before eol Deletes rest of arg Deletes rest of arg
On an implicit button/path Activates button Button help
Within a koutline cell Collapses and expands Shows tree props
Left of a koutline cell Creates a klink Moves a tree
diff --git a/man/hyperbole.texi b/man/hyperbole.texi
index 28c7f0ba41..2ffa6fbe3a 100644
--- a/man/hyperbole.texi
+++ b/man/hyperbole.texi
@@ -7,7 +7,7 @@
@c Author: Bob Weiner
@c
@c Orig-Date: 6-Nov-91 at 11:18:03
-@c Last-Mod: 1-Jul-23 at 16:32:29 by Bob Weiner
+@c Last-Mod: 8-Jul-23 at 10:31:40 by Bob Weiner
@c %**start of header (This is for running Texinfo on a region.)
@setfilename hyperbole.info
@@ -156,7 +156,7 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.</P>
<PRE>
Edition 8.0.1pre
-Printed July 1, 2023.
+Printed July 8, 2023.
Published by the Free Software Foundation, Inc.
Author: Bob Weiner
@@ -198,7 +198,7 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
@example
Edition 8.0.1pre
-July 1, 2023
+July 8, 2023
Published by the Free Software Foundation, Inc.
Author: Bob Weiner
@@ -1223,24 +1223,45 @@ Hyperbole user interface has an extensive core of
argument types that
it recognizes. Whenever Hyperbole is prompting you for an argument,
it knows the type that it needs and provides some error checking to
help you get it right. More importantly, it allows you to press the
-Action Key within an entity that you want to use as an argument and it
-will grab the appropriate thing and show it to you at the input prompt
-within the minibuffer. If you press (click with a mouse) the Action
-Key on the same thing again, it accepts the entity as the argument
-and moves on. Thus, a double click registers a desired argument.
-Double-quoted strings, pathnames, mail messages, Info nodes, dired
-listings, buffers, numbers, completion items and so forth are all
-recognized at appropriate times. All of the argument types mentioned
-in the documentation for the Emacs Lisp @code{interactive} function
-are recognized. Experiment a little and you will quickly get used to
-this direct selection technique.
+Action Key within an entity that you want to use as an argument.
+Hyperbole will copy the appropriate thing to the minibuffer as the
+argument. If you press (click with a mouse) the Action Key on the
+same thing again, e.g. within a list of possible completions,
+Hyperbole exits the minibuffer and uses the current argument. Thus, a
+double click registers a desired argument. Double-quoted strings,
+pathnames, mail messages, Info nodes, dired listings, buffers,
+numbers, completion items and so forth are all recognized at
+appropriate times. All of the argument types mentioned in the
+documentation for the Emacs Lisp @code{interactive} function are
+recognized. Experiment a little and you will quickly get used to this
+direct selection technique.
@cindex completion
-Wherever possible, standard Emacs completion is offered, as described in
-@ref{Completion,,,emacs,the GNU Emacs Manual}. Remember to use @bkbd{?}
-to see what your possibilities for an argument are. Once you have a
-list of possible completions on screen, press the Action Key twice on
-any item to enter it as the argument.
+@cindex Vertico completion
+Wherever possible, standard Emacs completion is offered, as described
+in @ref{Completion,,,emacs,the GNU Emacs Manual}. Remember to use
+@bkbd{?} to see what your possibilities for an argument are if
+completions are not automatically shown to you. Once you have a list
+of possible completions on screen, press the Action Key twice on any
+item to enter it as the argument. If you are using the Vertico
+completion library with completions displayed in the minibuffer,
+selection of completions works the same as if they were displayed in a
+separate buffer as in standard Emacs.
+
+@cindex minibuffer completion
+@cindex minibuffer arguments
+@cindex Smart Keys in minibuffer
+@cindex Action Key in minibuffer
+@cindex Assist Key in minibuffer
+Within the minibuffer itself, the Smart Keys are also
+context-sensitive. A press of the Action Key at the end of the
+argument line tries to accept the argument and when successful, exits
+the minibuffer. A press of the Assist Key at the end of the argument
+line displays matching completions for times when they are not
+automatically displayed or need updating. A press of the Action or
+Assist Key on part of the argument, deletes from point to the end of
+the line, expanding the set of available completions and redisplaying
+them.
@node Smart Key Debugging, Smart Key Thing Selection, Smart Key Argument
Selection, Smart Keys
@section Smart Key Debugging
