Using Hyperbole with tab completion
In my
previous article in
the Emacs
for Professionals
series, I talked about the way in which I
personally use the Emacs Bookmarks feature to create my own custom
list of files and directories through which I can search much more
quickly than I could when using the ordinary buffer
switching {C-x b}
command. I also mentioned that I do not actually use this method
very often because of the limitations of what Emacs allows you to
bookmark — Bookmarks must be associated with an actual
file.
In this article, I will talk about the Hyperbole package for Emacs, and what I actually use to create customized sets of files through which I can quickly search using a tab completion and narrowing framework such as Icomplete or Vertico. I actually use Vertico.
How Hyperbole compares with Emacs Bookmarks
Hyperbole is a markup language for creating hyperlinks (among many other things), so it is not too difficult to understand how it can be used to create lists of links to files in the same way you would with the built-in Emacs Bookmarks feature.
One big difference between them is when you compare
the *Bookmark
List*
, a special buffer that you use to edit your list of
bookmarks. With Hyperbole, there is no such special buffer for
managing your bookmarks. Instead you simply have
an Org-Mode or similar such plain
text file into which you write a mix of text and Hyperbole hyperlink
markup to define your bookmarks. Hyperbole takes advantage of the
fact that the hyperlink markup is easy to parse, and so a list of
hyperlink completions can be constructed quickly even if the file
does not use a rigid database format.
The most important difference, however, is that while Bookmarks must point to a file in the filesystem, Hyperbole allows you to link to nearly anything at all, so it overcomes the biggest limitation of the built-in Emacs Bookmarks feature.
That said, Hyperbole does not replace the Bookmarks feature.
Though you could rebind the Bookmarks keys {C-x r m}
, {C-x r
b}
, and {C-x r l}
with equivalent Hyperbole commands, this is really not necessary as
Hyperbole provides it's own key binding conventions. So both
systems can be used side-by-side if you choose.
Bookmarks keys | Hyperbole keys | What it does |
{C-x r m} |
{C-h h g c} |
Create a bookmark in a globally accessible set of bookmarks |
{C-x r b} |
{C-h h g a} |
Prompt for a hyperlink to which you wish to jump, with tab completion. |
{C-x r l} |
{C-h h b p} |
Show the globally accessible set of bookmarks so it can be updated. |
Using Hyperbole with Emacs Bookmarks
In fact, Hyperbole allows you to creat links to Emacs Bookmark links. If you use Emacs Bookmarks as a large, long-term database of bookmarks, you can use entries in the Emacs Bookmarks database as the link targets in the Hyperbole personal button file
The Personal Buttons
File
The plain text file into which you can write your bookmarks is
the Personal
Buttons File
. You can open this file for editing using
the {C-h h b p}
key
binding, and this could be thought of as a substitute for the
Bookmarks {C-x r l}
(list-bookmarks
) command. You can modify or delete
anything by simply editing the text of the buffer directly. You can
add bookmarks as well, by simply typing them in, or you can use
the {C-h h g c}
key
binding, which works from any buffer.
After pressing {C-h h g
c}
you are prompted for bookmark details in the
minibuffer:
Enter a bookmark label (actually an
explicit button label
), the human readable label that shows up in the tab completion list.an action type — tell Hyperbole what to actually link to here: a file, a directory, a buffer, a URL, a Git commit, etc. For files, use the
link-to-file
link type (type and use tab completion).If you are linking to a file, select the file you want to link as the hyperlink. You would select the current file.
The
link-to-file
action type also will ask if you want to link to the current point/cursor position. I selectyes
because I want to quickly jump back to where I was when I created this bookmark.
Using global buttons
To activate a hyperlink from within the personal buttons file,
navigate the cursor to a hyperlink and
press {M-RET}
(that
is, Alt-Return
) — the {M-RET}
key works in any buffer anywhere in Emacs as
long as the Hyperbole global minor mode is active.
All hyperlinks that are defined in this personal buttons
file
become what are
called Global
Buttons
, and can be accessed by way of
the Global Buttons Menu
. To jump to a global button
hyperlink without visiting the personal buttons file,
use {C-h h g a}
. This can
be thought of as a substitute for the
Bookmarks {C-x r b}
(bookmark-jump
) command. Here a tab completion and
narrowing framework
like Icomplete,
Vertico, or
Helm,
can make it much easier to select the item you want.
Unlimited bookmarking power
Unlike the built-in Emacs Bookmarks function, Hypebole buttons do not need to point to a file on some file system. You can create hyperlinks that execute arbitrary Emacs Lisp code, and arbitrary async shell commands, so you can link to almost anything imaginable.
This makes it more useful to me as a bookmarking feature because
I can bookmark URLs on the Internet as well file paths on my local
filesystem. I can also make a set of commonly used shell commands
accessible from the {C-h h g
a}
command. I can even activate Bookmarks created by
the {C-x r m}
.