rswgnu · matsl · Dec 3, 2023 · Dec 9, 2023 · Dec 9, 2023 · Dec 11, 2023
diff --git a/ChangeLog b/ChangeLog
diff --git a/DEMO b/DEMO
@@ -542,7 +542,7 @@ the Action Key is pressed.
   1. If on an Org todo keyword, cycle through the keywords in
      that set or if final done keyword, remove it.
 
-  2. If on an Org agenda item, jump to the item for editing.
+  2. If on an Org agenda view item, jump to the item for editing.
 
   3. Within a radio or internal target or a link to it, jump between
      the target and the first link to it, allowing two-way navigation.
@@ -828,6 +828,13 @@ brackets, < >, and come in three types:
 
           <$hbut:max-len>
 
+  4. ert-deftest tests - these consist of the test name only as tests take
+     no arguments, e.g.
+
+          <hbut-tests-ibut-insert-kbd-key>
+
+     This runs one of the Hyperbole regression tests.
+
 An Action Button is recognized only if the first name within the angle
 brackets is an existing action type or Emacs Lisp symbol.  Otherwise, other
 implicit button types will be tested and may activate instead.
@@ -1176,22 +1183,22 @@ on the *first* line of the button, within the button delimiters:
 Creating explicit buttons is fun and easy.  You can always try them out
 immediately after creating them or can utilize the Assist Key to verify what
 buttons do.  There are two ways to create them: by dragging between windows
-with the Action Mouse Key or by using the Hyperbole menus.
+with the Assist Mouse Key or by using the 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 window where you want the button
+the Assist Mouse Key to drag from a window where you want the button
 created (button source window) to a window showing its link referent.
 The drag must start outside of a draggable item which includes Hyperbole
-button, dired items and buffer menu items.
+buttons, dired items and buffer menu items.
 
 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 referent.  Depress the Assist 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
+or parentheses).  Then drag to the other window and release the Assist
 Mouse Key at the start point of the link referent.  The process
 becomes quite simple with a little practice.
 
@@ -1211,20 +1218,19 @@ the variable with a matching value when the link is later resolved.  This
 allows the sharing of links over wide areas, where links contain variables
 whose values differ between link creator and link activator.
 
-If you do the same think with the Assist Mouse Key instead of the Action
+If you do the same thing with the Action Mouse Key instead of the Assist
 Mouse Key, Hyperbole will create an implicit link button instead of an
 explicit one.  Such buttons are created without names but you can add
-a name preceding such buttons with {C-h h i l} to label them.
+a name preceding such buttons by using {C-u C-h h i l} instead.
 
 *** 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.  Use a C-u prefix argument to create
-an unnamed implicit link button instead and a M-1 prefix argument to
-create a named implicit link button.
+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`j
+<window id>} may be used to quickly create an unnamed implicit link button in
+the selected window that links to any other window chosen via the Ace Window.
+Use a M-1 prefix argument to create a named implicit link button.  If you
+want to create an explicit button instead, use the C-u prefix argument.
 
 *** Creation via Menu
 
@@ -1257,10 +1263,14 @@ buffer as the same button.
 
 If you create link buttons using the Hyperbole menus, the best technique is
 to place on screen both the source buffer for the button and the buffer to
-which it will link.  Mark the region of text to use as your button label,
-invoke the button create command from the menu, choose an action type which
-begins with `link-to-' and then use the direct selection techniques mentioned
-in "(hyperbole)Smart Key Argument Selection", to select the link referent.
+which it will link (referent buffer).  Leave point where you want to link
+to in the referent buffer, switch to the source buffer and put point where
+ you want to insert the link button.  If the button name is already there
+in the buffer, mark it as the region to use for your button label.  Then
+press {C-h h e l} and that will figure out the proper link type, prompt for
+any needed arguments and then insert the button.  You can use the direct
+selection techniques mentioned in "(hyperbole)Smart Key Argument Selection",
+to select any arguments.
 
 See "(hyperbole)Utilizing Explicit Buttons" for much more detail on how to
 work with explicit buttons.

diff --git a/DEMO-ROLO.otl b/DEMO-ROLO.otl
@@ -3,14 +3,14 @@
 ==================================================================
 *    HiHo Industries
 **     Strong, Hugo            <[email protected]>  W708-555-9821
-             Manager
+             Manager of Buttons
              04/12/2017
 ***      Smith, John           <[email protected]>  W708-555-2001
              Chief Ether Maintainer
              05/24/2017
 *    Work Industries
 **     Hansen, Dan             <[email protected]>  W218-555-2311
