How-To: Man Page Links on Linux

Lounge
1

I'm not sure how well known this is and I kind of stumbled on it while playing around when taking some notes on system commands. In a nutshell, with the right setup it's possible to link man pages on Linux using URLs like man:///path/to/manpage-file.

Personally, the system on which I'm using Joplin right now is a Linux Mint 20.1 Xfce and this works right out of the box, but let's not assume that's the case for everyone, so here are a few things you can try/check:

  • For example, the less pager should be present on most systems, and its man page is likely located on yours at /usr/share/man/man1/less.1.gz as well (if you have English man pages installed), so try copying this into a note:

    [less(1)](man:///usr/share/man/man1/less.1.gz)

    If the file itself doesn't exist, pick another one from a subfolder of /usr/share/man instead.

  • From what I understand, this is driven by a desktop's implementation of the XDG (acronym for "Cross-Desktop Group") freedesktop.org standards. In a desktop terminal emulator you can try the following:

    # open an URL, same as in Joplin:
xdg-open man:///usr/share/man/man1/less.1.gz

  • URL handlers are registered with a x-scheme-handler/... MIME type, and there's an XDG tool to get some information:

    # Find out where the man:// URL handler is associated:
xdg-mime query default 'x-scheme-handler/man'

    On my system, this prints yelp.desktop, which is the .desktop file for Yelp, the GNOME help browser. You might be able to get it with e.g. apt install yelp. Side note: Yelp understands some other URLs as well, e.g. info://... for GNU Info manuals.

  • There should be a global and possibly a user specific cache file containing the URL
    handlers. These are populated with data from .desktop files. See
    /usr/share/applications/mimeinfo.cache and maybe ~/.local/share/applications/mimeinfo.cache.

But how to find the right file path for a man page? These can be located in quite a few places on the file system. The short answer is to simply have the man command tell us with -w:

# Print a man page's full path:
man -w <page>

Long answer: There's a program to display a colon-separated list of these search paths:

manpath

The idea now is to use find with all these paths (this is a simple variant which only works if there are no spaces in what manpath returns), e.g. for bash:

find $(manpath | sed 's/:/ /g') -iname 'bash*'

and you might get:

/usr/share/man/man7/bash-builtins.7.gz
/usr/share/man/man1/bashbug.1.gz
/usr/share/man/man1/bash.1.gz
4 Likes
2

And before anyone asks, I've recently started using Joplin and I think it's great. So I've decided to
put this together as a way to contribute something back.

A thank you to everyone involved. :slight_smile:

1 Like
3

After further investigation I've found that it should also be possible to define link URLs in the form man:page, e.g. try <man:less> or even <man:less(1)>. This works at least with Yelp on my system.

Using full paths can just be considered as a good fallback option, then. For example if some man page is not stored in one of the default paths.

3 Likes