This is Info file ../info/hyperbole.info, produced by Makeinfo-1.63
from the input file hyperbole.texi.


File: hyperbole.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

Preface
*******

Copyright (C) 1991, 1992, 1993, 1994, 1995  Free Software Foundation,
Inc.

   All trademarks referenced herein are trademarks of their respective
holders.

   This edition of the Hyperbole User Manual is for use with any version
4.01 or greater of Hyperbole.

   Hyperbole is free software; you can use it, redistribute it and/or
modify it without fee under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2, or (at
your option) any later version.

   Hyperbole is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

   You should have received a copy of the GNU General Public License
along with GNU Emacs or XEmacs; see the file COPYING.  If not, write to
the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

   Hyperbole was designed and written by Bob Weiner.  Motorola, Inc.
funded and donated this work for free redistribution as part of the
InfoDock integrated software engineering and productivity toolset.  For
information on how to obtain Hyperbole, *Note Obtaining::.  InfoDock
can be found at the same location.

   This manual explains user operation and summarizes basic developer
facilities of Hyperbole.  This major release of Hyperbole concentrates
on providing convenient access to information and control over its
display.  The Hyperbole outliner emphasizes flexible views and structure
manipulation within bodies of information.

   Hyperbole (pronounced Hi-purr-boe-lee) is an open, efficient,
programmable information management and hypertext system.  It is
intended for everyday work on any UNIX platform supported by GNU Emacs.
It works well with the versions of Emacs that support multiple X or
NEXTSTEP windows: Emacs 19, XEmacs (formerly called Lucid Emacs) and
Epoch.  Hyperbole allows hypertext buttons to be embedded within
unstructured and structured files, mail messages and news articles.  It
offers intuitive mouse-based control of information display within
multiple windows.  It also provides point-and-click access to Info
manuals, ftp archives, Wide-Area Information Servers (WAIS), and the
World-Wide Web (WWW) hypertext system through encapsulations of software
that support these protocols.

Hyperbole consists of four parts:

*Info Management
     an interactive information management interface, including a
     powerful rolodex, which anyone can use.  It is easy to pick up and
     use since it introduces only a few new mechanisms and provides
     user-level facilities through a menu interface, which you control
     from the keyboard or the mouse;

*Hypertext Outliner
     an outliner with multi-level autonumbering and permanent ids
     attached to each outline node for use as hypertext link anchors,
     plus flexible view specifications that can be embedded within
     links or used interactively;

*Button Types
     a set of hyper-button types that provides core hypertext and other
     behaviors.  Users can make simple changes to button types and those
     familiar with Emacs Lisp can quickly prototype and deliver new
     types;

*Programming Library
     a set of programming library classes for system developers who
     want to integrate Hyperbole with another user interface or as a
     back-end to a distinct system.  (All of Hyperbole is written in
     Emacs Lisp for ease of modification.  Although Hyperbole was
     initially designed as a prototype, it has been engineered for
     real-world usage and is well structured.)

   Hyperbole may be used simply for browsing through documents
pre-configured with Hyperbole buttons, in which case, one can safely
ignore most of the information in this manual.  The `DEMO' file
included in the Hyperbole distribution demonstrates many of Hyperbole's
standard facilities.  It offers a much less technical introduction for
Hyperbole users by providing good examples of how buttons may be used
and an introduction to the outliner.

   So if this manual is too detailed for your taste, you can skip it
entirely and just jump right into the demonstration, normally by typing
{`C-h h d d'}, assuming Hyperbole has already been installed at your
site.  Otherwise, *Note Installation::, for Hyperbole installation and
configuration information.

   Many users, however, will want to do more than browse with Hyperbole,
