Setting up Hyperlinks (GNU poke Manual)

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.

Make sure your poke speaks hyperlinks
Use a terminal emulator that supports hyperlinks
Get and install the app-client utility
GNOME Terminal

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.