* GNU Hyperbole Demonstration by Bob Weiner

  Say thanks if you like Hyperbole: https://saythanks.io/to/rswgnu

    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 types
and shows how Hyperbole can support a style of self-documenting, interactive
files.  See the glossary in the Hyperbole Manual, "(hyperbole)Glossary", if
terms used here are unfamiliar to you.

Once you read the next section on "#Smart Keys", you can then browse any
other sections individually as you like.  Many people initially use Hyperbole
for its "#Implicit Buttons" capabilities, so you may want to jump to that
section.


* 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 letter of any menu item (upper or lower case 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.

A press of {q} or {C-g} will quit from the current menu without invoking any
commands.  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.

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

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}.
Then type {g} for Google and enter "GNU Hyperbole", 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} 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.  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 series'.  Press the
action key within the braces: {.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}.  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
prompted for the major mode and then the size of the grid.

To try it, activate: {C-hhsf .0 @}.

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.

Outside of HyControl, you can invoke the grid of windows command with {C-c @}
in most buffers.

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

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

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.

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.  Once
in the Info browser, use {s} to search for any topic throughout 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.

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.

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

** Action Buttons

A new feature of Hyperbole is a universal syntax for creating implicit
buttons known as Action Buttons that execute any existing action types or
Emacs Lisp functions.  Such buttons 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" 40>

  2. function calls - these are similar to action type invocations but begin
     with an Elisp function name rather than an action type name, e.g.

          <find-file-other-window "/tmp">

  3. variable displays - these consist of just an Elisp variable name 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.

          <$fill-column>

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.

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.

** 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 global 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 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", table of contents entries
act similarly.  Press on "README" to view that file and then press on a
table of contents entry to jump to the associated section in the "README"
file.  Or "README#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, mail-address-mode-list.  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.

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

** Annotated Bibliography Buttons

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.

** Completion Selection

Often when Emacs or Hyperbole prompts for an argument in the minibuffer, a
list of possible argument completions is available by pressing {?}.  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 causes it to be
used as the argument value and any succeeding argument prompt is then
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-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"

except it will contain the full pathname of the file.  If the button 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.

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 action types available to you when
creating explicit buttons and specifying their types.

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 Modifying 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 Action Mouse Key or by using the Hyperbole menus.

*** Creation via Dragging

The most efficient way to create an explicit button interactively is to use
the Action Mouse Key to drag from a button source window to a window showing
its link referent.  More specifically, you should split your current Emacs
frame into two windows: one which contains the point at which you want a
button to be inserted and another which shows the point to which you want to
link.  Depress the Action Mouse Key at the source point for the button
(anywhere but on a paired delimiter such as double quotes or parentheses).
Then drag to the other window and release the Action Mouse Key at the start
point of the link referent.  The process becomes quite simple with a little
practice.

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

*** 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 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.  Mark the region of text to use as your button label,
invoke the button create command from the menu, choose an action type which
begins with `link-to-' and then use the direct selection techniques mentioned
in "(hyperbole)Smart Key Argument Selection", to select the link referent.

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.

The `link-to-mail' action type allows you to reference mail messages that
you have stored away.  We can't demonstrate it here since we don't have the
mail messages that you do.

Hyperbole buttons may also be embedded within mail messages.  Even buttons
copied into mail replies can work:

    Emile said:
    >
    > Hyperbole is better than home baked bread but not as filling.
    > The following sample button displays a message, <(as long as 
    > you press within its first line)>.

Please note that support for explicit Hyperbole buttons within mail and
USENET news messages has not yet been updated for use with Emacs 24 and 25,
so these features are disabled by default.  If you want to try them knowing
this, {C-h h c m} will toggle this feature on and off.


* 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, as explained above.  All global buttons are activated by name
with completion provided, independent of which buffers are displayed.
Global buttons may be explicit buttons or labeled/named implicit
buttons.

The Hyperbole Gbut menu 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.

A good strategy for frequently used global buttons is to use short
names that you can remember.  Then they can be activated quickly.

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:

     {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}, type its name and 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}

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}


* 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 restore the mouse bindings that existed before Hyperbole
was loaded, use the `hmouse-toggle-bindings' command.  It switches between
the Hyperbole mouse key bindings and those set prior to loading Hyperbole
and then back again if invoked once more.  There is no default key binding
for this command, so you must use `M-x hmouse-toggle-bindings 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> 'hmouse-toggle-bindings)))

** 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 Key somewhere within this paragraph
and while holding it down, depress the Assist Key.  Then release the keys in
any order and the help display will pop up.  It explains the context in
which the Action 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 then jump 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.  A drag with this key from a blank area of a modeline or
a window side divider shows 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.

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

*** 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 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
and the selected item will be displayed in any Emacs window in which you
release.  Drag outside Emacs and it will be displayed in a new frame.  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).

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

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

* References

[FSF 19] Free Software Foundation, Inc.  GNU Emacs Manual.  Free Software
Foundation, Cambridge: MA, 2019.  "(emacs)Top"

* THE END
