This website was created for the man template on the Arch wiki. Other sites which could be used for linking either don't provide the same manuals as Arch packages, or don't have suitable URL addressing scheme, or have other issues. Therefore we decided to build a new service to meet our requirements:
- All man pages from official Arch packages are available. Old versions and permalinks are not necessary.
- Pages are addressable by their name and section, both occurring exactly once in the URL to avoid problems with pages such as ar(1) and ar(1p).
- The URLs used by the man template should not redirect to permalinks, otherwise users would start copy-pasting them to the wiki and it would be hard to check if they are the same as the canonical URLs.
- Human-readable subsection anchors.
- The page should clearly indicate the Arch package version containing the page.
See the original discussion for details.
We used a dynamic approach instead of building a website consisting of completely static pages. The main
building blocks are the Django web framework, the
PostgreSQL database server, the
mandoc tool from
the mandoc toolset for the conversion to HTML and the
pyalpm library for data extraction from the Arch repositories.
The code is available in the lahwaacz/archweb_manpages
repository at GitHub.
Overall, this approach allows us to provide the following features without rebuilding the whole website from scratch:
- Listings with custom filters and orderings.
- Links to other versions of the same manual provided by different packages.
- Links to similar manuals available in other sections or languages.