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.
I've been using
This provides the link, but also shows that it is a command.
I've been linking to manpages.ubuntu.com.
For specific sections they have anchors on the left so you can link to directly.
Using the expanded url, referring to man page versions on a specific Ubuntu release has drawbacks:
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:
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")
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
- The manual page for the
crontabfile 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
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.
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
[manpage for the `ping` command ![Manpage icon](http://i.stack.imgur.com/Eq5sS.png)](http://manpages.ubuntu.com/ping)