# See "hversion.el" for the Hyperbole lisp code directory entry.
#
# FILE:		README
# SUMMARY:	Information Hyperbole users and maintainers should read.
#
# AUTHOR:       Bob Weiner
#
# ORG:          InfoDock Associates.  We sell corporate support and development
#               contracts for InfoDock, Emacs and XEmacs.
#               E-mail: <info@infodock.com>  Web: http://www.infodock.com
#               Tel: +1 408-243-3300
#
# ORIG-DATE:    19-Oct-91 at 03:27:47
# LAST-MOD:     17-Mar-97 at 21:14:10 by Bob Weiner
#
# See the Copyright section below for license information.

We thank Motorola Inc. for sponsoring our initial development work on
Hyperbole.

We hope you enjoy using and developing with Hyperbole.  Suggestions
and bug reports are welcome, as described later in this document.
Feel free to mail or post news containing this file wherever it may be
of use.


===========================================================================
*			Table of Contents
===========================================================================
			* Hyperbole Overview
			* What's New
			* How to Obtain
			* Installation / Configuration
			* Quick Reference
			* Mail Lists
			* User Quotes
		        * Why was Hyperbole developed?
		        * Copyright


===========================================================================
*			   Hyperbole Overview
===========================================================================

Hyperbole 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 MS-Windows, X or NEXTSTEP windows: XEmacs and GNU Emacs.

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:

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

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

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

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

A Hyperbole user works with buttons; 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:

   1.  Explicit Buttons
          created by Hyperbole, accessible from within a single document; 

   2.  Global Buttons
          created by Hyperbole, accessible anywhere within a user's
          network of documents;

   3.  Implicit Buttons
          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.

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

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 Browsing
       Embed cross-references in your favorite documentation format.

       Add a point-and-click interface to existing documentation.

       Link code and design documents.  Jump to the definition of an
       identifier from its use within code or its reference within
       documentation.

    Brainstorming
       Capture ideas and then quickly reorganize them with the Hyperbole
       outliner.  Link to related ideas, eliminating the need to copy
       and paste information into a single place.

    Help/Training Systems
       Create tutorials with embedded buttons that show students how
       things work while explaining the concepts, e.g. an introduction
       to UNIX commands.  This technique can be much more effective than
       descriptions alone.

    Archive Managers
       Supplement programs that manage archives from incoming
       information streams 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.


