How Are Symbolic Links Handled on man.archlinux.org?

Updated

On man.archlinux.org, a symbolic link between manual pages is handled as an HTTP redirect: requesting a page that is a symlink returns a 302 status code pointing to the target page. The site counts these links as part of its index — its own description reports 83,633 manual pages and 8,796 symbolic links drawn from 3,790 packages — and they appear in per-package listings such as core/openssl.

What a symlink looks like in practice

Many commands are just alternate names for the same program, and their manual pages are symlinks rather than separate documents. The site's own example is bunzip2(1), which points to the bzip2 manual. If you open the bunzip2 page, your browser is redirected to the target page instead of being served a distinct document.

This matters for three reasons:

  • Bookmarks and scripts: a saved URL for a symlinked page still works, but it resolves to the target. If you need a stable canonical address, link to the target page.
  • Automated fetching: tools that follow redirects (most HTTP clients do by default) get the target content transparently. Tools that do not follow redirects will see only the 302 response.
  • Search results: because the symlink is not a separate document, content you read under the symlink name is the target's content.

Finding symlinks in package listings

Symbolic links are included in per-package listings. To see them, open the listing for a package — for example, the OpenSSL package listing at core/openssl — and look for entries that are marked as links rather than standalone pages. This is useful when you want to know whether a command's documentation is original or an alias.

Related behavior worth knowing

The redirect behavior fits into the site's broader addressing scheme, which is worth keeping in mind when a symlink redirect surprises you:

Situation What happens
Request a symlinked page (e.g. bunzip2(1)) HTTP 302 redirect to the target page
Section omitted in the URL Redirect to the first page found, checking sections in the order 1, n, l, 8, 6, 3, 0, 2, 5, 7, 4, 9
Package omitted in the URL Lookup order is core, extra, multilib
Language omitted Defaults to en, which is also the fallback for pages not translated
Format omitted Defaults to html; txt and raw are also supported

So a symlink redirect is one of several automatic redirects the site performs. If you land somewhere unexpected, check whether the page name is a symlink, whether you left out the section, or whether the package was ambiguous.

When this matters to you

  • You maintain links to Arch documentation: point to the canonical target page to avoid an extra hop, and expect the symlink URL to keep working via redirect.
  • You scrape or script against the site: enable redirect-following, or handle 302 responses explicitly, otherwise symlinked pages will appear empty.
  • You are checking whether a command has its own docs: a symlink in the package listing tells you the documentation lives with another command.