diff --git a/ChangeLog b/ChangeLog index ca193db9..965f6eb0 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2025-12-13 Bob Weiner + +* MANIFEST: Add "HY-TALK/HYPERBOLEQA.kotl" from EmacsConf2025 talk. + HY-TALK/HYPERBOLEQA.kotl - Add. + 2025-12-11 Mats Lidell * MANIFEST: @@ -6,6 +11,20 @@ * hsys-activities.el (hsys-activities): Add action button support for external package activities. +2025-12-07 Bob Weiner + +* 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 * hpath.el (hpath:absolute-to): Rewrite to fix when given multiple 'default-dirs' diff --git a/HY-TALK/.hypb b/HY-TALK/.hypb index ed8c113b..1b3c5335 100644 --- 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 new file mode 100644 index 00000000..5902a9c0 --- /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: + + + + Works for Lisp variables as well: + + + 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: + + + + 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 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 index 4d4173ab..2c371de1 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 e946091a..50d10248 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 c89799aa..bb37b475 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 c01b8e00..927a4bfb 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 169cf951..08d2dc27 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 4381b09f..3e4372c9 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 35beda1d..f76d5232 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.

 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