===========================================================================
*			 What's New in V4.02-V4.023
===========================================================================

  (See "ChangeLog" for more complete details of changes.)

  ACTION AND ASSIST KEYS

    - Action Key clicks on HTTP URLs use the Emacs internal web browser
      if not running under a window system.

    - Support for new ID-edit mode (a part of InfoDock) that allows rapid,
      cutting, copying and yanking of regions plus fast display management.
      In this mode, the Action and Assist keys yank the previously selected
      region at point.

    - An Action Key press on a Java identifier jumps to its definition
      (if an associated TAGS file or OO-Browser environment exists).  The
      same is true for an `@see' cross-reference within a Java comment.  The
      variable, `smart-java-package-dirs,' determines where Java package
      source can be found when the OO-Browser is not in use.

    - An Action Key press on a double or single quoted Emacs Lisp filename
      (without any path) displays the file by looking for it among the
      directories in the variable, `load-path'.

    - If the Action Key is pressed on a function identifier that is defined
      in the same buffer as the reference clicked upon, it will now be
      displayed faster, since the func-menu package will be used.  The
      reference identifier will also flash when pressed, if the display
      device supports this.

  EMACS VERSIONS

    - Further support for MS-DOS, Windows NT Emacs 19, and Win-Emacs.

    - Fixed configuration setup problem when running Emacs 19 on a dumb
      terminal.

  KOUTLINER

    - XEmacs 19.14 and above: Fixed display of current viewspec in the
      modeline to accomodate modeline extents (specialized modeline regions).
      This eliminated an error that occurred when reading in an Koutline file.

    - Fixed bug that prevented installation of Koutliner mode-specific
      menubar when running InfoDock.

  MENUS

    - New Hyperbole/About menu item added.  In minibuffer menus, this item is
      found under the Doc/ menu.

    - New window system menu, Hyperbole/Customization (and minibuffer menu,
      Cust/) added to set Hyperbole options, including where Hyperbole link
      referents are displayed, where URLs are displayed and whether to use
      proportional or windowful scrolling when a Smart Key is pressed at the
      end of a line.

    - The default setting of where Hyperbole link references are displayed
      may be set in "hsite.el" via the variable, `hpath:display-where'
      (after Hyperbole has been installed using `make install').
      See its documentation for detail.

    - The Hyperbole/Global-Button menu now includes a menu item that will
      activate each existing global button.  The Hyperbole/Explicit-Button
      menu does the same thing for explicit buttons in the current buffer.

  ROLODEX

    - Date stamps are added to each rolodex entry when created and updated
      when edited.  This feature can be toggled on and off with:
      M-x rolo-toggle-datestamps RET, or via the Toggle-Rolodex-Dates menu
      item on the Customization menu.

    - wrolo-add-hook is called after a new entry is added.
      wrolo-edit-hook is called after an entry is displayed for editing.

    - Rolo-edit, bound to {e} in the rolodex match buffer, now works properly
      if the rolodex is loaded before the rest of the Hyperbole system.


===========================================================================
*			     How to Obtain
===========================================================================

InfoDock Associates, the developer of Hyperbole and InfoDock (an industrial
quality turn-key version of XEmacs), is a firm dedicated to radical
productivity improvement in technical environments, whether in software
development or other knowledge intensive disciplines.  Our initial offerings
include high quality commercial support, training, books and custom package
development for InfoDock, XEmacs or GNU Emacs on a variety of platforms.
InfoDock provides a modern user interface on top of Emacs, information
management, and powerful software development tools, all in one package.

Contact us at <info@infodock.com> or visit our web site at
http://www.infodock.com.

Hyperbole is available as part of InfoDock or XEmacs and also as a standalone
package via anonymous ftp across the Internet.  Do not send requests to have
it mailed to you since it won't be.  Instead have another party who has
Internet access obtain it for the both of you.

Here is how to obtain Hyperbole as a standalone package on the Internet:

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

   cd <LOCAL-LISP-DIR>

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

   prompt> ftp ftp.xemacs.org  (If this doesn't work, try `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*

Close the ftp connection:

   ftp> quit
   221 Goodbye.

Unpack the tar archive using the GNU version of the 'zcat' program:

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

Apply any patches you retrieved, also:

   cd hyperbole; patch < <patch-file>


===========================================================================
*		      Installation / Configuration
===========================================================================

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.

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:

   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.

----

The Hyperbole Manual is included 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, you can simply set it so that <HYPERBOLE-DIR> is
an element in the list.  Otherwise, from a shell, cd to the directory given
by your 'Info-directory' variable and execute the following command:

      (rm hyperbole.info*; cp <HYPERBOLE-DIR>/man/hyperbole.info* .)

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

----

To set up so that all Emacs 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.  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.

----

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.


===========================================================================
*			    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 "(hyperbole.info)Questions and Answers" appendix in the
Hyperbole manual for information on how to alter the default
context-sensitive Hyperbole key bindings.


===========================================================================
*			       Mail Lists
===========================================================================

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

<hyperbole-request@infodock.com>
<hyperbole-announce-request@infodock.com>

   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 in the *body* of your message to execute requests,
   where you substitute your own values for the <> delimited items and items
   enclosed in [] are optional.
 
     subscribe <mail-list-name> [<your-email-address>]
       or
     unsubscribe <mail-list-name> [<your-email-address>]

   For example:

     To: hyperbole-request@infodock.com
     Subject: Used if a human happens to read your mail.

     subscribe hyperbole joe@nowhere.gov

   To change your address, you must unsubscribe your old address with
   once command and subscribe your new address with another command, though
   you can embed multiple commands on separate lines within a single message.


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

<hyperbole@infodock.com>

   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, e.g. 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@infodock.com>

   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.


===========================================================================
*			      User Quotes
===========================================================================


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

				    	-- Ken Olstad
					   Cheyenne Software, Inc.

-------

  I *love* koutlines.

	   				-- Bob Glickstein
					   Z-Code Software Corporation
-------

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

-------

  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
					   Informix

-------

   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 has been 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.


===========================================================================
*			       Copyright
===========================================================================

The following copyright applies to the Hyperbole system as a whole.

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

Available for use and distribution under the terms of the GNU Public License,
version 2 or higher.

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.

InfoDock Associates sells support and development services for this package
and most other aspects of Emacs or InfoDock.  Contact information is at the
top of this file.

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