use-package - finish reference implementation

ChangeLog

@@ -1,5 +1,14 @@
+2026-09-30  Bob Weiner  <rsw@gnu.org>
+
+* man/hy-package.el:
+  man/hy-straight.el: Remove configuration from these two files.
+  man/use-package: Finish reference 'use-package' configuration here.
+
 2026-09-29  Bob Weiner  <rsw@gnu.org>
 
+* man/hyperbole.texi (Implicit Button Types): Add new hbut-identifier
+    type.
+
 * hibtypes.el (hbut-identifier, hbut-identifier:help): Move smart
     tag handling of Hyperbole button variables from 'hkey-alist'
     where it was improperly shadowed by the hbut handling clause

MANIFEST

@@ -19,9 +19,9 @@ hyperbole.el         - Loads and initializes GNU Hyperbole
 ChangeLog            - Summary of changes in recent GNU Hyperbole releases
 
 * --- DOCUMENTATION ---
-man/hy-package.el    - Hyperbole package.el installation and configuration instructions
-man/hy-straight.el   - Hyperbole Straight installation and configuration instructions
-man/use-package      - Hyperbole use-package declaration
+man/hy-package.el    - Hyperbole package.el installation instructions
+man/hy-straight.el   - Hyperbole Straight installation instructions
+man/use-package      - Hyperbole use-package reference configuration
 man/dir              - GNU Hyperbole Info directory tree entry
 man/hyperbole.html   - The GNU Hyperbole Manual  (web version)
 man/hyperbole.info   - The GNU Hyperbole Manual  (GNU Info version)

hywiki.el

@@ -3,7 +3,7 @@
 ;; Author:       Bob Weiner
 ;;
 ;; Orig-Date:    21-Apr-24 at 22:41:13
-;; Last-Mod:     13-Sep-26 at 11:21:07 by Bob Weiner
+;; Last-Mod:     30-Sep-26 at 12:03:56 by Bob Weiner
 ;;
 ;; SPDX-License-Identifier: GPL-3.0-or-later
 ;;
@@ -948,14 +948,14 @@ HyWiki minor mode has three states as tracked by the `hywiki-mode' variable,
 with the default state when interactively enabled set by the value of
 `hywiki-default-mode':
 
