[elpa] externals/hyperbole 193e1b0e92 14/28: Merge branch 'master' into rsw

[ELPA Syncer]

branch: externals/hyperbole
commit 193e1b0e92548d426c365ee0d9359c46508c1d49
Merge: 1d2f6cdf76 7decf14c5c
Author: Bob Weiner <rsw@gnu.org>
Commit: Bob Weiner <rsw@gnu.org>

    Merge branch 'master' into rsw
---
 ChangeLog                   |  39 +++++
 hbdata.el                   |  95 +++++++-----
 hbut.el                     |   4 +-
 hpath.el                    |   4 +-
 hui-select.el               |  35 ++++-
 hversion.el                 |   4 +-
 interactive-demos/HYPERBOLE | 361 ++++++++++++++++++++++++++++++++++++++++++++
 interactive-demos/HYROLO    | 112 ++++++++++++++
 test/hui-tests.el           | 113 ++++++++++++++
 9 files changed, 720 insertions(+), 47 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 7a8aff22f4..fa85502864 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2023-10-30  Mats Lidell  <matsl@gnu.org>
+
+* hversion.el (hyperb:mouse-buttons):
+  hpath.el (hpath:get-external-display-alist): Add mac as possible
+    window-system on Mac OS.
+
 2023-10-29  Bob Weiner  <rsw@gnu.org>
 
 * hpath.el (hpath:find):
@@ -57,6 +63,30 @@
   kotl/kotl-mode.el (kotl-mode:goto-cell-ref): Add for use in kotl anchored
     pathname refs and in 'link-to-kcell' actype.
 
+2023-10-25  Mats Lidell  <matsl@gnu.org>
+
+* test/hui-tests.el (hui--ibut-link-directly-to-file)
+    (hui--ibut-link-directly-to-dired)
+    (hui--ibut-link-directly-with-label): Test cases for
+    ibut-link-directly
+
+2023-10-22  Mats Lidell  <matsl@gnu.org>
+
+* hui-select.el (hui-java-defun-prompt-regexp): Add prompt regexp as
+    separate defconst. Update provided by Alan Mackenzie. Thanks.
+    (hui-select-initialize): Use new java regexp.
+
+* test/hui-tests.el (hui-gbut-number-of-gebuts-from-mail-mode): Remove
+    expected to fail.
+
+* hbut.el (gbut:ebut-key-list): Use hbdata:to-entry-in-file for global
+    button file data.
+
+* hbdata.el (hbdata:is-but-data-stored-in-buffer)
+    (hbdata:to-entry-in-buffer, hbdata:to-entry-in-file): Refactor into
+    three methods to separate out button data stored in a file.
+    (hbdata:to-entry-buf): Use new methods.
+
 2023-10-22  Bob Weiner  <rsw@gnu.org>
 
 * hbut.el (gbut:save-buffer): Add function to use after global button file is
@@ -79,6 +109,15 @@
     rather than using its elisp backend.  Remove that code.
                 (tags-fix): Remove optional load of this very old file.
 
+2023-10-11  Mats Lidell  <matsl@gnu.org>
+
+* test/hui-tests.el (hui-gbut-number-of-gbuts-with-no-buttons)
+    (hui-gbut-number-of-gibuts-when-one-button)
+    (hui-gbut-number-of-gebuts-when-one-button)
+    (hui-gbut-number-of-gibuts-from-mail-mode)
+    (hui-gbut-number-of-gebuts-from-mail-mode): Verify number of global
+    ibuts and ebuts.
+
 2023-10-09  Mats Lidell  <matsl@gnu.org>
 
 * test/kotl-mode-tests.el (kotl-mode-kill-contents)
diff --git a/hbdata.el b/hbdata.el
index f723c07f0e..884ba82579 100644
--- a/hbdata.el
+++ b/hbdata.el
@@ -3,7 +3,7 @@
 ;; Author:       Bob Weiner
 ;;
 ;; Orig-Date:     2-Apr-91
-;; Last-Mod:      3-Oct-23 at 22:48:03 by Mats Lidell
+;; Last-Mod:     22-Oct-23 at 14:42:47 by Mats Lidell
 ;;
 ;; SPDX-License-Identifier: GPL-3.0-or-later
 ;;
@@ -443,7 +443,31 @@ Return value of evaluation when a matching entry is found 
or nil."
          (when end-func (funcall end-func)))))
     rtn))
 
