branch: externals/hyperbole
commit 234aa8948361641bb75fb4e55e105d158ad9d5cd
Author: bw <r...@gnu.org>
Commit: bw <r...@gnu.org>
hib-debbugs.el - Fix most issues with use of the GNU debbugs package
hbut.el - Improve error when lbl-key attribute is nil.
hib-kbd.el - In Texinfo mode, add support for key sequence recognition.
man/hyperbole.texi (Programmatic Implicit Button Types): Expand doc on
'at-p' argument and explain its 'ibut:label-set' and 'hact' calls.
---
ChangeLog | 15 +++++++++
hbut.el | 29 +++++++++++------
hib-debbugs.el | 23 +++++++++-----
hib-kbd.el | 11 ++++---
man/hyperbole.texi | 91 ++++++++++++++++++++++++++++++++++++++----------------
5 files changed, 121 insertions(+), 48 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index a73d8dd728..9eda7c08e3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,20 @@
+2024-06-30 Bob Weiner <r...@gnu.org>
+
+* man/hyperbole.texi (Programmatic Implicit Button Types): Expand doc on
+ 'at-p' argument and explain its 'ibut:label-set' and 'hact' calls.
+
+* hib-kbd.el (kbd-key): Add support for key sequences in Texinfo mode.
+
2024-06-29 Bob Weiner <r...@gnu.org>
+* hbut.el (ibut:to-text): Add current ibtype to the error when lbl-key attr is
nil.
+ hib-debbugs.el (debbugs-version-sufficient-p): Update to get version number
+ from either the package pathname or from "debbugs.el" or "debbugs-gnu.el".
+ Fixes bug where debbugs is installed bug not used so bug ibuts are not
+ active.
+ (defib debbugs-gnu-query): Add `ibut:label-set' call.
+ (defib): Improve doc to mention requirement for call to
'ibut:label-set'.
+
* test/hui-tests.el (hui-ebut-create-link-to-info-index-using-completion):
When finished, kill all *info*<#> buffers.
diff --git a/hbut.el b/hbut.el
index 958db847ee..7e27af988f 100644
--- a/hbut.el
+++ b/hbut.el
@@ -3,7 +3,7 @@
;; Author: Bob Weiner
;;
;; Orig-Date: 18-Sep-91 at 02:57:09
-;; Last-Mod: 25-Jun-24 at 01:03:43 by Bob Weiner
+;; Last-Mod: 29-Jun-24 at 22:03:56 by Bob Weiner
;;
;; SPDX-License-Identifier: GPL-3.0-or-later
;;
@@ -2289,8 +2289,8 @@ lines."
result))))
(defun ibut:label-set (label &optional start end)
- "Set current implicit button attributes.
-Get attributes from LABEL and optional START, END positions.
+ "Set current implicit button label attributes.
+Provide arguments LABEL and optional START, END positions.
Return label. When START and END are given, they specify the
region in the buffer to flash when this implicit button is
activated or queried for its attributes; this typically should
@@ -2892,7 +2892,9 @@ The caller must have populated the attributes of
\='hbut:current.
Return the symbol for the button if found, else nil."
(unless (stringp lbl-key)
- (error "(ibut:to-text): 'lbl-key' arg must be a string, not: %S" lbl-key))
+ (error "(ibut:to-text): %s 'lbl-key' arg must be a string, not: %S"
+ (hattr:get 'hbut:current 'categ)
+ lbl-key))
(hbut:funcall
(lambda (lbl-key _buffer _key-src)
(let* ((name-end (hattr:get 'hbut:current 'name-end))
@@ -2949,7 +2951,9 @@ Return the symbol for the button if found, else nil."
TYPE is an unquoted symbol. PARAMS are presently ignored.
AT-P is a boolean form of no arguments which determines whether or not point
-is within a button of this type and if it is, calls `hact' with an
+is within a button of this type. When non-nil, it must contain a call
+to `ibut:label-set' with the text and optional buffer region of the
+button's label. This must be followed by a call to `hact' with an
action to be performed whenever a button of this type is activated.
The action may be a regular Emacs Lisp function or a Hyperbole action
@@ -2972,11 +2976,16 @@ type for ibtype is presently undefined."
[&optional stringp] ; Doc string, if present.
def-body)))
(when type
- (let ((to-func (when to-p (action:create nil (list to-p))))
- (at-func (list at-p)))
- `(progn (symtable:add ',type symtable:ibtypes)
- (htype:create ,type ibtypes ,doc nil ,at-func
- '(to-p ,to-func style ,style))))))
+ (let* ((to-func (when to-p (action:create nil (list to-p))))
+ (at-func (list at-p))
+ (at-func-symbols (flatten-tree at-func)))
+ (progn (unless (member 'ibut:label-set at-func-symbols)
+ (error "(defib): %s `at-p' argument must include a call to
`ibut:label-set'" type))
+ (unless (member 'hact at-func-symbols)
+ (error "(defib): %s `at-p' argument must include a call to
`hact'" type))
+ `(progn (symtable:add ',type symtable:ibtypes)
+ (htype:create ,type ibtypes ,doc nil ,at-func
+ '(to-p ,to-func style ,style)))))))
;; Support edebug-defun for interactive debugging of ibtypes
(def-edebug-spec defib
diff --git a/hib-debbugs.el b/hib-debbugs.el
index 34d4343919..5452bd3ef1 100644
--- a/hib-debbugs.el
+++ b/hib-debbugs.el
@@ -3,7 +3,7 @@
;; Author: Bob Weiner
;;
;; Orig-Date: 21-Jun-16 at 14:24:53
-;; Last-Mod: 2-Feb-24 at 22:44:22 by Mats Lidell
+;; Last-Mod: 29-Jun-24 at 22:30:57 by Bob Weiner
;;
;; SPDX-License-Identifier: GPL-3.0-or-later
;;
@@ -114,6 +114,10 @@ attribute):
Note that `issue' or `debbugs' may be used as well in place of `bug'."
(when (debbugs-version-sufficient-p)
(when (debbugs-query:at-p)
+ (ibut:label-set (buffer-substring-no-properties
+ (match-beginning 1) (match-end 2))
+ (match-beginning 1)
+ (match-end 2))
(if (and (match-beginning 3) (string-equal "?" (match-string 3)))
(hact 'debbugs-gnu-query:string (buffer-substring-no-properties
(or (match-beginning 1)
(match-beginning 2))
@@ -265,18 +269,21 @@ Return t unless no attributes are printed."
"Return t iff debbugs version is sufficient for use with Hyperbole.
Must be greater than equal to 0.9.7."
(save-excursion
- (let* ((debbugs-src (locate-file "debbugs-gnu" load-path '(".el")))
+ (let* ((debbugs-src (or (locate-file "debbugs" load-path '(".el"))
+ (locate-file "debbugs-gnu" load-path '(".el"))))
(visiting-debbugs-src (when debbugs-src (get-file-buffer
debbugs-src)))
debbugs-src-buffer
version)
(when debbugs-src
(unwind-protect
- (progn (set-buffer (setq debbugs-src-buffer (find-file-noselect
debbugs-src)))
- (widen)
- (goto-char (point-min))
- (when (re-search-forward "^;; Version: \\([.0-9]+\\)" nil t)
- (setq version (match-string 1))))
- (unless visiting-debbugs-src
+ (if (string-match "debbugs-\\([0-9]+.[0-9]+\\(.[0-9]+\\)?\\)"
debbugs-src)
+ (setq version (match-string 1 debbugs-src))
+ (set-buffer (setq debbugs-src-buffer (find-file-noselect
debbugs-src)))
+ (widen)
+ (goto-char (point-min))
+ (when (re-search-forward "^;; Version: \\([.0-9]+\\)" nil t)
+ (setq version (match-string 1))))
+ (unless (or visiting-debbugs-src (null debbugs-src-buffer))
(kill-buffer debbugs-src-buffer)))
(when (and version (not (equal version "")))
(version-list-<= (version-to-list "0.9.7") (version-to-list
version)))))))
diff --git a/hib-kbd.el b/hib-kbd.el
index 9d93b9e0db..8dd80b222b 100644
--- a/hib-kbd.el
+++ b/hib-kbd.el
@@ -3,7 +3,7 @@
;; Author: Bob Weiner
;;
;; Orig-Date: 22-Nov-91 at 01:37:57
-;; Last-Mod: 23-Jun-24 at 00:04:17 by Mats Lidell
+;; Last-Mod: 30-Jun-24 at 02:19:16 by Bob Weiner
;;
;; SPDX-License-Identifier: GPL-3.0-or-later
;;
@@ -140,9 +140,12 @@ Any key sequence within the series must be a string of one
of the following:
;; Match only when start delimiter is preceded by whitespace,
;; double quotes or is the 1st buffer character, so do not
;; match to things like ${variable}.
- (when (memq (char-before start) '(nil ?\ ?\t ?\n ?\r ?\f ?\"))
- (when (and (stringp key-series)
- (not (string-equal key-series "")))
+ (when (or (memq (char-before start) '(nil ?\ ?\t ?\n ?\r ?\f ?\"))
+ ;; In Texinfo, allow for @bkbd{} or @kbd{}, so an
+ ;; alpha char preceding
+ (and (derived-mode-p 'texinfo-mode)
+ (= (char-syntax (char-before start)) ?w)))
+ (when (and (stringp key-series) (not (string-empty-p key-series)))
;; Replace any ${} internal or env vars; leave
;; $VAR untouched for the shell to evaluate.
(let ((hpath:variable-regexp "\\${\\([^}]+\\)}"))
diff --git a/man/hyperbole.texi b/man/hyperbole.texi
index 3f5b8a7de2..96d03b3153 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: 16-Apr-24 at 22:13:33 by Bob Weiner
+@c Last-Mod: 30-Jun-24 at 01:27:39 by Bob Weiner
@c %**start of header (This is for running Texinfo on a region.)
@setfilename hyperbole.info
@@ -159,7 +159,7 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.</P>
<PRE>
Edition 9.0.2pre
-Printed June 2, 2024.
+Printed June 30, 2024.
Published by the Free Software Foundation, Inc.
Author: Bob Weiner
@@ -201,7 +201,7 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
@example
Edition 9.0.2pre
-June 2, 2024
+June 30, 2024
Published by the Free Software Foundation, Inc.
Author: Bob Weiner
@@ -7175,23 +7175,45 @@ same thing without any special definitions.
@cindex ibtype
@findex defib
@findex ibtype:create
-An implicit button type is created or loaded via the @code{(defib)}
-function (which is an alias for @code{(ibtype:create)}). The calling
-signature for this function is given in its documentation; it is the
-same as that of @code{(defun)}, but with a number of constraints. The
-parameter list should always be empty since no parameters will be used.
-A documentation string is required; it is followed by the body of the
-type.
-
-@cindex ibtype, predicate
-@cindex ibtype, argument
-@cindex ibtype, return val
-@cindex ibtype, actype
-The body of an implicit button type is a predicate which determines
-whether or not point is within an implicit button of the type. If
-not, the predicate returns @samp{nil}. If the type is delimited,
-Hyperbole automatically sets up to flash the button when activated.
-Action invocations have the form: @code{(hact 'actype &rest
+@cindex ibtype predicate
+@cindex ibtype argument
+@cindex ibtype return val
+@cindex ibtype actype
+@cindex ibtype at-p
+An implicit button type is defined or updated via the @code{(defib)}
+macro (@code{ibtype:create} is alias for this). It may be called just
+as @code{(defun)} is, but with a number of constraints. The parameter
+list should always be empty since no parameters will be used. A
+documentation string is required. The last required form is the
+@code{at-p} predicate which when non-@samp{nil}, must do three things:
+@itemize @enumerate
+@item determine if there is a button at point that matches the type being
defined;
+@item if so, call @code{ibut:set-label) to identify the label text of the
button;
+@item if so, call @code{hact} to invoke the button's action, typically using
the label.
+@end itemize
+
+@findex ibut:label-set
+@cindex ibtype ibut:label-set
+The call to @code{ibut:label-set} may contain just the button's label
+argument or the label plus its start and end positions in the buffer,
+if you wnat the button to flash when pressed.
+
+@cindex ibtype hact
+The @code{hact} call, run whenever a button of the type is activated,
+must be the last expression within the @code{at-p} form; it will
+always return @samp{t} when the @code{at-p} form is tested for a
+boolean value since the implicit button type's check has already
+evaluated true before this is called. The arguments to the call to
+@code{hact} are an action function and whatever arguments it takes.
+The action may be a Hyperbole action type created with @code{defact}
+or a regular Emacs Lisp function. However, the action should not
+return @samp{nil} since any @samp{nil} value returned is converted to
+@samp{t} to ensure the implicit button checker recognizes that the
+action has been executed.
+
+@cindex action
+@cindex ibtype action
+Action invocations have the form: @code{(hact actype &rest
actype-arguments)} where @code{actype} is a Hyperbole action type
symbol or an Emacs Lisp function name or lambda;
@code{actype-arguments} are the arguments fed to the action invocation
@@ -7201,11 +7223,11 @@ It is imperative that all actions (non-predicate code)
be invoked
through the @code{(hact)} function or your ibtypes will not work
properly. (Hyperbole first tests to see if any ibtype matches the
current context before activating any type, so it ensures that
-@code{(hact)} calls are disabled during this testing.) Any action
+@code{(hact)} calls are disabled during this testing). Any action
types used in the definition of an implicit button type may be created
before or after the definition, but obviously, must be defined before
-any implicit buttons of the given type are activated; an error will
-result, otherwise.
+any implicit buttons of the given type are activated or an error will
+result.
If an implicit button type create is successful, the symbol that
Hyperbole uses internally to reference the type is returned. On
@@ -7215,6 +7237,21 @@ may be the same without any conflict. In fact, such
naming is
encouraged when an implicit button type is the exclusive user of an
action type.
+@cindex ibtype priorities
+@cindex priority of ibtypes
+@cindex types, implicit button
+@findex hui:htype-help 'ibtypes
+@kindex C-h h i t
+When the Action Key is pressed, each implicit button type predicate is
+checked in priority order and the first one whose @code{at-p} form
+evaluates non-@samp{nil} is activated (its action is run using the
+button label at point). The first time an implicit button type is
+defined, it becomes the highest priority type; repeated definitions of
+the same type update the type but do not change its priority order.
+@bkbd{C-h h i t @key{RET}} @code{(hui:htype-help 'ibtypes 'no-sort)}
+displays the doc strings for all current implicit button types in
+descending priority order.
+
@findex ibtype:delete
Call @code{(ibtype:delete)} to remove an implicit button type from a
Hyperbole environment. It takes a single parameter which should be the
@@ -7224,9 +7261,6 @@ by the implicit button; that must be done separately.
@cindex ibtype, help
@findex ibut:at-p
-@vindex class, hattr
-@vindex class, hbut
-@vindex file, hib-kbd.el
By default, a request for help on an implicit button will display the
button's attributes in the same manner as is done for explicit
buttons. For some implicit button types, other forms of help will be
@@ -7241,6 +7275,11 @@ context). Remember that the standard help for buttons
with custom
help functions is still available with @bkbd{C-h A} for the Action Key
and @bkbd{C-u C-h A} for the Assist Key.
+@vindex class, hattr
+@vindex class, hbut
+@cindex hbut class
+@cindex hattr class
+@vindex file, hib-kbd.el
To programmatically query implicit buttons for their attributes, use
the functions from the @samp{hbut} and @samp{hattr} classes. See
the @file{hib-kbd.el} file for an example of a custom help function.
