Pokology - a community-driven site around GNU poke
                             

     _____
 ---'   __\_______
            ______)         
Setting up hyperlinks support
            __)             
           __)
 ---._______)


Table of Contents
_________________

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





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 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.


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
  <code>app-client</code>:

  ,----
  | $ git clone https://gitlab.com/darnir/hyperlink-app-client
  | $ cd hyperlink-app-client
  | $ make
  | $ cp app-client /location/in/$PATH/variable
  `----


  Next step is to copy the app-client.desktop file in the git repository
  to $HOME/.local/share/applications. This is a XDG Desktop Entry for
  the app-client. And lets most applications on your system know that
  this should be used to handle app:// URIs. (See the MimeType field)

  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.


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 lets Gnome Terminal know how to open app:// links.