What does GNU Hyperbole do?

Home About Codeberg

GNU Hyperbole is one of the more well-established Emacs software packages out there, originating in the early 1990s, and has been on ELPA from the very beginning. Every so often, I find someone on the Internet who has stumbled upon the Hyperbole package, has read some of the documentation, and felt the need to ask the question, what exactly does Hyperbole do? The simplest possible explanation is that Hyperbole is a personalized information management system customizable with the full power of Emacs. But this explanation is usually less than satisfying, possibly because Emacs already has a number of built-in major and minor modes that can help to manage your personal information, so it begs the questions: how is Hyperbole different, what useful features does it add? I'll attempt to answer that question.

Hyperbole augments the already very powerful textual user interface (TUI) that is built-in to Emacs with the most useful aspects of a graphical user interface (GUI) in a very non-invasive way. The rest of this article explains the Hyperbole user experience, and recommends a simple but useful workflow that you can use to get started with it.

Enhancing the Emacs user experience

Let's start with a microscopic view, and then zoom out. The fundamental mechanism of Hyperbole is the hyperlink, that is, push buttons that perform actions. Of course, hyperlinks exist everywhere in Emacs, but Hyperbole works a bit differently: it provides a mechanism called implicit links or implicit buttons, which are triggered with a universal action key binding {M-RET} that behaves like the left mouse click in a GUI. So an implicit button is really any arbitrary text that is recognized by a cascade of context sensitive Hyperbole rules that are executed on-demand when the universal action key binding is pressed. Therefore, neither Emacs text properties, nor a markup language are necessary to create actionable text with Hyperbole.

A simply analogy

When you use a well-designed GUI, you can perform all sorts of different actions with just the left mouse click. This is because buttons, check boxes, scroll bars, title bars, every graphical element that you can click on in a GUI has it's own executable command attached to it. There are always visual cues that indicate what behavior to expect when you click. This is the fundamental principle behind Hyperbole, but applied to textual elements, rather than graphical elements. The big difference is that a GUI uses geometric information about a 2D scene to decide what action a click will trigger, whereas Hyperbole uses textual pattern matching.

Hyperbole is a global minor mode

As a global minor mode, Hyperbole push button behavior is active everywhere, regardless of whatever other major or minor modes are active. This is why I think of the universal action key as similar to a left mouse click in a GUI. In fact, Hyperbole can be used with a mouse, but more often you will use the universal keyboard action key binding, {M-RET} to trigger executable code associated with textual elements. (I prefer to say click on to mean typing the {M-RET} key binding.)

For example, Hyperbole treats any URL in any buffer as an actionable hyperlink, regardless of whether the current major mode has recognized that URL or applied clickable text properties to it. It works because URLs have an easily recognizable encoding. Once you have learned to recognize what a URL looks like, there is never any confusion as to what sort of action will happen when you click on that URL: you expect (and it should always) trigger the command to open that URL in a web browser.

Hyperbole's pattern matching rules are written in Lisp, and so can be much more elaborate than simply recognizing a URL with a regular expression pattern. We can probably think of other text patterns to which we could assign some obvious action to be performed when it is clicked:

And there are much deeper implications to the concept of implicit links, since you have the power to define implicit button types and actions for yourself. You can assign any executable actions that work in any and all buffers to any arbitrary text, without having to install or roll your own minor mode. Here are some ideas for the kinds of implicit links that do not exist by default, but you could define for yourself:

Getting started with using Hyperbole

If all this sounds intriguing to you and you want to give it a try, it is very easy to get started. You can install Hyperbole through the Emacs package manager, and then just start using the {M-RET} key on anything you want — don't be afraid to experiment with using {M-RET} on various things. You can also use {C-u M-RET} to pop-up a buffer explaining what action would be triggered by a piece of text. I would also encourage you to run the Hyperbole interactive demo with {C-h h d d} for more ideas.

Note: pressing the {M-RET} key chord will automatically enable the Hyperbole global minor mode, if it is not already enabled.

But let me recommend a more useful workflow: the first thing you should do is to create a personal button file, which can serve as a kind of dashboard or homepage, as a kind of jumping-off point into your various projects. This file is called HYPB and is accessible by the {C-h h b p} key binding. Typing this key binding creates the file if it does not exist.

Your personal button file will be stored into the Hyperbole user directory, which is at the ~/.hypb/ path by default. You can change this location by setting the hbmap:dir-user global variable in your init.el.

Once your personal HYPB button file is open in a buffer, you can begin creating hyperlink buttons. If you are not sure where to begin, I recommend you try creating buttons for some of your commonly used project directories as a starting point. To create a button simply type the path to your project directory. Then press {M-RET} on that directory.

From there you can start experimenting with other button types, like setting a window layout for a particular project, or running a shell script in the project directory. Hyperbole is one of the most thoroughly documented Emacs packages ever written, check out the user manual for more ideas on how to use it.

Conclusion

Hyperbole provides a powerful set of tools to assign actions to text, which is especially useful for creating relationships between pieces of information. As a global minor mode, the up-front investment is very low: just install it and use it whenever you see the need. You can trigger any implicit link with {M-RET}, which is a pretty useful feature in and of itself, even if you never use any of the other extensive Hyperbole features. Over all, I think it is a package worth keeping in your Emacs configuration.

Further reading

Special thanks

Much gratitude and a big thank you to Bob Weiner, the author of Hyperbole, for spending his time to help me keep this article both factually correct, and (if I may say so myself) interesting to read!