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