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.

POSIX.1 pages

man-pages currently includes pages from the POSIX.1 standard in Section 0p (Header Files), 1p (Commands), and 3p (Functions).

Obtain the next revision of the POSIX.1 pages

Another revision of POSIX.1 is coming to the final stages, and the new standard will probably appear in 2008. When it does, 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:

• Add 0p/1p/3p to the TH line.
• Add the PROLOG to the pages.
• Clean up any white space issues that may be present.

Create a public source code repository, with a web interface

Currently man-pages is maintained in a private subversion repository. The project should be moved to a public repository, on a server providing a web interface. Most likely this will mean a move to git on kernel.org. A move to kernel.org makes sense because much else related to man-pages is hosted there. A move to git makes sense for a few reasons:

• kernel developers are most used to using git nowadays;
• kernel.org provides a git server;
• It provides a good excuse for me to learn git.

Set up a Bugzilla

Set up a bugzilla for man-pages.

Status: done (it's here).

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

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

• It might encourage kernel developers to work on man pages by placing them in the same location as the kernel source code.
  
  
• Kernel source code patches changing the behavior of kernel-userland interfaces could include patches to the corresponding man page text, and thus documentation patches could flow up the maintainer chain in the usual fashion.

There are also some disadvantages:

• The split between system calls and library functions is not clear cut from the point of view of the userland programmer. Sometimes, glibc wrapper do some extra work before invoking the underlying system call. Currently, the section 2 pages typically document the behavior of the glibc wrapper, which may be different from the underlying system call.
  
  One way to address this would be to truly separate the system call and glibc wrapper information into two separate pages, one in Section 2, the other in Section 3. But this would require one of the following approaches, each of which has its problems:
  
  
  • Document the pure system call in a Section 2 page, and then document the differences provided by the glibc wrapper in a corresponding Section 3 page. The problem is that this would require the userland programmer to look at two separate pages to get the information they require.
    
    
  • Document the pure system call in a Section 2 page, and then document the complete behavior of the glibc wrapper in Section 3, repeating material from the Section 2 page as appropriate. The problem here is redundancy: any changes in the Section 2 page would need to be carried through to the Section 3 page; inevitably, inconsistencies will arise.
  
  
• Many pages in Section 3 and in Sections 5 and 7 relate purely to glibc. If those pages are not to be migrated into the kernel source tree (it makes little sense to do that), then they should be split out into a separate package (to be housed where?).

Status: undecided yet about whether to proceed; ideas welcome.

Design and adopt a new markup language (?)

Currently, the pages in man-pages are written for nroff, 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 markup language (probably some form of docbook) that:

• is unintrusive: the raw page source should remain very readable
• applies markup by function, not by effect
• can be easily processed to generate the present nroff from it
• can be easily processed to generate HTML from it
• is simple to learn and use

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.

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