rswgnu · rswgnu · Dec 14, 2025 · Dec 14, 2025 · Dec 14, 2025 · Dec 14, 2025
diff --git a/ChangeLog b/ChangeLog
@@ -1,3 +1,8 @@
+2025-12-13  Bob Weiner  <rsw@gnu.org>
+
+* MANIFEST: Add "HY-TALK/HYPERBOLEQA.kotl" from EmacsConf2025 talk.
+  HY-TALK/HYPERBOLEQA.kotl - Add.
+
 2025-12-11  Mats Lidell  <matsl@gnu.org>
 
 * MANIFEST:
@@ -6,6 +11,20 @@
 * hsys-activities.el (hsys-activities): Add action button support for
     external package activities.
 
+2025-12-07  Bob Weiner  <rsw@gnu.org>
+
+* 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  <rsw@gnu.org>
 
 * hpath.el (hpath:absolute-to): Rewrite to fix when given multiple 'default-dirs'

diff --git a/HY-TALK/.hypb b/HY-TALK/.hypb
@@ -1,4 +1,9 @@
 
+"HYPERBOLEQA.kotl"
+("HyControl" nil nil link-to-Info-node ("(hyperbole)HyControl") "rsw@gnu.org" "20251207:16:24:20" nil nil)
+("Koutliner" nil nil link-to-Info-node ("(hyperbole)Koutliner") "rsw@gnu.org" "20251207:16:04:04" "rsw" "20251207:16:04:47")
+("Hyperbole_Todos" nil nil kbd-key ("C-x 4 t") "rsw@gnu.org" "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") "rsw@gnu.org" "20231203:01:48:10" nil nil)
 

diff --git a/HY-TALK/HYPERBOLEQA.kotl 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 "rsw@gnu.org" create-time "20251207:14:28:32" id-counter 32)]
+ [1
+  (creator "rsw@gnu.org" create-time "20251207:14:28:32")]
+ [31
+  (creator "rsw@gnu.org" create-time "20251207:18:04:23")]
+ [5
+  (creator "rsw@gnu.org" create-time "20251207:14:32:31")]
+ [18
+  (creator "rsw@gnu.org" create-time "20251207:14:43:02")]
+ [19
+  (creator "rsw@gnu.org" create-time "20251207:14:43:54")]
+ [20
+  (creator "rsw@gnu.org" create-time "20251207:14:46:58")]
+ [21
+  (creator "rsw@gnu.org" create-time "20251207:14:59:06")]
+ [32
+  (creator "rsw@gnu.org" create-time "20251207:18:09:17")]
+ [6
+  (creator "rsw@gnu.org" create-time "20251207:14:32:35")]
+ [7
+  (creator "rsw@gnu.org" create-time "20251207:14:32:46")]
+ [2
+  (creator "rsw@gnu.org" create-time "20251207:14:31:22")]
+ [3
+  (creator "rsw@gnu.org" create-time "20251207:14:31:52")]
+ [16
+  (creator "rsw@gnu.org" create-time "20251207:14:40:26")]
+ [28
+  (creator "rsw@gnu.org" create-time "20251207:15:59:42")]
+ [29
+  (creator "rsw@gnu.org" create-time "20251207:16:02:57")]
+ [23
+  (creator "rsw@gnu.org" create-time "20251207:15:30:12")]
+ [25
+  (creator "rsw@gnu.org" create-time "20251207:15:30:59")]
+ [27
+  (creator "rsw@gnu.org" create-time "20251207:15:31:30")]
+ [26
+  (creator "rsw@gnu.org" create-time "20251207:15:31:04")]
+ [22
+  (creator "rsw@gnu.org" create-time "20251207:15:30:04")]
+ [8
+  (creator "rsw@gnu.org" create-time "20251207:14:33:09")]
+ [10
+  (creator "rsw@gnu.org" create-time "20251207:14:33:30")]
+ [12
+  (creator "rsw@gnu.org" create-time "20251207:14:33:42")]
+ [11
+  (creator "rsw@gnu.org" create-time "20251207:14:33:33")]
+ [13
+  (creator "rsw@gnu.org" create-time "20251207:14:33:53")]
+ nil nil nil nil nil nil nil]
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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