rswgnu · rswgnu · Jul 16, 2026 · Jul 15, 2026 · Jul 16, 2026 · Jul 16, 2026
diff --git a/ChangeLog b/ChangeLog
@@ -1,3 +1,33 @@
+2026-07-15  Bob Weiner  <rsw@gnu.org>
+
+* Makefile (env): Add and document this target (alias of echo target).
+
+* man/hyperbole.texi (Elpa Latest or Release Package Installation):
+    Combine Latest/In-Development and Release package installation
+    instructions into one subsection.
+
+* man/hy-package.el:
+  man/hy-straight.el: Add these two files of install and config
+    instructions for different package managers.  Include in
+    man/hyperbole.texi.
+  Makefile (HYPERBOLE_FILES):
+  MANIFEST (DOCUMENTATION): Add the above two files.
+
+* man/hyperbole-straight.el: Copy from "man/hyperbole.texi" and include
+    in the manual.  Update 'straight-use-package' configuration to latest.
+
+* hpath.el (hpath:to-markup-anchor): Fix programming mode anchors so
+    are anchored to the beginning of a line and may have one or more
+    initial 'comment-start' prefix characters.  Also, anchor to the
+    beginning of the line (plus whitespace) when in fundamental mode,
+    text mode or a non-file buffer.  These fixes prevent matching to
+    the "#link" reference rather than its referent in the same buffer.
+           (hpath:to-markup-anchor): Remove special handling for
+    fundamental and text modes as well as non-buffer files and just
+    use 'hpath:outline-section-pattern' for all of them.
+          (hpath:shell-comment-pattern): Add and use in new separate
+    shell-specific #anchor matching clause.
+
 2026-07-14  Bob Weiner  <rsw@gnu.org>
 
 * test/hy-test-dependencies.el: Add 'markdown-ts-mode' declaration.

diff --git a/MANIFEST b/MANIFEST
@@ -19,6 +19,8 @@ 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/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)

diff --git a/Makefile b/Makefile
@@ -3,7 +3,7 @@
 # Author:       Bob Weiner
 #
 # Orig-Date:    15-Jun-94 at 03:42:38
-# Last-Mod:     14-Jul-26 at 02:12:12 by Bob Weiner
+# Last-Mod:     15-Jul-26 at 21:34:14 by Bob Weiner
 #
 # Copyright (C) 1994-2026  Free Software Foundation, Inc.
 # See the file HY-COPY for license information.
@@ -50,6 +50,9 @@
 #		Generate the website sources and upload them:
 #		    make website - generate web site in folder $(HYPB_WEB_REPO_LOCATION)"
 #
+#               List major build env versions:
+#                   make env
+#
 #               Lint all Hyperbole code files:
 #                   make lint
 #
@@ -241,7 +244,8 @@ HYPERBOLE_FILES = dir info html $(EL_SRC) $(EL_KOTL) \
         INSTALL DEMO DEMO-ROLO.otl FAST-DEMO MANIFEST README.md TAGS _hypb \
         .hypb hyrolo.py smart-clib-sym topwin.py hyperbole-banner.png \
 	.dir-locals.el \
-	$(man_dir)/hkey-help.txt $(man_dir)/hyperbole.texi $(man_dir)/hyperbole.css \
+	$(man_dir)/hkey-help.txt $(man_dir)/hy-package.el $(man_dir)/hy-straight.el \
+        $(man_dir)/hyperbole.texi $(man_dir)/hyperbole.css \
         $(man_dir)/texinfo-7.css
 
 TEST_ERT_FILES = $(wildcard test/*tests.el) $(wildcard test/hy-test-*.el)
@@ -301,8 +305,9 @@ help:
 .PHONY: all
 all: help
 
-.PHONY: echo
-echo:
+.PHONY: echo env
+echo: env
+env:
 	@echo "Emacs: $(shell which ${EMACS})"
 	@echo "Version: $(shell ${EMACS} --version)"
 	@echo "TERM: $(TERM)"

diff --git a/hpath.el b/hpath.el
@@ -3,7 +3,7 @@
 ;; Author:       Bob Weiner
 ;;
 ;; Orig-Date:     1-Nov-91 at 00:44:23
-;; Last-Mod:     11-Jul-26 at 18:53:47 by Mats Lidell
+;; Last-Mod:     15-Jul-26 at 17:33:26 by Bob Weiner
 ;;
 ;; SPDX-License-Identifier: GPL-3.0-or-later
 ;;
@@ -693,15 +693,16 @@ Contains a %s for replacement of a specific anchor id.")
   "Regexp matching a Markdown anchor id definition.
 Contains a %s for replacement of a specific anchor id.")
 
-(defconst hpath:markdown-section-pattern "^[ \t]*\\(#+\\|\\*+\\)[ \t]+%s\\([\[<\({ \t[:punct:]]*\\)$"
-  "Regexp matching a Markdown section header.
-Contains a %s for replacement of a specific section name.")
+(defconst hpath:markdown-section-pattern "^[ \t]*\\(#+\\|\\*+\\)[ \t]*%s\\([\[<\({ \t[:punct:]]*\\)$"
+  "Bol-anchored regexp matching an exact Markdown section.
+Allows for both '#' and '*' section headers.  Contains a %s for replacement
+of a specific section name.")
 
 (defconst hpath:markdown-suffix-regexp "\\.[mM][dD]"
   "Regexp that matches to a Markdown file suffix.")
 
 (defconst hpath:outline-section-pattern "^\\(\\*+\\|#\\+TITLE:\\)[ \t]+%s[ \t]*\\([\[<\({[:punct:]]+\\|$\\)"
-  "Bol-anchored, no leading spaces regexp matching an Emacs outline section header.
+  "Bol-anchored, no leading spaces regexp matching an exact outline section.
 Also supports Org '#+TITLE:' lines and headings as sections.  Contains a %s
 for replacement of a specific section name.")
 
@@ -716,6 +717,11 @@ These are used to indicate how to display or execute the pathname.
   "\\`/[^/:]+:\\|\\`s?ftp[:.]\\|\\`www\\.\\|\\`https?:"
   "Regexp matching remote pathnames and urls which invoke remote file handlers.")
 
+(defconst hpath:shell-comment-pattern
+  "^[ \t]*#+[ \t]*%s\\([ \t]\\|\\([\[<\({ \t[:punct:]]\\)\\|$\\)"
+  "Bol-anchored regexp matching the first part of a shell comment.
+Contains a %s for replacement of the comment string.")
+
 (defconst hpath:shell-modes '(sh-mode csh-mode shell-script:mode)
   "List of modes for editing shell scripts where # is a comment character.")
 
@@ -1781,15 +1787,18 @@ of the buffer."
 								      (string-match-p "\\`[A-Z0-9][A-Z0-9_-]*\\'"
                                                                                       (file-name-nondirectory (hypb:buffer-file-name)))))
 							     hpath:outline-section-pattern)
-							    ((or (and (hypb:buffer-file-name)
-								      (string-match-p hpath:markdown-suffix-regexp (hypb:buffer-file-name)))
-								 (apply #'derived-mode-p hpath:shell-modes))
+							    ((and (hypb:buffer-file-name)
+								  (string-match-p hpath:markdown-suffix-regexp (hypb:buffer-file-name)))
 							     hpath:markdown-section-pattern)
+							    ((apply #'derived-mode-p hpath:shell-modes)
+							     hpath:shell-comment-pattern)
 							    ((derived-mode-p 'texinfo-mode)
 							     hpath:texinfo-section-pattern)
-							    ((or prog-mode (null (hypb:buffer-file-name))
-								 (apply #'derived-mode-p '(fundamental-mode text-mode)))
-							     "%s")
+							    (prog-mode
+							     (concat "^\\(" (regexp-quote comment-start) "\\)*" "[ \t]*%s"))
+							    ;; ((or (null (hypb:buffer-file-name))
+                                                            ;;     (apply #'derived-mode-p '(fundamental-mode text-mode)))
+                                                            ;; "^%s")
 							    (t hpath:outline-section-pattern))
 						      (regexp-quote anchor-name)))
 				    (referent-leading-spaces-regexp

diff --git a/man/hy-package.el b/man/hy-package.el
@@ -0,0 +1,86 @@
+;;; ************************************************************************
+;;; Requirements
+;;; ************************************************************************
+
+(require 'package)
+
+;;; ************************************************************************
+;;; Section 1: package.el setup
+;;; ************************************************************************
+
+;;; ========================================================================
+;;; NOTE: This section is only if you have not yet setup the package.el
+;;;       package manager.  If you have, ignore this and skip to "#Section 2"
+;;;       for the Hyperbole `use-package' recipe.
+;;; ========================================================================
+
+;; Step 1: Add the function definition below near the top of your
+;; "~/.emacs" or "~/.emacs.d/early-init.el" file.
+
+;; Step 2: Add a call to the function below its definition:
+;;         (setup-package)
+
+(defun setup-package ()
+  (require 'package)
+  (setq package-enable-at-startup nil) ;; Prevent double loading of libraries
+  (add-to-list 'package-archives
+	       ;; Leave only one of the following two lines uncommented
+	       '("elpa-devel" . "https://elpa.gnu.org/devel/"))
+	       ;; '("elpa" . "https://elpa.gnu.org/packages/"))
+  (unless (and (boundp 'package--initialized) package--initialized)
+    (package-initialize))
+  ;; To ensure you have the latest index of packages, you'll have to
+  ;; uncomment the next line.  It is commented because retrieving the
+  ;; list is slow.
+  ;; (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
diff --git a/man/hy-straight.el b/man/hy-straight.el
@@ -0,0 +1,64 @@
+;;; ************************************************************************
+;;; Section 1: Straight setup
+;;; ************************************************************************
+
+;;; ========================================================================
+;;; NOTE: This section is only if you have not yet setup the Straight
+;;;       package manager.  If you have, ignore this and skip to "#Section 2"
+;;;       for the Hyperbole `straight-use-package' recipe.
+;;; ========================================================================
+
+;; Step 1: Add the function definition below near the top of your
+;; "~/.emacs" or "~/.emacs.d/early-init.el" file.
+
+;; Step 2: Add a call to the function below its definition:
+;;         (setup-straight)
+
+(defun setup-straight ()
+  (when (< emacs-major-version 28)
+    (error "Hyperbole requires Emacs 28 or above, not %d"
+           emacs-major-version))
+  (defvar bootstrap-version)
+
+  ;; Prevent double loading of libraries
+  (setq package-enable-at-startup nil)
+
+  (let ((bootstrap-file
+         (expand-file-name "straight/repos/straight.el/bootstrap.el"
+                           user-emacs-directory))
+        (bootstrap-version 5))
+    (unless (file-exists-p bootstrap-file)
+      (with-current-buffer
+          (url-retrieve-synchronously
+           "https://raw.githubusercontent.com/raxod502/straight.el/develop/install.el"
+           'silent 'inhibit-cookies)
+        (goto-char (point-max))
+        (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