[elpa] externals/hyperbole 1dc43364e3 1/2: Recognize prog lang klinks only in comments

[ELPA Syncer]

branch: externals/hyperbole
commit 1dc43364e34f580167fc4f8ffcb67a035b5bf5fe
Author: Robert Weiner <rsw@gnu.org>
Commit: Robert Weiner <rsw@gnu.org>

    Recognize prog lang klinks only in comments
    
    Treat pathname klinks as normal pathnames
---
 ChangeLog          | 17 +++++++++++++----
 HY-NEWS            |  5 +++++
 kotl/EXAMPLE.kotl  |  2 +-
 kotl/klink.el      | 31 +++++++++++++++++++------------
 kotl/kotl-mode.el  | 13 ++++++++-----
 man/hyperbole.texi | 48 +++++++++++++++++++++++++++++++++++++++++-------
 6 files changed, 87 insertions(+), 29 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index ae1ebd2b37..7825152f9e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2022-01-29  Bob Weiner  <rsw@gnu.org>
+
+* man/hyperbole.texi (Glossary): Add Klink and Kcell Ref definitions.
+    Update idstamp definition to include 0 root cell.
+
+* kotl/klink.el (link-to-kotl): Fix so does not treat pathname refs as 
Koutlines
+    unless there is a kcell ref within the link.  Also, generalize so when in
+    any programming major mode, klinks are recognized within comments only.
+
 2022-01-25  Bob Weiner  <rsw@gnu.org>
 
 
@@ -1016,13 +1025,13 @@ Delete knode.el and integrate functionality into 
kcell.el.
   kotl/kproperty.el: Merge in "kprop-em.el" and remove "kprop-xe.el".
 
 * kotl/kexport.el (kexport:html-file-klink): Change '\0' back to
-   '\\&' to prevent klink nul char insertion bug.
+    '\\&' to prevent klink nul char insertion bug.
                   (kexport:html): Fix cell label vertical alignment
-   with table row-level valign=text-bottom.
+    with table row-level valign=text-bottom.
 
 * kotl/klink.el (klink:ignore-modes, klink:c-style-modes): Add so
-    can customize which modes in which klinks are ignored to avoid
-    false matches.
+    can customize modes in which klinks are ignored to avoid false
+    matches.
 
 * hsettings.el (hyperbole-web-search-alist): Update 'gitHub'
     name.
diff --git a/HY-NEWS b/HY-NEWS
index b0396d4244..9822fabbfe 100644
--- a/HY-NEWS
+++ b/HY-NEWS
@@ -194,6 +194,11 @@
        kotl-mode:copy-absolute-klink-to-register
        kotl-mode:copy-relative-klink-to-register
 
