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
utopicis Ubuntu release.
enis the language (English).
.htmlspecify which section of the manual contains the page.
lsis 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)
But that doesn't explain why it does work for
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.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.
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
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)?