Linux man-pages:   home | contributing | bugs | patches | download   ||   git | 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.

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 move to Sphinx, that tool is the obvious choice to consider for this task.)

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