-(defun hbdata:to-entry-buf (key-src &optional directory create)
+(defun hbdata:is-but-data-stored-in-buffer (key-src)
+  "True if we store but-data in the buffer rather than in a file."
+  ;; Drafts of mail messages now have a buffer-file-name since they
+  ;; are temporarily saved to a file until sent.  But but-data still
+  ;; should be stored in the mail buffer itself, so check explicitly
+  ;; whether is a mail composition buffer in such cases.
+  (or (hmail:mode-is-p)
+      (and (get-buffer key-src)
+           (set-buffer key-src)
+          (not buffer-file-name))))
+
+(defun hbdata:to-entry-in-buffer (create)
+  "Move point to end of line in but data in current buffer.
+Note: Button buffer has no file attached.  With optional CREATE,
+if no such line exists, insert a new entry at the beginning of
+the hbdata (which is created if necessary).  Return t."
+  (if (hmail:hbdata-to-p) ;; Might change the buffer
+      (setq buffer-read-only nil)
+    (when create
+      (setq buffer-read-only nil)
+      (insert "\n" hmail:hbdata-sep "\n")))
+  (backward-char 1)
+  t)
+
+(defun hbdata:to-entry-in-file (key-src &optional directory create)
   "Move point to end of line in but data buffer matching KEY-SRC.
 Use hbdata file in KEY-SRC's directory, or optional DIRECTORY or if nil, use
 `default-directory'.
@@ -452,44 +476,39 @@ beginning of the hbdata file (which is created if 
necessary).
 Return non-nil if KEY-SRC is found or created, else nil."
   (let (rtn
        ln-dir)
-    ;; Drafts of mail messages now have a buffer-file-name since they
-    ;; are temporarily saved to a file until sent.  But but-data still
-    ;; should be stored in the mail buffer itself, so check explicitly
-    ;; whether is a mail composition buffer in such cases.
-    (if (or (hmail:mode-is-p)
-           (and (get-buffer key-src)
-                (set-buffer key-src)
-                (not buffer-file-name)))
-       ;; Button buffer has no file attached
-       (progn (if (hmail:hbdata-to-p) ;; Might change the buffer
-                  (setq buffer-read-only nil)
-                (when create
-                  (setq buffer-read-only nil)
-                  (insert "\n" hmail:hbdata-sep "\n")))
-              (backward-char 1)
-              (setq rtn t))
-      (setq directory (or (file-name-directory key-src) directory))
-      (let ((ln-file) (link-p key-src))
-       (while (setq link-p (file-symlink-p link-p))
-         (setq ln-file link-p))
-       (if ln-file
-           (setq ln-dir (file-name-directory ln-file)
-                 key-src (file-name-nondirectory ln-file))
-         (setq key-src (file-name-nondirectory key-src))))
-      (when (or (hbdata:to-hbdata-buffer directory create)
-               (and ln-dir (hbdata:to-hbdata-buffer ln-dir nil)
-                    (setq create nil
-                          directory ln-dir)))
-       (goto-char 1)
-       (cond ((search-forward (concat "\^L\n\"" key-src "\"")
-                              nil t)
-              (setq rtn t))
-             (create
-              (setq rtn t)
-              (insert "\^L\n\"" key-src "\"\n")
-              (backward-char 1)))))
+    (setq directory (or (file-name-directory key-src) directory))
+    (let ((ln-file) (link-p key-src))
+      (while (setq link-p (file-symlink-p link-p))
+       (setq ln-file link-p))
+      (if ln-file
+         (setq ln-dir (file-name-directory ln-file)
+               key-src (file-name-nondirectory ln-file))
+       (setq key-src (file-name-nondirectory key-src))))
+    (when (or (hbdata:to-hbdata-buffer directory create)
+             (and ln-dir (hbdata:to-hbdata-buffer ln-dir nil)
+                  (setq create nil
+                        directory ln-dir)))
+      (goto-char 1)
+      (cond ((search-forward (concat "\^L\n\"" key-src "\"")
+                            nil t)
+            (setq rtn t))
+           (create
+            (setq rtn t)
+            (insert "\^L\n\"" key-src "\"\n")
+            (backward-char 1))))
     rtn))
 
+(defun hbdata:to-entry-buf (key-src &optional directory create)
+  "Move point to end of line in but data buffer matching KEY-SRC.
+Use hbdata file in KEY-SRC's directory, or optional DIRECTORY or if nil, use
+`default-directory'.
+With optional CREATE, if no such line exists, insert a new file entry at the
+beginning of the hbdata file (which is created if necessary).
+Return non-nil if KEY-SRC is found or created, else nil."
+    (if (hbdata:is-but-data-stored-in-buffer key-src)
+        (hbdata:to-entry-in-buffer create)
+      (hbdata:to-entry-in-file key-src directory create)))
+
 (defun hbdata:to-hbdata-buffer (dir &optional create)
   "Read in the file containing DIR's button data, if any, and return buffer.
 If it does not exist and optional CREATE is non-nil, create a new
diff --git a/hbut.el b/hbut.el
index 68ede303c4..670159760e 100644
--- a/hbut.el
+++ b/hbut.el
@@ -3,7 +3,7 @@
 ;; Author:       Bob Weiner
 ;;
 ;; Orig-Date:    18-Sep-91 at 02:57:09
-;; Last-Mod:     22-Oct-23 at 08:42:11 by Bob Weiner
+;; Last-Mod:     30-Oct-23 at 22:13:56 by Bob Weiner
 ;;
 ;; SPDX-License-Identifier: GPL-3.0-or-later
 ;;
@@ -838,7 +838,7 @@ Return the symbol for the button when found, else nil."
   "Return a list of explicit button label keys from the global button file."
   (save-excursion
     (save-restriction
-      (when (hbdata:to-entry-buf (gbut:file))
+      (when (hbdata:to-entry-in-file (gbut:file))
        (let (gbuts)
          (save-restriction
            (narrow-to-region (point) (if (search-forward "\f" nil t)
diff --git a/hpath.el b/hpath.el
index b176e705f9..73d173c973 100644
--- a/hpath.el
+++ b/hpath.el
@@ -3,7 +3,7 @@
 ;; Author:       Bob Weiner
 ;;
 ;; Orig-Date:     1-Nov-91 at 00:44:23
-;; Last-Mod:     29-Oct-23 at 23:45:02 by Bob Weiner
+;; Last-Mod:     30-Oct-23 at 22:13:11 by Bob Weiner
 ;;
 ;; SPDX-License-Identifier: GPL-3.0-or-later
 ;;
@@ -1677,7 +1677,7 @@ programs, such as a pdf reader.  The cdr of each element 
may be:
   or a function of one filename argument.
 See also `hpath:internal-display-alist' for internal,
 `window-system' independent display settings."
-  (cond ((memq window-system '(dps ns))
+  (cond ((memq window-system '(mac dps ns))
         hpath:external-display-alist-macos)
        (hyperb:microsoft-os-p
         hpath:external-display-alist-mswindows)
diff --git a/hui-select.el b/hui-select.el
index 902b04c8bf..35d0b218d9 100644
--- a/hui-select.el
+++ b/hui-select.el
@@ -3,7 +3,7 @@
 ;; Author:       Bob Weiner
 ;;
 ;; Orig-Date:    19-Oct-96 at 02:25:27
-;; Last-Mod:      3-Oct-23 at 22:59:57 by Mats Lidell
+;; Last-Mod:     22-Oct-23 at 17:26:49 by Mats Lidell
 ;;
 ;; SPDX-License-Identifier: GPL-3.0-or-later
 ;;
@@ -203,6 +203,36 @@ Used to include a final line when marking indented code.")
   :type 'boolean
   :group 'hyperbole-commands)
 
+(defconst hui-java-defun-prompt-regexp
+  (let* ((space* "[ \t\n\r\f]*")
+         (space+ "[ \t\n\r\f]+")
+         (modifier*
+          (concat "\\(?:"
+                  (regexp-opt '("abstract" "const" "default" "final" "native"
+                                "private" "protected" "public" "static"
+                                "strictfp" "synchronized" "threadsafe"
+                                "transient" "volatile")
+                              'words)   ; Compatible with XEmacs
+                  space+ "\\)*"))
+         (ids-with-dots "[_$a-zA-Z][_$.a-zA-Z0-9]*")
+         (ids-with-dot-\[\] "[[_$a-zA-Z][][_$.a-zA-Z0-9]*")
+         (paren-exp "([^);{}]*)")
+         (generic-exp "<[^(){};]*>"))
+    (concat "^[ \t]*"
+            modifier*
+            "\\(?:" generic-exp space* "\\)?"
+            ids-with-dot-\[\] space+                ; first part of type
+            "\\(?:" ids-with-dot-\[\] space+ "\\)?" ; optional second part of 
type.
+            "\\(?:[_a-zA-Z][^][ \t:;.,{}()=<>]*"    ; defun name
+                "\\|" ids-with-dots
+            "\\)" space*
+            paren-exp
+            "\\(?:" space* "]\\)*"      ; What's this for?
+            "\\(?:" space* "\\<throws\\>" space* ids-with-dot-\[\]
+                  "\\(?:," space* ids-with-dot-\[\] "\\)*"
+            "\\)?"
+            space*)))
+
 (defvar hui-select-previous nil)
 (defvar hui-select-prior-point nil)
 (defvar hui-select-prior-buffer nil)
@@ -362,8 +392,7 @@ Also, add language-specific syntax setups to aid in thing 
selection."
   ;; opening or closing brace.  This is all necessary since some
   ;; programmers don't put their function braces in the first column.
   (var:add-and-run-hook 'java-mode-hook (lambda ()
-                                         (setq defun-prompt-regexp
-                                               "^[ 
\t]*\\(\\(\\(public\\|protected\\|private\\|const\\|abstract\\|synchronized\\|final\\|static\\|threadsafe\\|transient\\|native\\|volatile\\)\\s-+\\)*\\(\\(\\([[a-zA-Z][][_$.a-zA-Z0-9]*[][_$.a-zA-Z0-9]+\\|[[a-zA-Z]\\)\\s-*\\)\\s-+\\)\\)?\\(\\([[a-zA-Z][][_$.a-zA-Z0-9]*\\s-+\\)\\s-*\\)?\\([_a-zA-Z][^][
 \t:;.,{}()=]*\\|\\([_$a-zA-Z][_$.a-zA-Z0-9]*\\)\\)\\s-*\\(([^);{}]*)\\)?\\([] 
\t]*\\)\\(\\s-*\\<throws\\>\\s-*\\(\\([_$a-zA-Z][_$.a-zA-Z0-9]*\\)[, 
\t\n\r\f]*\\)+\\)?\\s-*")))
+                                         (setq defun-prompt-regexp 
hui-java-defun-prompt-regexp)))
   (var:add-and-run-hook 'c++-mode-hook (lambda ()
                                         (setq defun-prompt-regexp
                                               "^[ 
\t]*\\(template\\s-*<[^>;.{}]+>\\s-*\\)?\\(\\(\\(auto\\|const\\|explicit\\|extern\\s-+\"[^\"]+\"\\|extern\\|friend\\|inline\\|mutable\\|overload\\|register\\|static\\|typedef\\|virtual\\)\\s-+\\)*\\(\\([[<a-zA-Z][]_a-zA-Z0-9]*\\(::[]_a-zA-Z0-9]+\\)?\\s-*<[_<>a-zA-Z0-9
 
,]+>\\s-*[*&]*\\|[[<a-zA-Z][]_<>a-zA-Z0-9]*\\(::[[<a-zA-Z][]_<>a-zA-Z0-9]+\\)?\\s-*[*&]*\\)[*&
 
\t\n\r]+\\)\\)?\\(\\(::\\|[[<a-zA-Z][]_a-zA-Z0-9]*\\s-*<[^>;{}]+>\\s-*[*&]*::\\|[[<a-zA-Z][]_~<>a-zA-Z0-9]*\\s-*
 [...]
diff --git a/hversion.el b/hversion.el
index f7a9ea6778..8ecbafebf2 100644
--- a/hversion.el
+++ b/hversion.el
@@ -4,7 +4,7 @@
 ;; Maintainer:   Bob Weiner, Mats Lidell
 ;;
 ;; Orig-Date:     1-Jan-94
-;; Last-Mod:      3-Oct-23 at 23:31:30 by Mats Lidell
+;; Last-Mod:     30-Oct-23 at 23:49:10 by Mats Lidell
 ;;
 ;; SPDX-License-Identifier: GPL-3.0-or-later
 ;;
@@ -39,7 +39,7 @@
 
 (defvar hyperb:mouse-buttons
   (if (or (and hyperb:microsoft-os-p (not (memq window-system '(w32 w64 x))))
-         (memq window-system '(ns dps)))
+         (memq window-system '(mac ns dps)))
       2 3)
   "Number of live buttons available on the mouse.
 Override this if the system-computed default is incorrect for
diff --git a/interactive-demos/HYPERBOLE b/interactive-demos/HYPERBOLE
new file mode 100644
index 0000000000..baaa88ffec
--- /dev/null
+++ b/interactive-demos/HYPERBOLE
@@ -0,0 +1,361 @@
+* GNU Hyperbole Interactive Demo
+
+    Table of Contents
+    ------------------
+    * Introduction
+    * Implicit Buttons
+    * Explicit Buttons
+    * Button Files
+    * Global Buttons
+
+* Introduction
+
+Welcome to GNU Hyperbole.  Hyperbole will super-charge your GNU Emacs
+experience, allowing you to work faster, utilize fewer key bindings, recall
+more information and link it all together by learning just a few concepts and
+keys.  Invest an hour learning Hyperbole now and speed your daily information
+management for years to come.
+
+If you simply want to know what Hyperbole is, see the file 
"${hyperb:dir}/HY-ABOUT".
+Hyperbole displays that file when you press {C-h h d a}.  Hyperbole assumes
+you know how to use Emacs.  Otherwise, run the Emacs tutorial by pressing
+{C-h t} first.
+
+You should be looking at this file within Emacs and Hyperbole should already
+be installed within your copy of Emacs.  To be sure, press 'C-h h' and you
+should see the Hyperbole menu in your minibuffer window at the bottom of
+your current Emacs frame.  Press 'q' to quit out of this menu and we can
+begin.  If Hyperbole is not installed, see the "${hyperb:dir}/INSTALL" file, 
in the
+same directory as this file, for instructions on installing it.
+
+This demo illustrates simple usage of the basic Hyperbole button-action types
+and shows how Hyperbole can support a style of self-documenting, interactive
+files.  See the glossary in the Hyperbole Manual, "(hyperbole)Glossary", if
+terms used here are unfamiliar to you.
+
+Once you read the next section on "#Smart Keys", you can then browse any
+other sections individually as you like.  Many people initially use Hyperbole
+for its "#Implicit Buttons" capabilities, so you may want to jump to that
+section.
+
+* Implicit Buttons
+
+** Paths
+Hyperbole can recognize a wide variety of links embedded within Emacs
+buffers, turning your unmodified text files into hypertexts via its
+incredibly powerful feature: implicit buttons. An example of an implicit
+button would be a path, such as ~/.emacs you can also put parenthesis around
+the path, to make it a bit more clear, like "~/.emacs".
+
+If you put your cursor over the above path and hit {M-RET} (also called
+a Smart Key in Hyperbole), you will see that it should take you to your
+.emacs file. Nothing needs to be added and nothing changes on your end,
+your just simply put in a valid path and it will take you there. Let's
+try another example to open up your Music directory with ~/Music/. Again,
+just hit {M-RET} on the path and it'll open up a buffer with the contents
+of the directory.
+
+One can also link to a specific line in a file such as ~/.emacs:10 which
+will take you to line 10. You can specify columns as well with ~/.emacs:10:9
+The numbers just need to be split by a colon.
+
+Now that you have a basic understanding on how the path implicit buttons work,
+make one that takes you to your favorite project.
+
+** Labels
+Implicit buttons can also have labels attached to them, such as the one
+below:
+
+<[My Emacs Files]>: "~/.emacs.d"
+
+You see that the label is delimited by '<[' and ']>'.  It must be at least 2
+characters in length and can be followed by any number of :, - or = characters,
+including none, and then a whitespace character.  You can activate the button
+either from its label or its pattern text.  With point on an implicit button,
+you can label it by using {C-h h i l}.
+
+Now that you know how labeling works, let's take the path you made to your 
favorite,
+project and add a label to it.
+
+** Key Series Buttons
+Another type of implicit but is key sequences which are delimited by curly
+braces, such as {M-X}. When using your Smart Key (M-RET) on the key sequence
+it will act as if you hit the keys on your keyboard.
+
+Hyperbole's minibuffer menu items may also be activated as a key series. For
+example, {C-h h d i} displays the online browsable Info version of the 
Hyperbole
+Manual.
+
+Another example is you can see your global buttons (of which we haven't 
created)
+with {C-h h g a}.
+
+We can see the buttons that have labels with the command {C-h h a}, and by 
using
+the Smart Key on there, you should see the label you created above.
+
+** URL Buttons
+URLs are another type of implicit button. Setting this up is as simple as 
typing
+in a URL such as http://www.gnu.org and use the Smart Key on the URL. Full,
+abbreviated, and FTP URLs are all recognized with or without quotes.
+
+** Email Addresses
+An Action Key press on an email address of any common domain name will
+start composing an email message to that name within Emacs.  This is
+limited to major modes listed in the variable, mail-address-mode-list.
+If that variable is nil, then email addresses are active in every
+buffer.
+
+Try composing a message to <hyperbole-users@gnu.org> and tell us what
+you think of Hyperbole.  Even better, a press of or on {C-h h m c}
+composes mail to the list that includes your system information.
+
+** Action Buttons
+Action Buttons are a very exciting feature in Hyperbole as they give a 
universal
+syntax for creating implicit buttons known as Action Buttons. These buttons 
execute
+any existing action types or Emacs Lisp functions. They are delimited by angle
+brackets, < >, and come in three types:
+
+    1. Action type invocations - these begin with an action type name (found by
+       running {C-h h d t a RET}) and are follow by any needed arguments to 
form the
+       action such as:
+
+           <link-to-file-line "${hyperb:dir}/hact.el" 41>
+
+    2. Function calls - these are similar to action type invocations but begin
+       with an Elisp function name rather than an action type name. These may 
contain
+       any number of levels of embedded List s-expressions, such as:
+
+                  <find-file-other-window (expand-file-name 
"kotl/EXAMPLE.kotl" hyperb:dir)>
+
+    3. Variable displays - these consist of an Elisp variable name on and 
display
+       a message with the variable name and value, such as:
+
+           <fill-column>
+
+       If there is a function binding with the same name as the variable you 
wish to
+       display, to prevent interpretation as a function call action button, 
precede
+       the name with a '$' such as:
+
+           <$hbut:max-len>
+
+** Defining New Action Button Types
+As useful as the current action keys are, sometimes you need something that 
you can define
+yourself, and does exactly what you want. For this you just need to understand 
basic
+regular expression-based pattern replacement, which isn't as bad as it sounds.
+
+
+In your ~/.emacs file, add a line in the form:
+
+
+    (defal TYPE LINK-EXPR &optional DOC)
+
+    
+where:
+
+    TYPE is the name of the new type you want to create;
+
+    LINK-EXPR in a regular expression containing a %s replacement string
+    into which Hyperbole will substitute the button text following the TYPE
+    from each button activated of this type. Alternatively, LINK-EXPR maybe be
+    the name of a function of one argument, the button text sans the function 
name;
+
+    Hyperbole automatically creates a doc string for the type but you can
+    override this by providing an optional DOC string.
+
+When the button is activated, the text following the type is substituted into
+LINK-EXPR. After which, the button is activated in one of 4 ways:
+    (1) brace-delimited key series;
+    (2) URL/web link;
+    (3) path (possibly with trailing colon-separated line and column numbers);
+    (4) a function or action type of one argument, the button text sans the 
function name.
+
+    
+That's kind of a lot to take in so here is an example:
+
+
+(defal elsearch "https://www.google.com/search?q=%s+filetype:el"; "Find Elisp 
libraries via a Google file type search")
+
+
+<elsearch burly>
+
+
+Or for those of us who prefer DuckDuckGo,
+
+
+(defal ddgsearch "https://www.duckduckgo.com/?q=%s"; "DuckDuckGo search")
+
+
+<ddgsearch searching>
+
+
+Where in both scenario's you can replace the second word with whatever you're 
looking for.
+It even works with multi-word arguments such as:
+
+
+<ddgsearch searching movie>
+
+
+Feel free to fill out the below example for a DDG search:
+
+
+<ddgsearch  insert term/s here>
+
+
+For more advanced regular expression-based link type creation, see 'defil' 
expression in
+"(hypberbole)Implicit Button Link Types". For any type of implicit button type 
creation using
+ELisp, see 'defib' in "(hyperbole)Programmatic Implicit Button Types".
+
+** GitHub/GitLab (Remote) References
+For software developers who use GitHub/Lab for publishing and version control,
+GitHub/Lab links are very straight forward.
+
+    github#/rswgnu/hyperbole
+    gitlab#/mobian1/callaudiod
+    
+which can also work with gh and gl shortcut for GitHub and GitLab respectively.
+
+    gh#/rswgnu/hyperbole
+    gl#/mobian1/callaudiod
+
+Try adding in a GitHub/Lab project of your below:
+
+    gh#/<name>/<project>
+    gl#/<name>/<project>    
+    
+There are a plethora of custom commands for both GitHub, and GitLab which can 
be found in
+the Hyperbole DEMO file (~/.emacs.d/elpa/hyperbole-8.0.0/DEMO).
+
+* Explicit Buttons
+Now that we've covered the implicit buttons, let's move on to explicit 
buttons. These are
+buttons that you can create, and embed within documents. Explicit buttons have 
a very
+distinct look which makes them easier to find in your documents, <(fake 
button)>. Though
+they are quickly recognizable, they are also discrete enough that they aren't 
distracting.
+Explicit buttons can link to local, and remote files or to a section within a 
document;
+they can calculate things or query databases. Unlike an HTML hyperbutton, 
there is no markup
+language to learn or specific document format required. You can create an 
explicit button with
+simple keyboard presses or mouse drags from one window to another.
+
+
+As an example, this button price the # <(factorial)> of 5 in the minibuffer 
when activated.
+This works by have the button run =eval-elisp= in the background, and 
essentially running
+=5*4*3*2*1=.
+
+Hyperbole is pretty forgiving when it comes to the formatting of explicit 
buttons. As an
+example, the buttons below all do the same thing when activated.
+
+ <(factorial button)>
+
+ <(factorial         button)>
+
+  Pam>  <(factorial
+  Pam>    button)>
+
+  ;; <(factorial
+  ;;   button)>
+
+  /* <( factorial      */
+  /*    button )> */
+
+
+** Creating and Editing Explicit Buttons
+Creating explicit buttons is fun, and easy. You can always try them out
+immediately after creating them. There are two ways to create explicit buttons:
+by dragging them between windows with the Action Mouse Key or by using 
Hyperbole menus.
+
+
+*** Creation via Dragging
+
+An efficient way to create an explicit button interactively is
+to use the Action Mouse Key to drag from a button source window to a
+window showing its link referent.  More specifically, you should split
+your current Emacs frame into two windows: one which contains the
+point at which you want a button to be inserted and another which
+shows the point to which you want to link, the referent.  Depress the
+Action Mouse Key at the source point for the button (anywhere but on a
+paired delimiter such as double quotes or parentheses).  Then drag to
+the other window and release the Action Mouse Key at the start point
+of the link referent.  The process becomes quite simple with a little
+practice.
+
+*** Creation via Ace Window
+
+For the fastest link button creation, use the Emacs package
+'ace-window' (see "(hyperbole)Keyboard Drags" for setup).  Once this
+is configured, then {M-o w <window id>} may be used to quickly create
+an explicit link button in the selected window that links to any other
+window chosen via the Ace Window.
+
+*** Creation via Menu
+
+You may instead use the Hyperbole menus to create explicit buttons.  First,
+mark/highlight a short region of text in any fashion allowed by Emacs and
+then select the Hyperbole menu item sequence, Ebut/Create {C-h h e c}.  You
+will be prompted for the button's label with the marked region as the
+default.  If you accept the default and enter the rest of the information you
+are prompted for, the button will be created within the current buffer and
+Hyperbole will surround the marked region with explicit button delimiters to
+indicate success.
+
+If you do not mark a region before invoking the button create command, you
+will be prompted for both a label and a target buffer for the button and the
+delimited label text will be inserted into the target buffer after a
+successful button creation.
+
+
+
+Now that we have a few ways of making a button, lets try it. I prefer to use 
the creation
+via the menu {C-h h e c}. Try making one over this text "Test1", and a second 
button
+that you create the words for yourself. A good example would be to your 
current project
+you are working on or your .emacs file. Or you can create a button that 
utilizes the
+shell to launch something, like the # <(Firefox browser)>.
+
+* Button Files
+Button files are a useful way of keeping track of your buttons. Hyperbole
+creates a button file by default which is "${hbmap:dir-user}/HYPB" which can
+be accessed with {C-h h d p}. Per-directory button files are stored in their
+respective directories, and are also named "HYPB". You can access your current
+directory button file with {C-h h b d}.
+
+
+Head to your default button file "${hbmap:dir-user}/HYPB", and try creating a
+few explicit buttons. Use this as a place to setup anything you want to do, or
+get to quickly.
+
+* Global Buttons
+Global buttons are labeled Hyperbole buttons in your personal button
+file. All global buttons are activated by name with completion provided,
+independent of which buffers are on-screen. Global buttons can be either
+explicit or implicit buttons.
+
+
+The Hyperbole Gbut menu, {C-h h g}, creates, modifies and activates
+global buttons by name.  Each button created by this menu is stored as
+an explicit button near the end of your personal button file.  But any
+buttons you create in other ways within this file also become global
+buttons, for example labeled/named implicit buttons.
+
+
+Since implicit buttons can be labeled with a name and placed in the
+global button file for invocation by name, you can give short names to
+any such buttons you want to invoke frequently.  For example, to
+create a labeled implicit global button that displays a personal todo
+file maintained with the Koutliner, activate the following key series
+by pressing M-RET within the first few characters:
+
+
+          {C-h h b p M-> <[td]>: <find-file "~/Todos.kotl"> RET}
+
+         
+From then on, you can jump to your todos with:
+
+
+          {C-h h g a td RET}
+
+         
+Call your global buttons with {C-h h g a}, those buttons should look familiar.
+That's because they are the explicit buttons you created in the previous 
section
+in your default button file. When you get used to using this you will find that
+essentially anywhere you want to go, online or offline, is a global button 
call away.
+
+ /* Local Variables:  */
+ /* mode: Text        */
+ /* End:              */
diff --git a/interactive-demos/HYROLO b/interactive-demos/HYROLO
new file mode 100644
index 0000000000..3b253f2f3d
--- /dev/null
+++ b/interactive-demos/HYROLO
@@ -0,0 +1,112 @@
+* HyRolo
+
+Think of HyRolo as a contact book, it keeps your contacts in an easy to read
+file with plenty of built in functions for things such as find, adding, and
+editing entries, to name a few.
+
+
+Let's start by creating our own entry with {C-h h r a}, which will prompt you
+for a name. Feel free to put anything in there. After you put in a name it will
+take you to ~/.rolo.otl, where you can see the entry you just created. Each 
entry
+must begin with at least one "*" at the beginning of their line. Entries are
+usually arranged in a hierarchy, where each child's line starts with one more
+"*" than the previous one. After these delimiters, the entries are free-form 
text.
+Ideally you want to put entries in "lastname, firstname" so that HyRolo will
+automatically alphabetize them. That being said, if you prefer "firstname, 
lastname"
+then alphabetizing them is a simple command away, # <(hyrolo-sort)>. Also note
+that when each contact is added, a date is automatically added underneath.
+
+
+Your rolo file is probably looking something like
+* Name
+      <date>
+
+ which is fairly basic. Let's go ahead and add a header to that to tell us that
+ this is a person HyRolo file, as apposed to a professional one. This is done
+ by adding in at least three equal signs above, and below the name you
+ want for the HyRolo. It should look something like this
+ 
+=====================
+Personal
+=====================
+* Name
+      <date>
+
+** String Searches
+Now let's say that you either don't want to add in a header or don't like the
+idea of maintaining multiple HyRolo files for Personal, Professional, etc. 
Good news
+is, we can just add a small tag to each contact (personal, professional, etc),
+and use string searches to find them. 
+
+
+There are a few ways to do string searching in HyRolo, and a few commands you
+can use. The first being the hyrolo-grep command which will find all entries
+containing a regular expression. Try this with the current date, and you will
+see that it picks up the line(s) with the current date, but nothing else. That
+being said, if you type in part of the name you used in your entry, you will 
see
+that pop up and be highlighted.
+
+
+Another option is the hyrolo-word command which will look for full words. 
Unlike
+the grep command, if the word isn't a complete match, it won't show up. Take 
the first
+three letters of a name in your rolo and search for that with hyrolo-word, and
+you'll notice that the mini-buffer says "No matching entries found in rolo".
+
+
+The final option is hyrolo-fgrep which can search for strings or logical 
expressions.
+Essentially, it can do what grep does, but with an added twist for logical 
expressions.
+Speaking of logical searches...
+
+** Logical Searches
+Similar to the regular string search, we can add logical expressions to our
+searches to help find what we're looking for. For now, let's add a few more
+entries to our rolo, such as the name Linus Torvalds, Richard Stallman, and
+Ken Thompson. Now that we have a more populated rolo, let's look at some
+uses of logical expressions in our searches. Below is a table of the kinds
+of logical expressions you can use.
+
+
+Operator Name   Number of Arguments    Description
+=====================================================================
+and             two or more            Match entries with all args
+or              two or more            Match entries with any args
+xor             two or more            Match entries with 1 arg only
+not             one                    Match entries without the arg
+=====================================================================
+
+Let's say we want to look for Linus, and Ken. We would run hyolo-fgrep-logical
+and our input would be (or linus ken), and that will pull up both Linus and 
Ken,
+and whatever information we have for them. Keep in mind, you need the 
parenthesis
+for the function to work.
+
+
+Now that you know how the logical searches work, try searching your rolo for
+everything except Linus.
+
+
+** Keys
+Now that we have a firm understanding of how to perform searches, what do we do
+with these results? That's where keys come in to play.
+
+
+After you preform a search, you get your results in a "rolo match buffer",
+'*Hyperbole Rolo', which uses 'hyrolo-mode' to simplify browsing many HyRolo
+matches. Let's try, and preform a search with hyrolo-grep, and when the results
+get pulled up, press {?}. That will pull up a summary of the available keys.
+
+
+Now that we know how to view our keys, let's start with {r}, which will allow
+us to start a new regular expression query. Let's preform a <(search)> for
+Linus. Now that we have our results we realize that we didn't want the 
information
+for Linus, we wanted it for Ken. Press the {r} key in the '*Hyperbole Rolo'
+buffer. It will prompt you for a new regular expression, type in Ken.
+
+
+Great, now that we have an understanding of how to use these keys, try
+making a search, and within that search hide the subtree for our entries. Once
+that is done, use the key to show them all.
+
+
+Once you are done with your query, and are ready to leave the rolo match 
buffer,
+use {q} to quit. This will restore your current frame to its state prior to the
+rolo search.
diff --git a/test/hui-tests.el b/test/hui-tests.el
index e00807dc55..82b39fc5a3 100644
--- a/test/hui-tests.el
+++ b/test/hui-tests.el
@@ -84,6 +84,66 @@
       (when (file-writable-p hbmap:dir-user)
        (delete-directory hbmap:dir-user t)))))
 
+(ert-deftest hui-gbut-number-of-gbuts-with-no-buttons ()
+  "Verify number of gbuts with no buttons created."
+  (defvar global-but-file)
+  (let ((global-but-file (make-temp-file "gbut" nil ".txt")))
+    (unwind-protect
+        (mocklet ((gbut:file => global-but-file))
+          (should (= 0 (length (gbut:key-list)))))
+      (hy-delete-file-and-buffer global-but-file))))
+
+(ert-deftest hui-gbut-number-of-gibuts-when-one-button ()
+  "Verify number of ibuts when one button is created."
+  (defvar file)
+  (let ((file (make-temp-file "gbut" nil ".txt")))
+    (unwind-protect
+        (with-mock
+          (stub gbut:file => file)
+          (hui:gibut-create "global" "/tmp")
+          (should (= 1 (length (gbut:ibut-key-list)))))
+      (hy-delete-file-and-buffer file))))
+
+(ert-deftest hui-gbut-number-of-gebuts-when-one-button ()
+  "Verify number of ebuts when one button is created."
+  (defvar global-but-file)
+  (let ((global-but-file (make-temp-file "gbut" nil ".txt")))
+    (unwind-protect
+        (mocklet ((gbut:file => global-but-file)
+                  (hpath:find-noselect => (find-file-noselect 
global-but-file)))
+          (gbut:ebut-program "label" 'link-to-directory "/tmp")
+          (should (= 1 (length (gbut:ebut-key-list)))))
+      (hy-delete-file-and-buffer global-but-file))))
+
+(ert-deftest hui-gbut-number-of-gibuts-from-mail-mode ()
+  "Verify number of global ibuts from within Hyperbole mail mode."
+  (defvar global-but-file)
+  (let ((global-but-file (make-temp-file "gbut" nil ".txt"))
+        (message-mode-file (make-temp-file "gbut" nil ".txt")))
+    (unwind-protect
+        (mocklet ((gbut:file => global-but-file))
+          (hui:gibut-create "global" "/tmp")
+          (find-file message-mode-file)
+          (message-mode)
+          (should (= 1 (length (gbut:ibut-key-list)))))
+      (hy-delete-file-and-buffer global-but-file)
+      (hy-delete-file-and-buffer message-mode-file))))
+
+(ert-deftest hui-gbut-number-of-gebuts-from-mail-mode ()
+  "Verify number of global ebuts from within Hyperbole mail mode."
+  (defvar global-but-file)
+  (let ((global-but-file (make-temp-file "gbut" nil ".txt"))
+        (message-mode-file (make-temp-file "gbut" nil ".txt")))
+    (unwind-protect
+        (mocklet ((gbut:file => global-but-file)
+                  (hpath:find-noselect => (find-file-noselect 
global-but-file)))
+          (gbut:ebut-program "label" 'link-to-directory "/tmp")
+          (find-file message-mode-file)
+          (message-mode)
+          (should (= 1 (length (gbut:ebut-key-list)))))
+      (hy-delete-file-and-buffer global-but-file)
+      (hy-delete-file-and-buffer message-mode-file))))
+
 (ert-deftest hui-ibut-label-create ()
   "Create a label for an implicit button."
   (with-temp-buffer
@@ -711,6 +771,59 @@ With point on label suggest that ibut for rename."
     (goto-char (point-min))
     (should (looking-at-p "<(new)><(new)>"))))
 
+(ert-deftest hui--ibut-link-directly-to-file ()
+  "Create a direct link to a file."
+  (let ((filea (make-temp-file "hypb" nil ".txt"))
+        (fileb (make-temp-file "hypb" nil ".txt" "1234567890")))
+    (unwind-protect
+        (progn
+          (delete-other-windows)
+          (find-file fileb)
+          (goto-char (point-max))
+          (split-window)
+          (find-file filea)
+          (hui:ibut-link-directly (get-buffer-window)
+           (get-buffer-window (get-file-buffer fileb)))
+          (should (string= (buffer-string) (concat "\"" fileb ":1:10\""))))
+      (hy-delete-file-and-buffer filea)
+      (hy-delete-file-and-buffer fileb))))
+
+(ert-deftest hui--ibut-link-directly-to-dired ()
+  "Create a direct link to a directory in dired."
+  :expected-result :failed
+  (let* ((file (make-temp-file "hypb" nil ".txt"))
+         (dir (file-name-parent-directory file))
+         dir-buf)
+    (unwind-protect
+        (progn
+          (delete-other-windows)
+          (setq dir-buf (dired dir))
+          (split-window)
+          (find-file file)
+          (hui:ibut-link-directly (get-buffer-window) (get-buffer-window 
dir-buf))
+          ;; Was expecting here an ibut "/tmp" but <link-to-directory
+          ;; /tmp> could be possible too. Seems a link to the file the
+          ;; point in the dired buffer is on!? Is that expected?
+          (should (string= (buffer-string) (concat "\"" dir "\""))))
+      (hy-delete-file-and-buffer file))))
+
+(ert-deftest hui--ibut-link-directly-with-label ()
+  "Create a direct link with a label."
+  (let ((filea (make-temp-file "hypb" nil ".txt"))
+        (fileb (make-temp-file "hypb" nil ".txt" "1234567890")))
+    (unwind-protect
+        (progn
+          (delete-other-windows)
+          (find-file fileb)
+          (goto-char (point-max))
+          (split-window)
+          (find-file filea)
+          (with-simulated-input "label RET"
+            (hui:ibut-link-directly (get-buffer-window) (get-buffer-window 
(get-file-buffer fileb)) 4))
+          (should (string= (buffer-string) (concat "<[label]> - " "\"" fileb 
":1:10\""))))
+      (hy-delete-file-and-buffer filea)
+      (hy-delete-file-and-buffer fileb))))
+
 ;; This file can't be byte-compiled without `with-simulated-input' which
 ;; is not part of the actual dependencies, so:
 ;;   Local Variables: