* GNU Hyperbole Full Demo/Tutorial by Bob Weiner

  Send an email or a testimonial if you like Hyperbole to <rsw@gnu.org>.

    Table of Contents
    -----------------
    * Introduction
    * Smart Keys
    * Koutliner
    * HyControl
    * HyRolo
    * History
    * Implicit Buttons
    * Explicit Buttons
    * Button Files
    * Global Buttons
    * Smart Mouse Keys
    * Epilog
    * References


* 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 "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 "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-type
model 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.


* Smart Keys 

Hyperbole provides two context-sensitive keys, the Action Key and the Assist
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
shift-left button on a two button mouse.  The Assist Key is {C-u M-RET} and
the shift-right mouse button.  Memorize these keys; you will use them a lot.
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") 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
serves a complementary function to whatever the Action Key does within a
context.  Press the Action Key within this <(button)> to see all of the
contexts and operations of the Smart Keys.  SPACE scrolls forward and
BACKWARDS DELETE scrolls backward within the Smart Key summary; {q} quits
and returns here.

See also the later section, <(Smart Mouse Keys)>.

Now let's look at some of the things you can do with the Smart Keys.

** Table of Contents Browsing

In DEMO, README and TUTORIAL files, Hyperbole recognizes table of contents
entries and jumps to their associated sections (by default, in another
window) with a press of the Action Key.  Go back to the table of contents at
the start of this file and try navigating to different sections.

** Smart Scrolling

By default, the variable `smart-scroll-proportional' is set to t (TRUE).  This
makes a press of the Action Key at the end of a line scroll forward, so that
the current line is placed at the top of the window; the Assist Key does the
reverse when pressed at the end of line; it places the current line at the
bottom of the window.  This is called proportional scrolling because the
amount of scrolling is relative to the point's position in the window.  Try
it with this DEMO buffer to see how you can precisely control what is
displayed in a window and then come back here.

Alternatively, if this variable is set to nil (FALSE), the Smart Keys scroll
forward or backward a windowful when at the end of a line, regardless of
which line point is on, just as {C-v} and {M-v} do.

Let's try windowful scrolling a bit.  Press the Action Key within the
following button and then practice scrolling: <(toggle-scroll-proportional)>.
If you prefer the default proportional scrolling, press on the previous
button again to restore it.

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
                (lambda () (setq smart-scroll-proportional nil)))

** Hyperbole Menus

Once Hyperbole is loaded into your Emacs, a Hyperbole menu will be added to
the Emacs menubar, if you have one.  This menu is mostly the same as the
minibuffer menu you saw at the beginning; one is for use from the keyboard
(the minibuffer menu) and one is for use with the mouse (the menubar menu).

In this demo, we will use the minibuffer menu.  To display the top-level
Hyperbole menu again use 'C-h h' or click the Action Mouse Key within the
blank/inactive minibuffer window.  You will see a single line (possibly
wrapped around) with submenus that end with a forward slash (/) and
non-menu items.  Type the first capitalized letter of any menu item (you
can type it as lower or upper case, it does not matter) or click on it with
the Action Mouse Key to select and activate it.  You may also move forward
an item with 'TAB' or 'M-f' or backward an item with 'Shift-TAB' or 'M-b'
and then use 'RET' to select the item.  Also, notice at the left of this
menu is your Hyperbole release version number for easy reference.

A press/click of the Assist Key on a menu item pops up a window
displaying help for it while keeping the current menu on screen.  'C-t' or
an Action Key press/click on the menu prefix (before the '>' character)
returns you to the top Hyperbole menu if you are in a submenu.  A press of
'q' or 'C-g' will quit from the current menu without invoking any further
commands.

Let's try a menu item that displays the Hyperbole Glossary of terms.  Use
{C-h h d g} to display the glossary.  Use {q} in the glossary to return here.
{C-h h d RET} would simply exit the menu and {C-h h d C-t q} would redisplay
the top Hyperbole menu and then quit it.

What if we want to do a web search for GNU Hyperbole?  Then we use the
Find/Web menu, typically bound to 'C-c /' or if not, then use {C-h h f w
g "GNU Hyperbole" RET} to search Google, including the quote marks
so that it is searched for as a phrase.  Your standard web browser will be
used to return the search results.

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
do in any given context before pressing them, especially when you are first
learning Hyperbole.  {C-h A} shows you what the Action Key will do in the
current context; {C-u C-h A} displays the same kind of help for the Assist
Key.  Only a capital A will work, so be sure to press shift.  Try these
help commands.

You can also see what mouse-only events like modeline clicks and drags across
frames will do.  Depress the Smart Mouse Key you are interested in at
a location, then while holding it down, depress the other Smart Mouse Key, move
to any release point and then release both keys.  The help displayed will show
you exactly what will happen in that context.  Try this for the Action Mouse Key
by dragging horizontally at least 10 characters in this buffer and depressing
the Assist Mouse Key before you finish the drag.

Any buffer whose name ends in `Help*' is presumed to be a temporary buffer
that you want to inspect and then remove from view.  If you press either the
Action or Assist Key at the end of a help buffer, the buffer is buried from
view and your window configuration is restored to its state prior to
displaying the help (same as what {q} does).  If you have removed the Smart
Key help buffer, bring it back.  Then press one of the Smart Keys at its end
to remove it.  Note how your window configuration is restored.

Remember that this works for any help buffer, whether or not Hyperbole
generated it.


* Koutliner

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 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.


* HyControl

Hyperbole includes the fastest, easiest-to-use Emacs window and frame
management system available, HyControl, found under the Hyperbole Screen
menu, {C-h h s}.  If you use a lot of Emacs windows or frames (native window
system windows), then this tool is for you.  A long video demonstrating most
of HyControl's features is available at https://youtu.be/M3-aMh1ccJk.

HyControl interactively adjusts the layout of your windows and frames down to
the pixel-level, if desired.  You adjust the location, size and display
elements of your windows and frames until they look as you like and then
simply quit HyControl and go back to work.  It has smart features for laying
out large grids of windows, avoiding having frames cover graphical toolbars
anchored at the edges of your screen, and allows you to quickly set numeric
arguments to apply to operations, like resizing a frame to a percentage of
your screen size.

There are two submodes of HyControl: one for controlling windows and one for
controlling frames, although a number of commands are available in both modes
where they are useful.

Hyperbole binds {C-c \ } to invoke HyControl windows control; otherwise, the
Hyperbole minibuffer menu item, Screen/WindowsControl {C-h h s w}, will do
the same thing.

