hyperbole / HY-README

# See "hversion.el" for the Hyperbole lisp code directory entry.
# SUMMARY:	Information Hyperbole users and maintainers should read.
# AUTHOR:       Bob Weiner
# ORG:
#               The Force for Open Source(TM)
#               Web: - Learn all about Open Source.
#               E-mail: <>  
# ORIG-DATE:    19-Oct-91 at 03:27:47
# LAST-MOD:     18-Jun-99 at 16:54:11 by Bob Weiner
# Copyright (C) 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999 and the Free Software Foundation, Inc.
# This file is part of Hyperbole.

We hope you enjoy using Hyperbole.  Feel free to mail or post news containing
this file wherever it may be of use.

*			Table of Contents
			* Files
			* How to Obtain
			* Installation / Configuration
			* Invocation
			* Quick Reference
			* User Quotes
			* Why was Hyperbole developed?

*			   Files

See the "HY-ABOUT" file for an overview of Hyperbole and

See the "HY-NEWS" file for a summary of new features in this release.

See the "HY-COPY" file for license information.

See the "MANIFEST" file for summaries of Hyperbole files.

"man/" contains the Info version of the Hyperbole User
Manual. can also provide professionally printed and bound
versions of the user manual in quantity for corporate use.

*			     How to Obtain

The latest production release of Hyperbole is always available for
download from  Professional releases of Hyperbole may
also be purchased there to help support development; they include
Hyperbole with full source code, a printed copy of this manual and
installation support.  Ongoing technical support and automatic upgrades
are available separately.  Further contact information may be found at
the top of this file.

Hyperbole works best when used together with's integrated
development environment, InfoDock.  InfoDock provides a modern user interface
on top of XEmacs, information management, and powerful software development
tools, all in one package.  Hyperbole is available as part of InfoDock or as
a standalone package for use with XEmacs or GNU Emacs.

Once you have obtained a Hyperbole distribution archive, move the
archive to the directory below which you want the hyperbole/ production
directory installed.

If you have obtained the Hyperbole distribution in gzipped, tar archive
format (.tgz suffix), then unpack the archive to create the
hyperbole/ directory by using the GNU version of the `zcat'
program, sometimes called `gzcat' or the `gunzip' program:

   zcat beopen-hyperbole*tgz | tar xvf -
   gunzip beopen-hyperbole*tgz; tar xvf beopen-hyperbole*tar

Alternatively, if you have obtained the Hyperbole distribution in zipped 
format (.zip suffix), then use your favorite unzip utility to create the
hyperbole/ directory.

*		      Installation / Configuration

If you are using InfoDock, Hyperbole is pre-configured so you can simply skip
to the next section.

Follow the instructions in the DESCRIPTION section at the top of the
"Makefile" to configure, build and install Hyperbole.


If you use mouse keys, be sure to add the lines below which load Hyperbole
after any setup of personal or site mouse key bindings, to ensure that
Hyperbole's mouse keys are properly initialized.  If you use any Hyperbole
mail or news support, 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

To set up so that all users have Hyperbole loaded for them, add the
following lines to a site initialization file such as "site-start.el".
Otherwise, each user will have to add these lines to his own "~/.emacs"
initialization file.  If you also use the OO-Browser package,
ensure that the following Hyperbole load instructions are executed before
the OO-Browser is loaded to minimize any potential conflict with the partial
set of Hyperbole variable settings which the OO-Browser provides.

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

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

