branch: externals/hyperbole
commit b7cc26a2af8c33b2ce55a8304a811cbfdde341ea
Merge: 8d5638ba33 82b146470d
Author: Robert Weiner <[email protected]>
Commit: GitHub <[email protected]>
Merge pull request #830 from rswgnu/rsw
hpath:shorten - Expand & abbrev, don't shorten gbut activated paths;
HY-TALK/HYPERBOLEQA.kotl - Add from EmacsConf2025 talk
---
ChangeLog | 19 ++++++
HY-TALK/.hypb | 5 ++
HY-TALK/HYPERBOLEQA.kotl | 146 +++++++++++++++++++++++++++++++++++++++++++++++
MANIFEST | 1 +
README.md | 2 +
hbut.el | 8 +--
hmouse-tag.el | 12 ++--
hpath.el | 8 ++-
hui-mouse.el | 11 +++-
man/hyperbole.texi | 16 +++---
10 files changed, 210 insertions(+), 18 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index ca193db90b..965f6eb0a5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2025-12-13 Bob Weiner <[email protected]>
+
+* MANIFEST: Add "HY-TALK/HYPERBOLEQA.kotl" from EmacsConf2025 talk.
+ HY-TALK/HYPERBOLEQA.kotl - Add.
+
2025-12-11 Mats Lidell <[email protected]>
* MANIFEST:
@@ -6,6 +11,20 @@
* hsys-activities.el (hsys-activities): Add action button support for
external package activities.
+2025-12-07 Bob Weiner <[email protected]>
+
+* hpath.el (hpath:shorten): Expand and abbreviate but don't shorten paths if
+ within a global button activation. Otherwise, relative paths may be
computed
+ wrong. Still this problem shown with (gbut:act "td") is not yet resolved.
+
+* hmouse-tag.el (smart-prog-tag):
+ hui-mouse.el (hkey-alist): Change Assist Key behavior when on a programming
+ symbol/tag. If the symbol is a variable holding an in-memory Hyperbole
button,
+ then display a help buffer with the button's attributes. Otherwise, if an
Elisp
+ symbol, then display a help buffer with symbol documentation, if any, to
match
+ the Hyperbole manual documentation. For any other language symbol,
display its
+ definiton, just as the Action Key does.
+
2025-12-06 Bob Weiner <[email protected]>
* hpath.el (hpath:absolute-to): Rewrite to fix when given multiple
'default-dirs'
diff --git a/HY-TALK/.hypb b/HY-TALK/.hypb
index ed8c113b39..1b3c5335ac 100644
--- a/HY-TALK/.hypb
+++ b/HY-TALK/.hypb
@@ -1,4 +1,9 @@
+"HYPERBOLEQA.kotl"
+("HyControl" nil nil link-to-Info-node ("(hyperbole)HyControl") "[email protected]"
"20251207:16:24:20" nil nil)
+("Koutliner" nil nil link-to-Info-node ("(hyperbole)Koutliner") "[email protected]"
"20251207:16:04:04" "rsw" "20251207:16:04:47")
+("Hyperbole_Todos" nil nil kbd-key ("C-x 4 t") "[email protected]"
"20251207:15:33:06" nil nil)
+
"HYPERAMP.org"
("ERT_test" nil nil link-to-file
("../test/hbut-tests.el#hypb:program-create-ebut-in-buffer") "[email protected]"
"20231203:01:48:10" nil nil)
diff --git a/HY-TALK/HYPERBOLEQA.kotl b/HY-TALK/HYPERBOLEQA.kotl
new file mode 100644
index 0000000000..5902a9c0ec
--- /dev/null
+++ b/HY-TALK/HYPERBOLEQA.kotl
@@ -0,0 +1,146 @@
+;; -*- Mode: kotl -*-
+"Kotl-4.0" ;; file-format
+
+ 1. Hyperbole hyperlinks all your information everywhere in Emacs with
minimal effort and markup.
+
+ 1a. To install:
+ (add-to-list 'package-archives '("melpa" .
"https://melpa.org/packages/";) t)
+ or
+ (add-to-list 'package-archives '("elpa-devel" .
"https://elpa.gnu.org/devel/";))
+
+ (package-install 'hyperbole)
+ (hyperbole-mode 1)
+
+ Then {M-RET}, the Action Key, will provide context-sensitive actions
everywhere.
+
+ 1b. Implicit Buttons - typed text patterns Hyperbole recognizes as buttons
+
+ 1b1. Any Lisp sexpression with outer parens replaced by angle brackets:
+ <occur "buttons">
+ <buffer-menu-other-window t>
+
+ Works for Lisp variables as well:
+ <hyperb:dir>
+
+ 1b2. Series of keystrokes surrounded by braces:
+ {C-c g 4}
+
+ 1b3. Pathnames with environment or Lisp variables, sections and
relative line numbers.
+ "${hyperb:dir}/README.md#Hyperbole Manual:L8"
+
+ 1b4. Display the discussion on an Emacs bug:
+ bug#24568
+
+ 1b5. Use {C-h A} to see what {M-RET} will do anywhere,
+ including the specific type of button that it will activate.
+
+ 1c. Explicit Buttons - buttons you add to a text, code or message buffers:
+ <(Hyperbole Todos)>
+
+ Can toggle Org todo states and have multiple sets of states, all with
the {M-RET} key.
+
+ 1d. Global Buttons - named buttons in Hyperbole home page available
anywhere by name:
+ {C-h h g a hyperbole-invocation-doc RET}
+
+ 2. HyRolo for fast lookup and insertion of records:
+ <setq hyrolo-file-list '("~/.rolo.otl"
"~/Dropbox/emacs/ramin-org-notes/")>
+ <global-set-key "\C-x4r" 'hyrolo-fgrep>
+
+ Interactive Record Lookup: {C-h h r s} Mandelbrot RET
+ Interactive Record Insertion: {C-h h r y} Mandelbrot RET
+
+ 3. HyWiki for no markup links to sections of documents
+
+ 3a. HyWiki words are automatically highlighted as you type them
+ in HyWiki pages or with <hywiki-mode 1> enabled, everywhere.
+
+ 3b. Link to HyWiki sections with # anchors:
+ EmacsMe#My-Section or "EmacsMe#My Section"
+
+ 4. The <(Koutliner)> produces autonumbered outlines with automatic
+ permanent hyperlink anchors (called idstamps) per cell/node. We are
+ using it here. <[Koutliner Tutorial]> {C-h h k e}
+
+ 5. Highlight, Wipe, Copy and Yank Structured Regions
+
+ 5a. Double-quoted Paths: "Any quoted string." "Recognizes start and end"
+
+ 5b. Matching Delimiters: [This is just text.]
+
+ 5c. Parenthesized Lisp Sexpressions: (+ (- 8 2) 7)
+
+ 6. <(HyControl)> provides fast control of windows and frame adjustments
+
+ 7. Extensive Documentation
+
+ 7a. Videos - "../README.md:L25"
+
+ 7b. Interactive Demos/Tutorials - {C-h h d d} {C-h h k e}
+
+ 7c. Reference Manual - {C-h h d i}
+ https://rswgnu.github.io/hyperbole
+
+ 7d. <[Architectural Reference]> https://deepwiki.com/rswgnu/hyperbole
+
+
+"ben" ;; kvspec:current
+32 ;; id-counter
+alpha ;; label-type
+4 ;; label-min-width
+". " ;; label-separator
+3 ;; level-indent
+
+;; depth-first kcell attributes
+[[0
+ (creator "[email protected]" create-time "20251207:14:28:32" id-counter 32)]
+ [1
+ (creator "[email protected]" create-time "20251207:14:28:32")]
+ [31
+ (creator "[email protected]" create-time "20251207:18:04:23")]
+ [5
+ (creator "[email protected]" create-time "20251207:14:32:31")]
+ [18
+ (creator "[email protected]" create-time "20251207:14:43:02")]
+ [19
+ (creator "[email protected]" create-time "20251207:14:43:54")]
+ [20
+ (creator "[email protected]" create-time "20251207:14:46:58")]
+ [21
+ (creator "[email protected]" create-time "20251207:14:59:06")]
+ [32
+ (creator "[email protected]" create-time "20251207:18:09:17")]
+ [6
+ (creator "[email protected]" create-time "20251207:14:32:35")]
+ [7
+ (creator "[email protected]" create-time "20251207:14:32:46")]
+ [2
+ (creator "[email protected]" create-time "20251207:14:31:22")]
+ [3
+ (creator "[email protected]" create-time "20251207:14:31:52")]
+ [16
+ (creator "[email protected]" create-time "20251207:14:40:26")]
+ [28
+ (creator "[email protected]" create-time "20251207:15:59:42")]
+ [29
+ (creator "[email protected]" create-time "20251207:16:02:57")]
+ [23
+ (creator "[email protected]" create-time "20251207:15:30:12")]
+ [25
+ (creator "[email protected]" create-time "20251207:15:30:59")]
+ [27
+ (creator "[email protected]" create-time "20251207:15:31:30")]
+ [26
+ (creator "[email protected]" create-time "20251207:15:31:04")]
+ [22
+ (creator "[email protected]" create-time "20251207:15:30:04")]
+ [8
+ (creator "[email protected]" create-time "20251207:14:33:09")]
+ [10
+ (creator "[email protected]" create-time "20251207:14:33:30")]
+ [12
+ (creator "[email protected]" create-time "20251207:14:33:42")]
+ [11
+ (creator "[email protected]" create-time "20251207:14:33:33")]
+ [13
+ (creator "[email protected]" create-time "20251207:14:33:53")]
+ nil nil nil nil nil nil nil]
diff --git a/MANIFEST b/MANIFEST
index 4d4173ab34..2c371de1ed 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -27,6 +27,7 @@ man/hyperbole.texi - The GNU Hyperbole Manual (GNU Texinfo
source form)
man/hkey-help.txt - Summarizes Smart Key behaviors in different contexts
HY-TALK/HY-TALK.org - EmacsNYC 2020 Talk: Make Your Text Come Alive slides
HY-TALK/HYPERAMP.org - EmacsConf 2023 Talk: Top 10 Ways Hyperbole Amps Up
Emacs slides
+HY-TALK/HYPERBOLEQA.kotl - EmacsConf 2025 Talk: Questions and answers to help
you fly with Hyperbole
HY-TALK/HYPERORG.org - EmacsConf 2022 Talk: Powerful Productivity with
Hyperbole and Org Mode slides
* --- USER INTERFACE ---
diff --git a/README.md b/README.md
index e946091ae8..50d1024877 100644
--- a/README.md
+++ b/README.md
@@ -236,6 +236,8 @@ window control menu if it was not already bound prior to
Hyperbole's
initialization. A long video demonstrating many of HyControl's
features is available at https://youtu.be/M3-aMh1ccJk.
+## Hyperbole Manual
+
The above are the best interactive ways to learn about Hyperbole.
Hyperbole also includes the Hyperbole Manual, a full reference manual,
not a simple introduction. It is included in the "man/" subdirectory
diff --git a/hbut.el b/hbut.el
index c89799aab9..bb37b4754a 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: 31-Aug-25 at 16:22:09 by Bob Weiner
+;; Last-Mod: 7-Dec-25 at 19:24:08 by Bob Weiner
;;
;; SPDX-License-Identifier: GPL-3.0-or-later
;;
@@ -1721,13 +1721,13 @@ Return number of buttons reported on or nil if none."
lbl
(concat ebut:label-start lbl ebut:label-end)))
(terpri)
+ (hattr:report attribs)
+ (terpri)
(let ((doc (actype:doc but (= 1 (length lbl-lst)))))
(when doc
(princ " ")
(princ doc)
- (terpri)))
- (hattr:report attribs)
- (terpri)))
+ (terpri)))))
lbl-lst))
(length lbl-lst))))
diff --git a/hmouse-tag.el b/hmouse-tag.el
index c01b8e0010..927a4bfbe4 100644
--- a/hmouse-tag.el
+++ b/hmouse-tag.el
@@ -3,7 +3,7 @@
;; Author: Bob Weiner
;;
;; Orig-Date: 24-Aug-91
-;; Last-Mod: 5-Oct-25 at 11:21:21 by Bob Weiner
+;; Last-Mod: 7-Dec-25 at 20:25:10 by Bob Weiner
;;
;; SPDX-License-Identifier: GPL-3.0-or-later
;;
@@ -983,9 +983,13 @@ Uses `xref' for identifier recognition."
;;;###autoload
(defun smart-prog-tag (&optional identifier next)
- "Jump to definition of optional programming IDENTIFIER or the one at point.
-Optional second arg NEXT means jump to next matching tag."
- (smart-tags-display (or identifier (hsys-xref-identifier-at-point)) next)
+ "Jump to definition of optional IDENTIFIER string or the one at point.
+Optional second arg NEXT is used by the Assist Key. If IDENTIFIER is
+an Elisp symbol, it displays the IDENTIFIER'S documention; otherwise, it jumps
+to next matching tag definition."
+ (if (and next (smart-emacs-lisp-mode-p))
+ (describe-symbol (intern identifier))
+ (smart-tags-display (or identifier (hsys-xref-identifier-at-point)) next))
t)
(defun smart-jedi-find-file (file line column other-window)
diff --git a/hpath.el b/hpath.el
index 169cf9510a..08d2dc275c 100644
--- a/hpath.el
+++ b/hpath.el
@@ -3,7 +3,7 @@
;; Author: Bob Weiner
;;
;; Orig-Date: 1-Nov-91 at 00:44:23
-;; Last-Mod: 6-Dec-25 at 22:57:33 by Bob Weiner
+;; Last-Mod: 7-Dec-25 at 21:12:14 by Bob Weiner
;;
;; SPDX-License-Identifier: GPL-3.0-or-later
;;
@@ -2078,6 +2078,8 @@ prior to calling this function."
(defun hpath:shorten (path &optional relative-to)
"Expand and then shorten and return a PATH optionally RELATIVE-TO other path.
+Don't shorten if acting on a global button.
+
Ignore optional RELATIVE-TO if editing a message,
i.e. (hmail:editor-p) => t. If RELATIVE-TO is omitted or nil,
set it to `default-directory'. Replace Emacs Lisp variables and
@@ -2097,7 +2099,9 @@ used. Then abbreviate any remaining path."
(setq relative-to (expand-file-name
(hpath:substitute-value relative-to))
path
- (cond ((string-equal path relative-to)
+ (cond ((hyperb:stack-frame '(gbut:act))
+ path)
+ ((string-equal path relative-to)
"")
((string-equal (file-name-directory path) relative-to)
(file-name-nondirectory path))
diff --git a/hui-mouse.el b/hui-mouse.el
index 4381b09f99..3e4372c9b1 100644
--- a/hui-mouse.el
+++ b/hui-mouse.el
@@ -3,7 +3,7 @@
;; Author: Bob Weiner
;;
;; Orig-Date: 04-Feb-89
-;; Last-Mod: 9-Sep-25 at 01:30:54 by Bob Weiner
+;; Last-Mod: 7-Dec-25 at 20:15:46 by Bob Weiner
;;
;; SPDX-License-Identifier: GPL-3.0-or-later
;;
@@ -455,6 +455,15 @@ The button's attributes are stored in the symbol,
`hbut:current'.")
((eq major-mode 'pages-directory-mode)
. ((pages-directory-goto) . (pages-directory-goto)))
;;
+ ;; If a variable holding an in-memory Hyperbole button object, e.g.
hbut:current:
+ ;; Action Key - Jump to variable definition
+ ;; Assist Key - Display button attributes of any Hyperbole button symbol
at point
+ ((and (setq hkey-value (smart-prog-at-tag-p))
+ (hbut:is-p (intern-soft hkey-value)))
+ . ((ignore-errors (smart-prog-tag hkey-value)) .
+ (hbut:report (intern-soft hkey-value))))
+ ;;
+ ;; Handle programming language tag definition finding via xref.
;; For most programming languages use xref which supports various
;; Language Servers
((and (setq hkey-value (smart-prog-at-tag-p))
diff --git a/man/hyperbole.texi b/man/hyperbole.texi
index 35beda1d85..f76d523254 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-Dec-25 at 10:00:11 by Mats Lidell
+@c Last-Mod: 7-Dec-25 at 20:30:10 by Bob Weiner
@c %**start of header (This is for running Texinfo on a region.)
@setfilename hyperbole.info
@@ -30,7 +30,7 @@
@set txicodequoteundirected
@set txicodequotebacktick
-@set UPDATED December 1, 2025
+@set UPDATED December 7, 2025
@set UPDATED-MONTH December 2025
@set EDITION 9.0.2pre
@set VERSION 9.0.2pre
@@ -171,7 +171,7 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.</P>
<PRE>
Edition 9.0.2pre
-Printed December 1, 2025.
+Printed December 7, 2025.
Published by the Free Software Foundation, Inc.
Author: Bob Weiner
@@ -213,7 +213,7 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
@example
Edition 9.0.2pre
-December 1, 2025 @c AUTO-REPLACE-ON-SAVE
+December 7, 2025 @c AUTO-REPLACE-ON-SAVE
Published by the Free Software Foundation, Inc.
@@ -11447,9 +11447,11 @@ identifier:
Emacs Lisp require, load, or autoload clause and the (find-library)
function is defined, jumps to the library source, if possible.
ASSIST KEY
- Jumps to the next tag matching an identifier at point or if
- the identifier is an Emacs Lisp symbol, then this displays the
- documentation for the symbol.
+ Jumps to the next tag matching an identifier at point unless
+ the identifier is an Emacs Lisp symbol, then:
+ 1. if it contains an in-memory Hyperbole button, display the buttons
+ attributes in a help buffer.
+ 2. otherwise, display the identifier's documentation in a help buffer.
@end group
@end format