e.g.  create their own buttons.  The standard Hyperbole button editing
user interface is GNU Emacs-based, so a basic familiarity with the Emacs
editing model is useful.  The material covered in the GNU Emacs
tutorial, normally bound to {`C-h t'} within Emacs, is more than
sufficient as background.  If some GNU Emacs terms are unfamiliar to
you, *Note Emacs Glossary: (emacs)Glossary.

   Before we delve into Hyperbole, a number of acknowledgments are in
order.  Peter Wegner has encouraged the growth in this work.  Morris
Moore has helped me pursue my own research visions and kept me striving
for excellence.  Doug Engelbart has shown me the bigger picture and
continues to be an inspiration.  His work provides a model from which I
am beginning to draw.  Kellie Clark and I jointly designed the Hyperbole
outliner while sharing a life together.  Chris Nuzum, as a user of
Hyperbole, has helped demonstrate its power since its inception; he
knows how to work with Hyperbole far better than I.

* Menu:

* Introduction::
* Installation::
* Buttons::
* Smart Keys::
* Menus::
* Entering Arguments::
* Outliner::
* Rolodex::
* Window Configurations::
* Developing with Hyperbole::
* Glossary::
* Smart Key Reference::
* Outliner Keys::
* Suggestion or Bug Reporting::
* Questions and Answers::
* Future Work::
* References::
* Key Binding Index::
* Code and File Index::
* Concept Index::

 -- The Detailed Node Listing --

Introduction

* Hyperbole Overview::
* Mail Lists::
* Manual Overview::

Installation

* Obtaining::
* Building::
* Installing::
* Configuring::

Configuring

* Internal Viewers::
* External Viewers::
* Link Variable Substitution::
* Button Colors::

Buttons

* Explicit Buttons::
* Global Buttons::
* Implicit Buttons::
* Action Types::
* Button Type Precedence::
* Button Files::
* Utilizing Explicit Buttons::

Utilizing Explicit Buttons

* Creation::
* Renaming::
* Deletion::
* Modification::
* Location::
* Buttons in Mail::
* Buttons in News::

Creation

* By Dragging::                 Creation Via Action Key Drags
* By Menu::                     Creation Via Menus

Outliner

* Menu Commands::
* Creating Outlines::
* Autonumbering::
* Idstamps::
* Editing::
* Viewing::
* Links::
* Cell Attributes::
* Outliner History::

Editing

* Adding and Killing::
* Moving Around::
* Relocating and Copying::
* Filling::
* Transposing::
* Splitting and Appending::
* Inserting and Importing::

Viewing

* Hiding and Showing::
* View Specs::

Rolodex

* Rolo Concepts::
* Rolo Menu::
* Rolo Keys::
* Rolo Settings::

Developing with Hyperbole

* Hook Variables::
* Creating Types::
* Explicit Button Technicalities::
* Encapsulating Systems::
* Embedding Hyperbole::

Creating Types

* Action Type Creation::
* Implicit Button Types::

Explicit Button Technicalities

* Button Label Normalization::
* Operational and Storage Formats::
* Programmatic Button Creation::

Smart Key Reference

* Smart Mouse Keys::
* Smart Keyboard Keys::


File: hyperbole.info,  Node: Introduction,  Next: Installation,  Prev: Top,  Up: Top

Introduction
************

   This chapter describes what Hyperbole is, lists some of its potential
applications, explains how to subscribe to its mail lists, and then
summarizes the structure of the rest of the manual.

* Menu:

* Hyperbole Overview::
* Mail Lists::
* Manual Overview::


File: hyperbole.info,  Node: Hyperbole Overview,  Next: Mail Lists,  Prev: Introduction,  Up: Introduction

Hyperbole Overview
==================

   A Hyperbole user works with *buttons* embedded within textual
documents; he may create, modify, move or delete buttons.  Each button
performs a specific action, such as linking to a file or executing a
shell command.

   There are three categories of Hyperbole buttons:
"explicit buttons"
     created by Hyperbole, accessible from within a single document;

"global buttons"
     created by Hyperbole, accessible anywhere within a user's network
     of documents;

"implicit buttons"
     created and managed by other programs or embedded within the
     structure of a document, accessible from within a single document.
     Hyperbole recognizes implicit buttons by contextual patterns
     given in their type specifications (explained later).

   Explicit Hyperbole buttons may be embedded within any type of text
file.  Implicit buttons may be recognized anywhere within a text file,
depending on the implicit button types that are available.  All global
buttons are stored in a single location and activated by entering their
names, rather than by direct selection, the means used to activate
explicit and implicit buttons.

To summarize:

     Button Category   Active Within        Activation Means      Managed By
     ========================================================================
     Explicit          a single document    direct selection      Hyperbole
     Global            any document         specifying its name   Hyperbole
     Implicit          a matching context   direct selection      other tools
     ========================================================================

   Hyperbole buttons may be clicked upon with a mouse to activate them
or to describe their actions.  Thus, a user can always check how a
button will act before activating it.  Buttons may also be activated
from a keyboard.  (In fact, virtually all Hyperbole operations,
including menu usage, may be performed from any standard character
terminal interface, so one need not be anchored to a workstation all
day).  *Note Smart Keys::.

   Hyperbole does not enforce any particular hypertext or information
management model, but instead allows you to organize your information in
large or small chunks as you see fit.  The Hyperbole outliner organizes
information hierarchies which may also contain links to external
information sources.

Some of Hyperbole's most important features include:

   * Buttons may link to information or may execute procedures, such as
     starting or communicating with external programs;

   * One simply drags between a button source location and a link
     destination to create or to modify a link button.  The same result
     can be achieved from the keyboard.

   * Buttons may be embedded within electronic mail messages;

   * Outlines allow rapid browsing, editing and movement of chunks of
     information organized into trees (hierarchies);

   * Other hypertext and information retrieval systems may be
     encapsulated under a Hyperbole user interface (a number of samples
     are provided).

Typical Hyperbole applications include:

*personal information management*
     Overlapping link paths provide a variety of views into an
     information space.  A search facility locates buttons in context
     and permits quick selection.

*documentation and code browsing*
     Cross-references may be embedded within documentation.  One can
     add a point-and-click interface to existing documentation, link
     code with associated design documents, or jump to the definition
     of an identifier by selecting its name within code or
     documentation.

*brainstorming*
     The Hyperbole outliner, *Note Outliner::, is an effective tool for
     capturing ideas and then quickly reorganizing them in a meaningful
     way.  Links to related ideas are easy to create, eliminating the
     need to copy and paste information into a single place.

*help/training systems*
     Tutorials containing buttons can show students how things work
     while explaining the concepts, e.g. an introduction to local
     commands.  This technique can be much more effective than written
     documentation alone.

*archive managers*
     Programs that manage archives from incoming information streams
     may be supplemented by having them add topic-based buttons that
     link to the archive holdings.  Users can then search and create
     their own links to archive entries.


File: hyperbole.info,  Node: Mail Lists,  Next: Manual Overview,  Prev: Hyperbole Overview,  Up: Introduction

Mail Lists
==========

   If you maintain or use Hyperbole, you should consider joining one of
the two Hyperbole interest mailing lists.  *Note Menus::, and the
description of the Msg/ menu item, for a convenient means of joining
and mailing to these lists.

   There are several Hyperbole-related mail addresses.  Learn what each
is for before you mail to any of them.

<hyperbole-request@hub.ucsb.edu>
<hyperbole-announce-request@hub.ucsb.edu>

     *All* mail concerning administration of the Hyperbole mailing
     lists should be sent to the appropriate one of these addresses.  That
     includes addition, change, or deletion requests.  Don't consider sending
     such a request to a Hyperbole mail list or people will wonder why you
     don't know that all Internet mail lists have a -request address for
     administrative requests.
     
     Use the following formats on your subject line to execute requests,
     where you substitute your own values for the <> delimited items.
     
        Subject: Subscribe '<' <user@domain> '>' (<your name>).
        Subject: Unsubscribe '<' <user@domain> '>'.
     
     To change your address, you must unsubscribe your old address in one
     message and then subscribe your new address in another message.
     
     For example:
     
        To: hyperbole-announce-request@hub.ucsb.edu
        Subject: Unsubscribe <joe@any.com>.
     
        To: hyperbole-announce-request@hub.ucsb.edu
        Subject: Subscribe <joe@any.com> (Joe Williams).

There are two Hyperbole-related mail lists.  Subscribe to one or the
other, not to both.

<hyperbole@hub.ucsb.edu>

     Mail list for discussion of all Hyperbole issues.  Bug reports and
     suggestions may also be sent here.
     
     Always use your Subject and/or Summary: lines to state the position that
     your message takes on the topic that it addresses.
     
     For example, send:
     
        Subject: Basic bug in top-level minibuffer menu.
     
     rather than:
     
        Subject: Hyperbole bug.
     
     Statements end with periods, questions with question marks (typically),
     and high energy, high impact declarations with exclamation points.  This
     simple rule makes all e-mail communication much easier for recipients to
     handle appropriately.
     
     If you ask a question, your subject line should end with a ?,
     e.g. "Subject: How can man page SEE ALSOs be made implicit buttons?"  A
     "Subject: Re: How can ..." then indicates an answer to the question.
     Question messages should normally include your Hyperbole and Emacs
     version numbers and clearly explain your problem and surrounding issues.
     Otherwise, you will simply waste the time of those who may want to help
     you.  (Your top-level Hyperbole menu shows its version number and {`M-x
     emacs-version RET'} gives the other.)
     
     If you ask questions, you should consider adding to the discussion by
     telling people the kinds of work you are doing or contemplating doing
     with Hyperbole.  In this way, the list will not be overwhelmed by
     messages that ask for, but provide no information.

<hyperbole-announce@hub.ucsb.edu>

     Those who don't want to participate in the discussion but want to hear
     about bug fixes and new releases of Hyperbole should subscribe to this
     list.  Anyone on the `hyperbole' list is automatically on this one too,
     so there is no need to subscribe to this one in that case.  This list is
     for official fixes and announcements so don't send your own fixes here.
     Send them to `hyperbole' instead.


File: hyperbole.info,  Node: Manual Overview,  Prev: Mail Lists,  Up: Introduction

Manual Overview
===============

   Remember that the `DEMO' file included in the Hyperbole distribution
demonstrates many of Hyperbole's standard facilities, (*note Preface:
Top.) for more details.

   *Note Glossary::, for definitions of Hyperbole terms for quick
reference, so in some cases terms are not precisely defined within the
text.  Be sure to reference the glossary if a term is unclear to you.
Although you need not have a keen understanding of all of these terms, a
quick scan of the Glossary should help throughout Hyperbole use.

   If you have a question, feature suggestion or bug report on
Hyperbole, follow the instructions given in *Note Suggestion or Bug
Reporting::.  A few commonly asked questions are answered in the
manual, *Note Questions and Answers::.  If you are interested in
classic articles on hypertext, *Note References::.

   *Note Installation::, for explanations of how to obtain, install,
configure and load Hyperbole for use.

   *Note Buttons::, for an overview of Hyperbole buttons and how to use
them.

   *Note Smart Keys::, for an explanation of the innovative,
context-sensitive mouse and keyboard Action and Assist Keys offered by
Hyperbole.  *Note Smart Key Reference::, for a complete reference on
what the Action and Assist Keys do in each particular context that they
recognize.

   (Keep in mind as you read about how to use Hyperbole that in many
cases, it provides a number of overlapping interaction methods are
provided to support different work styles and hardware limitations.
You need learn only one with which you can become comfortable, in such
instances.)

   *Note Menus::, for summaries of Hyperbole menu commands and how to
use the minibuffer-based menus that work on dumb terminals.

   *Note Entering Arguments::, for special support that Hyperbole
provides for entering arguments when prompted for them.

   *Note Outliner::, for concept and usage information on the
autonumbered, hypertextual outliner.  A full summary of the outliner
commands that are bound to keys may be found in *Note Outliner Keys::.

   *Note Rolodex::, for concept and usage information on the rapid
lookup, hierarchical, free text record management system included with
Hyperbole.

   *Note Window Configurations::, for instructions on how to save and
restore the set of buffers and windows that appear with a frame.  This
feature lets you switch among working contexts easily, even on a dumb
terminal.  Such configurations only last throughout your current editor
session.

   Developers comfortable with Emacs Lisp will want to continue on
through to, *Note Developing with Hyperbole::.

   *Note Future Work::, for future directions in Hyperbole's evolution.


File: hyperbole.info,  Node: Installation,  Next: Buttons,  Prev: Introduction,  Up: Top

Installation
************

   Hyperbole must be installed at your site before you can use it.  The
following sections explain how to obtain, install and configure
Hyperbole for use.

   If you want to customize the basic Hyperbole initialization sequence
for yourself rather than the users at your site, you should make a
personal copy of the `hsite.el' file, modify it the way you want, and
then load it.  (If you are familiar with Emacs Lisp, *Note Hook
Variables::.)

* Menu:

* Obtaining::
* Building::
* Installing::
* Configuring::


File: hyperbole.info,  Node: Obtaining,  Next: Building,  Prev: Installation,  Up: Installation

Obtaining
=========

   Hyperbole is actually part of an integrated tool framework that we
have developed called InfoDock.  InfoDock provides a modern user
interface on top of Emacs, information management, and powerful
software development tools, all in one package.  Hyperbole or InfoDock
can be obtained via anonymous ftp on the Internet from:

   `ftp://ftp.xemacs.org/pub/infodock'.

Here are detailed instructions for downloading and unpacking Hyperbole.

   Move to a directory below which you want the `hyperbole' directory to
be created.  Unpacking the Hyperbole archive will create the
`hyperbole' directory and will place all of the files below it.

       cd <LOCAL-EMACS-LISP-DIR>

Ftp to ftp.xemacs.org  (Internet Host ID = 128.174.252.16):

        prompt> ftp ftp.xemacs.org

Login as *anonymous* with your own *<user-id>@<site-name>* as a
password.

        Name (ftp.xemacs.org): anonymous
        331 Guest login ok, send EMAIL address (e.g. user@host.domain)
            as password.
        Password:
        230 Guest login ok, access restrictions apply.

Move to the Hyperbole directory:

        ftp> cd pub/infodock

Set your transfer mode to binary:

        ftp> bin
        200 Type set to I.

Turn off prompting:

        ftp> prompt
        Interactive mode off.

Retrieve just the Hyperbole archive and any diff-based patches (there
may not be any patches):

        ftp> mget hyperbole*
        ftp> mget hdiff*

Close the ftp connection:

        ftp> quit
        221 Goodbye.

Unpack the tar archive using the GNU version of the `zcat' program,
sometimes called `gzcat' or the `gunzip' program:

        zcat hyperbole*tar.gz | tar xvf -
     or
        gunzip hyperbole*tar.gz; tar xvf hyperbole*tar

Apply any patches you retrieved:

        cd hyperbole; patch < <patch-file>


File: hyperbole.info,  Node: Building,  Next: Installing,  Prev: Obtaining,  Up: Installation

Building
========

   The following explains how to Use the Hyperbole `Makefile' to
compile any needed code, to generate the `hsite.el' file used for
site-specific Hyperbole customization, and to produce printable
documentation.

   Edit the line near the top of `Makefile' that represents the emacs
version that you use, so that it corresponds to the emacs executable
name used on your system.  Then immediatly below there, set the EMACS
variable to the variable name for the emacs that you will use to
compile the Hyperbole Lisp files.

   You may also have to set the SITE-PRELOADS variable defined further
down in the file; follow the instructions that precede the
SITE-PRELOADS = line.  Make these changes now and save the `Makefile'.

   The following instructions use the term `<HYPERBOLE-DIR>/' to refer
to your `hyperbole/' directory, so substitute your own value.

To install Hyperbole for use with InfoDock, XEmacs, GNU Emacs or Epoch,
from a shell:

        cd <HYPERBOLE-DIR>; make

All of the .elc compiled Lisp files are already built for XEmacs and
V19, so this build will finish very quickly.  If you really want to
rebuild all of the .elc files, use:

        cd <HYPERBOLE-DIR>; make all-elc

To produce the Postscript version of the Hyperbole manual, you must have
the TeX formatter on your system:

        cd <HYPERBOLE-DIR>; make ps

To install Hyperbole for use with GNU Emacs V18 or Epoch:

        cd <HYPERBOLE-DIR>; make all-elc-v18

This will produce a complete set of Emacs V18 .elc files.


File: hyperbole.info,  Node: Installing,  Next: Configuring,  Prev: Building,  Up: Installation

Installing
==========

   You may want to explore the Hyperbole configuration options before
installing it.  *Note Configuring::.  If you just want to get up and
running quickly, however, there is no need to configure anything, just
follow these instructions to install Hyperbole.

   Add the following lines to a site initialization file such as
`site-start.el' to set up so that all users have Hyperbole loaded for
them when they run Emacs.  Otherwise, each user will have to add these
lines to his own `~/.emacs' initialization file.

To autoload Hyperbole so that it loads only when needed:

     (defvar hyperb:dir "<HYPERBOLE-DIR>/")
       "Directory where the Hyperbole executable code is kept.
     It must end with a directory separator character.")
     
     (load (expand-file-name "hversion" hyperb:dir))
     (load (expand-file-name "hyperbole" hyperb:dir))

   This establishes a few key bindings and sets up Hyperbole to
automatically load whenever you activate its menu.  If you would rather
have the whole Hyperbole system loaded when you start up so that you can
always use the Smart Keys and other facilities, add the additional line:

     (require 'hsite)

   If you use mouse keys, be sure to add the above lines after any
setup of mouse key bindings, to ensure that Hyperbole's mouse keys are
properly initialized.  *Note Smart Keys::, for further details.  If you
use any Hyperbole mail or news support, *Note Buttons in Mail::, be
certain to perform all of your personal mail/news initializations
before the point at which you load Hyperbole.  Otherwise, the mail/news
support may not be configured properly.  For example, if you use the
Emacs add-on Supercite package, its setup should come before Hyperbole
initialization.

The Hyperbole Manual is included in the distribution in two forms:

     `man/hyperbole.info'   - online version
     `man/hyperbole.texi'   - source form

To add pointers to the Info version of the Hyperbole manual within your
Info directory, follow these instructions.  If INFO-DIRECTORY-LIST is
bound as a variable within your Emacs (all versions except V18 and
Epoch), then you can simply set it so that <HYPERBOLE-DIR> is an element
in the list:

     (setq Info-directory-list (cons "<HYPERBOLE-DIR>" Info-directory-list))

Otherwise, from a shell:

        cd to the directory given by your INFO-DIRECTORY variable
        rm hyperbole.info*; cp <HYPERBOLE-DIR>/man/hyperbole.info* .

For all versions of Emacs, add an Info menu entry for the Hyperbole
manual in your Info `dir' file (the `*' should be placed in the first
column of the file):

     * Hyperbole::  GNU Emacs-based everyday information management system.
         Use {C-h h d d} for a demonstration.  Includes context-sensitive
         mouse and keyboard support, a powerful rolodex, an autonumbered
         outliner with hyperlink anchors for each outline cell, and extensible
         hypertext facilities including hyper-links in mail and news messages.

   That's all there is to the installation.  Once Hyperbole has been
installed for use at your site, you can invoke it with {`C-h h'} or
{`M-x hyperbole RET'} to bring up the Hyperbole main menu in the
minibuffer window.


File: hyperbole.info,  Node: Configuring,  Prev: Installing,  Up: Installation

Configuring
===========

   There are many Hyperbole configuration options that may be changed by
editing the `hyperbole.el' and `hsite.el' files in the `hyperbole/'
directory.  The following sections discuss the configuration options
most likely to be of interest to users.

* Menu:

* Internal Viewers::
* External Viewers::
* Link Variable Substitution::
* Button Colors::


File: hyperbole.info,  Node: Internal Viewers,  Next: External Viewers,  Prev: Configuring,  Up: Configuring

Internal Viewers
----------------

   When given a file name, Hyperbole will by default display the file
for editing within an Emacs buffer.  The HPATH:DISPLAY-ALIST variable
can be used to specify file name patterns, such as matching suffixes,
which will invoke a special Emacs Lisp function to display any matching
files within Emacs.  This can be used to format raw data files for
convenient display.

   Configure the HPATH:DISPLAY-ALIST variable in `hsite.el'.  Its value
is an association list whose elements are
(<file-name-regular-expression> . <function-of-one-arg>) pairs.  Any
path whose name matches a <file-name-regular-expression> will be
displayed by calling the associated <function-of-one-arg> with the file
name as the argument.

   *Note External Viewers::, for instructions on associating file names
with external, window-system specific viewers.


File: hyperbole.info,  Node: External Viewers,  Next: Link Variable Substitution,  Prev: Internal Viewers,  Up: Configuring

External Viewers
----------------

   If you will be using Hyperbole under a window system, you may want to
configure the HPATH:FIND-ALIST variable in `hsite.el' to support
hyperlinks which open files using non-Emacs tools, e.g. a fax reader or
a bitmap viewer.

   The value of HPATH:FIND-ALIST is determined when Hyperbole is
initialized based upon the current window system and the version of
Emacs in use.  The value is an association list whose elements are
(<file-name-regular-expression> . <viewer-program>) pairs.  Any path
whose name matches a <file-name-regular-expression> will be displayed
using the corresponding viewer-program.  If a <viewer-program> entry
contains a `%s' string, the filename to display will be substituted at
that point within the string.  Otherwise, the filename will be appended
to the <viewer-program> entry.  See the "x-suffixes" and
"nextstep-suffixes" settings within the definition of HPATH:FIND-ALIST
as examples.


File: hyperbole.info,  Node: Link Variable Substitution,  Next: Button Colors,  Prev: External Viewers,  Up: Configuring

Link Variable Substitution
--------------------------

   Another variable to consider modifying in the `hsite.el' file is
HPATH:VARIABLES.   This variable consists of a list of Emacs Lisp
variable names, each of which may have a pathname or a list of pathnames
as a value.  Whenever a Hyperbole file or directory link button is
created, its pathname is compared against the values in
HPATH:VARIABLES.  The first match found, if any, is selected and its
associated variable name is substituted into the link pathname, in
place of its literal value.  When the link is resolved (the button is
activated), Hyperbole replaces each variable with the first matching
value from this list.  (Environment variables are also replaced whenever
link paths are resolved.

   This permits sharing of links over wide areas, where the variable
values may differ between link creator and link activator.  The entire
process is wholly transparent to the user; it is explained here simply
to help you in deciding whether or not to modify the value of
HPATH:VARIABLES.


File: hyperbole.info,  Node: Button Colors,  Prev: Link Variable Substitution,  Up: Configuring

Configuring Button Colors
-------------------------

   When Hyperbole is run under a window system together with Emacs 19,
XEmacs or Epoch, it automatically highlights any explicit buttons in a
buffer and makes them flash when selected.  The main setting you may
want change is the selection of a color (or style) for button
highlighting and button flashing.  See the `hui-*-b*.el' files for
lists of potential colors and the code which supports this behavior.  A
call to `(hproperty:cycle-but-color)' within a Hyperbole initialization
sequence in the `hsite.el' file changes the color used to highlight and
flash explicit buttons.

   Additionally, under XEmacs and Emacs 19, if HPROPERTY:BUT-EMPHASIZE-P
is set to `t' in `hsite.el', then whenever the mouse pointer moves over
an explicit button, it will be emphasized in a different color or
style.  This emphasis is in addition to any non-mouse-sensitive button
highlighting.

   If you read in a file with explicit buttons before you load
Hyperbole, these buttons won't be highlighted.  Load Hyperbole and then
use `M-x hproperty:but-create RET' to highlight the buttons in the
current buffer.


File: hyperbole.info,  Node: Buttons,  Next: Smart Keys,  Prev: Installation,  Up: Top

Buttons
*******

   This chapter explains the user-level notion of Hyperbole buttons.
Hyperbole buttons that are stored in files persist across Emacs
sessions, so they provide a convenient means of linking from one
information source to another.

* Menu:

* Explicit Buttons::
* Global Buttons::
* Implicit Buttons::
* Action Types::
* Button Type Precedence::
* Button Files::
* Utilizing Explicit Buttons::


File: hyperbole.info,  Node: Explicit Buttons,  Next: Global Buttons,  Prev: Buttons,  Up: Buttons

Explicit Buttons
================

   Hyperbole creates and manages *explicit buttons* which look like
this `<(fake button)>' to a Hyperbole user.  They are quickly
recognizable, yet relatively non-distracting as one scans the text in
which they are embedded.  The text between the `<(' and `)>' delimiters
is called the "button label".  Spacing between words within a button
label is irrelevant to Hyperbole, so button labels may wrap across
several lines without causing a problem.

   Hyperbole stores the "button data" that gives an explicit button its
behavior, separately from the button label, in a file named `.hypb'
within the same directory as the file in which the button is created.
Thus, all files in the same directory share a common button data file.
Button data is comprised of individual "button attribute" values.  A
user never sees this data in its raw form but may see a formatted
version by asking for help on a button.

   Explicit buttons may be freely moved about within the buffer in which
they are created.  (No present support exists for moving buttons between
buffers).  A single button may also appear multiple times within the
same buffer; one simply copies the button label with its delimiters to
a new location in such cases.

   Each explicit button is assigned an action type which determines the
actions that it performs.  "Link action types" connect buttons to
particular types of referents.  "Activation" of such buttons then
displays the referents.

   Hyperbole does not manage referent data; this is left to the
applications that generate the data.  This means that Hyperbole
provides in-place linking and does not require reformatting of data to
integrate it with a Hyperbole framework.


File: hyperbole.info,  Node: Global Buttons,  Next: Implicit Buttons,  Prev: Explicit Buttons,  Up: Buttons

Global Buttons
==============

   Access to explicit buttons depends upon the information on your
screen since they are embedded within particular buffers.  Sometimes it
is useful to activate buttons without regard to the information with
which you are presently working.  In such instances, you use "global
buttons", which are simply explicit buttons which may be activated or
otherwise operated upon by entering their labels when they are prompted
for, rather than selecting the buttons within a buffer.

   If you want a permanent link to a file section that you can follow at
any time, you can use a global button.  Or what about an Emacs keyboard
macro that you use frequently?  Create an `exec-kbd-macro' button with
an easy to type name and then you can easily activate it whenever the
need arises.


File: hyperbole.info,  Node: Implicit Buttons,  Next: Action Types,  Prev: Global Buttons,  Up: Buttons

Implicit Buttons
================

   Implicit buttons are those defined by the natural structure of a
document.  They are identified by contextual patterns which limit the
locations or states in which they can appear.  Their behavior is
determined by one or more actions which they trigger when activated.  An
action is derived from either a Hyperbole action type specification,
*Note Action Types::, or an Emacs Lisp function.  Implicit button types
may use the same action types that explicit buttons do.

   Implicit buttons never have any button data associated with them.
They are recognized in context based on predicate matches defined within
implicit button types.  For example, Hyperbole recognizes file names
enclosed in double quotes and can quickly display their associated files
in response to simple mouse clicks.

See `hibtypes.el' for complete examples.  Standard implicit button
types include (in alphabetical order):

`annot-bib'
     Displays annotated bibliography entries referenced internally,
     delimeters = [].  References must be delimited by square brackets,
     must begin with a word constituent character, and must not be in
     buffers whose names begin with a ' ' or '*' character.

`completion'
     Inserts completion at point into minibuffer or other window.

`dir-summary'
     Detects filename buttons in files named "MANIFEST" or "DIR".
     Displays selected files.  Each file name must be at the beginning
     of the line and must be followed by one or more spaces and then
     another non-space, non-parenthesis, non-brace character.

`doc-id'
     Displays an index entry for a site-specific document given its id.
     Ids must be delimited by 'doc-id-start' and 'doc-id-end' and must
     match the function given by 'doc-id-p'.  This permits creation of
     catalogued online libraries.  See `${hyperb:dir}/hib-doc-id.el'
     for more information.

`elisp-compiler-msg'
     Jumps to source code for definition associated with byte-compiler
     error message.  Works when activated anywhere within an error line.

`debugger-source'
     Jumps to source line associated with debugger stack frame or
     breakpoint lines.  This works with gdb, dbx, and xdb.  Such lines
     are recognized in any buffer.

`grep-msg'
     Jumps to line associated with grep or compilation error msgs.
     Messages are recognized in any buffer.

`hyp-address'
     Turns a Hyperbole e-mail list address into an implicit button which
     inserts Hyperbole environment information.  Useful when sending
     mail to a Hyperbole mail list.  See also the documentation for
     `actypes::hyp-config'.

`hyp-source'
     Turns source location entries in Hyperbole reports into buttons
     that jump to the associated location.

`Info-node'
     Makes "(file)node" buttons display the associated Info node.

`kbd-key'
     Executes a key sequence delimited by curly braces.  Key sequences
     should be in human readable form, e.g. {`C-b'}.  Forms such as
     {}, {}, and {^b} will not be recognized.

`klink'
     Follows a link delimited by <> to a koutline cell.  See
     documentation for `actypes::link-to-kotl' for valid link
     specifiers.

`mail-address'
     If on an e-mail address in a specific buffer type, mail to that
     address in another window. Applies to the rolodex match buffer,
     any buffer attached to a file in ROLO-FILE-LIST, or any buffer
     with `mail' or `rolo' (case-insensitive) within its name.

`man-apropos'
`UNIX manual'
`man pages'
`man apropos'
     Makes man apropos entries display associated man pages when
     selected.

`patch-msg'
     Jumps to source code associated with output from the `patch'
     program.  Patch applies diffs to source code.

`pathname'
     Makes a delimited, valid pathname display the path entry.  Also
     works for delimited and non-delimited ange-ftp and efs pathnames.
     See `hpath:at-p' function documentation for possible delimiters.
     See HPATH:SUFFIXES variable documentation for suffixes that are
     added to or removed from pathname when searching for a valid match.
     See `hpath:find' function documentation and HPATH:DISPLAY-ALIST
     and HPATH:FIND-ALIST variable documentation for special file
     display options.

`rfc'
     Retrieves and displays an Internet rfc referenced at point.
     Requires ange-ftp or efs when needed for remote retrievals.  The
     following formats are recognized: RFC822, rfc-822, and RFC 822.
     The HPATH:RFC variable specifies the location from which to
     retrieve RFCs."

`rfc-toc'
     Summarizes contents of an Internet rfc from anywhere within rfc
     buffer.  Each line in summary may be selected to jump to section.

`text-toc'
     Jumps to the text file section referenced by a table of contents
     entry at point. File name must contain `README' and there must be a
     `Table of Contents' or `Contents' label on a line by itself (it may
     begin with an asterisk), preceding the table of contents.  Each toc
     entry must begin with some whitespace followed by one or more
     asterisk characters.  Each file section name line must start with
     one or more asterisk characters at the very beginning of the line.

`www-url'
     When not in a w3 browser buffer, follow any non-ftp url (link) at
     point.  The variable, ACTION-KEY-URL-FUNCTION, can be used to
     customize the url browser that is used.

   The Hyperbole Smart Keys offer extensive additional context-sensitive
point-and-click type behavior beyond these standard implicit button
types.  *Note Smart Keys::.


File: hyperbole.info,  Node: Action Types,  Next: Button Type Precedence,  Prev: Implicit Buttons,  Up: Buttons

Action Types
============

   "Action types" provide action procedures that specify button
behavior.  The arguments needed by an action type are prompted for at
button creation time.  When a button is activated, the stored arguments
are fed to the action type's "action" body to achieve the desired
result.  Hyperbole handles all of this transparently.

Standard action types in alphabetical order include:

`annot-bib'
     Follows internal ref KEY within an annotated bibliography,
     delimiters=[].

`completion'
     Inserts completion at point into minibuffer or other window.
     Unless at end of buffer or if completion has already been
     inserted, then deletes completions window.

`eval-elisp'
     Evaluates a Lisp expression LISP-EXPR.

`exec-kbd-macro'
     Executes KBD-MACRO REPEAT-COUNT times.  KBD-MACRO may be a string
     of editor command characters or a function symbol.  Optional
     REPEAT-COUNT nil means execute once, zero means repeat until error.

`exec-shell-cmd'
     Executes a SHELL-CMD string asynchronously.  Optional non-nil
     second argument INTERNAL-CMD means do not display the shell
     command line executed.  Optional non-nil third argument KILL-PREV
     means kill last output to shell buffer before executing SHELL-CMD.

`exec-window-cmd'
     Executes an external window-based SHELL-CMD string asynchronously.

`hyp-config'
     Inserts Hyperbole configuration info at end of optional OUT-BUF or
     current.

`hyp-request'
     Inserts Hyperbole mail list request help into optional OUT-BUF or
     current.

`hyp-source'
     Displays a buffer or file from a line beginning with
     'hbut:source-prefix'.

`kbd-key'
     Executes the function binding for KEY-SEQUENCE, delimited by {}.
     Returns t if a KEY-SEQUENCE has a binding, else nil.

`link-to-buffer-tmp'
     Displays a BUFFER in another window.  Link is generally only good
     for current Emacs session.  Use 'link-to-file' instead for a
     permanent link.

`link-to-directory'
     Displays a DIRECTORY in Dired mode in another window.

`link-to-doc'
     Displays online version of a document given by DOC-ID, in other
     window.  If the online version of a document is not found in
     DOC-ID-INDICES, an error is signalled.

`link-to-ebut'
     Performs action given by another button, specified by KEY and
     KEY-FILE.

`link-to-elisp-doc'
     Displays documentation for FUNC-SYMBOL.

`link-to-file'
     Displays a PATH in another window scrolled to optional POINT.
     With POINT, buffer is displayed with POINT at the top of the
     window.

`link-to-file-line'
     Displays a PATH in another window scrolled to LINE-NUM.

`link-to-kcell'
     Displays FILE with kcell given by CELL-REF at the top of the
     window.  CELL-REF may be a kcell's display label or its permanant
     idstamp.  If FILE is nil, the current buffer is used.  If CELL-REF
     is nil, the first cell in the view is shown.

`link-to-kotl'
     Displays at the top of another window the referent pointed to by
     LINK.  LINK may be of any of the following forms, with or without
     delimiters:
            < pathname [, cell-ref] >
            < [-!&] pathname >
            < @ cell-ref >

     See documentation for `kcell:ref-to-id' for valid cell-ref formats.

`link-to-Info-node'
     Displays an Info NODE in another window.  NODE must be a string of
     the form '(file)nodename'.

`link-to-mail'
     Displays mail msg with MAIL-MSG-ID from MAIL-FILE in other window.
     See documentation for the variable HMAIL:INIT-FUNCTION for
     information on how to specify a mail reader to use.

`link-to-regexp-match'
     Finds REGEXP's Nth occurrence in FILE and displays location at
     window top.  Returns t if found, signals an error if not.

`link-to-rfc'
     Retrieves and displays an Internet rfc given by RFC-NUM.  RFC-NUM
     may be a string or an integer.  Requires ange-ftp or efs for
     remote retrievals.

`link-to-string-match'
     Finds STRING's Nth occurrence in FILE and displays location at
     window top.  Returns t if found, nil if not.

`man-show'
     Displays man page on TOPIC, which may be of the form
     `<command>(<section>').

`rfc-toc'
     Computes and displays summary of an Internet rfc in BUF-NAME.
     Assumes point has already been moved to start of region to
     summarize.  Optional OPOINT is point to return to in BUF-NAME
     after displaying summary.

`text-toc'
     Jumps to the text file SECTION referenced by a table of contents
     entry at point.

`www-url'
     Follows a link given by URL.  The variable,
     ACTION-KEY-URL-FUNCTION, can be used to customize the url browser
     that is used.

   The use of action types provides a convenient way of specifying
button behavior without the need to know how to program.  Expert users
who are familiar with Emacs Lisp, however, may find that they often
want to tailor button actions in a variety of ways not easily captured
within a type system.  In such cases, HUI:EBUT-PROMPT-FOR-ACTION should
be set non-nil.  This will cause Hyperbole to prompt for an action to
override the button's action type at each explicit button creation.  For
those cases where the action type is sufficient, a nil value should be
entered for the action.  An action may be any Lisp form that may be
evaluated.


File: hyperbole.info,  Node: Button Type Precedence,  Next: Button Files,  Prev: Action Types,  Up: Buttons

Button Type Precedence
======================

   Explicit buttons always take precedence over implicit buttons.
Thus, if a button selection is made which falls within both an explicit
and implicit button, only the explicit button will be selected.
Explicit button labels are not allowed to overlap; Hyperbole's behavior
in such cases is undefined.

   If there is no explicit button at point during a selection request,
then each implicit button type predicate is tested in turn until one
returns non-nil or all are exhausted.  Since two implicit button types
may have overlapping domains (those contexts in which their predicates
are true), only the first matching type is used.  The type predicates
are tested in *reverse* order of definition, i.e. most recently entered
types are tested first, so that personal types defined after standard
system types take precedence.  It is important to keep this order in
mind when defining new implicit button types.  By making their match
predicates as specific as possible, one can minimize any overlapping of
implicit button type domains.

   Once a type name is defined, its precedence relative to other types
remains the same even if you redefine the body of the type, as long as
you don't change its name.  This allows incremental modifications to
types without having to worry about shifts in type precedence.  *Note
Creating Types::, for information on how to develop or modify types.


File: hyperbole.info,  Node: Button Files,  Next: Utilizing Explicit Buttons,  Prev: Button Type Precedence,  Up: Buttons

Button Files
============

   It is often convenient to create lists of buttons that can be used as
menus to provide centralized access to distributed information pools or
for other purposes.  These files can serve as useful roadmaps to help
efficiently guide a user through both unfamiliar and highly familiar
information spaces.  Files that are created specifically for this
purpose, we call "button files".

   The Hyperbole menu system provides quick access to two types of these
button files: personal and directory-specific, through the ButFile menu.
(The variable, HBMAP:FILENAME, contains the base name of these standard
button files.  Its standard value is `HYPB'.)

   A personal button file may serve as a user's own roadmap to
frequently used resources.  Selection of the ButFile/PersonalFile menu
item displays this file for editing.  The default personal button file
is stored within the directory given by the HBMAP:DIR-USER variable
whose standard value is `~/.hyperb'.  The standard Hyperbole
configuration also appends all global buttons to the end of this file,
one per line, as they are created.  So you can edit or annotate them
within the file.

   A directory-specific button file may exist for each file system
directory.  Such files are useful for explaining the contents of
directories and pointing readers to particular highlights within the
directories.  Selection of the ButFile/DirFile menu item displays the
button file for the current directory; this provides an easy means of
updating this file when working on a file within the same directory.
If you want to view some other directory-specific button file, simply
use the normal Emacs file finding commands.

   One might suggest that menu quick access be provided for
group-specific and site-specific button files.  Instead, link buttons
to such things should be placed at the top of your personal button
file.  This provides a more flexible means of quick access.


File: hyperbole.info,  Node: Utilizing Explicit Buttons,  Prev: Button Files,  Up: Buttons

Utilizing Explicit Buttons
==========================

   Explicit buttons are a fundamental building block for creating
personal or organizational hypertext networks with Hyperbole.  This
section summarizes the user-level operations available for managing
these buttons.

* Menu:

* Creation::
* Renaming::
* Deletion::
* Modification::
* Location::
* Buttons in Mail::
* Buttons in News::