To fully load Hyperbole upon startup, add the additional line:

   (require 'hsite)

That's all there is to the installation.

*			    Invocation

Once Hyperbole has been installed for use at your site, you can invoke its
commands in one of three ways:

   use the Hyperbole entry on your menubar;

   type {C-h h} or {M-x hyperbole RET} to bring up the Hyperbole main menu
   in the minibuffer window;

   use a specific Hyperbole command such as an Action Key click on a
   pathname to display the associated file or directory.

Read the Hyperbole Manual to learn all about it.

*			    Quick Reference

"MANIFEST" summarizes most of the files in the distribution.

See "DEMO" for a demonstration of standard Hyperbole button capabilities.

Naming conventions:

  - All Hyperbole-specific code files begin with an 'h', aside from the
    Koutliner files which are in the kotl/ subdirectory and begin with a 'k'.

  - Hyperbole user-interface files begin with 'hui-' or 'hmous'.

  - Files that define implicit button types begin with 'hib'.

  - Encapsulations of foreign systems begin with 'hsys-'.

Most of the standard Emacs user interface for Hyperbole is located in
"hui.el".  Most of the Hyperbole application programming interface can be
found in "hbut.el".  "hbdata.el" encapsulates the button attribute storage
handling presently implemented by Hyperbole.  "hmail.el" provides a basic
abstract interface for folding mail readers other than Rmail into Hyperbole.

See the "( and Answers" appendix in the Hyperbole
manual for information on how to alter the default context-sensitive
Hyperbole key bindings.

*			      User Quotes

  *** MAN I love Hyperbole!!!  Wow! ***

				    	-- Ken Olstad
					   Cheyenne Software, Inc.


  I *love* koutlines.

	   				-- Bob Glickstein
					   Z-Code Software Corporation


  For me, Emacs isn't Emacs without Hyperbole.  I have depended on Hyperbole
  daily since 1992, when I first started using it to manage my development
  environment.  It didn't take long before I could summon almost any
  information I needed directly from within my editing environment with an
  implicit button. Since I almost never have to slow down to look for
  things--one context-dependent button usually produces exactly what I need
  --I am able to maintain focus on the task I am working on and complete it
  more quickly.  With its gestural interface, seamless integration with other
  Emacs packages and incredibly useful set of core features.  I think that
  Hyperbole is one of the best designed and most easily extensible software
  products I have ever come across.  It is certainly the one which has made
  the biggest improvement in my personal productivity.

					-- Chris Nuzum
					   Vice President, Twisted Systems, Inc.


  I've found Hyperbole (in conjunction with XEmacs) to be very useful
  for signal processing algorithm development.

  For me, it has almost completely obsoleted the engineering notebook:
  I keep a set of files with ideas, algorithms, and results, linked
  together and to the implementation in C++ files.  Using XEmacs'
  support for embedding graphics, I've written a mode that accepts
  image tags (formatted like HTML), and reads in GIF files to display
  plots.  I have another program that converts the file to HTML (not
  perfect, but adequate), so I can put any aspect of development on
  our internal web for others to see.

                                        -- Farzin Guilak
		                           Protocol Systems, Inc., Engineer


  I am blind and have been using Hyperbole since 1992.  I used to use a PC as
  a talking terminal attached to a UNIX system, but then I developed
  Emacspeak which lets me use Emacs and Hyperbole from standard UNIX
  workstations with an attached voice synthesizer.

  My main uses are:
    1) Global and implicit buttons for jumping to ftp sites.
    2) The contact manager with Emacspeak support.
    3) Explicit buttons as part of comments made about a structured document.
       Each button jumps to the document section referred to by the comment.
       This is very, very useful.
    4) The Hyperbole outliner, which I find a very useful tool.  I've
       implemented Emacspeak extensions to support it.

					-- TV Raman
					   Digital Cambridge Research Lab


  I've been a grateful Hyperbole user for a few years now.  Hyperbole's
  flexibility and ease of use is a marvel.

  Mainly, I write easy little implicit button types (and corresponding action
  types) to make my life easier.  For example, I have an implicit button type
  to bury certain buffers when I click at their bottoms, one that recognizes
  a bug report record in various contexts and edits it, one that links pieces
  of test output in a log file to the corresponding test case source code
  (EXTREMELY helpful in interpreting test output), others that support our
  homegrown test framework, one that handles tree dired mode the way I'd
  like, one that completely handles wico menus (I've also overloaded the
  wconfig actions triggered by diagonal mouse drags with wicos actions), and
  a couple that support interaction with BBDB.

  Other than that, I keep a global button file with 30 or so explicit buttons
  that do various little things, and I index saved mail messages by putting
  explicit link-to-mail buttons in an outline file.

				    	-- Ken Olstad
					   Cheyenne Software, Inc.


  In general, Hyperbole is an embeddable, highly extensible hypertext
  tool.  As such, I find it very useful. As it stands now, Hyperbole is
  particularly helpful for organizing ill-structured or loosely coupled
  information, in part because there are few tools geared for this purpose.
  Hyperbole also possesses a lot of potentials in supporting a wider
  spectrum of structuredness, ranging from unstructured to highly
  structured environments, as well as structural changes over time.

  Major Uses:

  * Menu interface to our own Epoch-based collaborative support environment
    called CoReView: This interface brings together all top-level user
    commands into a single partitioned screen, and allows the end user to
    interact with the system using simple mouse-clicking instead of the
    meta-x key.

  * Gateway to internet resources: this includes links to major Internet
    archive sites of various types of information. Links are made at both
    directory and file levels.

  * Alternative directory organizer: The hierarchical nature of the Unix
    file system sometimes makes it difficult to find things quickly and
    easily using directory navigational tools such as dired. Hyperbole
    enables me to create various "profile" views of my directory tree, with
    entries in these views referring to files anywhere in the hierarchy.

  * Organizing and viewing online documentation: using Hyperbole along with
    Hyper-man and Info makes it truly easy to look up online documentation.
  * Other desktop organization tasks: including links to various mail
    folders, saved newsgroup conversation threads, online note-taker,
    emacs-command invocations, etc.

				    	-- Dadong Wan
					   University of Hawaii


  Hyperbole is the first hyper-link system I've run across that is
  actually part of the environment I use regularly, namely Emacs. The
  complete flexibility of the links is both impressive and expected -- the
  idea of making the link itself programmable is clever, and given that one
  assumes the full power of Emacs.  Being able to send email with buttons
  in it is a very powerful capability.  Using ange-ftp mode, one can make
  file references "across the world" as easily as normal file references.

				        -- Mark Eichin
					   Cygnus Support

   I just wanted to say how much I enjoy using the Hyperbole outliner.
   It is a great way to quickly construct very readable technical documents
   that I can pass around to others.   Thanks for the great work.  

				        -- Jeff Fried


   The Hyperbole system provides a nice interface to exploring corners of
   Unix that I didn't know existed before.

					-- Craig Smith

*		      Why was Hyperbole developed?

Hyperbole was originally designed to aid in research aimed at Personalized
Information production/retrieval Environments (PIEs).  Hyperbole is a
PIE Manager that provides services to PIE Tools.  PIEmail, a mail reader is
the only PIE Tool developed to date.

An examination of many hypertext environments as background research did
not turn up any that seemed suitable for the research envisioned, mainly
due to the lack of rich, portable programmer and user environments.  We also
tired of trying to manage our own distributed information pools with standard
UNIX tools.  And so Hyperbole was conceived and raved about until it
got its name.

Since then Hyperbole has proved indispensible at improving information
access and organization in daily use for over seven years.  Why not start
improving your information processing efficiency today?