Linux man-pages:   home | contributing | bugs | patches | download   ||   online pages

TODO list for the Linux man-pages project

There are many things that might or should be done in the future for man-pages. This page describes a few of them. Help with, or opinions about, these ideas is welcome.

Publish the next revision of the POSIX.1 pages

man-pages currently provides (as a separate package) pages from the POSIX.1 standard, in Sections 0p (Header Files), 1p (Commands), and 3p (Functions). These pages are derived from the 2001 version of POSIX.1.

A revision of POSIX.1 appeared in 2008. We should ask once more for permission to redistribute the new version of the pages.

A few formatting fixes will need to repeated for the new version of the pages, including at least the following:

Status: completed in January 2014 (publication of the POSIX.1-2013 pages).

Migrate man-pages into the kernel source tree (?)

This idea has been floated by a few people. There are some advantages:

There are also some disadvantages:

And there are some other points, which, while not exactly disadvantages, should be kept in mind when considering any change away from the approach currently employed in man-pages:


Design and adopt a new mark-up language (?)

Currently, the pages in man-pages are created with groff, using one of two macro packages: man, or the BSD derived mdoc. (The vast majority of pages in man-pages employ the man macro package.) Neither macro package is optimal, since they don't encode sufficient semantic detail about the elements of a page. (This is especially true of the man macro package.)

What is perhaps required is a new mark-up language (probably some form of docbook) that:

And of course, the existing pages would need to be converted to the new format.

Status: too big a job to seriously entertain at the moment. (Since the kernel documentation's moce to Sphinx, that tool is the obvious choice to consider for this task.)

Global formatting fixes

There are various global formatting fixes that should be made (or at least considered):

Devise or adopt a style guide

Because the pages in man-pages have been produced by many authors, there was much inconsistency in spelling, layout, terminology, and so on. During the course of the 2.xx and 3.xx releases there has been quite a lot of work done to achieve greater consistency (see for example the "Global changes" in releases 2.07, 2.10, 2.13, 2.21, 2.38, 2.44, 2.46, 2.47, 2.48, 2.51, 2.52, 2.53, 2.54, 2.56, 2.59, 2.60, 2.61, 2.62, 2.64, 2.65, 2.67, 2.69, 2.70, 2.71, 2.72, 2.74, 2.75, 2.80, 3.00, 3.01, 3.04, 3.12, 3.19, 3.20, 3.24, 3.27, 3.29, 3.30, 3.35, 3.42, 3.43, 3.44, 3.48, 3.49, 3.56, 3.59, and 4.05), but there is still more work to be done. To guide that work, as well as authors of future pages, man-pages should have (i.e., probably adopt) a style guide.

Status: The open question is: what existing style guide is suitable? (In the meantime, man-pages(7) provides guidance on some points.)