diff --git a/ChangeLog b/ChangeLog
index eefae8f1..cfab4896 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,41 @@
+2026-06-27 Bob Weiner
+
+* man/hyperbole.texi (Smart Key - Hyperbole Buttons): Cross-reference
+ how to add ibtype help functions.
+
+* hywiki.el (hywiki-word-highlight-post-command): Fix to add support
+ for WikiWord rehighlighting after a capitalize, downcase or upcase
+ command.
+
+2026-06-26 Bob Weiner
+
+* hmouse-drv.el (hkey-help): Suppress generic Assist Key doc when
+ ibut has its own :help function.
+
+* hibtypes.el (hywiki-word:help): Add to to dispatch for creating a
+ HyWikiWord with prompting for its reference type or displaying
+ help for the potential WikiWord ibtype.
+
+* hywiki.el (hywiki-add-page): Fix so 'page-in-hasht' is t only if ref
+ type is a page, not some other type.
+ (hywiki-word-dehighlight-in-buffers): Fix so does not move
+ point in any of these buffers.
+ (hywiki-referent-menu): Change title from 'HyWiki Add>' to
+ 'HyWiki RefType>' to match that used in 'hywiki-create-referent'.
+ (hywiki-add-spec): Add this autoloaded command that
+ lets you create a HyWikiWord but defer deciding on its type until
+ it is activated with the Action Key.
+ (hywiki-display-spec): Add to transform spec to a standard
+ HyWiki referent.
+ (hywiki-referent-menu): Change "Sexp" to "Elisp" and add in
+ "Spec".
+ (hywiki-display-sexpression): Make obsolete; replace with
+ 'hywiki-display-elisp'.
+ (hywiki-add-sexpression): Replace with 'hywiki-add-elisp'.
+ (hywiki-add-elisp, hywiki-display-elisp): Add.
+ man/hyperbole.texi (HyWiki Menu): Add doc on referent types that when
+ activated aare given the WikiWord as an argument.
+
2026-06-25 Bob Weiner
* hasht.el (hash-merge-values): Remove ordered result requirement to allow
diff --git a/hibtypes.el b/hibtypes.el
index 2e65c7ab..d335de80 100644
--- a/hibtypes.el
+++ b/hibtypes.el
@@ -3,7 +3,7 @@
;; Author: Bob Weiner
;;
;; Orig-Date: 19-Sep-91 at 20:45:31
-;; Last-Mod: 14-Jun-26 at 15:13:01 by Bob Weiner
+;; Last-Mod: 27-Jun-26 at 18:36:25 by Bob Weiner
;;
;; SPDX-License-Identifier: GPL-3.0-or-later
;;
@@ -115,8 +115,9 @@
(defib hywiki-word ()
"When on a non-existing HyWikiWord, create it and display its referent.
-A call to (hywiki-active-in-current-buffer-p) must return non-nil
-for this to activate.
+This is the Action Key function that activates HyWikiWords. A call
+to (hywiki-active-in-current-buffer-p) must return non-nil for this to
+activate.
If the associated HyWiki referent is a page, create it automatically
unless it is the first HyWiki page to be created, in which case,
@@ -136,6 +137,40 @@ Existing HyWikiWords are handled by the implicit button type
(ibut:label-set wikiword start end)
(hact 'hywiki-word-create-and-display wikiword))))))
+(defun hywiki-word:help (ibut)
+ "Dispatch to desired HyWikiWord Assist Key function based on prefix arg.
+
+This table summarizes the function run for each prefix argument:
+|--------------------------------------+-------------------------------------|
+| Function | Key Binding |
+|--------------------------------------+-------------------------------------|
+| 1. Set Referent Type and Display | {M-0 M-RET} or {C-u C-u M-RET} |
+| 2. Create a WikiWord Spec | {M-1 M-RET} or {M-0 M-RET s} |
+| (Set Referent on Activation) | |
+| 3. Show Assist Key Help for WikiWord | {C-u M-RET} or any other prefix arg |
+|--------------------------------------+-------------------------------------|
+
+#1 prompts for a referent type, creates and displays the wikiword's
+referent. With an Assist Key press on a non-existing wikiword, it prompts
+for its wikiword referent type, then creates and displays it. A call
+to (hywiki-active-in-current-buffer-p) must return non-nil for this to
+activate.
+
+#2 creates a wikiword spec that when activated via the Action Key with
+{M-RET} prompts for and replaces the spec with the chosen referent type
+and associated attributes (it follows the procedure in #2 above).
+
+#3 shows the wikiword attributes and this doc string."
+ (pcase current-prefix-arg
+ ((or '(16) 0) (hywiki-word-create-and-display
+ (ibut:key-to-label (hattr:get ibut 'lbl-key))
+ t))
+ (1 (let ((wikiword (ibut:key-to-label (hattr:get ibut 'lbl-key))))
+ (hywiki-add-spec wikiword)
+ (hywiki-message-spec wikiword)))
+ ;; Any other prefix arg, show wikiword attributes and the doc string.
+ (_ (hkey-help t))))
+
;;; ========================================================================
;;; Jumps to source line from Python traceback lines
;;; ========================================================================
@@ -1809,6 +1844,8 @@ not yet existing HyWikiWords."
(ibut:label-set wikiword))
(hact 'link-to-wikiword wikiword))))))
+(defalias 'hywiki-existing-word:help 'hywiki-word:help)
+
;;; ========================================================================
;;; Inserts completion into minibuffer or other window.
;;; ========================================================================
diff --git a/hmouse-drv.el b/hmouse-drv.el
index d88703f1..4ee08d5a 100644
--- a/hmouse-drv.el
+++ b/hmouse-drv.el
@@ -3,7 +3,7 @@
;; Author: Bob Weiner
;;
;; Orig-Date: 04-Feb-90
-;; Last-Mod: 25-Jun-26 at 08:53:26 by Bob Weiner
+;; Last-Mod: 26-Jun-26 at 12:36:25 by Bob Weiner
;;
;; SPDX-License-Identifier: GPL-3.0-or-later
;;
@@ -1146,7 +1146,14 @@ documentation is found."
(setq hkey-help-msg
(if (and cmd-sym (symbolp cmd-sym))
(progn
- (let* ((condition (car hkey-form))
+ (let* ((actype (or (actype:elisp-symbol
+ (hattr:get 'hbut:current 'actype))
+ (hattr:get 'hbut:current 'actype)))
+ (assist-function-flag (and assisting
+ (symbolp actype)
+ (fboundp actype)
+ (documentation actype)))
+ (condition (car hkey-form))
(temp-buffer-show-hook
(lambda (buf)
(set-buffer buf)
@@ -1171,10 +1178,8 @@ documentation is found."
;; Print Hyperbole button attributes
(when (memq cmd-sym '(hui:hbut-act hui:hbut-help))
- (let* ((actype (or (actype:elisp-symbol (hattr:get 'hbut:current 'actype))
- (hattr:get 'hbut:current 'actype)))
- ;; (lbl-key (hattr:get 'hbut:current 'lbl-key))
- (categ (hattr:get 'hbut:current 'categ))
+ (let* ;; (lbl-key (hattr:get 'hbut:current 'lbl-key))
+ ((categ (hattr:get 'hbut:current 'categ))
(attributes (nthcdr 2 (hattr:list 'hbut:current)))
(but-def-symbol (htype:def-symbol
(if (eq categ 'explicit) actype categ)))
@@ -1227,9 +1232,7 @@ documentation is found."
(replace-regexp-in-string
"^" " " (documentation type-help-func)
nil t))))
- (when (and (symbolp actype)
- (fboundp actype)
- (documentation actype))
+ (when assist-function-flag
(princ (format "\n%s ACTION KEY SPECIFICS:\n%s\n"
(or (actype:def-symbol actype) actype)
(replace-regexp-in-string "^" " " (documentation actype)
@@ -1252,34 +1255,35 @@ documentation is found."
nil t))))
(terpri))))
- (princ (format "A %s of the %s %sKey"
- (if mouse-flag
- (if mouse-drag-flag "drag" "click")
- "press")
- (if assisting "Assist" "Action")
- (if mouse-flag "Mouse " "")))
- (terpri)
- (princ "WHEN ")
- (princ
- (or condition
- "there is no matching context"))
- (terpri)
-
- (mapc (lambda (c)
- (when (and (> (length calls) 1)
- (not (eq (car calls) c)))
- ;; Is an 'or' set of calls
- (princ "OR "))
- (princ "CALLS ") (princ (if (consp c) c (list c)))
- (when (and (fboundp (setq call (if (consp c) (car c) c)))
- (setq doc (documentation call)))
- (princ " WHICH")
- (princ (if (string-match "\\`[a-zA-Z]*[a-rt-zA-RT-Z]+s[ [:punct:]]" doc)
- ":" " WILL:"))
- (terpri) (terpri)
- (princ (replace-regexp-in-string "^" " " doc nil t))
- (terpri) (terpri)))
- calls)))
+ (unless assist-function-flag
+ (princ (format "A %s of the %s %sKey"
+ (if mouse-flag
+ (if mouse-drag-flag "drag" "click")
+ "press")
+ (if assisting "Assist" "Action")
+ (if mouse-flag "Mouse " "")))
+ (terpri)
+ (princ "WHEN ")
+ (princ
+ (or condition
+ "there is no matching context"))
+ (terpri)
+
+ (mapc (lambda (c)
+ (when (and (> (length calls) 1)
+ (not (eq (car calls) c)))
+ ;; Is an 'or' set of calls
+ (princ "OR "))
+ (princ "CALLS ") (princ (if (consp c) c (list c)))
+ (when (and (fboundp (setq call (if (consp c) (car c) c)))
+ (setq doc (documentation call)))
+ (princ " WHICH")
+ (princ (if (string-match "\\`[a-zA-Z]*[a-rt-zA-RT-Z]+s[ [:punct:]]" doc)
+ ":" " WILL:"))
+ (terpri) (terpri)
+ (princ (replace-regexp-in-string "^" " " doc nil t))
+ (terpri) (terpri)))
+ calls))))
"")
(message "No %s Key command for current context."
(if assisting "Assist" "Action"))))
diff --git a/hywiki.el b/hywiki.el
index 7180bfe9..4be002a0 100644
--- a/hywiki.el
+++ b/hywiki.el
@@ -3,7 +3,7 @@
;; Author: Bob Weiner
;;
;; Orig-Date: 21-Apr-24 at 22:41:13
-;; Last-Mod: 25-Jun-26 at 15:39:05 by Bob Weiner
+;; Last-Mod: 27-Jun-26 at 18:45:09 by Bob Weiner
;;
;; SPDX-License-Identifier: GPL-3.0-or-later
;;
@@ -763,6 +763,10 @@ deletion commands and those in `hywiki-non-character-commands'."
(max hywiki--start hywiki--end))
(hywiki-maybe-dehighlight-references start end)
(hywiki-maybe-highlight-references start end))))
+ ((and (symbolp this-command)
+ (string-match-p "\\(^\\|-?\\)\\(capitalize\\|downcase\\|upcase\\)\\(-\\|$\\)"
+ (symbol-name this-command)))
+ (hywiki--maybe-rehighlight-at-point))
((when (or (memq this-command hywiki-non-character-commands)
(and (symbolp this-command)
(string-match-p "^\\(org-\\)?\\(delete-\\|kill-\\)\\|\\(-delete\\|-kill\\|eval-last-sexp\\|eval-expression\\)\\(-\\|$\\)\\|^\\(hkey-either\\|action-key\\|assist-key\\)" (symbol-name this-command))))
@@ -1088,7 +1092,7 @@ After successfully finding a referent, run `hywiki-display-referent-hook'."
(defcustom hywiki-referent-menu
(delq nil
(list
- '("HyWiki Add>")
+ '("HyWiki RefType>")
(when (fboundp #'activities-new)
'("Activity" (hywiki-add-activity hkey-value)
"Add a HyWikiWord that activates a saved activity from the Activities package."))
@@ -1096,6 +1100,8 @@ After successfully finding a referent, run `hywiki-display-referent-hook'."
"Add a HyWikiWord that jumps to an Emacs bookmark.")
'("Command" (hywiki-add-command hkey-value)
"Add a HyWikiWord that runs an Emacs command or Hyperbole action type.")
+ '("Elisp" (hywiki-add-elisp hkey-value)
+ "Add a HyWikiWord that evaluates an Elisp sexpression.")
'("Find" (hywiki-add-find hkey-value)
"Add a HyWikiWord that greps through `hywiki-directory' for its matches.")
;; "<(global explicit button name)>"
@@ -1126,8 +1132,8 @@ After successfully finding a referent, run `hywiki-display-referent-hook'."
;; e.g. (kbd "key sequence")
'("orgRoamNode" (hywiki-add-org-roam-node hkey-value)
"Add a HyWikiWord that displays an Org Roam node given its title.")
- '("Sexp" (hywiki-add-sexpression hkey-value)
- "Add a HyWikiWord that evaluates an Elisp sexpression.")
+ '("Spec" (hywiki-add-spec hkey-value)
+ "Highlight HyWikiWord; defer referent creation until activation.")
))
"Menu of HyWikiWord custom referent types of the form:
\(LABEL-STRING ACTION-SEXP DOC-STR)."
@@ -1204,7 +1210,7 @@ use `hywiki-active-in-current-buffer-p' for that."
(defun hywiki-add-activity (wikiword)
"Make WIKIWORD resume a prompted for, existing activity.
-If WIKIWORD is invalid, trigger a `user-error' if called interactively
+If WIKIWORD is invalid, trigger an error if called interactively
or return nil if not.
After successfully adding the activity, run `hywiki-add-referent-hook'.
@@ -1223,7 +1229,7 @@ calling this function."
(defun hywiki-add-bookmark (wikiword)
"Make WIKIWORD display a bookmark at point and return the action.
-If WIKIWORD is invalid, trigger a `user-error' if called interactively
+If WIKIWORD is invalid, trigger an error if called interactively
or return nil if not.
After successfully adding the bookmark, run `hywiki-add-referent-hook'.
@@ -1260,7 +1266,7 @@ string argument and that argument is the empty string or matches WIKIWORD
sans any #suffix, then WIKIWORD (including any suffix) is sent as the first
argument.
-If WIKIWORD is invalid, trigger a `user-error' if called interactively
+If WIKIWORD is invalid, trigger an error if called interactively
or return nil if not.
After successfully adding the actype, run `hywiki-add-referent-hook'.
@@ -1294,11 +1300,29 @@ calling this function."
(t (error "(hywiki-display-command): Unbound referent command, '%s'"
command))))
+(defun hywiki-add-elisp (wikiword)
+ "Make WIKIWORD evaluate a prompted for Elisp sexpression and return it.
+
+If WIKIWORD is invalid, trigger an error if called interactively
+or return nil if not.
+
+After successfully adding the sexpression, run `hywiki-add-referent-hook'.
+
+Use `hywiki-get-referent' to determine whether WIKIWORD exists prior to
+calling this function."
+ (interactive (list (or (hywiki-word-at)
+ (hywiki-word-read-new "Add/Edit HyWikiWord: "))))
+ (hywiki-add-referent wikiword (cons 'elisp
+ (read--expression "Elisp Sexpr: "))))
+
+(defun hywiki-display-elisp (_wikiword elisp)
+ (eval elisp))
+
(defun hywiki-add-find (wikiword)
"Make WIKIWORD grep across `hywiki-directory' for matches to itself.
Return the command to invoke.
-If WIKIWORD is invalid, trigger a `user-error' if called interactively
+If WIKIWORD is invalid, trigger an error if called interactively
or return nil if not.
After successfully adding the grep, run `hywiki-add-referent-hook'.
@@ -1317,7 +1341,7 @@ calling this function."
(defun hywiki-add-global-button (wikiword)
"Make WIKIWORD evaluate a prompted for global button.
-If WIKIWORD is invalid, trigger a `user-error' if called interactively
+If WIKIWORD is invalid, trigger an error if called interactively
or return nil if not.
After successfully adding the button link, run `hywiki-add-referent-hook'.
@@ -1337,7 +1361,7 @@ calling this function."
(defun hywiki-add-hyrolo (wikiword)
"Make WIKIWORD search and display `hyrolo-file-list' matches.
-If WIKIWORD is invalid, trigger a `user-error' if called interactively
+If WIKIWORD is invalid, trigger an error if called interactively
or return nil if not.
After successfully adding the hyrolo search, run `hywiki-add-referent-hook'.
@@ -1356,7 +1380,7 @@ calling this function."
(defun hywiki-add-info-index (wikiword)
"Make WIKIWORD display an Info manual index item and return it.
-If WIKIWORD is invalid, trigger a `user-error' if called interactively
+If WIKIWORD is invalid, trigger an error if called interactively
or return nil if not.
After successfully adding the Info index item, run `hywiki-add-referent-hook'.
@@ -1379,7 +1403,7 @@ calling this function."
(defun hywiki-add-info-node (wikiword)
"Make WIKIWORD display an Info manual node and return it.
-If WIKIWORD is invalid, trigger a `user-error' if called interactively
+If WIKIWORD is invalid, trigger an error if called interactively
or return nil if not.
After successfully adding the Info node, run `hywiki-add-referent-hook'.
@@ -1402,7 +1426,7 @@ calling this function."
(defun hywiki-add-key-series (wikiword)
"Make WIKIWORD invoke a prompted for key series and return it.
-If WIKIWORD is invalid, trigger a `user-error' if called interactively
+If WIKIWORD is invalid, trigger an error if called interactively
or return nil if not.
After successfully adding the key series, run `hywiki-add-referent-hook'.
@@ -1424,7 +1448,7 @@ calling this function."
Point must be in the buffer with the id. If no id exists, it is created.
Return the referent created with the form: \\='(org-id . ).
-If WIKIWORD is invalid, trigger a `user-error' if called interactively
+If WIKIWORD is invalid, trigger an error if called interactively
or return nil if not.
After successfully adding the Org id, run `hywiki-add-referent-hook'.
@@ -1454,7 +1478,7 @@ calling this function."
(defun hywiki-add-org-roam-node (wikiword)
"Make WIKIWORD display an Org Roam Node and return the action.
-If WIKIWORD is invalid, trigger a `user-error' if called interactively
+If WIKIWORD is invalid, trigger an error if called interactively
or return nil if not.
After successfully adding the action, run `hywiki-add-referent-hook'.
@@ -1476,21 +1500,6 @@ calling this function."
(or (alist-get 'file org-link-frame-setup)
(alist-get hpath:display-where hpath:display-where-alist))))
-(defun hywiki-create-page (wikiword &optional message-flag)
- "Prompt for, add to HyWiki lookups and return a WIKIWORD page.
-With optional prefix arg MESSAGE-FLAG non-nil, display a minibuffer message
-with the page."
- (interactive (list nil current-prefix-arg))
- (unless (stringp wikiword)
- (setq wikiword (hywiki-word-read-new "Create/Edit HyWikiWord: ")))
- (setq hkey-value wikiword)
- (let ((page-file (cdr (hywiki-add-page wikiword t))))
- (if (or message-flag (called-interactively-p 'interactive))
- (if page-file
- (message "HyWikiWord '%s' page: \"%s\"" wikiword page-file)
- (user-error "(hywiki-create-page): Invalid HyWikiWord: '%s'; must be capitalized, all alpha" wikiword)))
- page-file))
-
(defun hywiki-add-page (page-name &optional force-flag)
"Add a new or return any existing HyWiki page path for PAGE-NAME.
Returned format is: \\='(page . \"\") or nil when none.
@@ -1522,7 +1531,7 @@ Use `hywiki-get-referent' to determine whether a HyWiki page exists."
(let* ((page-file (hywiki-get-page-file page-name))
(page-file-readable (file-readable-p page-file))
(referent-hasht (hywiki-get-referent-hasht))
- (page-in-hasht (hywiki-get-referent page-name)))
+ (page-in-hasht (hywiki-page-exists-p page-name)))
(unless page-file-readable
(if (file-writable-p page-file)
(write-region "" nil page-file nil 0)
@@ -1545,6 +1554,61 @@ Use `hywiki-get-referent' to determine whether a HyWiki page exists."
(when (called-interactively-p 'interactive)
(user-error "(hywiki-add-page): Invalid HyWikiWord: '%s'; must be capitalized, all alpha" page-name))))
+(defun hywiki-create-page (wikiword &optional message-flag)
+ "Prompt for, add to HyWiki lookups and return a WIKIWORD page.
+With optional prefix arg MESSAGE-FLAG non-nil, display a minibuffer message
+with the page."
+ (interactive (list nil current-prefix-arg))
+ (unless (stringp wikiword)
+ (setq wikiword (hywiki-word-read-new "Create/Edit HyWikiWord: ")))
+ (setq hkey-value wikiword)
+ (let ((page-file (cdr (hywiki-add-page wikiword t))))
+ (if (or message-flag (called-interactively-p 'interactive))
+ (if page-file
+ (message "HyWikiWord '%s' page: \"%s\"" wikiword page-file)
+ (user-error "(hywiki-create-page): Invalid HyWikiWord: '%s'; must be capitalized, all alpha" wikiword)))
+ page-file))
+
+;;;###autoload
+(defun hywiki-add-spec (wikiword)
+ "Create a WIKIWORD spec whose action selects and displays its referent type.
+The specified WIKIWORD is highlighted. This replaces any existing referent
+the WIKIWORD may have. Use ‘hywiki-get-referent’ to determine any referent
+type associated with WIKIWORD prior to invoking this.
+
+This differs from `hywiki-word-create-and-display' in that selection and
+display of the WIKIWORD referent is deferred until the first Action Key
+activation of the WIKIWORD.
+
+When the WIKIWORD spec is activated, prompt for and choose a typed referent.
+See ‘hywiki-referent-menu’ for valid referent types. Select Page for a
+standard HyWiki page.
+
+If WIKIWORD is invalid, trigger an error if called interactively
+or return nil if not.
+
+After successfully adding the spec, run `hywiki-add-referent-hook'."
+ (interactive (list (or (hywiki-word-at)
+ (hywiki-word-read-new "Add HyWikiWord Spec: "))))
+ (when (or (not (stringp wikiword)) (string-empty-p wikiword))
+ (error "(hywiki-word-create-spec): No HyWikiWord specified"))
+ (setq hkey-value wikiword)
+ (hywiki-add-referent wikiword '(spec . t)))
+
+;; Need unused optional second arg here because `hywiki-display-referent-type'
+;; calls this with the spec value (which is always t) to conform to other
+;; referent types.
+(defun hywiki-display-spec (wikiword &optional _spec_value)
+ ;; Prevent infinite recursion
+ (unless (hyperb:stack-frame '(hywiki-create-referent-and-display))
+ (hywiki-create-referent-and-display wikiword t))
+ (hywiki-message-spec wikiword))
+
+(defun hywiki-message-spec (wikiword)
+ "When WIKIWORD has a referent type of `spec', print a message saying so."
+ (when (eq (car (hywiki-get-referent wikiword)) 'spec)
+ (message "%s is now a wikiword spec; press the Action Key on it to set its referent type" wikiword)))
+
;;;###autoload
(defun hywiki-word-create (wikiword &optional ref-type-flag)
"Create a HyWiki referent for WIKIWORD and return it; don't display it.
@@ -1646,7 +1710,8 @@ Each candidate is an alist with keys: file, line, text, and display."
:exit-function #'hywiki-completion-exit-function))))))
(defun hywiki-create-referent-and-display (wikiword &optional prompt-flag)
- "Display the HyWiki referent for WIKIWORD if not in an ert test; return it.
+ "Display the HyWiki referent for WIKIWORD and return the referent value.
+The value is the referent linked to without its type.
If there is no existing WIKIWORD referent and PROMPT-FLAG is non-nil,
prompt for and choose a referent type; see `hywiki-referent-menu' for
@@ -1694,7 +1759,7 @@ an existing or new HyWikiWord."
(defun hywiki-add-path-link (wikiword &optional file pos)
"Set a path link anchored possible position for WIKIWORD and return it.
-If WIKIWORD is invalid, trigger a `user-error' if called interactively
+If WIKIWORD is invalid, trigger an error if called interactively
or return nil if not.
Interactively prompt for the file and whether to use the current
@@ -1719,22 +1784,9 @@ calling this function."
(defun hywiki-display-path-link (_wikiword path)
(funcall hywiki-display-page-function path))
-(defun hywiki-add-sexpression (wikiword)
- "Make WIKIWORD evaluate a prompted for sexpression and return it.
-
-If WIKIWORD is invalid, trigger a `user-error' if called interactively
-or return nil if not.
-
-After successfully adding the sexpression, run `hywiki-add-referent-hook'.
-
-Use `hywiki-get-referent' to determine whether WIKIWORD exists prior to
-calling this function."
- (interactive (list (or (hywiki-word-at)
- (hywiki-word-read-new "Add/Edit HyWikiWord: "))))
- (hywiki-add-referent wikiword (cons 'sexpression
- (read--expression "Sexpression: "))))
-
+;; Leave for backward compatibility if any such WikiWords already exist.
(defun hywiki-display-sexpression (_wikiword sexpression)
+ (make-obsolete 'hywiki-display-sexpression 'hywiki-display-elisp "9.0.2pre")
(eval sexpression))
;; Presently used only in tests; maybe move it to the test/ dir
@@ -4421,16 +4473,17 @@ completion to work properly."
(interactive)
(dolist (buf buffers)
(with-current-buffer buf
- (hywiki-word-remove-completion-at-point)
- (remove-hook 'pre-command-hook 'hywiki-word-store-around-point :local)
- (remove-hook 'post-self-insert-hook 'hywiki-word-highlight-post-self-insert :local)
- (remove-hook 'post-command-hook 'hywiki-word-highlight-post-command :local)
- ;; Display buffer before `normal-mode' triggers possibly
- ;; long-running font-locking
- (sit-for 0)
- ;; Force dehighlighting in buffer with this `let'
- (setq hywiki-buffer-highlighted-state 'h)
- (hywiki-maybe-dehighlight-references)))
+ (save-excursion
+ (hywiki-word-remove-completion-at-point)
+ (remove-hook 'pre-command-hook 'hywiki-word-store-around-point :local)
+ (remove-hook 'post-self-insert-hook 'hywiki-word-highlight-post-self-insert :local)
+ (remove-hook 'post-command-hook 'hywiki-word-highlight-post-command :local)
+ ;; Display buffer before `normal-mode' triggers possibly
+ ;; long-running font-locking
+ (sit-for 0)
+ ;; Force dehighlighting in buffer with this `let'
+ (setq hywiki-buffer-highlighted-state 'h)
+ (hywiki-maybe-dehighlight-references))))
(hywiki-maybe-directory-updated))
(defun hywiki-mode-disable ()
@@ -4707,7 +4760,7 @@ the HyWikiWord reference."
(hywiki-maybe-dehighlight-between-references)))
(defun hywiki--maybe-rehighlight-at-point ()
- "Dehighlight any existing HyWikiWord when needed.
+ "Highlight any existing HyWikiWord when needed.
That is, only if the editing command has changed the word-only part of
the HyWikiWord reference.
diff --git a/man/hyperbole.texi b/man/hyperbole.texi
index 01a8cdc5..c65c030b 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: 25-Jun-26 at 13:36:38 by Bob Weiner
+@c Last-Mod: 28-Jun-26 at 00:20:55 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 June 25, 2026
+@set UPDATED June 28, 2026
@set UPDATED-MONTH June 2026
@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 June 25, 2026.
+Printed June 28, 2026.
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
-June 25, 2026 @c AUTO-REPLACE-ON-SAVE
+June 28, 2026 @c AUTO-REPLACE-ON-SAVE
Published by the Free Software Foundation, Inc.
@@ -370,6 +370,10 @@ HyWiki
* Publish HyWiki::
* HyWiki Menu::
+HyWikiWords
+
+* Creating HyWikiWords::
+
Koutliner
* Menu Commands::
@@ -4519,7 +4523,8 @@ It uses Org mode for note taking and adds automatic hyperlinking and
highlighting of HyWikiWords in Org files within
@code{hywiki-directory} (default = @file{~/hywiki}). With @bkbd{C-h h
h p} you can publish any updated part of your HyWiki to an HTML
-directory for export to the web.
+directory for export to the web. HyWiki is built for scale and
+has been tested to be performant with 10,000 HyWikiWords.
@float Image,image:HyWiki Page
@caption{HyWiki Page}
@@ -4543,29 +4548,46 @@ directory for export to the web.
@cindex Org link, HyWiki
@cindex hy: prefix
A @dfn{HyWikiWord} is a capitalized word that contains upper and
-lowercase letters only and has a corresponding @file{HyWikiWord.org}
-wiki page file below @code{hywiki-directory}. HyWikiWords in HyWiki
-pages are automatically highlighted and turned into hyperlinks as soon
-as you type them, without the need for any delimiters. However, if
-you prefer to use Org-style links, simply delimit them with double
-square brackets and the `hy:' prefix like so: [[hy:MyWikiWord]].
+lowercase letters only and has an associated referent (a link or an
+action). The default, most common referent type is a Wiki Page, an
+Org file with the wikiword's name and a @file{.org} suffix that lives
+in @code{hywiki-directory}.
+
+HyWikiWords are automatically highlighted and turned into hyperlinks
+to their referents as soon as you type them, without the need for any
+delimiters. By default, this happens only in HyWiki pages so as not
+to confuse new users. But with one setting, you can enable them in
+all text buffers and within the comments of programming language
+buffers. @xref{HyWiki Mode}.
+
+HyWiki is fully compatible with Org mode and if you prefer your HyWiki
+links to be Org links, then simply delimit them with double square
+brackets and the @samp{hy:} prefix like so: @samp{[[hy:MyWikiWord]]}.
+
+@menu
+* Creating HyWikiWords::
+@end menu
+
+@node Creating HyWikiWords, , HyWikiWords, HyWikiWords
+@subsection Creating HyWikiWords
@cindex create a HyWikiWord
@cindex HyWikiWord create
-To create a new HyWikiWord, insert it into a text buffer, move point
-onto the word and press @bkbd{C-h h h c} to create a new blank HyWiki
-page that you can immediately start editing. HyWiki is built for
-scalability and has been tested to be performant with 10,000
-HyWikiWords.
+To create a new HyWikiWord, insert it into a buffer where it is
+recognized, move point anywhere within the word and press @bkbd{C-h h
+h c} to create a new blank HyWiki page that you can immediately start
+editing.
@cindex Org M-RET override
@cindex override Org M-RET
@kindex C-h h h o a
@kindex C-h h h c
@cindex menu item, HyWiki/Org-M-RET/All-Hyperbole-Contexts
-The Action Key can create new HyWiki pages when on an undefined
+The Action Key, @bkbd{M-@key{RET}}, provides a faster way to create
+HyWikiWords to speed your note-taking, if you let HyWiki have priority over this key rather than Org mode. Simpl
+ can create new HyWiki pages when on an undefined
HyWikiWord if you change the setting that controls the Org mode
-@bkbd{M-@key{RET}} binding. Have Hyperbole override Org's control of
+ binding. Have Hyperbole override Org's control of
that key in all Action and Assist Key contexts with the
@samp{All-Hyperbole-Contexts} setting bound to @bkbd{C-h h h o a}.
@@ -4634,6 +4656,7 @@ HyWikiWords everywhere and enabling them in all editable buffers.
A nil value disables HyWikiWord hyperlink buttons in both HyWiki
pages and all other buffers (since it also disables `hywiki-mode').
+@anchor{HyWiki Mode}
Outside of HyWiki pages, the global minor mode `hywiki-mode' must be
manually enabled for auto-HyWikiWord highlighting. Interactively,
@bkbd{C-h h h m a} does this; programmatically, use `(hywiki-mode :all)'
@@ -4755,10 +4778,10 @@ consult grep over its HyWiki backlink references, selecting one.
@cindex HyWikiWord creation
@cindex HyWikiWord types
-@vindex hywiki-referent-menu
@cindex HyWiki referent type, Activity
@cindex HyWiki referent type, Bookmark
@cindex HyWiki referent type, Command
+@cindex HyWiki referent type, Elisp
@cindex HyWiki referent type, Find
@cindex HyWiki referent type, Gbut
@cindex HyWiki referent type, HyRolo
@@ -4769,10 +4792,11 @@ consult grep over its HyWiki backlink references, selecting one.
@cindex HyWiki referent type, OrgID
@cindex HyWiki referent type, Page
@cindex HyWiki referent type, orgRoamNode
-@cindex HyWiki referent type, Sexp
+@cindex HyWiki referent type, Spec
@findex hywiki-add-activity
@findex hywiki-add-bookmark
@findex hywiki-add-command
+@findex hywiki-add-elisp
@findex hywiki-add-find
@findex hywiki-add-global-button
@findex hywiki-add-hyrolo
@@ -4783,16 +4807,20 @@ consult grep over its HyWiki backlink references, selecting one.
@findex hywiki-add-org-id
@findex hywiki-add-page
@findex hywiki-add-org-roam-node
-@findex hywiki-add-sexpression
+@findex hywiki-add-spec
+@vindex hywiki-referent-prompt-flag
+@cindex referent type, auto-prompting
+@cindex referent type menu
+@vindex hywiki-referent-menu
@item Create
Create and display a new or existing HyWikiWord referent, prompting
with any existing referent names. With either
-@code{hywiki-referent-prompt-flag} set or optional prefix ARG, prompt
+@code{hywiki-referent-prompt-flag} set or a prefix argument, prompt
for and choose a typed referent; otherwise, create and/or display a
HyWiki page. The following table details the potentially prompted for
referent types, as given by @code{hywiki-referent-menu}, with the
-``HyWiki Add>'' prompt (Activity appears only if the @code{activities}
-package is loaded):
+``HyWiki RefType>'' prompt (Activity appears only if the
+@code{activities} package is loaded):
@exampleindent 0
@example
@@ -4802,6 +4830,7 @@ Menu Item Command Description
Activity hywiki-add-activity Activate a saved Activity
Bookmark hywiki-add-bookmark Jump to an Emacs bookmark
Command hywiki-add-command Run a Hypb action or cmd
+Elisp hywiki-add-elisp Evaluate an Elisp sexp
Find hywiki-add-find Grep through hywiki dir
Gbut hywiki-add-global-button Activate a global button
HyRolo hywiki-add-hyrolo Search @code{hyrolo-file-list}
@@ -4812,11 +4841,44 @@ infoNode hywiki-add-info-node Display an Info doc node
OrgID hywiki-add-org-id Display a sect for Org ID
Page hywiki-add-page Display a HyWiki page#sect
orgRoamNode hywiki-add-org-roam-node Display an Org Roam node
-Sexp hywiki-add-sexpression Evaluate an Elisp sexp
+Spec hywiki-add-spec Defer referent linkage
===================================================================
@end group
@end example
+@noindent
+Below are notes on a few of the HyWiki referent types.
+
+@table @asis
+@item Command
+If the command referent is just a symbol without any arguments, then
+the WikiWord is passed as the sole argument when the command is run.
+If the command takes a single argument and the empty string is given
+for the argument, then this is replaced with the WikiWord when the
+command is run.
+
+@findex hywiki-word-grep
+@item Find
+Search all of the HyWiki pages for matches of the WikiWord using the
+@code{hywiki-word-grep} command.
+
+@findex hyrolo-fgrep
+@item HyRolo
+Search all of the HyRolo files for matches of the WikiWord using the
+@code{hyrolo-fgrep} command.
+
+@item Page
+Display the HyWiki page named for the WikiWord, e.g. WikiWord.org.
+
+@vindex hywiki-referent-menu
+@item Spec
+Create and highlight a WikiWord but defer specifying its type and
+creating its referent until the WikiWord is activated with the Action
+Key. When activated, prompt for and choose a typed referent. See
+@code{hywiki-referent-menu} for valid referent types. Select
+@emph{Page} for a standard HyWiki page.
+@end table
+
@vindex hywiki-directory
@vindex action-key-modeline-buffer-id-function
@findex dired
@@ -4869,17 +4931,19 @@ Select from three states for the global minor mode, @code{hywiki-mode}.
@item All-Editable-Buffers
This is the default setting. Highlight HyWikiWord references within
HyWiki page buffers only. The @code{hywiki-mode} variable is set to
-@samp{:pages}.
+@samp{:pages}. Programatically, use: @code{(hywiki-mode :pages)}.
@vindex hywiki-exclude-major-modes
@item HyWiki-Pages-Only
Highlight HyWikiWord references within all editable buffers except
those with major modes in @code{hywiki-exclude-major-modes}. The
-@code{hywiki-mode} variable is set to @samp{:all}.
+@code{hywiki-mode} variable is set to @samp{:all}. Programatically,
+use: @code{(hywiki-mode :all)}.
@item Nowhere
Disable highlighting HyWikiWord references everywhere. The
-@code{hywiki-mode} variable is set to @samp{nil}.
+@code{hywiki-mode} variable is set to @samp{nil}. Programatically,
+use: @code{(hywiki-mode nil)}.
@end table
@kindex C-h h h o
@@ -4932,7 +4996,7 @@ implicit button type that HyNote defines, @code{hynote-file}.
In the future, HyNote will also provide a universal way to easily link to
information across many file formats.
-For more, @ref{HyWiki}.
+For more, @pxref{HyWiki}.
@node HyControl, Koutliner, HyNote, Top
@@ -7930,7 +7994,8 @@ same type symbol used in the type definition call (not the Hyperbole
symbol returned by the call). This will not delete the action type used
by the implicit button; that must be done separately.
-@cindex ibtype, help
+@anchor{ibtype help}
+@cindex ibtype help
@findex ibut:at-p
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
@@ -7942,9 +8007,9 @@ assist-action whenever the Assist Key is pressed, to respond to
requests for help on buttons of that type. Any such function should
take a single argument of an implicit button construct. (This is what
@code{(ibut:at-p)} returns when point is within an implicit button
-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.
+context). Remember that documentation of the Action Key's behavior is
+always available on @bkbd{C-h A} and @bkbd{C-u C-h A} for the Assist
+Key's.
@vindex class, hattr
@vindex class, hbut
@@ -11067,7 +11132,9 @@ When pressed on a Hyperbole button:
Activates the button.
ASSIST KEY
Displays help for the button, typically a summary of its
- attributes.
+ attributes. For implicit button types, the help behavior can be
+ overridden by defining a help function function for the stype,
+ @pxref{ibtype help}.
@end group
@end format