Once in HyControl, your minibuffer window at the bottom of the selected
frame will display a summary of keys you may use to adjust your windows
until you press {Q} (or {q} once or twice) to quit from HyControl.  If you
don't see it, press {?} to turn on this help display.  The key {t} will
always switch you between controlling frames and windows, the minor modes of
HyControl, with a modeline indicator of either "HyFrm" or "HyWin" depending
on which type of control is active.  See "(hyperbole)HyControl" for full
usage information.

** Frame Commands

Let's try some of the more interesting commands.  You can either type the
following key sequences (ignoring the braces) for practice or simply press
the Action Key within them to see what they look like.

   {C-h h s f}  - enter HyControl Frames mode

   {.50 %}      - make frame 50% of screen size
   { c }        - use this multiple times to move frame around screen edges
   { a }        - use this multiple times to adjust frame width
   { A }        - use this multiple times to adjust frame height

The following 4 commands use the prefix argument as a percentage of the
screen height, except that no argument or an argument of 1 mean 50% since
the argument is used to adjust one dimension of the frame.

   { i }        - move to top edge, next press cuts height by ARG %
   { m }        - move to bottom edge, next press cuts height by ARG %
   { j }        - move to left edge, next press cuts width by ARG %
   { k }        - move to right edge, next press cuts width by ARG %

   { f }        - clone the selected window to a new frame
   { F }        - tear off the selected window (if more than one window)
          into a new frame

** Windows Grid

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.  Outside of
HyControl, you can invoke the grid of windows command with {C-c @} in most
buffers.

By default, this command shows buffers with attached files only and prompts
for the size of the grid to display.  With a negative prefix argument, the @
command prompts for a shell glob-type pattern of files to match, e.g. *hypb*.el,
and then chooses the smallest square grid patterns that can accommodate the number
of files matched, e.g. 3x3 or 4x4, etc.


With a zero prefix argument, the @ command prompts for a major mode name,
e.g. emacs-lisp-mode, then the size of the grid and then displays the existing
buffers with that major mode.

Let's try this unique command.  First we will expand our frame to full screen
with the {C-h h s f .1 % Q} command and then show a 2 x 3 grid.  We can do the whole
thing in one 'key series'.  Press the action key within the braces:
{C-h h s f .1 % .23 @ Q}.  Using the global key binding in any buffer is even simpler:
{C-23 C-c @}. 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.

