Linking directly to a specific manual page in the Ubuntu Manpage Repository is not ideal, because the URL points to a manpage for a specific Ubuntu release, which will become obsolete and may even one day be removed, as detailed in this answer by Volker Siegel.

Unfortunately, the commonly recommended ways to link to online manpages so a page for a current release is automatically selected (including the recommendation in that answer) don't work the way people think they do, and often fail. I am hoping someone may have insight into a better way to do it.

^{Strictly speaking, I could've asked this question on the main site, since it's about making links to the Ubuntu manpages (an Ubuntu topic) and has applications outside Ask Ubuntu. But since in practice this is particularly of interest in writing posts on our site, I've asked this on meta instead. Note also that while this relates closely to How to link to manpages?, this is a much narrower question, the answers there do not solve this problem, and the question asked there does not motivate consideration of this specific problem.}

##The Original Problem

When one views a specific manual page on manpages.ubuntu.com, the URL looks like http://manpages.ubuntu.com/manpages/utopic/en/man1/ls.1.html, where:

• utopic is Ubuntu release.
• en is the language (English).
• man1 and the 1 before .html specify which section of the manual contains the page.
• ls is the name of the page, within that section.

Whatever release's manpage is linked to, that release will become obsolete, eventually become unsupported (end-of-life), and may ultimately be removed from the manpages repository. Even if it remains, most of the time we link to manpages we'd prefer readers see the newest manpage, rather than some old one.

##The Common "Fix"

The mostly widely recommended way to universalize an Ubuntu manpage link is to use a URL like http://manpages.ubuntu.com/ls. This sometimes works but frequently gives the wrong page. In particular, for ls this redirects the ls manpage, for the most recent stable Ubuntu release, in section 1posix of the manual, rather than in section 1. Currently it gives the page http://manpages.ubuntu.com/manpages/utopic/en/man1/ls.1posix.html. (These "POSIX manpages" are not usually what we want to refer people to, as they document what the standard says about a minimal and fully POSIX-compliant ls; the actual ls in Ubuntu is different.)

The problem is that the page is not always selected from the desired section of the manpage. In particular, manpages.ubuntu.com seems always to select pages from the highest possible section. This is strange and might be considered a bug; I'm not sure. (The man command itself selects the lowest possible section when no section number is given.) I'm also not really sure this is exactly how the online repository works--see below.

##The Refined "Fix"

A less common refinement is to put the section number in the URL also, like http://manpages.ubuntu.com/ls.1. This works more often, but still sometimes fails. ls is one of the manpages for which it fails.

A similar refinement is to use a longer link http://manpages.ubuntu.com/manpages/man1/ls.1.html. This might seem intuitively like it would work better, but it does not.

I presume the reason this still redirects to the ls.1posix manpage instead of the ls.1 manpage is that it is being treated as a search term and ls.1posix contains (and thus matches the search for) ls.1.

But that doesn't explain why it does work for chmod: http://manpages.ubuntu.com/chmod redirects to the chmod page in section 3posix of the manual, while http://manpages.ubuntu.com/chmod.1 redirects to the chmod page in section 1 of the manual, even though a chmod page in section 1posix of the manual does also exist!

I believe the reason for that is that ls.1posix is listed last after ls.1 and ls.1plan9, and thus selected by the search for ls.1; in contrast, chmod.1posix is listed first before chmod.1, so searching for chmod.1 selects the chmod.1 page instead. But I have no idea why that is, how to predict which will be listed last without actually checking, and how (if there is a way) to make a release-agnostic link that will always resolve to a current manpage for a specific command in a specific section of the manual.

##Other Possibilities?

The traditional way for documentation to refer to manpages, in the UNIX world, is with syntax like ls(1). Unfortunately this is not supported at all in the Ubuntu manpages repository.

One possibility is to simply not solve the original problem. Then one's manpage links work reliably, but become obsolete, and may eventually stop working. Or, more likely, they may eventually come to have the same problem as is introduced by the fixes proposed so far. For example, http://manpages.ubuntu.com/manpages/feisty/en/man1/ls.1.html currently redirects to the ls.1posix manpage for Utopic (same as http://manpages.ubuntu.com/ls.1).

Keeping the manpages/ part of the URL (e.g., http://manpages.ubuntu.com/manpages/ls.1) does not help--the search and redirection works the same.

Theoretically we could just update manpage links frequently, finding ones that look outdated with the data explorer, manually reading the surrounding context to ensure updating them to a later version is really appropriate, and then updating them. In practice I don't think this is a workable solution. Even in the best case, it would take a great deal of work, the effort would require constant renewal, and would take energy away from other, more important site maintenance (and answering people's questions).

I (or someone) could report a bug against the ubuntu-manpage-repository project. This seems like bug 606456 at first glance, but I think that's actually an unrelated problem. The feature requested in untriaged bug 680229 for a current/ symlink would, if implemented, provide a solution to this meta question, but it's had no activity since 2011.

But maybe there is already some good way of achieving stable, release-agnostic links to individual Ubuntu manpages, and it just has to be brought out from obscurity into the light of day. Does anyone know of one, or otherwise have any advice as to how to proceed toward a solution to this problem (or whether or not to proceed)?