2.1 Setting up Hyperlinks

GNU poke uses terminal hyperlinks in order to improve the interactive usage of the tool: clicking on terminal hyperlinks requests poke to execute certain actions. This is used to implement buttons and other interactive goodies.

Many terminal emulators support terminal hyperlinks. However, we are using a very simple protocol called app:// that is not supported (yet) on GNU/Linux distros. Fortunately, it is very easy to set your system to use this protocol, and this chapter shows you how.

2.1.1 Make sure your poke speaks hyperlinks

The first step in having an hyperlinks-capable poke is to make sure to have a recent enough version of libtextstyle when building poke. If your poke can emit hyperlinks you will see a message like this when running it on the terminal:

hserver listening in port 43713.

2.1.2 Use a terminal emulator that supports hyperlinks

Gnome Terminal has support for displaying hyperlinks as do many other emulators that rely on VTE. Check the list at https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda#supporting-apps for a mostly up-to-date, non-exhaustive list of emulators that support printing hyperlinks.

2.1.3 Get and install the app-client utility

Since app:// is a new URI protocol that we designed, common terminal emulators don’t know what to do when they encounter such a URI. To work around this problem we use the XDG Desktop Specification and a little C utility called app-client, which can be found at https://gitlab.com/darnir/hyperlink-app-client.

By setting app-client as the default handler for app:// URIs, the terminal emulator does not need to understand the syntax or semantics of the app:// protocol. It offloads the handling of the URI entirely to app-client. In order to use this, first download and install app-client:

$ git clone https://gitlab.com/darnir/hyperlink-app-client
$ cd hyperlink-app-client
$ make
$ sudo make install

This is enough for any utility (like terminals) that use xdg-open to do the right thing with hyperlinks. However, certain terminals require additional setup. See below if that is your case.

2.1.4 GNOME Terminal

Gnome Terminal doesn’t use xdg-open to start the applications. Instead, it parses the mimeapps.list file manually to find the right application.

Edit your mimeapps.list, it is usually located at $HOME/.local/share/applications/mimeapps.list, but it might also be at $XDG_CONFIG_DIR/mimeapps.list, and add the following line to it:

x-scheme-handler/app=app-client.desktop

This let’s Gnome Terminal know how to open app:// links.