-             Manager
+             Manager of Clasps
              02/18/2017
 ***      Dunn, John            <[email protected]>  W218-555-3233
              Media Maker

diff --git a/FAST-DEMO b/FAST-DEMO
@@ -4,9 +4,10 @@
 
   Send an email or a testimonial if you like Hyperbole to <[email protected]>.
 
-  This demo is the fast way to get started with Hyperbole after installation.
-  The prior, lengthier Hyperbole demo/tutorial can be found in this file: "DEMO".
-  For a non-interactive introduction to Hyperbole concepts, see "HY-CONCEPTS.kotl".
+  This interactive demo is the fast way to get started with Hyperbole after
+  installation.  The prior, lengthier Hyperbole demo/tutorial can be found
+  in this file: "DEMO".  For a non-interactive introduction to Hyperbole
+  concepts, see "HY-CONCEPTS.kotl".
 
 
 * Introductory Videos
@@ -53,10 +54,12 @@
   |-----------------------------------------------------+------------------------------|
   |-----------------------------------------------------+------------------------------|
   | <[Overview and Demo]>                               | https://youtu.be/WKwZHSbHmPg |
-  |     Sections broken out in the prior table          |                              |
+  | Sections broken out in the prior table              |                              |
   |-----------------------------------------------------+------------------------------|
   | <[Quick Introduction]>                              | https://youtu.be/K1MNUctggwI |
   |-----------------------------------------------------+------------------------------|
+  | <[Top 10 ways Hyperbole amps up Emacs]>             | https://youtu.be/BysjfL25Nlc |
+  |-----------------------------------------------------+------------------------------|
   | <[Introduction to Buttons]>                         | https://youtu.be/zoEht66N2PI |
   |-----------------------------------------------------+------------------------------|
   | <[Linking Personal Info with Implicit Buttons]>     | https://youtu.be/TQ_fG7b1iHI |
@@ -65,10 +68,14 @@
   |-----------------------------------------------------+------------------------------|
   | <[HyRolo, fast contact/hierarchical record viewer]> | https://youtu.be/xdJGFdgKPFY |
   |-----------------------------------------------------+------------------------------|
+  | <[Using Koutline for stream of thought journaling]> | https://youtu.be/dO-gv898Vmg |
+  |-----------------------------------------------------+------------------------------|
   | <[Build a Zettelkasten with HyRolo]>                | https://youtu.be/HdlCK9w-LyQ |
   |-----------------------------------------------------+------------------------------|
   | <[HyControl, fast Emacs frame and window manager]>  | https://youtu.be/M3-aMh1ccJk |
   |-----------------------------------------------------+------------------------------|
+  | <[Writing test cases for GNU Hyperbole]>            | https:/youtu.be/maNQSKxXIzI  |
+  |-----------------------------------------------------+------------------------------|
   | <[Find/Web Search]>                                 | https://youtu.be/8lMlJed0-OM |
   |-----------------------------------------------------+------------------------------|
 
