1 README -- Intro information on Hyperbole.
3 The author's work on this project has been sponsored by Motorola Inc.
5 We hope you enjoy using and developing with Hyperbole. Suggestions and bug
6 reports are welcome, as described later in this document. Feel free to
7 mail or post news containing this file wherever it may be of use.
10 ===========================================================================
12 ===========================================================================
16 * Installation / Configuration
20 * Why was Hyperbole developed?
24 ===========================================================================
26 ===========================================================================
28 Hyperbole is an open, efficient, programmable information management
29 and hypertext system. It is intended for everyday work on any
30 platform supported by GNU Emacs. It works well with versions of Emacs
31 that supports windowed systems but can also be used on text only
34 Hyperbole allows hypertext buttons to be embedded within unstructured
35 and structured files, mail messages and news articles. It offers
36 intuitive mouse-based control of information display within multiple
37 windows. It also provides point-and-click access to Info manuals, ftp
38 archives, Wide-Area Information Servers (WAIS), and the World-Wide Web
39 (WWW) hypertext system through encapsulations of software that support
42 Hyperbole consists of four parts:
44 1. Info Management: an interactive information management interface,
45 including a powerful rolodex, which anyone can use. It is easy
46 to pick up and use since it introduces only a few new mechanisms
47 and provides user-level facilities through a menu interface,
48 which you control from the keyboard or the mouse;
50 2. Hypertext Outliner: an outliner with multi-level autonumbering
51 and permanent ids attached to each outline node for use as
52 hypertext link anchors, plus flexible view specifications that
53 can be embedded within links or used interactively;
55 3. Button Types: A set of hyper-button types that provides
56 core hypertext and other behaviors. Users can make simple
57 changes to button types and those familiar with Emacs Lisp can
58 quickly prototype and deliver new types;
60 4. Programming Library: a set of programming library classes for
61 system developers who want to integrate Hyperbole with another
62 user interface or as a back-end to a distinct system. (All of
63 Hyperbole is written in Emacs Lisp for ease of modification.
64 Although Hyperbole was initially designed as a prototype, it has
65 been engineered for real-world usage and is well structured.)
67 A Hyperbole user works with buttons; he may create, modify,
68 move or delete buttons. Each button performs a specific action, such as
69 linking to a file or executing a shell command.
71 There are three categories of Hyperbole buttons:
74 created by Hyperbole, accessible from within a single document;
77 created by Hyperbole, accessible anywhere within a user's
81 buttons created and managed by other programs or embedded
82 within the structure of a document, accessible from within a
83 single document. Hyperbole recognizes implicit buttons by
84 contextual patterns given in their type specifications.
86 Hyperbole buttons may be clicked upon with a mouse to activate them or
87 to describe their actions. Thus, a user can always check how a button
88 will act before activating it. Buttons may also be activated from a
89 keyboard. (In fact, virtually all Hyperbole operations, including menu
90 usage, may be performed from any standard character terminal interface, so
91 one need not be anchored to a workstation all day).
93 Hyperbole does not enforce any particular hypertext or information management
94 model, but instead allows you to organize your information in large or small
95 chunks as you see fit. The Hyperbole outliner organizes information
96 hierarchies which may also contain links to external information sources.
98 Some of Hyperbole's most important features include:
100 Buttons may link to information or may execute procedures, such as
101 starting or communicating with external programs;
103 One simply drags between a button source location and a link destination
104 to create or to modify a link button. The same result can be achieved
107 Buttons may be embedded within electronic mail messages;
109 Outlines allow rapid browsing, editing and movement of chunks of
110 information organized into trees (hierarchies);
112 Other hypertext and information retrieval systems may be
113 encapsulated under a Hyperbole user interface (a number of samples
116 Typical Hyperbole applications include:
118 Personal Information Management
119 Overlapping link paths provide a variety of views into an
122 A search facility locates buttons in context and permits quick
125 Documentation Browsing
126 Embed cross-references in your favorite documentation format.
128 Add a point-and-click interface to existing documentation.
130 Link code and design documents. Jump to the definition of an
131 identifier from its use within code or its reference within
135 Capture ideas and then quickly reorganize them with the Hyperbole
136 outliner. Link to related ideas, eliminating the need to copy
137 and paste information into a single place.
139 Help/Training Systems
140 Create tutorials with embedded buttons that show students how
141 things work while explaining the concepts, e.g. an introduction
142 to UNIX commands. This technique can be much more effective than
146 Supplement programs that manage archives from incoming
147 information streams by having them add topic-based buttons that
148 link to the archive holdings. Users can then search and create
149 their own links to archive entries.
152 ===========================================================================
153 * What's New in V5.0.5?
154 ===========================================================================
156 Version 5.0.5 fixes a problem in hyperbole.texi so it is compatible
159 See "ChangeLog" and "NEWS" for more complete details of changes.
162 ===========================================================================
164 ===========================================================================
166 Hyperbole can be downloaded here: "http://ftp.gnu.org/gnu/hyperbole/"
168 Unpack the tar archive using the GNU version of the 'zcat' program:
170 zcat h*tar.gz | tar xvf -
172 gunzip h*tar.gz; tar xvf h*tar
175 ===========================================================================
176 * Installation / Configuration
177 ===========================================================================
179 Hyperbole is built and installed using configure. cd to the directory
180 where you unpacked the tar archive, <HYPERBOLE-DIR>.
184 Now you configure the build by using the configure script.
188 It is possible to give options to configure. Try the option '--help'
189 with configure for more info.
191 Now you can build and install Hyperbole doing "make" and "make
194 If you have downloaded the source using CVS you need to create the
195 configure script first using autotools.
199 The Hyperbole Manual is included in two forms:
201 "man/hyperbole.info" - online version
202 "man/hyperbole.texi" - source form
204 To add pointers to the Info version of the Hyperbole manual within your Info
205 directory, follow these instructions. If `Info-directory-list' is bound as a
206 variable within your Emacs, you can simply set it so that <HYPERBOLE-DIR> is
207 an element in the list. Otherwise, from a shell, cd to the directory given
208 by your 'Info-directory' variable and execute the following command:
210 (rm hyperbole.info*; cp <HYPERBOLE-DIR>/man/hyperbole.info* .)
212 Then add an Info menu entry for the Hyperbole manual in your Info "dir" file:
213 (the `*' should be placed in the first column of the file):
215 * Hyperbole:: GNU Emacs-based everyday information management system.
216 Use {C-h h d d} for a demonstration. Includes context-sensitive
217 mouse and keyboard support, a powerful rolodex, an autonumbered
218 outliner with hyperlink anchors for each outline cell, and extensible
219 hypertext facilities including hyper-links in mail and news messages.
223 To set up so that all Emacs users have Hyperbole loaded for them, add the
224 following lines to a site initialization file such as "site-start.el".
225 Otherwise, each user will have to add these lines to his own "~/.emacs"
226 initialization file. The following instructions use the term
227 <HYPERBOLE-DIR>/ to refer to your hyperbole/ directory, so substitute your
230 To autoload Hyperbole so that it loads only when needed:
232 (defvar hyperb:dir "<HYPERBOLE-DIR>/")
233 "Directory where the Hyperbole executable code is kept.
234 It must end with a directory separator character.")
236 (load (expand-file-name "hversion" hyperb:dir))
237 (load (expand-file-name "hyperbole" hyperb:dir))
239 To fully load Hyperbole upon startup, add the additional line:
243 That's all there is to the installation.
247 Once Hyperbole has been installed for use at your site, you can invoke it
248 with {C-h h} or {M-x hyperbole RET} to bring up the Hyperbole main menu in
249 the minibuffer window.
252 ===========================================================================
254 ===========================================================================
256 "MANIFEST" summarizes most of the files in the distribution.
258 See "DEMO" for a demonstration of standard Hyperbole button
263 - All Hyperbole-specific code files begin with an 'h', aside from the
264 Koutliner files which are in the kotl/ subdirectory and begin with a 'k'.
266 - Hyperbole user-interface files begin with 'hui-' or 'hmous'.
268 - Files that define implicit button types begin with 'hib'.
270 - Encapsulations of foreign systems begin with 'hsys-'.
272 Most of the standard Emacs user interface for Hyperbole is located in
273 "hui.el". Most of the Hyperbole application programming interface can be
274 found in "hbut.el". "hbdata.el" encapsulates the button attribute storage
275 handling presently implemented by Hyperbole. "hmail.el" provides a basic
276 abstract interface for folding mail readers other than Rmail into Hyperbole.
278 See the "(hyperbole.info)Questions and Answers" appendix in the
279 Hyperbole manual for information on how to alter the default
280 context-sensitive Hyperbole key bindings.
283 ===========================================================================
285 ===========================================================================
287 There are two Hyperbole-related mail lists. One for discussing using
288 hyperbole, hyperbole-users, and the other for reporting bugs,
291 To subscribe to the mail lists use the links below with your web
292 browser (or if your using hyperbole just click on them)
294 http://lists.gnu.org/mailman/listinfo/hyperbole-users
296 http://lists.gnu.org/mailman/listinfo/bug-hyperbole
298 All administration of the Hyperbole mailing lists should be
299 dealt with one of these web addresses. That includes addition,
302 Don't send administrative requests to the mail lists or people will
303 wonder why you don't know that the list administration is handled on
306 So there are two Hyperbole-related mail lists:
308 <hyperbole-users@gnu.org>
310 Mail list for discussion of all issues regarding using Hyperbole.
312 Always use your Subject and/or Summary: lines to state the position that
313 your message takes on the topic that it addresses.
315 Statements end with periods, questions with question marks (typically),
316 and high energy, high impact declarations with exclamation points. This
317 simple rule makes all e-mail communication much easier for recipients to
318 handle appropriately.
320 If you ask a question, your subject line should end with a ?,
321 e.g. "Subject: How can man page SEE ALSOs be made implicit buttons?" A
322 "Subject: Re: How can ..." then indicates an answer to the question.
323 Question messages should normally include your Hyperbole and Emacs
324 version numbers and clearly explain your problem and surrounding issues.
325 Otherwise, you will simply waste the time of those who may want to help
326 you. (Your top-level Hyperbole menu shows its version number and {`M-x
327 emacs-version <RET>'} gives the other.)
329 If you ask questions, you should consider adding to the discussion by
330 telling people the kinds of work you are doing or contemplating doing
331 with Hyperbole. In this way, the list will not be overwhelmed by
332 messages that ask for, but provide no information.
334 <bug-hyperbole@gnu.org>
336 Bug reports and suggestions should go here. It is important here that
337 you include as much info about your environment and program versions
340 ===========================================================================
342 ===========================================================================
345 *** MAN I love Hyperbole!!! Wow! ***
348 Cheyenne Software, Inc.
355 Z-Code Software Corporation
358 I am blind and have been using Hyperbole since 1992. I used to use a PC as
359 a talking terminal attached to a UNIX system, but then I developed
360 Emacspeak which lets me use Emacs and Hyperbole from standard UNIX
361 workstations with an attached voice synthesizer.
364 1) Global and implicit buttons for jumping to ftp sites.
365 2) The rolodex with Emacspeak support.
366 3) Explicit buttons as part of comments made about a structured document.
367 Each button jumps to the document section referred to by the comment.
368 This is very, very useful.
369 4) The Hyperbole outliner, which I find a very useful tool. I've
370 implemented Emacspeak extensions to support it.
373 Digital Cambridge Research Lab
377 I've been a grateful Hyperbole user for a few years now. Hyperbole's
378 flexibility and ease of use is a marvel.
380 Mainly, I write easy little implicit button types (and corresponding action
381 types) to make my life easier. For example, I have an implicit button type
382 to bury certain buffers when I click at their bottoms, one that recognizes
383 a bug report record in various contexts and edits it, one that links pieces
384 of test output in a log file to the corresponding test case source code
385 (EXTREMELY helpful in interpreting test output), others that support our
386 homegrown test framework, one that handles tree dired mode the way I'd
387 like, one that completely handles wico menus (I've also overloaded the
388 wconfig actions triggered by diagonal mouse drags with wicos actions), and
389 a couple that support interaction with BBDB.
391 Other than that, I keep a global button file with 30 or so explicit buttons
392 that do various little things, and I index saved mail messages by putting
393 explicit link-to-mail buttons in an outline file.
396 Cheyenne Software, Inc.
400 In general, Hyperbole is an embeddable, highly extensible hypertext
401 tool. As such, I find it very useful. As it stands now, Hyperbole is
402 particularly helpful for organizing ill-structured or loosely coupled
403 information, in part because there are few tools geared for this purpose.
404 Hyperbole also possesses a lot of potentials in supporting a wider
405 spectrum of structuredness, ranging from unstructured to highly
406 structured environments, as well as structural changes over time.
410 * Menu interface to our own Epoch-based collaborative support environment
411 called CoReView: This interface brings together all top-level user
412 commands into a single partitioned screen, and allows the end user to
413 interact with the system using simple mouse-clicking instead of the
416 * Gateway to internet resources: this includes links to major Internet
417 archive sites of various types of information. Links are made at both
418 directory and file levels.
420 * Alternative directory organizer: The hierarchical nature of the Unix
421 file system sometimes makes it difficult to find things quickly and
422 easily using directory navigational tools such as dired. Hyperbole
423 enables me to create various "profile" views of my directory tree, with
424 entries in these views referring to files anywhere in the hierarchy.
426 * Organizing and viewing online documentation: using Hyperbole along with
427 Hyper-man and Info makes it truly easy to look up online documentation.
429 * Other desktop organization tasks: including links to various mail
430 folders, saved newsgroup conversation threads, online note-taker,
431 emacs-command invocations, etc.
437 Hyperbole is the first hyper-link system I've run across that is
438 actually part of the environment I use regularly, namely Emacs. The
439 complete flexibility of the links is both impressive and expected -- the
440 idea of making the link itself programmable is clever, and given that one
441 assumes the full power of Emacs. Being able to send email with buttons
442 in it is a very powerful capability. Using ange-ftp mode, one can make
443 file references "across the world" as easily as normal file references.
449 I just wanted to say how much I enjoy using the Hyperbole outliner.
450 It is a great way to quickly construct very readable technical documents
451 that I can pass around to others. Thanks for the great work.
458 The Hyperbole system provides a nice interface to exploring corners of
459 Unix that I didn't know existed before.
466 ===========================================================================
467 * Why was Hyperbole developed?
468 ===========================================================================
470 Hyperbole has been designed to aid in research aimed at Personalized
471 Information production/retrieval Environments (PIEs). Hyperbole is a
472 PIE Manager that provides services to PIE Tools. PIEmail, a mail reader is
473 the only PIE Tool developed to date.
475 An examination of many hypertext environments as background research did
476 not turn up any that seemed suitable for the research envisioned, mainly
477 due to the lack of rich, portable programmer and user environments. We also
478 tired of trying to manage our own distributed information pools with standard
479 UNIX tools. And so Hyperbole was conceived and raved about until it
483 ===========================================================================
485 ===========================================================================
487 The following copyright applies to the Hyperbole system as a whole.
489 Copyright (C) 1989, 1990, 1991, 1992, 1993, 1994, 1995, 2004, 2005,
490 2006, 2007, 2008 Free Software Foundation, Inc.
492 Available for use and distribution under the terms of the GNU Public
493 License, version 3 or higher.
495 Hyperbole is free software; you can redistribute it and/or modify it
496 under the terms of the GNU General Public License as published by the
497 Free Software Foundation; either version 3 of the License, or (at your
498 option) any later version.
500 Hyperbole is distributed in the hope that it will be useful, but
501 WITHOUT ANY WARRANTY; without even the implied warranty of
502 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
503 General Public License for more details.
505 You should have received a copy of the GNU General Public License
506 along with Hyperbole; if not, write to the Free Software Foundation,
507 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA