Merge remote-tracking branch 'hyperbole/master' into externals/hyperbolescratch/hyperbole-lexbind

1 files changed, 174 insertions, 62 deletions

diff --git a/DEMO b/DEMO
index a8e650c..d72a6db 100644
--- a/DEMO
+++ b/DEMO
@@ -1,5 +1,7 @@
 * GNU Hyperbole Demonstration by Bob Weiner
 
+  Say thanks if you like Hyperbole: https://saythanks.io/to/rswgnu
+
     Table of Contents
     -----------------
     * Introduction
@@ -43,7 +45,7 @@ terms used here are unfamiliar to you.
 * Smart Keys 
 
 Hyperbole provides two context-sensitive keys, the Action Key and the Assist
-Key, jointly referred to as Smart Keys that each do dozens of things,
+Key, jointly referred to as Smart Keys.  Each do dozens of things,
 essentially whatever is most helpful in any given textual context where they
 are pressed.  The Action Key is {M-RET} (ESC RETURN if you are unsure) on the
 keyboard and the shift-middle mouse button on a 3-button mouse or the
@@ -53,7 +55,7 @@ To distinguish the mouse buttons from the keyboard keys, we will often refer
 to the Action Mouse Key or Assist Mouse Key.  (It is possible to rebind these
 keys to the unshifted middle and right mouse buttons, if desired.  See the
 Smart Key Bindings section of the Hyperbole Manual, "(hyperbole)Smart Key
-Bindings").
+Bindings") simply by pressing the Action Key on that reference.
 
 The Action Key selects entities, creates links and activates buttons.  The
 Assist Key provides help, such as reporting on a button's attributes, or
@@ -65,7 +67,7 @@ and returns here.
 
 See also the later section, <(Smart Mouse Keys)>.
 
-Now let's look at many of the things you can do with the Smart Keys.
+Now let's look at some of the things you can do with the Smart Keys.
 
 ** Table of Contents Browsing
 
@@ -94,9 +96,10 @@ following button and then practice scrolling: <(toggle-scroll-proportional)>.
 If you prefer the default proportional scrolling, click on the previous
 button again to restore it.
 
-If you always want windowful (non-proportional) scrolling, you'll have to
-add a setting of smart-scroll-proportional to your "~/.emacs" file after the
-point at which you load Hyperbole or else set it as part of
+If you always want windowful (non-proportional) scrolling, use the Emacs
+customize system to set it permanently.  Otherwise, you can set it manually
+by adding a setting of smart-scroll-proportional to your "~/.emacs" file
+after the point at which you load Hyperbole or else set it as part of
 hyperbole-init-hook, which executes whenever Hyperbole is loaded, e.g.:
 
    (add-to-list 'hyperbole-init-hook
@@ -139,7 +142,6 @@ You can change which browser is used with {C-h h c w}, the Cust/Web-Search
 menu.  Advanced users can change the search engines listed by editing the
 option, <(hyperbole-web-search-alist)>.
 
-
 ** Help Buffers
 
 Since the Smart Keys do so many things, it is helpful to see what they will
@@ -175,17 +177,17 @@ A unique feature of Hyperbole is the Koutliner; it is for outlining thoughts,
 developing requirements or listing tasks and hyperlinking them to other
 documents.
 
-The Hyperbole Koutliner produces structured, autonumbered documents composed
-of hierarchies of cells.  Each cell has two identifiers, a relative
-autonumber indicating its present position within the outline and a permanent
-identifier suitable for use within hyperlink references to the cell.
+The Hyperbole Koutliner produces multi-level, autonumbered hierarchies of
+cells.  Each cell has two identifiers, a relative autonumber indicating its
+present position within the outline and a permanent identifier suitable for
+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
-alphabetical order the Koutliner commands which are bound to keys.
+"(hyperbole)Koutliner".  "(hyperbole)Koutliner Keys" summarizes, in
+alphabetical order, the Koutliner commands which are bound to keys.
 
 
 * HyControl
@@ -253,15 +255,16 @@ the argument is used to adjust one dimension of the frame.
 The {@} command splits a frame into a grid of up to 9 rows by 9 columns of
 windows, showing a different buffer in each window, if available.  First
 let's expand our frame to full screen with the {.1 %} command and then show
-a 2 x 3 grid.  We can do multiple commands in one key sequence.  Press the
+a 2 x 3 grid.  We can do multiple commands in one 'key series'.  Press the
 action key here: {.1 % .23 @}.
 
 You can even write something like this to do the whole thing in one sequence.
 First, let's quit out of HyControl Frames mode with {q}.  Then go back to one
-window with {C-x 1}.  Now we can execute a single sequence from any buffer that
-creates our 2x3 window grid:  {C-h h s f  .1 %  .23 @  q}.  Pretty amazing,
-right?  You can separate each command by any number of spaces or even jam them
-all together: {C-hhsf.1%.23@q}.
+window with {C-x 1}.  Now we can execute a single sequence from any buffer
+that creates our 2x3 window grid: {C-h h s f .1 % .23 @ q}.  Pretty amazing,
+right?  You can separate each command by any number of spaces or even jam
+them all together: {C-hhsf.1%.23@q}.  Use SPC (separated by spaces) to
+include a space as part of the key series.
 
 A zero argument to the {@} command is special.  It means you want to display
 buffers with a particular major mode first, e.g. c-mode.  You will be
@@ -348,7 +351,7 @@ Action Key click on {C-x4r work RET} to search for all entries from Work
 Industries; then type {q} to quit from the HyRolo search results buffer.
 {C-x4r manager RET} finds all managers plus their staff across companies.
 {C-x4r Dunn,\ J RET} finds just that staffer.  Notice that you must quote the
-space with a backslash when including it in a key sequence search string or
+space with a backslash when including it in a key series search string or
 else the space will be removed; when just typing the same string
 interactively, don't add the backslash.
 
@@ -372,9 +375,9 @@ not             one                    Match entries without the arg
 =====================================================================
 
 So for example, {C-x4r (or smith dunn) RET} finds both the Smith and Dunn
-entries.  (Note that you do not need to backslash quote spaces within
+entries.  (Note that you do not need to quote spaces with backslashes within
 parentheses, square brackets, angle brackets or double quotes when used in
-key sequences).  To find any Managers and their staffers at HiHo Industries,
+key series).  To find any Managers and their staffers at HiHo Industries,
 use: {C-x4r (and manager hiho) RET}.  To find managers anywhere but at HiHo:
 {C-x4r (and manager (not hiho)) RET}.  Finally, this will find all people who
 are not managers at HiHo: {C-x4r (not (and manager hiho)) RET}.
@@ -399,32 +402,53 @@ command to return to this DEMO later.
 
 * Implicit Buttons
 
-An incredibly powerful feature of Hyperbole is known as implicit buttons,
-i.e. a specific format of text within a buffer that Hyperbole recognizes as a
-button and lets you activate.  Hyperbole recognizes these by context and does
-not require any specialized markup.
+Hyperbole can automatically turn your existing, unchanged text files into
+hypertexts via its incredibly powerful feature: implicit buttons.  An
+implicit button is a span of text within a buffer that Hyperbole recognizes
+as a button and lets you activate.  Hyperbole recognizes these buttons using
+its predefined implicit button types that specify how to recognize a
+particular type of button and what action such buttons perform.  For example,
+double-quoted pathnames have a type of 'pathname' and an action of: display
+the path in Emacs. (Hyperbole lets you configure where to display it).
+
+Hyperbole has many built-in implicit button types, a number of which you will
+see here.  You may also create your own types.  Once a type is known, you can
+embed an infinite number of buttons of that type within your text documents
+simply by typing them.  Let's look at some of these button types and how you
+can use them.
 
 Note that you must press a Smart Key on the first line of an implicit button
 to utilize it if it spans multiple lines and always press on a regular
 character, not a delimiter like ( or ) since these are treated specially and
 used to select groups of text.
 
-Hyperbole has many built-in implicit button types, a number of which you will
-see here, and allows you to create your own.  Once a type is known, you can
-embed an infinite number of buttons of that type within your text simply by
-typing them.  Let's look at some of these button types and how you can use
-them.
+Individual implicit buttons may be labeled so that they may be activated
+by name or linked to by other buttons.  Here is a pathname button with a label
+of 'My Emacs Files':
+
+<[My Emacs Files]>: "~/.emacs.d"
 
-** Key Sequence Buttons
+You see that the label is delimited by <[ and ]> 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}.
 
-Any Emacs key sequence delimited with curly braces is an implicit button.
-Press the Action Key with {C-u C-p} for example and the point should move
-four lines upward.  An Assist Key press on the key sequence displays the
-documentation for its command binding, i.e. what it does.  Key sequences
-together with the arguments their commands prompt for also may be given,
-e.g. {M-x apropos RET hyperbole RET}.  Click in the braces to try it out.
+Now let's explore some implicit button types.
 
-Hyperbole minibuffer menu items may also be activated as key sequences.  For
+** Key Series Buttons
+
+Any series of Emacs key sequences (or 'key series') delimited by curly
+braces is an implicit button.  Press the Action Key within {C-u C-p C-n C-e}
+for example and the point should move three lines upward and to the end of
+line.  An Assist Key press on the key series either displays the documentation
+for its command binding (if a single key sequence) or displays help for the
+implicit button, i.e. what it does.  Key series together with the
+arguments their commands prompt for, may also be given, e.g. {M-x apropos
+RET hyperbole RET}.  Click with the Action Mouse Key within the first line
+of this button to try it out.
+
+Hyperbole minibuffer menu items may also be activated as key series.  For
 example, {C-h h d i} displays the online browsable Info version of the
 Hyperbole Manual.  Press your Action Key between the braces to see it.  Once
 in the Info browser, use {s} to search for any topic throughout the manual.
@@ -436,14 +460,27 @@ demonstrations and tours with this and other implicit button types.
 
 ** Org Mode
 
-For users of Emacs Org mode, Hyperbole does a few things.  First, the
-Action Key will follow and execute links in Org mode files.  Second, when
-point is on an outline heading in Org mode, the Action Key cycles the view
-of the subtree at point and the Assist Key cycles the view of all headings
-in the buffer.  The Assist Key will also display help when pressed on an Org
-mode link.
+For users of Emacs Org mode, Hyperbole does quite a few things.
+
+First, the Action Key follows internal links in Org mode files.  When
+pressed on a link referent/target, the link definition is displayed,
+allowing two-way navigation between definitions and targets.
+
+Second, the Action Key follows Org mode external links.  The Assist Key
+displays help when pressed on an Org mode link.
+
+Third, within a radio target definition, the Action Key jumps to the first
+occurrence of an associated radio target.
+
+Fourth, when point is on an outline heading in Org mode, the Action Key
+cycles the view of the subtree at point and the Assist Key cycles the view
+of all headings in the buffer.
 
-In any other context besides the end of a line, the Action Key will invoke
+Fifth, with point on the first line of a code block definition, the Action
+Key executes the code block via the Org mode standard binding of {C-c C-c},
+(org-ctrl-c-ctrl-c).
+
+In any other context besides the end of a line, the Action Key invokes
 the Org mode standard binding of {M-RET}, (org-meta-return).
 
 ** Implicit Path Links
@@ -486,7 +523,7 @@ headings preceded by asterisks rather than hash marks.  So to jump back to
 the Org Mode section in this file, press the Action Key on "#Org-Mode".
 
 HTML hash-links are case-sensitive; other hash-links are not.  Hash links
-typically use dashes in place of the spaces that referents may contain but if
+typically use dashes in place of the spaces that referents may contain, but if
 the link is enclosed in quotes, Hyperbole allows spaces to be used as well.
 In fact, it is best practice to always enclose hash-style links in quotes so
 Hyperbole can distinguish them from other similar looking constructs, such as
@@ -515,7 +552,7 @@ Thus an Action Key press on "simple.el", "hyperbole.info" or even
 
 Some file types require external programs to view them, such as pdf files.
 The function (hpath:get-external-display-alist) determines the file
-suffixes which should be viewed externally together with their associated
+suffixes which should be viewed externally, together with their associated
 viewer programs, on a per-frame, per window-system basis.  See its
 documentation for more details.  The association lists used by this
 function are stored in variables for each available window system:
@@ -585,6 +622,37 @@ you can also use paths of the form:
 
 	ftp://ftp.gnu.org/pub/
 
+*** POSIX and MSWindows Paths
+
+Hyperbole recognizes standard POSIX paths as well as typical MSWindows
+paths (both local and network shares) and can convert an in-buffer
+path between POSIX and MSWindows formats multiple times, even paths
+involving mount points.  Hyperbole even recognizes the different ways
+paths are accessed when using Windows for GNU/Linux (WSL) atop
+MSWindows, where all of these reference the same directory:
+"c:/Users", "c:\Users", "/C/Users", "/c/Users", and "/mnt/c/Users".
+
+MSWindows paths may be used within links and implicit path buttons
+just like POSIX paths, whether running Emacs under a POSIX system or
+MSWindows.  If under POSIX, a remote MSWindows path must be accessed
+through a mount point to the network share.  Hyperbole caches such
+mount points when it is first loaded.  Use {M-x
+hpath:cache-mswindows-mount-points RET} to update them if more mounts
+are made later.
+
+{M-x hpath:substitute-posix-or-mswindows-at-point RET} toggles any
+path at point between POSIX and MSWindows styles.  Bind it to a key
+for rapid path transformations.
+
+The function, `hpath:substitute-posix-or-mswindows', does the same thing
+for properly quoted path strings, for example:
+  (hpath:substitute-posix-or-mswindows "C:\\Users") yields "/mnt/c/Users"
+and
+  (hpath:substitute-posix-or-mswindows "/c/Users") yields "c:\\Users".
+
+To convert pathnames in one direction only, use the
+`hpath:mswindows-to-posix' or `hpath:posix-to-mswindows' functions.
+
 ** Internet Request For Comments (RFC) Document Browsing
 
 With Tramp, you can also retrieve and browse RFC documents used in Internet
@@ -684,6 +752,46 @@ user, project and commit hash code are all included.  The second and
 third versions require the setup of default values, as explained in
 the commentary near the top of "hib-social.el".
 
+Similarly, the same file above explains how to link to pull requests,
+issues, branches and tags.
+
+** Gitlab (Remote) References
+
+For software developers who use Gitlab for publishing and version control,
+Gitlab links are similar to social media links but reference specific Gitlab
+web pages.  See "#Github (Remote) References" for the basic syntax of such
+links but substitute 'gl' instead of 'gh'.
+
+Gitlab offers many more types of reference links than Github, here they are:
+
+  gl#gitlab-org/gitlab-ce/activity          Summarize user's project activity
+  gl#gitlab-org/gitlab-ce/analytics         Display user project's cycle_analytics
+  gl#gitlab-org/gitlab-ce/boards            Display user project's kanban-type issue boards
+
+  Once you set the default user and project variables, you can leave
+  them off any reference links:
+
+    (setq hibtypes-gitlab-default-user "gitlab-org")
+    (setq hibtypes-gitlab-default-project "gitlab-ce")
+
+  gl#jobs                                   Display default project's computing jobs
+  gl#labels                                 Display default project's issue categories
+  gl#members                                Display default project's staff list
+  gl#contributors                           Show contributor push frequency charts
+  gl#merge_requests or gl#pulls             Display default project's pull requests
+  gl#milestones                             Display default project's milestones status
+  gl#pages                                  Display default project's web pages
+  gl#pipelines                              List build and test sequences
+  gl#pipeline_charts                        Graphical view of pipeline run results across time
+  gl#schedules                              Display schedules for project pipelines
+  gl#snippets                               Project snippets, diffs and text with discussion
+
+  gl#groups                                 List all available groups of projects
+  gl#projects                               List all available projects
+
+  gl#milestone=38                           Show a specific project milestone
+  gl#snippet/1689487                        Show a specific project snippet
+
 ** Git (Local) References
 
 Similarly, again for software developers, git references work on local
@@ -727,7 +835,7 @@ e.g. filter a file to just lines that don't match a pattern (RemoveLines).
 
 ** Annotated Bibliography Buttons
 
-Annotated Bibliography references such as [FSF 16] may be embedded in any file
+Annotated Bibliography references such as [FSF 19] may be embedded in any file
 and activated with the Action Key to find the reference at the end of the file.
 Try that one by pressing between the square brackets.
 
@@ -742,8 +850,9 @@ displayed.  Test this technique with a {C-x C-f} (find-file) and then a {?}.
 
 ** Hyperbole Source Buttons
 
-If you ask for help with the Assist Key or {C-u C-h A} from within the
-[FSF 16] button, the first line of the help buffer will look like this:
+If you ask for help with the Assist Key or {C-h A} from within this button,
+{M-x dired-other-window RET ~ RET}, the first line of the help buffer will
+look like this:
 
 @loc> "DEMO"
 
@@ -1136,7 +1245,7 @@ If you want a new window where you release (so the original destination window's
 buffer stays onscreen), just drag to a window's modeline; that window will be
 split before the buffer is displayed.
 
-*** Displaying File and Buffer Items
+*** Displaying File and Buffer Items and Moving Buffers
 
 You can do the same thing with items in dired, buffer menu and ibuffer menu
 listing buffers rather than buffers themselves.  Drag with the Action Mouse Key
@@ -1153,15 +1262,18 @@ made.  An Assist Key Drag will move the the item list buffer to the destination
 (swapping buffers), just as it does with other buffers.  Practice these drags as
 they will prove very beneficial across time.
 
-For even faster keyboard-based drag emulation, use the Emacs package 'ace-window'
-(see "(hyperbole)Keyboard Drags" for setup).  Once this is configured, the
-leftmost character or two of each window's modeline will show the ID to type to
-use that window as the drag destination. Then whenever point is on an item you
-want displayed in another window, use M-o i <window-id> and watch the magic
-happen.  You can also use this to create explicit button links to other window
-buffers when in an editable buffer.  If you want to display multiple items in
-different windows, instead use the M-o t <window-id> key sequence to @emph{throw}
-the item to the window.
+For even faster keyboard-based drag emulation, use the Emacs package
+'ace-window' (see "(hyperbole)Keyboard Drags" for setup).  Once this is
+configured and the suggested M-o key binding is made, the leftmost character or
+two of each window's modeline will show the <window-id> to type to use that
+window as the drag destination. Then whenever point is on an item you want
+displayed in another window, use M-o i <window-id> and watch the magic happen.
+If you want to display multiple items in different windows, instead use the
+M-o t <window-id> key sequence to @emph{throw} each item to a different window,
+while leaving the same selected window.  To replace the selected window's
+buffer with that of another window, use M-o r <window-id>.  To instead swap the
+selected window's buffer with that of another window, use M-o m <window-id>.
+Try these commands out and they will speed your work.
 
 *** Cloning Windows
 
@@ -1273,7 +1385,7 @@ to dive deeper.  Read it online with the GNU Info reader at "(hyperbole)Top".
 
 * References
 
-[FSF 16] Free Software Foundation, Inc.  GNU Emacs Manual.  Free Software
-Foundation, Cambridge: MA, 2016.  "(emacs)Top"
+[FSF 19] Free Software Foundation, Inc.  GNU Emacs Manual.  Free Software
+Foundation, Cambridge: MA, 2019.  "(emacs)Top"
 
 * THE END