@@ -104,45 +111,50 @@
   These patterns are called `implicit buttons' and are activated by pressing
   {M-RET} (ESC RETURN, ALT-RETURN, or CMD-RETURN) or SHIFT-MIDDLE-MOUSE
   anywhere within them (this is known as the Action Key).  Hyperbole
-  recognizes these buttons using its predefined implicit button types that
-  specify how to recognize each type of button and what action it performs.
-  (For example, the web links in the table above are implicit buttons that
-  display web pages).  You can also add your own button and action types.
+  recognizes these buttons using its many predefined implicit button types
+  that specify how to recognize each type of button and what action it
+  performs.  (For example, the web links in the table above are implicit
+  buttons that display web pages.  So are the series of key presses
+  surrounded by braces throughout this document).  You can also add your own
+  button and action types.
 
   Try pressing {M-RET} or SHIFT-MIDDLE-MOUSE on some of the implicit buttons
   in double quotes below to activate them and see how they behave.  Press
-  {C-h A} (the A must be capitalized) on any Hyperbole button to see exactly
-  what it does prior to activating it.
+  {C-h A} (the A must be capitalized) on any Hyperbole button or highlighted
+  Emacs push-button to see exactly what it does prior to activating it.
+
+
+** Implicit Link Buttons
 
   You can simply type implicit buttons into a buffer or you can use {C-h h i
-  c} to create them and give them names.  To create an implicit link button
-  from a buffer in one window to another, simply depress the Assist Mouse
-  Key (not the Action Mouse Key) where you want the new button (but not
-  within a draggable item), drag to a point in another Emacs window and
-  release.  An implicit link button of an appropriate type for the release
-  context will be inserted at the original depress point.
-
-  If you have exactly two Emacs windows in your current frame or exactly two
-  windows visible across two Emacs frames, there is an even simpler way to
-  create implicit links.  Use the Link menu item, {C-h h i l}, to create a
-  new unnamed implicit link button or to edit the one at point.  {C-u C-h h
-  i l} will additionally prompt to add a name or rename the button at
-  point.  With more than two windows, Hyperbole will prompt you to choose
-  the referent window and its associated point to which to link.  If the Ace
+  c} to create them and give them names.  When you have exactly two windows
+  in an Emacs frame, you can instantly create an unnamed implicit link
+  button from the selected window to point in the other window by using {C-h
+  h i l}.  {M-1 C-h h i l} creates or renames a named implicit button that
+  looks like <[name]>.
+
+  You can create the same button by depressing the Action Mouse Key in the
+  text of one window and dragging to the text of the other and releasing it.
+  An implicit link button of an appropriate type for the release context
+  will be inserted at the original depress point.
+
+  With more than two windows, Hyperbole will prompt you to choose the
+  referent window and its associated point to which to link.  If the Ace
   Window package is installed and active, this will be used to choose the
   window; otherwise, you will be prompted to select it by mouse.
 
 
 ** Pathname Implicit Buttons
 
-    "HY-NEWS#ORG MODE:2:6"   - outline section anchor & relative line number
+    "HY-NEWS#ORG MODE:3:6"   - outline section anchor & relative line number
 
        Display the file, "HY-NEWS", go to the star-outline section 'ORG
-       MODE', move 2 lines into that section and then move 6 characters
-       forward.
+       MODE', move 3 lines into that section and then move 6 characters
+       forward.  "HY-NEWS#ORG MODE:L3:C6" with the line and column numbers
+       labeled works as well.
 
-       Existing files and pathnames are recognized without double quotes as
-       well.
+       Existing files and pathnames without spaces are also recognized without
+       double quotes.
 
        The variable, <hpath:display-where>, determines where Hyperbole
        displays all button referents, whether in another window or frame.
@@ -329,6 +341,21 @@ pspell-config(1)         - prints information about a libpspell installation
        Display a Hyperbole Koutline starting from cell 3b10 with lines per
        cell clipped to 2.
 
+    <ert-deftest hbut-tests-ibut-program-link-to-directory ()
+      "Programmatically create ibut link-to-directory."
+      (with-temp-buffer
+	(ibut:program nil 'link-to-directory "/tmp")
+	(should (string= "\"/tmp\"" (buffer-string))))>
+
+    <hbut-tests-ibut-program-link-to-directory>
+
+       Tests defined with the Emacs Regression Test framework using
+       `ert-deftest' can be run via action buttons as well.  Press {M-RET}
+       on the first line of each of the two above action buttons, within
+       the <> delimiters.  Start with the first one which defines an ERT
+       test case; the second one runs it, displaying the result which should
+       be successful.
+
 
 ** Many More Implicit Button Types to Learn Across Time
 
@@ -356,8 +383,10 @@ pspell-config(1)         - prints information about a libpspell installation
 |----------------------------------------------------------------------------|
 
 Implicit button types are stored in their own namespace, 'ibtypes::', so to
-see the doc on the 'pathname' ibtype, use {C-h f ibtypes::pathname RET}.  To
-learn how to create new kinds of implicit button and action types, see:
+see the doc on the 'pathname' ibtype, use {C-h f ibtypes::pathname RET}.
+
+See "DEMO#Implicit Buttons" or "(hyperbole)Implicit Buttons" for more detail.
+To learn how to create new kinds of implicit button and action types, see
 "(hyperbole)Creating Types".
 
 
@@ -366,31 +395,32 @@ learn how to create new kinds of implicit button and action types, see:
   You have learned the basics of Hyperbole implicit button types.  Hyperbole
   has two other categories of buttons:
 
