Is there a reliable, release-agnostic way to link to manpages?

Question

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)?

Answer 1

This is a very decent proposal but I'm not sure it's worth the effort. Personally, I very rarely link to man pages. Instead, I tend to do something like this:

As explained in man ls:

Quote the relevant section of the man page here.

This has several advantages:

• It teaches people how to fish as opposed to just feeding them (man ls).
• I can be sure that whatever man ls produces on the reader's system, that will be the relevant man page for the user reading it (even if it differs from what I have quoted).
• It keeps the information here, avoiding the need to go off site.
• It makes the answer portable to other distributions. I know this is Ask Ubuntu and portability is not really relevant (and correctly so), but there's nothing wrong with making an answer more global and helping someone who finds it and happens to be using another distro. As long as the answer is correct for Ubuntu and primarily targeted at Ubuntu, making it more portable can only be a benefit.

For those, in my experience, rare cases where a link to a man page needs to be provided, I would just link to the manual of the current version and leave it at that.

That said, do we have any data on how many manual pages are different in Ubuntu versus Debian? I have been using linux.die.net and ss64.com for many years and on many different distributions. I guess I must have, at some point, come across a case where the information there did not match the distribution I was using at the time but, if so, it was such a rare occurrence that I don't even remember it. Usually, the generic man pages serve perfectly well.

Given that i) we can generally just quote the man page directly and so don't need to link to them and ii) that the generic (Linux, not UNIX or POSIX) man pages from the sites I mention above or manpages.ubuntu.com are going to be enough in the vast majority of cases, I don't think this is worth spending much effort on.

Now, if there is an automated system that always links to the most recent Ubuntu man page, we may as well use that, but if not, I don't really think it's a big enough issue to warrant building something.

Answer 2

.1 matches .1posix because a * is tacked on to the search string:

path = "../www/manpages/%s/%s/man%d/%s.%d%s*.html" % (d, lr, i, t, i, extra)

As to why the ordering is weird, it's because they use glob.glob, which has weird ordering. One quick fix would be to sort by length, which would return shorter (and presumably more exact). In any case, a "fix" from the client side looks difficult.