How to follow links in linux man pages?

Question

Is there a way to follow the links mentioned in a man page? For example, here's the man page for ps; how do I access the underlined link circled in red in the screenshot: top(1)?

Answer 1

Man pages date back to Unix First Edition. While hypertext had been invented, it was still in infancy; the web was two decades away, and the manual was an actual printed book, often with one command per page if they fit (that's why they were called pages).

The format used for manual pages has evolved somewhat since then, but most pages aren't really designed for hypertext, and the default man program doesn't support it (it's just a plain text viewer, with hacks to support some basic formatting). There are however man page viewing programs that reconstruct some hyperlinks, mainly links to other man pages, which are traditionally written in the form man(1) where man is the name of the man page and 1 is the section number:

• tkman, a GUI man page viewer with hyperlinks
• WoMan (wiki, man comparsion, formerly), a man page browser for Emacs, supporting hyperlinks
• man2html, a man to HTML converter (plus a web browser to read the result)

You can browse the manual pages of several operating systems, converted to HTML by man2html or similar tools, on a number of sites online, for example:

• Arch Linux
• CentOS
• Debian
• FreeBSD (and a bunch of other collections)
• macOS: archive from 10.9 Mavericks, recent version at unix.com, partial copy at ss64.com
• MINIX 3
• NetBSD
• OpenBSD
• Solaris 10, Solaris 11, other Solaris versions
• Ubuntu
• Unix 1st edition, Unix 6th edition, Unix 8th edition

Some time after man pages had become the established documentation format on unix and some time before the web was invented, the GNU project introduced the info documentation format, more advanced than man while sticking to simple markup designed for text terminals. The major innovation of info compared to man was to have multi-page documentation with hyperlinks to other pages. Info is still the prefered documentation format for GNU projects, though most Info pages are generated from a Texinfo source (or sometimes other formats) that can also generate HTML. When info documentation for a program exists, it's often the main manual, while the man pages only contain basic information about command line arguments.

Answer 2

First of all, it's not a link. It's just an underline. Man pages are just text documents with a little bit of simple formatting that a terminal can handle. The underline is just a highlight, there is no "link" involved.

The normal man command is just a text formatter. In fact the man command doesn't even display the text, man just formats the information stored in the man page file^[1] and sends the formatted output to another program (usually less) that displays the formatted output to the screen. These display programs have no concept of links.

There are some special documentation readers that might be able to look at formatting like that and make an educated guess that such a highlight might indicate that there is a related man page that could be pulled up and create a link, but I don't know which ones do. Perhaps pinfo?

If you want web like formatting with hyperlinks you can find almost any UNIX man page online with links added in. Try typing man [anything] into google and you will almost certainly get one in the first couple hits.

In the case of your example, the visual highlighting is a clue that that is another program name that has it's own man page that you can easily pull up. Try man 1 top. The 1 indicates the section of the man pages to look in. See this question for an explanation of the sections: What do the numbers in a man page mean?

---

^[1] If you open the man page file in a text editor, you will see the raw man page that is not formatted for easy reading. The raw man page is written in a markup language called troff. For more information on troff and how to write a man page see: https://liw.fi/manpages/ .

Answer 3

I recommend w3mman, the system’s manual pager through the w3m command-line browser. It colors links and enables tabbing through them

You can try it by installing the w3m package, which is available in most software repositories and Cygwin.

Answer 4

Let me try to interpret your question a bit more in a sense in which I try to follow your workflow. What you probably would like to have is a key combination within a man page that leads you directly to the underlined commands you are reading about. So, not having to install something else, nor opening up another console and forgetting the exact syntax for example.

This simplest solution is the exclamation mark (if you are using less to display the man pages) and you want to go to the underlined top:

!man top

Or

!man 1 top

You will have to close them all by pressing q multiple times. Note also that this won't work if LESSSECURE=1 is set as environmental variable which would make run less in secure mode and not allow you to use !. It will tell you something like "Command not available".

Answer 5

I have a (couple of) hack(s).

hack 1

Put this in your ~/.bashrc or your ~/.zshrc

function man(){
    for arg in "$@"; do
        vim -c 'execute "normal! :let no_man_maps = 1\<cr>:runtime ftplugin/man.vim\<cr>:Man '"${arg}"'\<cr>:wincmd o\<cr>"'
    done
}

Screenshot..

Asciinema..

https://asciinema.org/a/130131

Now..

1. when you type man vim, for example, it will open up this man page in vim

   • if you type man man vim, for example, it will first open man's manual and after you exit vim, it will open vim's manual

2. when you press K (that's capital k) when you are on another man page at the bottom (the SEE ALSO section), you will jump to this manual (unfortunately inside of a less pager -- this is because we have let no_man_maps = 1; if you don't do that, then vim will force q to be :q and you will be unable to record a macro easily, and vim may behave wonkily in other ways).

   • exiting this second manual you have entered will bring you back to the previous manual you were viewing

3. you get very pretty syntax highlighting since you have loaded ftplugin/man.vim and the ft is (automatically) set to man.

4. you can copy and paste, navigate freely in vim, and even modify the buffer and :w ~/usefulfile. You can do everything you would normally do in vim, including record macros, yank to clipboard with "+y (if you have +clipboard), etc, etc.

I find it much nicer than less.

The only minor setback I have found (which still exists if you use less as your pager) is if you want to have multiple manuals open in one vim session. I don't really see a way to do this.

A few notes:

1. if you try to save the buffer, you will get E382: Cannot write, 'buftype' option is set

   • I like that you cannot save as it prevents accidentally saving it

2. you can still save like :w /tmp/man.man

   • if you save it with a .man extension, then opening it up will set the filetype to man for you
   • if you do not save it with a .man extension, you can just set the ft to man by running :set ft=man

3. if you need to do things when opening up man pages you can use autocmd VimEnter *.~ echom 'hooray, we are using vim for man pages!', for example.

4. I have put the following in my vimrc so that I can press K to try to open manual, and then press G to go back to previous manual:

---

augroup man
    autocmd!
    autocmd VimEnter *.~ nnoremap B :execute "normal! `Z"<cr>
    autocmd VimEnter *.~ nnoremap <buffer> K :execute "normal! mZyiw:Man \<lt>c-r>\"\<lt>cr>"<cr>
augroup END

---

hack 2

put this in your ~/.bashrc or ~/.zshrc

function man(){
    declare -a args
    for arg in "$@"; do
        command man "$arg" > "/tmp/${arg}.man"
        args+=("/tmp/${arg}.man")
    done
    vim "${args[@]}"
}

Screenshot..

Asciinema..

https://asciinema.org/a/9Q6Si90Pi46cDVUknxFxfIwsv

This solves problem that hack 1 and less face (now you can view multiple manuals in one buffer), but it is less elegant.

Notes:

1. IMPORTANT if you want hack2 to work, then you must put :let no_man_maps = 1 in your ~/.vimrc. This is because vim will source .../vim80/man.vim and q will be forcibly remapped to :q.

2. there is more clean up involved (now you store every manual to /tmp/*.man)

3. you can now, however, view multiple man pages in one session, as noted above

4. if you press K, you will still open a new vim session, however

   • if you want you can bind an autocmd (using an autocmd like the one above) to do something like autocmd VimEnter man.~ nnoremap <buffer> K :execute "normal! Byt(:silent !man \<c-r>\" > /tmp/\<c-r>\".man\<cr>:edit /tmp/\<c-r>\".man\<cr>" or something crazy like that (untested)

Answer 6

Specifically for Ubuntu, there is Yelp. It's installed by default and is by default able to display manual pages, although the invocation to do so, is not the same as that of the man command; an alias or a shell function can work around the latter point (depends on your shell).

yelp 'man:exit'

It will default to a section in a way I don't know. Reminder: to get the sections list for a manual topic, use whatis, as in whatis exit.

To request Yelp to display a manual page from a specific section, say 2, do:

yelp 'man:exit(2)'

Issues: yelp has bugs and be prepared to get multiple errors output when invoking it from the command line. There also, an alias or a custom shell function can help redirecting all errors to /dev/null

Answer 7

Just thought I'd add my 2 pence.

I'm using the following to view man pages, I've aliased man to the below command (which if you use zsh will still provide autocomplete).

man --html='lynx --cfg=~/.lynx.cfg' <manpage>

With the following in ~/.lynx.cfg which sets up keys for easy navigation and sets q to quit, like in man. I had to copy the HELPFILE entry from the main /etc/lynx/lynx.cfg otherwise the help was not displaying properly.

KEYMAP:k:UP_TWO                # Move display up two lines
KEYMAP:j:DOWN_TWO              # Move display down two lines
KEYMAP:K:UP_HALF                # Move display up half a page
KEYMAP:J:DOWN_HALF              # Move display down half a page
KEYMAP:h:PREV_LINK        # Move to the previous link or page
KEYMAP:l:NEXT_LINK        # Move to the next link or page
KEYMAP:q:ABORT
HELPFILE:file://localhost/usr/share/doc/lynx-common/lynx_help/lynx_help_main.html.gz

Note: you will need to install the groff package for this to work.

sudo apt install groff

The result is quite nice, since man is doing the conversion to html I expect its the best option for getting links working correctly.

Answer 8

You can set vim (or nvim) as the viewer for the man page:

export MANPAGER='nvim +Man!'

Then you can use CTRL-] to follow a tag, and CTRL-t or CTRL-o to go back a tag.

For more info, read the plugin's documentation and do :h tag in nvim.

Answer 9

Like they said, it wasn't designed for it.

You can use info man and then hit enter once you're under SEE ALSO section on your item.

info - read Info documents

Answer 10

Although w3mman is a solution to follow links, does not use all the screen (at least on ubuntu 12.10)

I prefer to use:

$ sudo -i
# apt-get install w3m man2html
# exit
$ alias man=' hman -P w3m'

add the last command to ~/.bash_aliases or similar startup script to get it on every session.

The -P w3m is because first browser to hman is lynx or sensible-browser but I prefer w3m

hman is a tool bundled on html2man. See this

If exit with confirmation is annoying to you, as to me is use this

Answer 11

I was able to use the --html argument to man in order to open it in the browser defined by $BROWSER environment variable, so:

BROWSER=google-chrome man ps --help

I'm using Fedora. Not sure if this works for your distro, please test and report in comments.