-  - :pages - highlight HyWikiWords in HyWiki pages only (Org files in
-             `hywiki-directory'); also enable `hyperbole-mode' minor mode
-             if off.
-
   - :all   - highlight HyWikiWords in all editable buffers except those
              with a major mode in `hypb:exclude-major-modes'; also
              enable `hyperbole-mode' minor mode if off.
 
+  - :pages - highlight HyWikiWords in HyWiki pages only (Org files in
+             `hywiki-directory'); also enable `hyperbole-mode' minor mode
+             if off. (default)
+
   - nil    - no highlighting, the `hywiki-mode' is disabled.
 
 HyWikiWord references may also include optional suffixes:

kotl/kotl-mode.el

@@ -3,7 +3,7 @@
 ;; Author:       Bob Weiner
 ;;
 ;; Orig-Date:    6/30/93
-;; Last-Mod:     29-Sep-26 at 01:35:06 by Bob Weiner
+;; Last-Mod:     29-Sep-26 at 19:20:34 by Bob Weiner
 ;;
 ;; SPDX-License-Identifier: GPL-3.0-or-later
 ;;
@@ -95,16 +95,16 @@ tree and {\\[kotl-mode:untab-command]} promotes the tree.  See their
 associated documentation strings for deeper details.
 
 2. The symbol, cycle, enables org-like outline view cycling when point is in
-a context other than that specified by `org-cycle-emulate-tab'.  Then
+a context other than that specified by `kotl-mode:emulate-tab'.  Then
 {\\[kotl-mode:tab-command]} cycles the current tree through three views.
 With a universal prefix arg, C-u, or via {\\[kotl-mode:untab-command]}, it
-cycles the whole outline through three views as defined in
-`kotl-mode:cycle'.
+cycles the whole outline through three views.  See the documentation strings
+for those commands for details.
 
 3. Any other non-nil value, makes {\\[kotl-mode:tab-command]} indent lines
 and insert literal <tab> characters according to the context setting of
-`org-cycle-emulate-tab'.  It also determines where
-{\\[kotl-mode:untab-command]} deletes backward."
+`kotl-mode:emulate-tab'.  It also determines where {\\[kotl-mode:untab-command]}
+deletes backward."
   :type 'boolean
   :group 'hyperbole-koutliner)
 

man/hy-package.el

@@ -3,7 +3,7 @@
 ;; Author:       Bob Weiner
 ;;
 ;; Orig-Date:    15-Jul-26 at 12:28:58
-;; Last-Mod:     25-Jul-26 at 22:25:11 by Mats Lidell
+;; Last-Mod:     30-Sep-26 at 12:37:33 by Bob Weiner
 ;;
 ;; SPDX-License-Identifier: GPL-3.0-or-later
 ;;
@@ -49,52 +49,4 @@
   ;; (package-refresh-contents)
   )
 
-;;; ************************************************************************
-;;; Section 2: package.el Hyperbole installation and configuration
-;;; ************************************************************************
-
-;; Step 1: Add the following expression to your "~/.emacs" or
-;; "~/.emacs.d/init.el" file.
-
-(use-package hyperbole
-
-  ;; ensure Hyperbole is installed
-  :ensure t
-
-  ;; Initialize the global HyWiki minor mode to one of these values:
-  ;;   :all   - highlights and makes HyWikiWord links active in
-  ;;            all text and programming buffer comments
-  ;;   :pages - highlights and makes HyWikiWord links active in
-  ;;            only within HyWiki page buffers
-  ;;   nil    - leaves HyWiki mode disabled.
-  :config
-  (progn
-    ;; Older Hyperbole releases do not have HyWiki
-    (when (fboundp 'hywiki-mode)
-      (hywiki-mode :all))
-
-    ;; Initialize the global Hyperbole minor mode to one of these values:
-    ;;   1 - enabled on startup so the Action and Assist Smart Keys are active
-    ;;   0 - off until you toggle it on
-    ;; If you left hywiki-mode enabled above, that enables hyperbole-mode too.
-    (unless (and (fboundp 'hywiki-mode) hywiki-mode)
-      (hyperbole-mode 1)))
-
-  :bind
-  (("M-RET" . hkey-either)
-   ;; Uncomment the next binding if you want to emulate Hyperbole mouse drag
-   ;; events from your keyboard.
-   ;; See "https://www.gnu.org/s/hyperbole/man/hyperbole.html#Keyboard-Drags".
-   ;; ("M-o"   . hkey-operate)
-   )
-
-  ;; Customize how Hyperbole and Org mode share the M-RET key:
-  ;;   t        - With hyperbole-mode enabled, Hyperbole controls the key
-  ;;   'buttons - With hyperbole-mode enabled, Hyperbole controls the key
-  ;;              only when on a button or link; otherwise, Org controls it
-  ;;   nil      - In Org mode, Org controls the key
-  :custom
-  (hsys-org-enable-smart-keys t)
-  )
-
 ;;; End

man/hy-straight.el

@@ -3,7 +3,7 @@
 ;; Author:       Bob Weiner
 ;;
 ;; Orig-Date:    15-Jul-26 at 12:28:58
-;; Last-Mod:     25-Jul-26 at 22:25:45 by Mats Lidell
+;; Last-Mod:     30-Sep-26 at 12:41:25 by Bob Weiner
 ;;
 ;; SPDX-License-Identifier: GPL-3.0-or-later
 ;;
@@ -13,7 +13,7 @@
 ;; This file is part of GNU Hyperbole.
 
 ;;; ************************************************************************
-;;; Section 1: Straight setup
+;;; Straight installation setup
 ;;; ************************************************************************
 
 ;;; ========================================================================
@@ -50,29 +50,4 @@
         (eval-print-last-sexp)))
     (load bootstrap-file nil 'nomessage)))
 
-;;; ************************************************************************
-;;; Section 2: Straight Hyperbole installation and configuration
-;;; ************************************************************************
-
-;; Step 1: Add the following expression to your "~/.emacs" or
-;; "~/.emacs.d/init.el" file.
-
-(straight-use-package
- '(hyperbole
-   :host nil
-
-   :repo "https://git.savannah.gnu.org/git/hyperbole.git"
-
-   :config
-   (progn
-     (hywiki-mode :all)
-     (unless hywiki-mode
-       (hyperbole-mode 1)))
-
-   :bind
-   (("M-RET" . hkey-either))
-
-   :custom
-   (hsys-org-enable-smart-keys t)))
-
 ;;; End

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:     29-Sep-26 at 01:42:53 by Bob Weiner
+@c Last-Mod:     29-Sep-26 at 19:05:46 by Bob Weiner
 
 @c %**start of header (This is for running Texinfo on a region.)
 @setfilename hyperbole.info
@@ -3241,6 +3241,15 @@ for a matching @code{should} clause in the source buffer where the
 associated test is defined.  This speeds debugging when a single test
 name contains many subtests, each with their own unique @code{should}
 clauses.
+
+@findex ibtypes hbut-identifier
+@cindex tag definition
+@cindex button variable
+@item hbut-identifier
+When on the name of a variable that holds a Hyperbole button, e.g. hbut:current:
+  Action Key - Jump to variable definition;
+  Assist Key - Display button attributes of any Hyperbole button symbol at point.
+
 @end table
 
 @node Action Buttons,  , Implicit Button Types, Implicit Buttons

man/use-package

@@ -1,42 +1,91 @@
-;;; -*- mode: emacs-lisp; lexical-binding: t; -*-
+;;; use-package --- Hyperbole use-package reference configuration   -*- mode: emacs-lisp; lexical-binding: t; -*-
 
+;; Default values herein represent the settings Hyperbole will default
+;; to if not set within this `use-package' configuration.
 (use-package hyperbole
 
+  :config
+  ;; Hyperbole binds {C-h h} in the `global-map' to display its
+  ;; minibuffer command menus. If you prefer a different binding,
+  ;; uncomment the two lines below which restore the standard binding
+  ;; for {C-h h} and set your preferred binding: example {C-c h}.
+  ;;   (global-set-key (kbd "C-h h") #'view-hello-file)
+  ;;   (global-set-key (kbd "C-c h") #'hyperbole)
+
   :init
-  (progn
-    ;; Initialize the global Hyperbole minor mode to one of these values:
-    ;;   1 - enabled on startup so the Action and Assist Smart Keys are active
-    ;;   0 - off until you toggle it on
-    ;; If you left hywiki-mode enabled above, that enables hyperbole-mode too.
-    (unless (and (fboundp 'hywiki-mode)
-                 (bound-and-true-p hywiki-mode))
-      (hyperbole-mode 1)))
-
-    ;; Older Hyperbole releases do not have HyWiki
-    (when (bound-and-true-p hywiki-mode)
-      ;; Initialize the global HyWiki minor mode to one of these values:
-      ;;   :all   - highlights and makes HyWikiWord links active in
-      ;;            all text and programming buffer comments
-      ;;   :pages - highlights and makes HyWikiWord links active in
-      ;;            only within HyWiki page buffers
-      ;;   nil    - leaves HyWiki mode disabled.
-      (hywiki-mode :all))
+  ;; Enable or disable the global Hyperbole minor mode on startup:
+  ;;   1 - enabled after Hyperbole is loaded so the Action and
+  ;;       Assist Smart Keys are active
+  ;;
+  ;;   0 - off (default)
+  (hyperbole-mode 1)
+
+  ;; Initialize the global HyWiki minor mode to one of these values:
+  ;; - :all   - highlight HyWikiWords in all editable buffers except those
+  ;;            with a major mode in ‘hypb:exclude-major-modes’; also
+  ;;            enable ‘hyperbole-mode’ minor mode if off.
+  ;;
+  ;; - :pages - highlight HyWikiWords in HyWiki pages only (Org files in
+  ;;            ‘hywiki-directory’); also enable ‘hyperbole-mode’ minor mode
+  ;;            if off. (default)
+  ;;
+  ;; - nil    - no highlighting, the ‘hywiki-mode’ is disabled.
+  (hywiki-mode :all)
 
   :bind
-  ;; Bind Smart Keys: {M-RET} is the Action Key; {C-u M-RET} is the
-  ;; Assist Key
-  (("M-RET" . hkey-either)
-   ;; Uncomment the next binding if you want to emulate Hyperbole mouse drag
-   ;; events from your keyboard.
-   ;; See "https://www.gnu.org/s/hyperbole/man/hyperbole.html#Keyboard-Drags".
-   ;; ("M-o"   . hkey-operate)
-   )
+  (:map hyperbole-mode-map
+	;; Bind Smart Keys: {M-RET} executes `action-key' and {C-u M-RET}
+	;; executes `assist-key' via this next binding
+	("M-RET" . hkey-either))
 
-  ;; Customize how Hyperbole and Org mode share the M-RET key:
-  ;;   t        - With hyperbole-mode enabled, Hyperbole controls the key
-  ;;   'buttons - With hyperbole-mode enabled, Hyperbole controls the key
-  ;;              only when on a button or link; otherwise, Org controls it
-  ;;   nil      - In Org mode, Org controls the key
   :custom
+  ;; Action and Assist Key Customizations
+
+  ;; Customize how Hyperbole and Org mode share the M-RET key:
+  ;;   t        - With `hyperbole-mode' enabled, Hyperbole controls the key.
+  ;;
+  ;;   'buttons - With `hyperbole-mode enabled', Hyperbole controls the key
+  ;;              only when on a button or link; otherwise, Org controls
+  ;;              it. (default)
+  ;;
+  ;;   nil      - In Org mode, Org controls the key.
   (hsys-org-enable-smart-keys t)
-  )
+
+  ;; Koutliner Customizations
+
+  ;; Customize the behavior of the <tab> and S-<tab> keys in a Koutline.
+  ;; One of three possible values:
+  ;;   nil      - {TAB} demotes the current tree and {Shift-TAB} promotes the
+  ;;              tree. (default)
+  ;;
+  ;;   'cycle  -  enables Org-like outline view cycling when point is in
+  ;;              a context other than that specified by ‘org-cycle-emulate-tab’.
+  ;;              See {C-h f kotl-mode:tab-command RET} for details.
+  ;;
+  ;;   t       -  makes {TAB} indent lines and insert literal <tab> characters
+  ;;              according to the context setting of ‘kotl-mode:emulate-tab’,
+  ;;              which also determines where {Shift-TAB} deletes backward.
+  (kotl-mode:tab-flag nil)
+
+  ;; Setup contexts where ‘kotl-mode:tab-command’ should override
+  ;; `kotl-mode:tab-flag' and run ‘kotl-mode:indent-line’, often
+  ;; inserting a <tab> character.
+  ;; Potential values are:
+  ;;   nil         - Never
+  ;;
+  ;;   white       - Only in completely white lines
+  ;;
+  ;;   whitestart  - Only at the beginning of lines, before the first non-white char
+  ;;
+  ;;   t           - Everywhere except in headlines
+  ;;
+  ;;   exc-hl-bol  - Everywhere except at the start of a headline
+  (kotl-mode:emulate-tab nil)
+
+  ;; Configure whether `kotl-mode:indent-line' uses tabs and spaces or
+  ;; spaces only.
+  ;; Potential values are:
+  ;;   t   - may insert literal <tab> characters. (default)
+  ;;
+  ;;   nil - may insert <spc> characters only.
+  (kotl-mode:indent-tabs-mode t))