How to link to manpages?

Question

What would be the best way to link to (and highlight) manpages when answering questions? I frequently want to refer back to manpages, and I'd like to get it right. (For example, in an answer, I'll say "For more information see 'man whatever'". It would be nice to have that stand out or be a link.

Answer 1

I've been using man hello

This provides the link, but also shows that it is a command.

[`man hello`](http://manpages.ubuntu.com/manpages/maverick/en/man1/hello.1.html)

Answer 2

I've been linking to manpages.ubuntu.com.

For specific sections they have anchors on the left so you can link to directly.

Answer 3

Using the expanded url, referring to man page versions on a specific Ubuntu release has drawbacks:

[`man bash`](http://manpages.ubuntu.com/manpages/maverick/en/man1/bash.1.html)

man bash

This is the same kind of url that is used in the "man hello" example - except that the man page exists so you can try.

• It shows an outdated version.
  • It's outdated by about two years here, the time since EOL of that release
  • The version is not a specific, stable one - which would be good when citing it
• It could break by link rot
  • that can happen if "manpages.ubuntu.com" should decide to not keep man page versions forever, even for "end of life" non LTS releases.

The link can actually make use of the man page resolving algorithm by using a link like this:

[`man bash`](http://manpages.ubuntu.com/bash)

man bash

This shows always the most current man page version of the current Ubuntu release.

Ideally, the tooltip can be used to show the whatis information, inserted manually:

[`man cut`](http://manpages.ubuntu.com/cut "cut - remove sections from each line of files")

man cut

Answer 4

When naming links to http://manpages.ubuntu.com (or other online sources for manual pages), I think man topic (e.g., man ls)--as suggested by andrewsomething's answer and others here--is the way to go.

However, occasionally there are multiple manpages with the same name (i.e., from different sections of the manual). When one actually runs the command man topic, typically the page for topic in the lowest-numbered section is shown, and typically this is desired. For example, running man chmod shows the chmod page from section 1 of the manual.

There are other manpages for chmod, though. If I were to link to the manual page on the chmod system call, I would not label that link man chmod, because running man chmod doesn't show that manual page. To show that manual page on the command line, one would run man 2 chmod (since it's in page 2 of the manual).

Therefore, calling the link man 2 chmod makes the most sense.

Note that while running man 1 chmod shows the same page as man chmod--the manual page for the chmod command--I am not suggesting labeling links with the man N topic syntax except when it would be necessary on the command line--i.e., except when man topic would usually refer to a manpage different from the one desired.

This ambiguity can arise even when answering non-programming questions posted by novice users. The crontab topic is such an instance:

• man crontab (equivalent to man 1 crontab) shows the manual page for the crontab command.
• The manual page for the crontab file format (i.e., how to write a crontab), which is perhaps more commonly cited and recommended, is man 5 crontab.

Syntactic/Historical Note and "Citation"

Traditionally among UNIX/*nix aficionados, manual pages are referred to as topic(n) (e.g., ls(1), sudo(8)). This notation is useful for brevity, and when everyone knows what that means because they have to be conversant with manpages to use the system (i.e, on Unix-like OSes that are way less user-friendly or GUI-oriented than Ubuntu), and on systems where hyperlinking often cannot be facilitated (e.g., email, usenet). I am not suggesting we adopt that notation widely here, though I wouldn't necessarily edit it out of someone else's post.

However, that notation is my motivation for my suggestion to specify the section of the manual when a different section would otherwise be inferred. I would cite the topic(n) tradition as the source for the man n topic idea I've put forward in this post.

Answer 5

You should be using the Ask Ubuntu Toolbar Buttons UserScript!

Not only do you get a button in the toolbar for inserting links to manpages, but you also get a button for inserting links to packages and inserting links to PPAs.

For the record, the following markdown is generated by the script for the ping command:

[manpage for the `ping` command ![Manpage icon](https://i.sstatic.net/Eq5sS.png)](http://manpages.ubuntu.com/ping)

Rendered as:

manpage for the ping command