Now let's display a 2x2 grid of windows preferring Emacs Lisp buffers.
First let's add a few Emacs Lisp files to the bottom of our buffer list.
Press the Action Key anywhere within the first line of the code of this
action button:

   <progn (mapc (lambda (f) (bury-buffer (find-file-noselect f)))
                '("hibtypes.el" "hactypes.el" "hsettings.el"))
          (message "Last 3 buffers are: %S"
                   (mapcar #'buffer-name
                           (nthcdr (- (length (buffer-list)) 3) (buffer-list))))>

To display the grid, activate this key series button:

   {C-0 C-c @ emacs-lisp-mode RET 22 RET}

Or how about we display a bunch of matching files in a directory, say Elisp files
with 'hypb' in their names:

   {C--1 C-c @ *hypb*.el RET}

If you ever need to experiment with different sized window grids, use
{M-x hycontrol-window-grid-repeatedly RET}.  It will repeatedly prompt you
for a grid size and then display it.  When you are done, simply press RET
to exit.

There is lots more to discover in HyControl as you explore.


* HyRolo

HyRolo is an advanced hierarchical, record-oriented retrieval system that
uses text files for storing its records.  Most often this is used for contact
management but it can quickly be adapted to most any record-oriented lookup
task requiring fast retrieval.

HyRolo manages and searches rolo files which consist of an optional header
that starts and ends with a line of equal signs (at least three equal signs
starting at the beginning of a line), followed by zero or more rolo records.
You must manually add a header to any rolo file if you want it to have one.

We call rolo records, entries.  Entries begin with a delimiter of one or more
`*' characters at the beginning of a line.  Entries may be arranged in a
hierarchy, where child entries start with one more `*' character than do
their parents.  Top-level entries begin with a single `*'.

Beyond this initial delimiter, entries are completely free-form text.  It is
best to use a "lastname, firstname" format, however, when adding contact
entries into a rolo.  Then HyRolo will automatically keep your entries
alphabetized as you enter them.  Then you can sort the entries if you ever
need.

HyRolo commands are invoked from the Hyperbole Rolo menu.  See
"(hyperbole)HyRolo" for a full reference on commands including adding
entries, regular expression searches and manipulating the HyRolo search
results buffer.

For demonstration purposes, we discuss only the most common searches and use
a global key binding for quick access to HyRolo searches of existing entries.
Below is a sample rolo file (indented 3 spaces) that we will work with in
this DEMO.  The date at the end of each record is automatically added by
HyRolo whenever a new record is added.

   ==================================================================
              DEMO ROLO
   ==================================================================
   *    HiHo Industries
   **     Strong, Hugo            <hs@hiho.com>  W708-555-9821
        Manager
        04/12/2017
   ***      Smith, John           <js@hiho.com>  W708-555-2001
        Chief Ether Maintainer
        05/24/2017
   *    Work Industries
   **     Hansen, Dan             <dh@work.com>  W218-555-2311
        Manager
        02/18/2017
   ***      Dunn, John            <md@work.com>  W218-555-3233
        Media Maker
        11/2/2017

** String Searches

Any search done on the rolo scans the full text of each entry and ignores the
case of the text.  During a search, the rolo file header separator lines and
anything in between are appended to the buffer of matched entries before any
entries are retrieved from the file.  Whenever an entry is matched, it and
all of its descendant entries are retrieved.  If your emacs version supports
textual highlighting, each search match is highlighted for quick, visual
location.

Let's try the HyRolo.  First load the HyRolo demo commands with an Action Key
press on "-hyrolo-demo.el".  Now C-x 4 r will search the DEMO ROLO file.
Action Key press 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 series search string or
else the space will be removed (or you could type SPC); when just typing the
same string interactively, don't add the backslash.

A prefix argument used with any of the find commands listed above limits the
search to a maximum number of matches given by the argument.  For example
{C-u 1 C-x4r John RET}, finds only the John Smith entry and ignores John
Dunn.

** Logical Searches

The same search command can be used to perform logical searches of the HyRolo
files.  A simple parenthesis delimited prefix format is used with the
following logical operators.

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
=====================================================================

So for example, {C-x4r (or smith dunn) RET} finds both the Smith and Dunn
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 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}.

See "(hyperbole)HyRolo Keys" for how to navigate the HyRolo Matches buffer
when many entries are found or how to edit a matched entry.

We are now finished with the HyRolo section of the demo.  Activate this
to remove the HyRolo demo code and restore any prior key binding:
{M-x hyrolo-demo-quit RET}.


* History

Hyperbole provides a history command that returns you to previous button
locations in the reverse order of the way you traverse them.  It actually
restores your complete frame and window configuration at the time of the
button press.  You access it by selecting the Hist command from the top-level
Hyperbole menu, {C-h h h}.  Remember this because you will want to use that
command to return to this DEMO later.


* Implicit Buttons

    Table of Contents
    -----------------
    ** Key Series Buttons
    ** Org Mode
    ** Implicit Path Links
       *** Paths with Line and Column Numbers
       *** HTML Markdown and Emacs Outline Hash Links
       *** Path Suffixes and Variables
       *** Path Prefixes
       *** Info Paths
       *** Remote Paths
       *** POSIX and MSWindows Paths
    ** Internet Request For Comments (RFC) Document Browsing
    ** MANIFEST Files and Tables of Contents
    ** World Wide Web URL Buttons
    ** Email Addresses
    ** Action Buttons
       *** Using Action Buttons
       *** Defining New Action Button Types
    ** Github (Remote) References
    ** Gitlab (Remote) References
    ** Git (Local) References
    ** Grep, Occurrence, Debugger and Compiler Error Buttons, and Cscope Analyzer Lines
    ** Annotated Bibliography Buttons
    ** Completion Selection
    ** Hyperbole Source Buttons
    ** UNIX Man Apropos Buttons
    ** Site-specific Online Library Document IDs

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 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 it performs.  For example,
an Action Key press on a double-quoted pathname displays it.  (This is
because an implicit button type of 'pathname' is recognized and it has
an associated action type of 'hpath:find' which displays the path in a
window specified by the setting of 'hpath:display-where').

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
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.

Hyperbole has many built-in implicit button types, a number of which you
will see here.  You may also create your own types through the use of
regular expressions or via Emacs Lisp, see "(hyperbole)Creating Implicit
Button 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.

Individual implicit buttons may be labeled so that they can 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"

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 let's explore some implicit button types.

** 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.
Another press here: {C-x o m implicit\ buttons RET} should jump to the
Implicit Buttons section of the manual.

Now when you write notes about particular global key sequences you want to
remember, just surround them with curly braces and you'll always be able to
try them out with a simple click or press.  You can even create your own
demonstrations and tours with this and other implicit button types.

** Org Mode

For users of Emacs Org mode, Hyperbole does quite a few things when
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 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.

  4. Follow other internal links in Org mode files.

  5. Follow Org mode external links.

  6. When on a Hyperbole button, activate the button.

  7. With point on the :dir path of a code block definition, display the
     directory given by the path.

  8. With point on any #+BEGIN_SRC, #+END_SRC, #+RESULTS, #+begin_example
     or #+end_example header, execute the code block via the Org mode
     standard binding of {C-c C-c}, (org-ctrl-c-ctrl-c).
  
  9. When point is on an Org mode heading, cycle the view of the subtree
     at point.

  10. In any other context besides the end of a line, invoke the Org mode
      standard binding of {M-RET}, (org-meta-return).

To disable ALL Hyperbole support within Org major and minor modes, set
the custom option `hsys-org-enable-smart-keys' to nil.  Then the
Action Key will simply invoke the Org mode standard binding of
{M-RET}, (org-meta-return).

** Implicit Path Links

Any existing absolute or relative pathname (whether doubly quoted or not)
acts as an implicit button that either displays the referenced path within a
buffer, passes it to an external viewer program, or runs a function that
operates upon the path.  These are `pathname' implicit buttons.  For example,
activate "HY-ABOUT".  HY-ABOUT or `HY-ABOUT' would work as well.   Or try
"~/.emacs".  Pathname implicit buttons provide one example of how Hyperbole
can improve your working environment without requiring any work from you.

*** Paths with Line and Column Numbers

If you want to display a path at a specific line number and optionally column
number, then add each number preceded by a colon at the end of the path.
For example, "HY-ABOUT:10" displays HY-ABOUT at line 10, the second
paragraph, with point at the start of the line.  "HY-ABOUT:17:7" shows the
first numbered item on line 17 at column 7, where the text starts.

*** HTML Markdown and Emacs Outline Hash Links

Often links to HTML and Markdown files use a hash mark (#) plus an identifier
to refer to a section of such files.  When the Action Key is pressed on any
such reference, it jumps to the section referenced by the link.

For example, "man/hyperbole.html#Smart-Keys" will take you to the Smart Keys
description in the HTML version of the Hyperbole manual.  Inside that manual
in HTML form, "#Smart-Keys" would do the same thing.  Similarly,
"README.md#why-was-hyperbole-developed" jumps to the referenced section of
that Markdown file, while accounting for the difference in case, whitespace
and trailing punctuation between the identifier and the section header.
(Inline Markdown links surrounded by parentheses and square bracketed
reference links work similarly but are handled specifically as Markdown
links, not as pathnames).

Hyperbole allows hash-style links to Emacs outline files (including Org-mode
files); they work just like the Markdown section links but match to section
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
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
social media hashtags (see "#Social Media Hashtags and Usernames").

*** Path Suffixes and Variables

Most file path buttons directly name their associated files in full, but
Hyperbole can also add file name suffixes and resolve Emacs and environment
variables within path buttons.  If you have the source code for your Emacs
installation, then there is a Lisp library, simple.el.gz, stored in
compressed form within a directory listed in the variable, load-path.  An
Action Key press on "${load-path}/simple.el" will dynamically locate the file
within load-path, uncompress it and display it for editing.  There is no need
to know whether the file is compressed or not or what values are set for
load-path at your particular location.  Thus, you can provide path links that
vary from site to site, especially handy if you email Hyperbole buttons to
your associates.  Shell environment variables also work.  To see your home
directory, try "${HOME}".  Press the Action Key within the quoted text of
"(hyperbole)Link Variable Substitution" for a bit more on this topic.

For the special cases of Emacs Lisp files and Info manual files, you can omit
the variable of directories to search since Hyperbole knows them already.
Thus an Action Key press on "simple.el", "hyperbole.info" or even
"(hyperbole)" will display these properly as well.

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
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:
hpath:external-display-alist-macos, hpath:external-display-alist-mswindows,
and hpath:external-display-alist-x.  Examine and modify these
values to suit your needs.

Under the X Window System, if you have the `xv' program, all of the following
file formats may be displayed externally as images: gif, tiff, xbm, pm, pbm,
and jpeg.  Under X or Mac OS, try a press of the Action Key on
"man/hyperbole.pdf" to browse the printable version of the Hyperbole Manual.

*** Path Prefixes

Several prefix characters may be attached to pathnames to indicate that a
different action should be taken when the button is activated.  An
exclamation point prefix indicates that the full pathname should be run as a
non-windowed shell program.  For example, try "!${PATH}/date" on a POSIX
system.  This will run the program in a subshell within Emacs.  An ampersand
prefix means run the full pathname as a windowed program, outside of Emacs.
Under the X window system, try "&${PATH}/xeyes".  Finally, a hyphen indicates
that the filename should be executed as an Emacs Lisp library,
e.g. "-subr.elc", rather than displayed.

*** Info Paths

Double quoted GNU Info manual references of the form "(filename)refname"
work as implicit buttons that display the associated referent in the Emacs Info
Browser.  Thus, Action Key presses on "(hyperbole)Glossary" or "(emacs)Glossary",
take you right there.  Typically, you exclude any path and file suffix from
the filename.

Refname can be an Info node name or any Info index item (an item listed in
any of a manual's indices).  Index items let you jump to a specific,
referenced point within an Info node.  As an example, suppose you want quick
access to a summary of Hyperbole's key bindings.  Store "(hyperbole)key
binding list" in your personal file of buttons (accessed with {C-h h b p})
and you will always have quick access to a list of Hyperbole's key
bindings.  Press the Action Key on the Info reference and try it.  Press the
Action Key on the key binding of your personal button file and then store the
implicit link there if you like.

Since Emacs and most GNU programs include Info manuals, you now have a simple
way to link to and jump to any named item within a manual.

*** Remote Paths

If you use the standard Emacs library "tramp.el" for working with remote
files and directories, then remote pathnames of the form:

    /protocol:user@host.domain:/path

will be recognized by Hyperbole.

Once you have Tramp configured for loading and are on the Internet, you can
press on any of the following to jump to the ftp site of Hyperbole tarball
distributions:

    /ftp:anonymous@ftp.gnu.org:/pub/gnu/hyperbole/

For Tramp pathnames, Hyperbole recognizes them with or without double quote
delimiters.

If you enable the Hyperbole option to use URLs when finding files with
the {C-x C-f} (find-file) command via the {C-h h c f} key sequence, then
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
standard-making.  Simply use the Action Key on an RFC document identifier,
like RFC-822 or rfc 822, and the RFC will be retrieved and displayed for
browsing.  The `rfc' implicit button type provides this service.  The
`hpath:rfc' variable specifies the location from which to retrieve RFCs.

Once you have retrieved an RFC, an Action Key press most anywhere within a
line typically will produce a table of contents summary of the RFC (via the
`rfc-toc' implicit button type).  An Action Key press on any of the table of
contents lines then displays that section, for easy sectional browsing.

** MANIFEST Files and Tables of Contents

Now suppose you want to browse through a number of files within the Hyperbole
distribution.  You could use the Emacs dired subsystem, "(emacs)Dired", but a
faster way is to note that files named MANIFEST and DIR are used to summarize
the files in a directory, so we can use each of their entries as an implicit
button (of type `dir-summary') to take us to the file.

Let's look at "MANIFEST".  Now press anywhere within a line in the MANIFEST
file and you see that it is displayed as expected.  (Remember to use the
Hyperbole history command to return here.)  You can get help on these buttons
just like any others.

In README files, such as Hyperbole's "README.md", table of contents entries
act similarly.  Press on "README.md" to view that file and then press on a
table of contents entry to jump to the associated section in the "README.md"
file.  Or "README.md#User Quotes" goes directly to that section.

** World Wide Web URL Buttons

You can browse URLs (universal resource locators) from within any buffer once
Hyperbole is loaded.  Hyperbole's Cust (Customization) menu allows you to set
the web browser used for display (this is turn sets the standard Emacs
"browse-url.el" library settings).

Try using the Action Key on:  "http://www.gnu.org".

Full and abbreviated web and ftp URLs, e.g. www.gnu.org, are 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, hypb: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

*** Using Action Buttons

A new feature of Hyperbole is a universal syntax for creating implicit
buttons known as Action Buttons.  These buttons execute any existing
action types or Emacs Lisp symbols.  They are delimited by angle
brackets, < >, and come in three types:

  1. action type invocations - these begin with an action type name (from the
     list displayed by {C-h h d t a RET}) and are followed by any needed
     arguments to form the action, e.g.

          <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.  They may
     contain any number of levels of embedded Lisp s-expressions, e.g.

          <find-file-other-window (expand-file-name "kotl/EXAMPLE.kotl" hyperb:dir)>

  3. variable displays - these consist of an Elisp variable name only and
     display a message with the variable name and value, e.g.

          <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 '$', e.g.

          <$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.

With Action Buttons you need not remember any special syntax for each type of
implicit button.  You can freely embed them in any type of text and use the
Action and Assist keys on them as you do with any other type of implicit
button.

*** Defining New Action Button Types

You can do many things with existing Action Button types but sometimes you
may want to define your own types for more advanced usage.  Hyperbole lets
you easily create your own Action Button link types without knowing Elisp, if
you understand basic regular expression-based pattern replacement.

In your Emacs initialization file, e.g. ~/.emacs, you will add a line of
the form:

    (defal TYPE LINK-EXPR &optional DOC)

where:

    TYPE is the name of the new type you want to create;

    LINK-EXPR is 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 may 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 a button of this new type is activated, the button text following
the type is substituted into LINK-EXPR.  After which, the button is
activated as one of these 4 kinds:
    (1) a brace-delimited key series;
    (2) a URL/web link;
    (3) a path (possibly with trailing colon-separated line and column numbers);
    (4) or a function or action type of one argument, the button text sans the
        function name.

Let's try an example.  If you use Python and have a PYTHONLIBPATH
environment variable, then pressing {C-x C-e} after this expression:

   (defal pylib "${PYTHONLIBPATH}/%s")

defines a new action button link type called 'pylib’ whose buttons
take the form of:

   <pylib PYTHON-LIBRARY-FILENAME>

and display the associated Python libraries (typically Python source
files).  Optional colon separated line and column numbers may be given
as well.

Now press the Action Key press within:

   <pylib string.py:5:7>

This will display the source for "string.py" (wherever it is installed
on your system) from the Python standard library with point on the
fifth line at the seventh character.

----

As another example, suppose you want to do a web search for Emacs Lisp
libraries whose names may be very generic, like hyperbole.  For this,
you can use a Google filetype-specific search.

Define an action link type with:

    (defal elsearch "https://www.google.com/search?q=%s+filetype:el"
           "Find Elisp libraries via a Google file type search")

Then, an Action Key press on:

    <elsearch burly>

will find major links to that library which makes window
configurations and framesets persistent across Emacs sessions.

This search is actually built in to the Hyperbole menus, so you could
have defined it more simply (and sans docstring) with a key series
definition:

    (defal elsearch "{C-hhfwe %s RET}")

as well.

----

For more advanced and flexible regular expression-based link type
creation, see the 'defil' expression in "(hyperbole)Implicit Button
Link Types".  For any type of implicit button type creation using
ELisp, see 'defib' in "(hyperbole)Programmatic Implicit Button Types".

** Social Media Hashtags and Usernames

An Action Key press on a social media hashtag or username reference at point
displays the web page associated with the reference at the associated
service.  References are of the form:

             [facebook|instagram|twitter][#@]<hashtag-or-username>
          or
             [fb|in|tw][#@]<hashtag-or-username>.

If the service is omitted and there is no other usage of a hash reference
without a prefix in the buffer, then the service defaults to the value of
`hibtypes-social-default-service', which is initially "twitter".

For example, these make the same hashtag reference: twitter#gnu or tw#gnu
and display the page for tweets with that hashtag.  Similarly, in@lostart or
instagram@lostart would display the page for the user lostart at instagram.
Try pressing the Action Key on these if you like.

The file "hib-social.el" has more details on this.

** Github (Remote) References

For software developers who use Github for publishing and version control,
Github links are similar to social media links but reference specific Github
web pages.

Press the Action Key on github@rswgnu to go to RSW's gihub home page.
gh@rswgnu works too. 

References to project home pages look like this (the / is required):

  github#/hyperbole           (uses user default setting)
  github#/rswgnu/hyperbole

References to specific commits use the # hash symbol and short versions
of the git commit hash code:

  gh#rswgnu/hyperbole/5ae3550 (if include user, must include project)
  github#hyperbole/5ae3550    (project can be given with user default)
  gh#5ae3550                  (user and project defaults are used)

An Action Key press on the first commit reference above works because
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
git repositories.  If you have a clone of the Hyperbole git repository
on your local system, then you can activate all of the following buttons.

  git#/hyperbole            (displays the top directory of the hyperbole repository)
  git#/hyperbole/55a1f0     (displays hyperbole git commit diff)
  git#=hactypes.el          (displays a git-versioned file regardless of directory)
  git#=master:kotl/kview.el (displays file in subdirectory from master branch)
  gt#55a1f0                 (when within a git repo, displays its commit diff)

The first four examples work anywhere regardless of the buffer since Hyperbole
locates all git repositories for you by repository/project name.  If you set a
default project, then the last example will work anywhere as well.

** Grep, Occurrence, Debugger and Compiler Error Buttons, and Cscope Analyzer Lines

The output of `grep -n', the UNIX line pattern matcher, can be activated as
buttons that jump to each matched line within its source file; use {M-x grep
RET} or even better, the Hyperbole recursive directory grep, {C-h h f g}.

Compiler error messages also serve as implicit buttons that jump to
associated source lines; use {M-x compile RET}.  GDB, DBX or XDB stack frames
along with GDB breakpoint listing lines also link to source lines.

{C-h h f o} or {M-x occur RET} (find matches in a single buffer) and {C-h h f
m} or {M-x moccur RET} (find matches across multiple buffers and files) also
produce implicit button output that display associated source lines.

If you have the Cscope C/C++ code analyzer from the AT&T Toolchest and have
loaded the cscope.el library add-on for GNU Emacs, then the output lines
from a cscope query serve as implicit buttons which jump to associated
source lines.  Cscope goes beyond the basic Emacs tags facility to allow you
to see the callers of a function and the functions called by a specific
routine.

Many of these find-a-line features exist in the Hyperbole Find/ menu,
{C-h h f}.  Give it a try for fast access to complex file line filters,
e.g. filter a file to just lines that don't match a pattern (RemoveLines).

** Completion Selection

Often when Emacs or Hyperbole prompts for an argument in the
minibuffer, a list of possible argument completions is available by
pressing {?} or automatically displayed.  A single Action Key press on
any of these completions inserts it into the minibuffer for your
inspection.  A second press on the same completion uses it as the
argument value and moves on to any next minibuffer argument prompt.
Test this technique with a {C-x C-f} (find-file) and then a {?}.

Within the minibuffer itself, the Smart Keys are also
context-sensitive.  A press of the Action Key at the end of the
argument line tries to accept the argument and when successful, exits
the minibuffer.  A press of the Assist Key at the end of the argument
line displays matching completions for times when they are not
automatically displayed or need updating.  A press of the Action or
Assist Key on part of the argument, deletes from point to the end of
the line, expanding the set of available completions and redisplaying
them.

** Hyperbole Source Buttons

If you ask for a report on all the explicit buttons in this buffer
with {C-h h e h b}, the first line of the resulting help buffer will
look like this:

@loc> "DEMO"

except it will contain the full pathname of the file.  If the buttons were
embedded within a buffer without an attached file, the first line of the help
buffer might look like:

@loc> #<buffer *scratch*>

If you press the Action Key on the buffer name, the buffer will be displayed
just as a file buffer would.  This type of implicit button is called a
`hyp-source' button.

You can also activate any explicit buttons (see "#Explicit Buttons") shown in
help buffers thanks to hyp-source buttons.

** UNIX Man Apropos Buttons

Below are some lines output by the UNIX `apropos' command (with a little
touchup for display purposes).  A button activation anywhere within such a
line recognizes the line as an apropos entry and displays the man page for
the entry.  Try it.

grep, egrep, fgrep (1) - search a file for a string or regular expression
rm (1)                 - remove (unlink) files or directories
touch (1)              - update the access and modification times of a file
cat (1)                - concatenate and display 

** Site-specific Online Library Document IDs

Hyperbole offers a powerful, yet easy to use facility for building online
libraries through the use of the `doc-id' implicit button type.  A document
id is used just like a reference citation in traditional publications but it
actually links to the document that it references and the card catalog
(index) entry for the document.  One can easily pass around doc ids to point
people to appropriate documents.  For example, a mail message in response to
a question might say, "See [Emacs-001] for examples of what Emacs can do."

Since the format and handling of document identifiers and their index
entries is site-specific, document id handling is not completely configured
in a default Hyperbole configuration.  If you wish to setup this facility
for site or personal use, see the DESCRIPTION section in "hib-doc-id.el" for
installation and use information.


* Explicit Buttons

Beyond implicit buttons recognized in-context by Hyperbole, Hyperbole also
offers `explicit buttons' that you create and embed within documents.  As you
have seen, 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 depressed on
a draggable item).

This button prints the <(factorial)> of 5 in the minibuffer when activated
with the Action Key.  If you instead press the Assist Key, you get help for
the preceding button.  The help offered is a summary report of the button.
You will see that it utilizes the `eval-elisp' action type.  You can also see
who created it.  Try it.  {q} will quit the summary report display.

Note that the create-time and mod-time are displayed using your own timezone
but they are stored as universal times.  So if you work with people at other
sites, you can mix their buttons with your own within the same document and
see one unified view of the modification times on each button.

Every explicit button utilizes an `action type', many of which are predefined
by Hyperbole.  {C-h h e t RET} lists all Hyperbole action types but Emacs Lisp
commands may be utilized as well.

Hyperbole is pretty forgiving about the format of explicit buttons.  For
example, all of the following represent the same button, as long as you press
on the *first* line of the button, within the button delimiters:

  <(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 or can utilize the Assist Key to verify what
buttons do.  There are two ways to create them: by dragging between windows
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 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
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 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 Assist
Mouse Key at the start point of the link referent.  The process
becomes quite simple with a little practice.

Hyperbole uses the link referent context to determine the type of link
to make.  If there are a few different types of links which are
applicable from the context, you will be prompted with a list of the
types.  Simply use the Action Key or the first letter of the link
type to select one of the type names and to finish the link creation.
Hyperbole will then insert explicit button delimiters around the button
label and display a message in the minibuffer indicating both the
button name and its action/link type.

When a link is created, if its path contains a match for any of the variable
values listed in hpath:variables, then the variable's name surrounded by ${
} delimiters is substituted for the literal value.  Hyperbole then replaces
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 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 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`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

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.

After Hyperbole has the button label and its target buffer, it will prompt
you for an action type for the button.  Use the {?} completion list key to
see all of the available types.  The type selected determines any following
values for which you are prompted.

If a previous button with the same label exists in the same buffer, Hyperbole
will add an instance number to the label when it adds the delimiters so that
the name is unique.  Thus, you don't have to worry about accidental button
name conflicts.  If you want the same button to appear in multiple places
within the buffer, just copy and paste the button with its delimiters.
Hyperbole will interpret all occurrences of the same delimited label within a
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 (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.

** Sample Explicit Buttons and Types

Below we demonstrate some uses and types of explicit buttons.

Activation of the next button will tell you about <(keyboard macros)>.  Can't
remember a Hyperbole term?  Check out the Hyperbole Manual <(glossary)>.

Here is a <(keyboard macro)> button.  It displays documentation for the
first Emacs Lisp function that follows it, e.g. (hbut:report).  You can see
that a button label may consist of many characters, up to a set <(maximum
length)>.

A <(shell command)> button can do many things, such as display the length of
this file.  While such commands are executing, you can perform other
operations.  If you create a button that runs a shell command which displays
its own window system window, i.e. a window outside of Emacs, use
`exec-window-cmd' rather than `exec-shell-cmd' as its action type.

You can link to files such as your <(.emacs)> file.  Or directories, like
the <(tmp directory)>.  When creating file links, if the file you are
linking to is loaded in a buffer, you are prompted as to whether you want
the link to jump to the present point in that buffer.  If so, the link will
always jump there, so position point within the referent file to take
advantage of this feature.  Note how a separate window is used when you
activate file link buttons.  Most basic Hyperbole action types display their
results in this manner.

You can create buttons that run specific web searches such as a Wikipedia
query on an <(electric car)> with the `link-to-web-search' action type.

You can make a button an alias for another by using the `link-to-ebut'
action type.  This <(factorial alias)> button does whatever the earlier
<(factorial)> button does.


* Button Files

It is often convenient to create files filled with buttons as a means
of navigating distributed information pools or for other purposes.
These files can also serve as useful roadmaps that guide you through
both unfamiliar and highly familiar information spaces.  Files that are
created specifically for this purpose are called "Hyperbole button
files".

Hyperbole's ButFile menu provides quick access to two types of these
button files.  Your personal button file is stored in
"${hbmap:dir-user}/HYPB" and accessed with {C-h h b p}.  Per-directory
button files are stored in the respective directories and are also
named "HYPB".  Access the current one with {C-h h b d}.

If you want group and site-specific button files, simply place links
to such files at the top of your personal button file and do so for your
colleagues.  This provides a flexible means of connecting to such
resources.


* 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
may be explicit buttons or labeled/named 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}

Or bind the global button activation command, hui:gbut-act, to a key
of your choice for even faster access to all of your global buttons.

Let's create a global button that counts the lines in the current
buffer and displays the count in the minibuffer.  Press the Action Key
on the first line of this key series to create the global button named
"line-count":

     {C-h h g c line-count RET eval-elisp RET
      (message "Lines in %s = %s"
               (buffer-name) (count-lines (point-min) (point-max))) RET}

Then activate it with {C-h h g a line-count RET}. Try it out in
different buffers.

To avoid embedding such code in the button itself, just define a
function in your Emacs initialization file and then activate that:

(defun line-count ()
  (interactive)
  (message "Lines in %s = %s"
           (buffer-name) (count-lines (point-min) (point-max))))

Then button creation would be:

     {C-h h g c line-count RET eval-elisp RET (line-count) RET}

and activation would be the same as above.

Defining a link to a file section is even easier, say to the section
below here:

     {C-h h g c smk RET link-to-file RET "DEMO#Smart Mouse Keys" RET}

Then from anywhere:

     {C-h h g a smk RET}

will activate it.


* Smart Mouse Keys

If you use Emacs with mouse support under the macOS window system, the
X Window System or MS Windows, Hyperbole automatically configures your
mouse keys for use as Smart Keys and provides additional
display-oriented operations as demonstrated here.

See the Hyperbole menu item, Doc/SmartKeys {C-h h d s}, for a summary of
all Smart Key operations.  For extensive details on Smart Key operation,
see the Hyperbole manual section, "(hyperbole)Smart Key Reference".

If you ever want to disable Hyperbole key and mouse bindings, simply toggle
Hyperbole minor mode off with {M-x hyperbole-mode RET}.  Alternatively, you may
select a key and bind it as part of any setting of `hyperbole-init-hook'
within your personal .emacs file.

For example:
  (add-hook 'hyperbole-init-hook
   (lambda () (global-set-key <YOUR-KEY-HERE> 'hyperbole-mode)))

** Thing Selection

Hyperbole has some radically cool ways to select, copy and move
regions of structured text or source code that we call `things'.  You
can copy or move things between buffers with a single mouse drag or
two key presses.  A great deal of smarts are built-in so that it does
the right thing most of the time.

Things are structured entities that Hyperbole can select and
manipulate.  These include: delimited pairs of (), {}, <>, [] and
quote marks, source code functions, source code comments and matching
tag pairs in HTML and SGML modes.  Delimited things are those things
that contain a selectable delimiter such as an opening parenthesis.

The best way to mark a delimited thing is to move your cursor to the
starting delimiter of the thing and then press the Action Key.  Typically,
you will see the thing highlight.  You can then operate upon it as you
would any Emacs region.  An Action Key press on the start of an HTML or
SGML tag pair marks the entire region span of the pair.  If you use the
Assist Key instead, it will mark and kill (delete) the thing.

Even better are Smart Mouse Key drags which let you copy or move delimited
things in one operation without even highlighting them.  To copy, simply
drag with the Action Key from a thing's opening delimiter and release
somewhere outside of the thing, either within the same window or within
another window.  The thing will be copied to the point of release.  If you
want to move a thing, simply perform the same drag but with the Assist
Mouse Key.  Ensure that you do not move any explicit buttons from one
buffer to another as that does not work.

Try out some of these operations in HTML or source code files to see
how they can speed your editing.

Hyperbole also binds two convenience keys for working with things.

{C-c RET} selects bigger and bigger syntactic regions with each successive
use.  Double or triple clicks of the Selection Key (left mouse key) do the
same thing.  The first press selects a region based upon the character at
point.  For example, with point over an opening or closing grouping
character, such as { or }, the whole grouping is selected, e.g. a C
function.  When on an _ or - within a programming language variable name,
the whole name is selected.  The type of selection is displayed in the
minibuffer as feedback.  When using a language based mainly on indenting,
like Bourne shell, a double click on the first alpha character of a line,
such as an if statement, selects the whole statement.  Use {C-g} to unmark
the region when done.

The second convenience key is bound only in HTML/web mode.  {C-c .} jumps
between the opening and closing tag of a pair.  It moves point to the start
of the tag paired with the closest tag that point is within or which it
precedes.  A second press moves point to the matching tag of the pair,
allowing you to quickly jump back and forth between opening and closing
tags.

** Context-sensitive Help

Since the Smart Keys perform different operations in different contexts, it
is important to have context-sensitive help available.  The earlier section
on Help Buffers explained how to display such help from the keyboard.  The
same help can be displayed using the mouse by depressing the Smart Key for
which you want help, performing any action necessary to register a context,
such as a drag motion, and then pressing the other Smart Key and releasing
both.

Here is an example.  Depress the Action Mouse Key somewhere within this
paragraph and while holding it down, depress the Assist Mouse Key.  Then
release the keys in any order and the help display will pop up.  It
explains the context in which the Action Mouse Key was pressed and what it
does in that context.  Try it.  Basically, you just depress the Smart
Mouse Key you want help for and while holding it down, depress the other
Smart Mouse Key to get help.  If you use the mouse a lot, this is a great
key combination to master as it will let you explore the many different
contextual actions that Hyperbole offers without having to trigger any of
them.

** Creating and Deleting Windows

Horizontal and vertical drags of the Smart Mouse Keys are used to split and
delete Emacs windows.

An Action Mouse Key horizontal drag of five or more characters in either
direction within a single window creates a new window by splitting the
current window into two windows, one on top of the other.  An Action Mouse
Key vertical drag in either direction splits the current window into two
side-by-side windows.  A horizontal or vertical drag of the Assist Mouse Key
within a single window, deletes that window.

Let's try these.  You need only move your mouse pointer a few characters to
register a drag.  First, split this window with an Action Key horizontal
drag.  Then click the Assist Key on the buffer name in the modeline of one of
the windows to change the buffer that it displays, so you can tell the windows
apart.  Then delete either one of the windows with a horizontal drag of the
Assist Key within the window.  If you split windows many times and then
delete a number of the windows, you'll be left with windows of differing
heights.  Use {C-x +} to re-balance the sizes of the remaining windows, so
they are fairly even.

Now try a side-by-side window split.  Drag vertically with the Action Key by
three or more lines to split the window.  Again, change the buffer of one of
the windows.  Then use a vertical Assist Key drag within either one of the
side-by-side windows to delete it.

** Resizing Windows

You can easily resize Emacs windows by dragging their window separators
(modelines or vertical side lines) within a frame.  Simply depress either
Smart Key on a modeline or near a window side, hold it down while you drag
to a new location and then release.  The window separator will move to
the location of release.  Basically, just drag the window separator to where
you want it.  Nowadays a better version of Emacs window resizing exists on
the left mouse key.  Drags from a blank area of a modeline show visible
feedback as the window is resized.

Did you follow all that?  Let's try it to be sure.  First, you need at least
two windows, so create a new one with the drag techniques you just learned.
Now drag with either Smart Key from the shared window edge to a new location.
See how both windows change size?  For side-by-side windows, you drag from
just to the left of any window border controls and drag within this same
window.

Try to drag the bottom modeline.  You see that you can't; you would have to
resize the frame to move the bottom up.

** Moving Frames

Drags of either Smart Key from a bottommost modeline can be configured
to drag Emacs frames to new locations on screen.  See "(hyperbole)Moving Frames"
for how to configure this behavior.

** Dragging Buffers, Windows and Items

*** Swapping Buffers

Swapping buffer locations is quick and easy with Hyperbole.  Simply drag from
one window to another with the Assist Key (not the Action Key).

Split the current window into two, one above the other.  Drag the upper
modeline so that one window is clearly bigger than the other.  Now switch to
another buffer in one of the windows.  Then depress your Assist (not Action)
Mouse Key within one window, drag to the other window and release the key.
Boom, the buffers are swapped.  This works across frames as well.

If you have just two windows in an Emacs frame, you can swap their buffers
from the keyboard.  Use this Hyperbole minibuffer menu key sequence to swap
the buffers and quit from the Hyperbole minibuffer menu: {C-h h s w ~ Q}.
Similarly, if you have two single window frames, you can swap buffers between
them with {C-h h s f ~ Q}.

*** Displaying Buffers

What if you want to display the same buffer in another window and not swap
buffers?  Depress the Action Key in the open area of the modeline of the source
window and drag to the text area of the destination window.  Voila, the buffer
appears in the new location as well as the old one.

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 Items via Drags and Moving Buffers

You can do the same thing with items in dired, buffer menu and ibuffer menu
listing buffers as well as with Hyperbole button referents.  Drag with the
Action Mouse Key from the item and the selected item/referent will be
displayed in the Emacs window in which you release.  To display the last
item you want, press the Action Key on it and it will display within the
listing window itself.  (If you use the Treemacs file viewer package, item
dragging works there as well).  Under the MacOS window manager, you can also
drag outside of an Emacs frame and the item will be displayed in a newly
created and selected frame.

So now you can rapidly put a bunch of buffers and files on your screen wherever
you like.  Typically, a brief visual pulse is shown first at the source item and
then in the destination window, to help you see that the transfer has been
made.  An Assist Key Drag will move 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 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> to display it there and select
the window.

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,
without changing the 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.

You can also throw the active (highlighted) region of text to another window.
Simply activate a region and then use M-o t <window-id> just like before.  If
you don't use region highlighting, i.e. transient-mark-mode, then use C-u M-o t
<window-id> for the same effect.  The buffer in the target window must differ
from the one in the source window.  With no region active, this command throws
the source buffer to the target window.

*** Cloning Windows

To clone a window with its buffer to a new frame, simply drag the Action Mouse
Key from the window to outside of Emacs and release the key.  A new frame will
be created, selected and sized according to the original window.  Do the same
thing with the Assist Mouse Key and the original window will be deleted as well,
unless it is the only window in that frame.  Create a few windows and try these
actions.

** Window Configuration Drags

A window configuration consists of the set of windows within a single Emacs
frame.  This includes their locations, buffers, and scrolled positions of
their buffers.

Hyperbole allows you to save and restore window configurations with simple
diagonal mouse drags within a single window.  A diagonal drag in any
direction of the Action Key saves the current window configuration to a ring
of window configurations, just like the Emacs text kill ring.  (See
"(Emacs)Kill Ring".)  Each diagonal drag in any direction of the Assist Key
restores a prior saved window configuration from the ring.  Window
configurations are restored in reverse order of the way they were saved.
Since a ring is circular, after the oldest element is restored, the newest
element will again be restored and so on.

If these operations are unclear to you, just forget about them and move on.
They are not necessary to enjoy the rest of Hyperbole.  Otherwise, give them
a try by creating various window configurations and then saving and
restoring them.

** Modeline Mouse Clicks

Smart Mouse Key clicks on window modelines are treated specially by
Hyperbole.  They are broken up into separate regions, each with their own
Smart Mouse Key operations.  The regions are: the left edge, the buffer ID,
the blank middle portion (the non-edge part of the modeline), and the right
edge.  The edge regions are the left first character and the rightmost three
characters of the modeline, by default.

*** Switching to Another Buffer

An Action Key click in the left edge of a modeline buries the current buffer,
i.e. puts it on the bottom of the buffer list and removes it from view, if it
is not the only available buffer.  An Assist Key click in the left edge of a
modeline unburies the bottom buffer.  Repeated clicks of either key allow you
to cycle through buffers to get to the one you want.  Try this out.  A
similar thing can be accomplished by using the left mouse key and the Assist
Mouse Key on the modeline buffer name if you need a wider space as a target.

*** Running Dired on the Current Directory

An Action Key click on the modeline buffer name runs dired on the current
directory.  An Action key click on an item in the dired buffer, displays the
item.  An Action Key click on part of the directory name in the first line of
the dired buffer runs dired on the ancestor directory given by the text to
the left of the click location.  A click at the end of the first line quits
the dired session.

*** Displaying Documentation

An Action Key click in the right edge of a modeline displays the Info manual
browsing system, see "(info)".  Once in Info, you can click with your Action
Key to follow menu items, cross references, or to jump to Info nodes
referenced within the top header line of a node.  Try browsing a bit and
while in Info, display context-sensitive help for both the Action and Assist
Keys to see all that they can do.

If you click again with the Action Key on the right edge of the window
displaying Info, it will hide the Info buffer.  Thus, it works as a toggle to
display or to hide the Info buffer.  Isn't that easy?

A click of the Assist Key at the right edge of a modeline toggles between
display and removal of the Smart Key operation summary.  To remove the summary,
you must click on the modeline of the window displaying the summary.

*** Buffer Menu and Screen Control

An Action Key click in the blank center portion of a modeline displays
a buffer menu, a summary of available buffers.  An Action Key click on
any buffer menu line then displays that buffer and closes the buffer
menu.

If you want to display several buffers, first create some new windows, then
display the buffer menu and drag from each buffer name to the window in which
you want it displayed.  This works across frames and also works in ibuffer
and dired modes too!  Try it now.

Alternatively, you may display the buffer menu, use its {m} command to mark
buffers and then use the {@} command to display the marked buffers in a grid
of popup windows whose number of rows and columns you specify at the prompt
or via a prefix argument.  This also works in ibuffer-menu and dired modes.

An Assist Key click in the blank center portion of a modeline pops up
a menu of convenient screen commands that lets you select buffers
grouped by major mode, use HyControl, or jump to specific windows,
window configurations or frames.

See "(hyperbole)action-key-modeline-function" for how to adjust this
behavior.

* Epilog

We hope you have enjoyed this introduction to Hyperbole. It can be your
ever-ready sidekick in your daily knowledge work.  Explore the Hyperbole
menus to learn more interactively.  For reference, the Hyperbole Manual, has
extensive detail about the many things that Hyperbole does when you are ready
to dive deeper.  Read it online with the GNU Info reader at "(hyperbole)Top".

* THE END