* Overview

This file demonstrates 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,
"(hypb.info)Glossary", if terms used here are unfamiliar to you.

* Smart Keys

** Button Activation and Help

This button prints the <(factorial)> of 5 in the minibuffer when activated
with the primary Smart Key, normally the middle mouse button or {M-RET} on
your keyboard.  (Once you have Hyperbole installed, just click on the word,
<(factorial)>.)  If you use the secondary Smart Key, normally the right mouse
button or {C-u M-RET}, you get help for the preceding button.  The help
provides 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.

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.  These times will also be useful for sorting buttons by
time when such features are provided in future Hyperbole releases.

** Smart Scrolling

You can scroll through this file by clicking after the end of
any line.  The primary Smart Key scrolls forward a windowful and the
secondary Smart key scrolls backward.  Try it and then come back
here.

By default, the variable smart-scroll-proportional is set to nil (FALSE),
which makes 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.  If it is set to t (TRUE), the primary Smart Key scrolls so that the
line clicked upon is placed at the top of the window; the secondary Smart Key
does the reverse, placing the line clicked upon 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.

Let's try proportional scrolling a bit.  Click this button and then practice
scrolling: <(toggle-scroll-proportional)>.  If you don't like proportional
scrolling, click on the previous button again to restore regular scrolling.
If you always want proportional scrolling, you'll have to add a setting of
smart-scroll-proportional to your "~/.emacs" file after the point at which
you load Hyperbole or else set it as part of hyperb:init-hook, which executes
whenever Hyperbole is loaded, e.g.:

   (setq hyperb:init-hook '((lambda () (setq smart-scroll-proportional t))))


** Hyperbole Menus

To display the top-level Hyperbole menu, click the Smart Key anywhere
within this paragraph or alternatively, use {C-h h}.  Clicking within the
paragraph, applies the default operation, given by smart-key-other-mode-cmd,
since the Smart Key finds no more specialized context.  The default
operation happens to bring up the Hyperbole menu.

{q} or {C-g} will quit from the menu without invoking any commands if you
just want to take a look.  A menu item is selected by pressing the Smart Key
over it or by typing its first letter in upper or lower case.

A click of the secondary Smart Key on a menu item gives help on it.


** Help Buffers

Context-sensitive Smart Key help typically is bound to {C-h S}.  {C-u C-h S}
displays the same kind of help for the secondary Smart Key.  Try it.

Any buffer whose name ends in `Help*' is presumed to be a temporary buffer
that one wants to inspect and then remove from view.  If you click either
Smart Key at the end of a help buffer, it is buried from view and your screen
configuration is restored to its state prior to displaying the help.  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 screen configuration is
restored.

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

* Explicit Button Samples

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

  <(factorial button)>

  <( factorial      button)>

  Pam>  <(factorial
  Pam>    button)>

  ;; <(factorial
  ;;   button)>

  /* <( factorial      */
  /*    button )> */


If your <(Info-directory-list)> or <(Info-directory)> variables include the
directory that contains the online GNU Emacs manual, 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 can consist of a number of words, 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 <(.login)> 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 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 click within its first line)>.


* Implicit Button Samples

** Key Sequence Buttons

Any Emacs key sequence delimited with braces may be executed by
activating it as a button, for example {C-u C-p} should leave point four
lines above the button line.  A help request upon the key sequence
displays the documentation for its command binding, i.e. what it does.
If it does not represent a bound key sequence, it will not be
treated as a key sequence button.

** Implicit Path Links

Any doubly quoted pathname acts as an implicit button that displays the
referenced path.  These are 'pathname' implicit buttons.  For example,
activate "README".

If you use the Andrew File System or the ange-ftp add-on to GNU Emacs,
such remote pathnames will work as well.  (The latest version of
ange-ftp may always be obtained via anonymous ftp to:
"/anonymous@alpha.gnu.ai.mit.edu:ange-ftp/ange-ftp.tar.Z").  Once you
have loaded the ange-ftp package, if you are on the Internet, you can
click on any of the following to browse the contents of the Hyperbole
distribution at Brown University (limit the amount you do this so as not
to deny others access to the archive):

	 "/anonymous@wilma.cs.brown.edu:pub/hyperbole/"
          /anonymous@128.148.31.66:/pub/hyperbole/
          # This one requires:  (setq ange-ftp-default-user "anonymous")
          /wilma.cs.brown.edu:pub/hyperbole/

You can see that for ange-ftp pathnames, Hyperbole recognizes them with
or without the double quote delimiters.  These same pathnames can be
used within explicit buttons which link to files or directories.


GNU Info (filename)node references such as "(hypb.info)Glossary" or
"(emacs)Glossary", work similarly, thanks to the 'Info-node' button type.
Try one of the Glossary buttons above.

So now when browsing the many documents that refer to filenames or Info
nodes in this way, you can just click on the name to see the contents.
(If a doubly quoted string references a local pathname that does not
exist within the file system, it will not be considered a pathname
button by Hyperbole.)  Pathname implicit buttons provide one example of
how Hyperbole can improve your working environment without you having to
do any work at all.


Hyperbole provides a history command which returns you to previous button
locations in the reverse order of the way you traverse them.  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.

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 'dir-summary' type) to
take us to the file.

Let's look at "MANIFEST".  Now click 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.

** Annotated Bibliography Buttons

Here's a use of an annotated bibliography reference implicit button
which allows you to see a bibliography entry such as [Stallman 87] when
you activate the button between brackets.

** Hyperbole Source Buttons

If you ask for help on the [Stallman 87] button, 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 click 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 shown in a help buffer.

** 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 tries to display the
man page for the entry.  Try it.  (If you happen to use the 'superman'
package which fetches man pages in the background, you'll have to wait
for the next version of superman which removes incompatibilities with
the standard man page fetch command before you can use these
'man-apropos' implicit buttons.)

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


** Internet Request For Comments (RFC) Document Browsing

If you are on the Internet and you have loaded the ange-ftp remote file
handling package for GNU Emacs, you can retrieve and browse RFC documents
used in Internet standard making just by using the Smart Key on an RFC
document identifier, like RFC-822.  Rfc822 and rfc 822 work as well.
The 'rfc' implicit button type provides this service.

Once you have retrieved an RFC, a Smart 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).  A Smart Key press on any of the table of
contents lines then displays that section, for easy random access browsing.

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


* Smart Mouse Keys

If you use Emacs with mouse support under the X window system, NeXTstep,
OpenWindows, SunView, or Apollo's DM window system, Hyperbole automatically
configures your mouse keys for use as Smart Keys and provides additional
screen-oriented operations as demonstrated here.

See the Hyperbole menu item, Doc/SmartKy, for a summary of all Smart Key
operations.  For extensive details on Smart Key operation, see the Hyperbole
manual section, "(hypb.info)Smart Key Reference".

Please note that any Smart Key actions involving modeline presses presently
do not work under Lucid Emacs because of some deficiencies in its event
reporting facilities.

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

Here is an example.  Depress the primary Smart Key somewhere within this
paragraph and while holding it down, depress the secondary Smart Key.  Then
release the keys in any order and the help display will pop up.  It explains
that their was no particular matching Smart Key context, so a default
operation is performed (the value of the variable 'smart-key-other-mode-cmd'
determines the operation performed).

** Scrolling to the Beginning and End of Buffers

A left to right horizontal drag of the primary Smart Key scrolls the current
buffer to its end (what {M->} does by default).  A right to left drag of the
primary Smart Key does the opposite; it scrolls to the buffer's beginning
(what {M-<} does by default).  Try out these operations and then use the
Smart Key end of line scrolling capability to return here.

** Creating and Deleting Windows

Horizontal and vertical drags of the SECONDARY Smart Key within a single
window can be used to create and delete Emacs windows.

A horizontal drag from left to right creates a new window by splitting the
current window into two windows, one on top of the other.  A horizontal drag
from right to left deletes the current window.  A vertical drag in either
direction splits the current window into two side-by-side windows.

Let's try these.  Remember to use your secondary Smart Key.  You need only
move your mouse pointer a few characters to register a drag.  First, split
this window with a left to right drag, then delete either one of the windows
with a right to left drag.

Now try a side-by-side window split.  Drag vertically in the up or down
direction to split the window and then use a right to left drag to delete
either one of the side-by-side windows.

** Resizing Windows

You can easily resize Emacs windows by dragging their window separators
(modelines or vertical side lines) around on screen.  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.  If you want a window to fill the screen, drag its modeline, and if
necessary its side, to the edge of the Emacs screen.

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?

Try to drag the bottom modeline.  You see that you can't.

** Swapping Buffers and Windows

Swapping buffer and window locations is quick and easy with Hyperbole.
Simply drag from one window to another.  The primary Smart Key swaps the two
windows' buffers.  The secondary Smart Key swaps the windows themselves,
including their buffers.

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 try
dragging from inside one window to another.  First with the primary Smart Key
and then with the secondary Smart Key.  Notice the difference in their
operation.


** Modeline Clicks

Window modelines are treated specially be Hyperbole.  They are broken up into
three regions, each with their own Smart Key operations.  The regions are:
the left edge, the right edge, and the middle portion (the non-edge part of
the modeline).  The edge regions are the left or rightmost three characters
of the modeline, by default.

*** Switching to Another Buffer

A primary Smart 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.  A secondary Smart 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.

*** Displaying Documentation

A primary Smart 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
primary Smart 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 primary and
secondary Smart Keys to see all that they can do.

If you click again with the primary Smart 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.  Try it.

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


*** Menu Display

Clicks in the center portion of modelines are reserved for future popup menu
capabilities in Hyperbole.

** Saving and Restoring Window Configurations

A window configuration consists of the set of windows on a single Emacs
screen.  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 primary Smart 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 secondary
Smart Key restores a prior saved window configuration from the ring.  Each
window configuration is 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 screen configurations and then saving and restoring
them.


* References

[Stallman 87]  Stallman, Richard.  GNU Emacs Manual.  Free Software
Foundation, Cambridge: MA, March 1987.

* THE END
