Hyperbole Overview

GNU Hyperbole (pronounced Ga-new Hi-per-bo-lee), or just Hyperbole, is like Markdown for hypertext. Hyperbole automatically recognizes dozens of common, pre-existing patterns in any buffer regardless of mode and can instantly activate them as hyperbuttons with a single key: email addresses, URLs, grep -n outputs, programming backtraces, sequences of Emacs keys, programming identifiers, Texinfo and Info cross-references, Org links, Markdown links and on and on. All you do is load Hyperbole and then your text comes to life with no extra effort or complex formatting.

Hyperbole includes easy-to-use, powerful hypertextual button types without the need to learn a markup language. Hyperbole’s button types are written in Lisp and can be wholly independent of the web, i.e. web links are one type of Hyperbole link, not fundamental to its link architecture. However, Hyperbole is a great assistant when editing HTML or Javascript or when browsing web pages and links.

Hyperbole comes pre-built with most of the implicit button types you will need but with a little extra effort and a few lines of code (or even just a few words), you can define your own implicit button types to recognize your specific buttons and then activate them anywhere in Emacs. You press a single key, {M-RET} by default, on any kind of Hyperbole button to activate it, so you can rely on your muscle memory and let the computer do the hard work of figuring out what to do. {C-u M-RET} shows you what any button will do in any context before you activate it, so you can always be sure of what you are doing when needed or if someone emails you a button (Hyperbole allows embedding buttons in email messages too).

Hyperbole is something to be experienced and interacted with, not understood from reading alone. It installs normally as a single Emacs package with no dependencies outside of built-in Emacs libraries, see Installation. Most of Hyperbole is a single global minor mode that you can activate and deactivate at will. And it can be uninstalled quickly as well if need be, so there is no risk in giving it a spin.

Once you have it installed, try the interactive demo with {C-h h d d}. In fact, if you have Hyperbole loaded and you use the Emacs Info reader to read this manual, you can press {M-RET} inside any of the brace delimited series of keys you see in this document and Hyperbole will execute them on-the-fly (easy keyboard-macro style buttons in any text).

Hyperbole can dramatically increase your productivity and greatly reduce the number of keyboard/mouse keys you’ll need to work efficiently.

Hyperbole consists of five parts.

Buttons and Smart Keys

There are three categories of buttons:

explicit buttons

may be added to documents with a simple drag between windows, no markup language needed. With two windows on screen, an explicit link button can be created at point in the current buffer linking to the position in the other window’s buffer by pressing {C-h h e l}.

Implicit buttons

are patterns automatically recognized within existing text that perform actions, e.g. bug#24568 displays the bug status information for that Emacs bug number, without the need for any additional markup. Implicit link buttons can be added to documents with a simple drag between windows too.

Or from the keyboard, With two windows on screen, an implicit link button can be created at point in the current buffer linking to the position in the other window’s buffer by pressing {C-h h i l}. Use {M-1 C-h h i l} instead to be prompted for a name for the implicit button.

Global buttons

are buttons that are activated by name from anywhere within Emacs. They may be either explicit or named implicit buttons. They are the named buttons stored in the a user’s personal button file, directly editable from the minibuffer menu with {C-h h b p}.

With two windows on screen, a global explicit link button can be created at point in the current buffer linking to the position in the other window’s buffer by pressing {C-h h g l}. Use {C-u C-h h g l} instead to create a named global implicit button.

Buttons are activated by pressing {M-RET} on them, clicking them with a dedicated mouse button, or by referencing them by name (global buttons that can be activated regardless of what is on screen). Users create and activate Hyperbole buttons; see Buttons. Emacs Lisp programmers can develop new button types and actions. See Creating Types.

Hyperbole includes two special Smart Keys, the Action Key and the Assist Key, that perform an extensive array of context-sensitive operations across emacs usage, including activating and showing help for Hyperbole buttons. In many popular Emacs modes, they allow you to perform common, sometimes complex operations without having to use a different key for each operation. Just press a Smart Key and the right thing happens. The mouse versions of these keys additionally allow for drag actions. We call these the Action Mouse and Action Assist keys or buttons. See Smart Keys.

HyRolo

a powerful, hierarchical contact manager which anyone can use, is also included. It is easy to learn since it introduces only a few new mechanisms and has a menu interface, which may be operated from the keyboard or the mouse. It may also be used for full-text searching over any record-based information in any number of Org, Markdown, Koutline or Emacs Outline files. Hyperbole buttons may be embedded in any records. See HyRolo.

HyControl

the fastest, easiest-to-use window and frame control available for GNU Emacs. With just a few keystrokes, you can shift from increasing a window’s height by 5 lines to moving a frame by 220 pixels or immediately moving it to a screen corner. Text in each window or frame may be enlarged or shrunk (zoomed) for easy viewing, plus many other features; this allows Hyperbole to quickly control the way information is presented on-screen. See HyControl.

Koutliner

an advanced outliner with multi-level autonumbering and permanent identifiers attached to each outline node for use as hypertext link anchors, per node properties and flexible view specifications that can be included in links or used interactively. See Koutliner.

Hyperbole API

a set of programming libraries 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. It has been engineered for real-world usage and is well structured). See Developing with Hyperbole.

Hyperbole may be used simply for browsing through documents pre-configured with Hyperbole buttons, in which case, you can safely ignore most of the information in this manual. Jump right into the Hyperbole fast demonstration by typing {C-h h d d}, assuming Hyperbole has been installed at your site. If you need to install Hyperbole, see Setup, for Hyperbole installation and configuration information. The demo offers a much less technical introduction to Hyperbole by supplying good examples of use.

Image 1.1: Hyperbole Minibuffer Menu and Demonstration Screenshot

You likely will want to do more than browse with Hyperbole, e.g. create your own buttons. The standard Hyperbole button editing user interface is Emacs-based, so a basic familiarity with the Emacs editing model is useful. The material covered in the Emacs tutorial, normally bound to {C-h t}, is more than sufficient as background. See Glossary in the GNU Emacs Manual, if some emacs-related terms are unfamiliar to you.

A Hyperbole user works with chunks of information that need to be organized, interlinked, and processed. Such chunks can be hyperbuttons, address book contacts, items in an outline, or even database query results. 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 into hierarchies which may also contain links to external information sources. See Koutliner.

Some of Hyperbole’s most significant features are:

• Buttons may link to information or may execute functions, such as starting or communicating with external programs;
• A simple mouse drag from a button source location to its link destination is often all that is needed to create a new link. The keyboard can also be used to emulate such drags;
• 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

Hyperlinks provide a variety of views into an information space. A search facility locates hyperbuttons in context and permits quick selection.

documentation and code browsing

Cross-references may be embedded within documentation and code. Existing documentation may be augmented with point-and-click interfaces to link code with associated design documents, or to permit direct access to the definition of identifiers by selecting their names within code or other documents.

brainstorming

The Hyperbole outliner (see Koutliner) is an effective tool for capturing ideas and then quickly reorganizing them in a meaningful way. Links to related ideas are easy to create so the need to copy and paste information is greatly reduced.

help/training systems

Tutorials with buttons can show students how things work while explaining the concepts, e.g. an introduction to the commands available on a computer system. 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.