+    - Klinks Ignored Outside Comments in Programming Language Modes: In
+      previous Hyperbole versions, this was true for C-based language
+      modes.  Now it is true for any programming mode descended from
+      `prog-mode'.
+
     - Prevent Movement Outside Editable Cell Bounds: Add
       kotl-mode:pre-self-insert-command as a pre-command-hook
       to prevent Koutline editing with point in an invalid location,
diff --git a/kotl/EXAMPLE.kotl b/kotl/EXAMPLE.kotl
index cd53f9fcfb..cec876230a 100644
--- a/kotl/EXAMPLE.kotl
+++ b/kotl/EXAMPLE.kotl
@@ -121,7 +121,7 @@
            of the root cell of the tree to move and then double click within
            the body of the root cell of the tree you want it to follow.
 
-      3b9. Tree Text or Region Copying to a Non-Koutline Buffer: 
+      3b9. Tree Text or Region Copying to a Non-Koutline Buffer:
             {C-c M-c} - Copy <tree> text or active region to a non-Koutline 
buffer.
             {C-c C-@} - Copy <tree> text to an outgoing mail message.
            
diff --git a/kotl/klink.el b/kotl/klink.el
index f0a587a0a9..6894fe79c8 100644
--- a/kotl/klink.el
+++ b/kotl/klink.el
@@ -3,7 +3,7 @@
 ;; Author:       Bob Weiner
 ;;
 ;; Orig-Date:    15-Nov-93 at 12:15:16
-;; Last-Mod:     24-Jan-22 at 00:25:18 by Bob Weiner
+;; Last-Mod:     29-Jan-22 at 10:54:02 by Bob Weiner
 ;;
 ;; Copyright (C) 1993-2021  Free Software Foundation, Inc.
 ;; See the "../HY-COPY" file for license information.
@@ -138,6 +138,11 @@ link-end-position, (including delimiters)."
         (if (fboundp 'br-browser-buffer-p)
             (not (br-browser-buffer-p))
           t)
+        ;; If in a programming mode, Klinks can occur only within comments.
+        (if (derived-mode-p 'prog-mode)
+            ;; Next line means point is within a comment
+            (nth 4 (syntax-ppss))
+          t)
         ;; If in a C-based mode, Klinks can only occur within comments.
         (if (and (memq major-mode klink:c-style-modes)
                  (fboundp 'c-within-comment-p))
@@ -146,6 +151,7 @@ link-end-position, (including delimiters)."
                   (and (re-search-backward "//\\|\n" nil t) (looking-at 
"//"))))
           t)
         ;; Don't match to C-style lines like:  #include < path >
+        ;; even if inside a comment.
         (if (memq major-mode klink:c-style-modes)
             (save-excursion
               (beginning-of-line)
@@ -155,6 +161,7 @@ link-end-position, (including delimiters)."
           t)
         (save-excursion
           ;; Don't match Elisp print objects such as #<buffer>
+          ;; even if inside a comment
           (and (search-backward "<" bol t)
                (not (eq (preceding-char) ?#))
                ;; Don't match to \<(explicit)> Hyperbole buttons
@@ -168,11 +175,11 @@ link-end-position, (including delimiters)."
                 (progn (setq path (substring referent 0 (match-beginning 0)))
                        (hpath:is-p path))
               (hpath:is-p referent)))
-        ;; Eliminate matches to e-mail addresses like, <user@domain>.
+        ;; Eliminate matches to e-mail addresses like, <user@domain>
         (not (string-match "[^<> \t\n\r\f][!&@]" referent))
         ;; Eliminate matches to URLs
         (not (string-match "\\`[a-zA-Z]+:" referent))
-        ;; Don't match to <HTML> and </SGML> tags.
+        ;; Don't match to <HTML> and </SGML> type tags
         (not (and (memq major-mode hui-select-markup-modes)
                   ;; Assume , followed by a number is a klink.
                   (not (string-match ",\\s-*[0-9]" referent))
@@ -196,7 +203,7 @@ See documentation for the `link-to-kotl' function for valid 
klink formats."
 
 (defact link-to-kotl (link)
   "Display at the top of another window the referent pointed to by LINK.
-LINK may be of any of the following forms, with or without delimiters:
+LINK may be of any of the following forms:
   < pathname [, cell-ref] >
   < [-!&] pathname >
   < @ cell-ref >
@@ -215,18 +222,18 @@ See documentation for `kcell:ref-to-id' for valid 
cell-ref formats."
     (hact 'link-to-kcell
          nil
          (kcell:ref-to-id (match-string 1 link))))
-   ((string-match
-     (format "\\`<?\\s-*\\([^ 
\t\n\r\f,<>]+\\)\\s-*\\(,\\s-*\\(%s\\)\\)?\\s-*>?\\'"
-            klink:cell-ref-regexp)
-     link)
-    ;; < pathname [, cell-ref] >
+   ((and (string-match
+         (format "\\`<?\\s-*\\([^ 
\t\n\r\f,<>]+\\)\\s-*\\(,\\s-*\\(%s\\)\\)?\\s-*>?\\'"
+                 klink:cell-ref-regexp)
+         link)
+        (match-end 3))
+    ;; < pathname, cell-ref >
     (hact 'link-to-kcell (match-string 1 link)
-         (when (match-end 3)
-           (kcell:ref-to-id (match-string 3 link)))))
+         (kcell:ref-to-id (match-string 3 link))))
    ((string-match
      "\\`<?\\s-*\\(\\([-!&]\\)?\\s-*[^ \t\n\r\f,<>]+\\)\\s-*>?\\'" link)
     ;; < [-!&] pathname >
-    (hpath:find-other-window (match-string 1 link)))
+    (hpath:find (match-string 1 link)))
    (t (error "(link-to-kotl): Invalid link specifier, %s" link))))
 
 ;;; ************************************************************************
