* 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 if terms
used here are unfamiliar to you.

* Smart Key Handling

This button prints the <(factorial)> of 5 in the minibuffer when
activated with the primary Smart Key, normally the middle mouse button.
(Once you have Hyperbole installed, just click on the word,
<(factorial)>.)  If you use the secondary Smart Key, normally the right
mouse button, 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 that it was created by
rsw@cs.brown.edu.

Note that the create-time and mod-time are normalized to your own
timezone.  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.  You do this by asking for a
'Report' from the top-level Hyperbole menu.

To display this menu, click the Smart Key anywhere within this paragraph or
alternatively, use {C-h h}.  {q} quits you 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.  A click of
the same key within this paragraph, when a Hyperbole menu is not displayed,
pops up a summary of all the things the Smart Keys can do.  Try it.


* Explicit Button Samples

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 that shows documentation for the first
parenthesis delimited Emacs Lisp function that follows it,
e.g. (hbut:report).

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.  You can see that a button label can consist of a number of
words, up to a set <(maximum length)>.

You can link to files such as your <(.login)> file.  Or directories,
like the <(tmp directory)>.  For 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 view pops up in which
you can see the referent of these links.  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.


* Implicit Button Samples

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

So now when browsing the many documents that refer to filenames in this
way, you can just click on the filename to see the contents.  (If a
doubly quoted string contains whitespace or references a name 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
put in 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 HistJump command from the top-level Hyperbole menu, {C-h h h}.

Now suppose you want to browse through a number of files within the
Hyperbole distribution.  You could use the Emacs dired subsystem, 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.  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.

** UNIX Man Apropos Buttons

Below are some lines output by the UNIX 'apropos' command.  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 

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

* References

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