-    `Explicit buttons' are manually created and embedded within buffers and
-    explicitly assigned any of many action types that Hyperbole and Emacs
-    include.  These contrast with implicit buttons which Hyperbole generates
-    automatically by recognizing text patterns in buffers.  Explicit buttons
-    look like this: <(fake button)>.  They are quickly recognizable, yet
-    relatively non-distracting as one scans the text in which they are
-    embedded.  Explicit buttons can link to local and remote files or to a
-    section within a document; they can calculate things or query databases
-    or show different views of bodies of information.  Unlike HTML
-    hyperbuttons, there is no markup language to learn nor specific document
-    format required.  You can create explicit buttons with simple keyboard
-    presses or mouse drags from one window to another (when not on a draggable
-    item).  See the {C-h h e} menu for explicit button commands.
-    {C-h h e c} creates an explicit button and {C-h h e l} creates an explicit
-    link button between two windows, just like their counterparts for implicit
-    butons.  See "DEMO#Explicit Buttons" or "(hyperbole)Explicit Buttons" for
-    more detail.
-
-    `Global buttons' are labeled Hyperbole buttons in your personal button
-    file, {C-h h b p}.  All global buttons are activated by name with
-    completion provided, independent of which buffers are on-screen, {C-h h g
-    a}.  Global buttons may be <(explicit buttons)> or <[labeled/named]>
-    implicit buttons in the personal button file.  See the {C-h h g} menu for
-    global button commands.  See "DEMO#Global Buttons" or "(hyperbole)Global
-    Buttons" for more detail.
+  `Explicit buttons' are manually created and embedded within buffers and
+  explicitly assigned any of the many action types that Hyperbole includes.
+  These contrast with implicit buttons which Hyperbole generates
+  automatically by recognizing text patterns in buffers.  Explicit buttons
+  look like this: <(fake button)>.  They are quickly recognizable, yet
+  relatively non-distracting as one scans the text in which they are
+  embedded.  Explicit buttons can link to local and remote files or to a
+  section within a document; they can calculate things or query databases or
+  show different views of bodies of information.
+
+  Unlike HTML hyperbuttons, there is no markup language to learn nor
+  specific document format required.  You can create explicit buttons with
+  simple keyboard presses or mouse drags from one window to another (when
+  not on a draggable item).  See the {C-h h e} menu for explicit button
+  commands.  {C-h h e c} creates an explicit button and {C-h h e l} creates
+  an explicit link button between two windows, just like their counterparts
+  for implicit butons.  See "DEMO#Explicit Buttons" or "(hyperbole)Explicit
+  Buttons" for more detail.
+
+  `Global buttons' are explicit or named implicit Hyperbole buttons that are
+  stored in your personal button file edited with {C-h h b p}.  Any such
+  button in there becomes global and is accessible by name without the need
+  to have the that file on screen.  Simply press {C-h h g a} to activate a
+  global button and you will be prompted with completion for the button
+  name.  See the {C-h h g} menu for the rest of the global button commands.
+  See "DEMO#Global Buttons" or "(hyperbole)Global Buttons" for more detail.
 
 
 * Hyperbole Subsystems
@@ -424,17 +454,17 @@ learn how to create new kinds of implicit button and action types, see:
   use within hyperlink references to the cell.
 
   A demonstration of the Koutliner is found on the Hyperbole Kotl/Example
-  menu entry.  {C-h h k e}, gives you an editable copy of Hyperbole's example
-  Koutliner file.  This explains the Koutliner commands and lets you try them
-  out as you learn.  Additional documentation can be found in
-  "(hyperbole)Koutliner".  "(hyperbole)Koutliner Keys" summarizes, in
+  menu entry, {C-h h k e}.  This gives you an editable copy of Hyperbole's
+  example Koutliner file.  This file explains the Koutliner commands and
+  lets you try them out as you learn.  Additional documentation can be found
+  in "(hyperbole)Koutliner".  "(hyperbole)Koutliner Keys" summarizes, in
   alphabetical order, the Koutliner commands which are bound to keys.
 
 
 * Reference Documentation
 
   As noted at the start, "DEMO" provides a more extensive, interactive look
-  into Hyperbole, {C-h h d d}.
+  into Hyperbole, {C-h h d d}, if you have more time.
 
   For a quick, non-interactive introduction to Hyperbole concepts, use
   "HY-CONCEPTS.kotl" available with {C-h h d c}.
@@ -445,9 +475,11 @@ learn how to create new kinds of implicit button and action types, see:
   and action types and much more.  See "(hyperbole)" or use {C-h h d i}.
 
   It is included in the "${hyperb:dir}/man/" subdirectory of Hyperbole in
-  four forms:
+  four forms, accessible as the links below:
 
     "man/hyperbole.info"   - online Info browser version
     "man/hyperbole.html"   - web HTML version
     "man/hyperbole.pdf"    - printable version
     "man/hyperbole.texi"   - source form
+
+-- The End --