diff --git a/kotl/kotl-mode.el b/kotl/kotl-mode.el
index 38d8f53f04..8ae132fe7e 100644
--- a/kotl/kotl-mode.el
+++ b/kotl/kotl-mode.el
@@ -3,7 +3,7 @@
 ;; Author:       Bob Weiner
 ;;
 ;; Orig-Date:    6/30/93
-;; Last-Mod:     25-Jan-22 at 23:46:26 by Bob Weiner
+;; Last-Mod:     29-Jan-22 at 09:58:17 by Bob Weiner
 ;;
 ;; Copyright (C) 1993-2021  Free Software Foundation, Inc.
 ;; See the "../HY-COPY" file for license information.
@@ -367,7 +367,7 @@ With optional prefix arg DELETE-FLAG, delete region."
   "Delete up to the preceding prefix ARG characters.
 Return number of characters deleted.
 Optional KILL-FLAG non-nil means save in kill ring instead of deleting.
-Does not delete across cell boundaries."
+Do not delete across cell boundaries."
   (interactive "*P")
   (when (called-interactively-p 'interactive)
     (when current-prefix-arg
@@ -404,7 +404,7 @@ whitespace at the end of the cell."
   "Delete up to prefix ARG characters following point.
 Return number of characters deleted.
 Optional KILL-FLAG non-nil means save in kill ring instead of deleting.
-Does not delete across cell boundaries."
+Do not delete across cell boundaries."
   (interactive "*P")
   (when (called-interactively-p 'interactive)
     (when current-prefix-arg
@@ -2683,7 +2683,10 @@ included only if INVISIBLE-FLAG is non-nil."
       (kotl-mode:copy-region-to-buffer target-buf start end nil 
invisible-flag))))
 
 (defun kotl-mode:copy-tree-or-region-to-buffer ()
-  "If no usable active region, prompt for and copy a Koutline tree to a 
specified buffer, otherwise, copy the active region."
+  "If no usable active region, prompt for and copy a Koutline tree to a 
specified buffer, otherwise, copy the active region.
+
+Use 0 to copy the whole outline buffer.  Prompt for whether or not
+to expand and include any hidden/invisible text within the copied text."
   (interactive)
   (call-interactively 
    (if (use-region-p)
@@ -3005,7 +3008,7 @@ Optionally, INDENT and region START and END may be given."
 
 (defun kotl-mode:delete-line (&optional pos)
   "Delete and return contents of cell line at point or optional POS as a 
string.
-Does not delete newline at end of line."
+Do not delete newline at end of line."
   (save-excursion
     (when pos
       (goto-char pos))
diff --git a/man/hyperbole.texi b/man/hyperbole.texi
index 505d65264e..c9913a68f4 100644
--- a/man/hyperbole.texi
+++ b/man/hyperbole.texi
@@ -3038,7 +3038,7 @@ If FILE is @samp{nil}, use the current buffer.  If 
CELL-REF is
 @findex actypes link-to-kotl
 @item link-to-kotl
 Display at the top of a window the referent pointed to by LINK.
-LINK may be of any of the following forms, with or without delimiters:
+LINK may be of any of the following forms:
 @example
   < pathname [, cell-ref] >
   < [-!&] pathname >
@@ -5281,8 +5281,12 @@ two customizable variables which disable klink 
recognition in selected major
 modes, @code{klink:ignore-modes} and @code{klink:c-style-modes}.  Add a mode
 to one of these if you find any syntax that improperly registers as a klink.
 
-* kotl/klink.el (klink:ignore-modes, klink:c-style-modes): Add so
-    can customize.
+@code{klink:ignore-modes} is for non-programming modes, as Hyperbole ensures
+that within all programming major modes, klinks are recognized only when point
+is within a comment.
+
+@code{klink:c-style-modes} is rarely needed but is there if Hyperbole ever
+mistakenly recognizes a pattern within a comment as a klink when it isn't.
 
 
 @node Cell Attributes, Koutliner History, Links, Koutliner
@@ -5298,7 +5302,8 @@ has its own attribute list.  Every cell has three 
standard attributes:
 @cindex idstamp attribute
 @item idstamp
 The permanent id of the cell, typically used in cross-file hyperlinks
-that reference the cell.
+that reference the cell, this is a whole number that starts from 0, which
+is always the hidden root cell of the outline tree.
 
 @cindex creator attribute
 @cindex e-mail address
@@ -6752,7 +6757,6 @@ if any emacs-related terms are unfamiliar to you.
 @table @b
 
 @item Action
-@itemx Button Action
 An executable behavior associated with a Hyperbole button.  @dfn{Links}
 are a specific class of actions which display existing entities, such as
 files. See also @b{Action Type}.
@@ -7039,6 +7043,35 @@ A series of one or more Emacs key sequences delimited by 
braces that
 Hyperbole processes when activated as an implicit button, as if the
 keys were typed in by the user.
 
+@item Kcell Ref
+A reference to a Koutline cell.  Such a reference may be:
+
+  12       - a whole number representing a permanent idstamp
+
+or any of the following string forms:
+
+  1 or 1b   - relative id, augment style
+  1.2       - relative id, legal style
+  012       - permanent idstamp
+  1a=012    - both relative and permanent ids (in that order) separated by =
+  |viewspec - a viewspec setting, rather than a cell reference
+
+Optionally, any of these id forms (or the relative form) may be followed by
+zero or more whitespace characters, a | and some view specification
+characters.  @xref{View Specs}
+
+@item Klink
+An angle bracket, <>, delimited implicit button type that displays a
+koutline cell referent at the top of a window.  The link may be of any
+of the following forms:
+@example
+  < pathname [, kcell-ref] >
+  < [-!&] pathname >
+  < @@ kcell-ref >
+@end example
+
+See the above definition of @italic{Kcell Ref} for kcell-ref formats.
+
 @item Koutline
 A hierarchically ordered grouping of cells which may be stored as a file
 and viewed and edited as an outline.
@@ -8183,6 +8216,7 @@ Leave point at the start of the root cell of the new tree.
 @item kotl-mode:copy-tree-or-region-to-buffer  @bkbd{C-c M-c}
 If no usable active region, prompt for and copy a Koutline tree to a
 specified buffer, otherwise, copy the active region.
+
 Use 0 to copy the whole outline buffer.  Prompt for whether or not
 to expand and include any hidden/invisible text within the copied text.
 
@@ -8196,7 +8230,7 @@ With optional prefix arg DELETE-FLAG, delete region.
 Delete up to the preceding prefix ARG characters.
 Return number of characters deleted.
 Optional KILL-FLAG non-nil means save in kill ring instead of deleting.
-Does not delete across cell boundaries.
+Do not delete across cell boundaries.
 
 @findex kotl-mode:delete-blank-lines
 @item kotl-mode:delete-blank-lines  @bkbd{C-x C-o}
@@ -8212,7 +8246,7 @@ whitespace at the end of the cell.
 Delete up to prefix ARG characters following point.
 Return number of characters deleted.
 Optional KILL-FLAG non-nil means save in kill ring instead of deleting.
-Does not delete across cell boundaries.
+Do not delete across cell boundaries.
 
 @findex kotl-mode:delete-indentation
 @item kotl-mode:delete-indentation  @bkbd{M-^}