man-pages currently provides (as a separate package) pages from the
POSIX.1 standard, in Sections
0p (Header Files),
1p (Commands), and
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:
Convert the POSIX.1 text to man-pages mark-up.
Add 0p/1p/3p to the TH line.
Add the PROLOG to the pages.
Clean up any white space issues that may be present.
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:
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 wrappers do some extra work before invoking
the underlying system call.
Currently, the section 2 pages document the behavior of the
glibc wrapper, which may be different from the underlying system call,
and attempt (i.e., it's the goal, but not all pages do this well)
to include NOTES that describe differences in the
underlying system call.
(For example, see the "C library/kernel ABI differences" in the
section of select(2).)
In addition, the man pages for system calls document
other user space details, such as header file requirements,
feature test macro requirements for glibc,
thread-safety (under the ATTRIBUTES section),
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 userland programmers
(the main audience of the pages)
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.
Note: I am doubtful that the problem noted in
the above point could be resolved
via some "include" mechanism that includes relevant
pieces from the Section 2 page into the Section 3 page.
I think that would make the man page source files more difficult
to work with, and would likely be error-prone in practice
(because the producers of the "include" mark-up (man2) would
be separate from the consumers of that mark-up (man3)).
And of course it's worth noting that implementing either of
the above approaches would be a significant piece of work.
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.
This raises several issues:
Where should the "glibc" pages be hosted?
Apparently not with glibc, which favors info
pages (and it's worth noting that the man-pages
project often does a better job of documenting
the glibc interfaces).
Splitting the manual pages into two separate packages is
a significant piece of work. It's not always obvious which
package a particular page would belong to. Many pages
contain content that would relate to both packages.
(Do we split those pages into separate pages in the
That's a big task.)
From a maintenance point of view,
maintaining two separate (but at times quite closely related)
man page packages would be a little less comfortable
than a single unified package.
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:
man-pages maintains historical information on interfaces.
That is, each man page documents not just the the latest kernel
(or glibc) implementation, but also changes in the interface over time.
Such information is of course important for userland programmers.
Sometimes, a man page relates to multiple underlying system calls.
For example, there have over time been many system calls that
correspond to the
Other examples are the Section 2 pages for the sockets API and
the System V IPC APIs;
for both of those APIs, there are several Section 2 pages,
but (on most architectures), only one multiplexed system call
In my opinion, the disadvantages outweigh the advantages.
Furthermore, making the necessary changes would entail significant
time (which I don't have), and it's unproven whether the claimed
benefits would be borne out in practice (the state of
much of the material in the kernel
does not give grounds for optimism).
But I'm open to hearing further ideas,
and don't discount the possibility of doing
something about this in the future.
Here's an alternative idea.
Employ a couple of patch tags in the style of
One of these could be (say)
that someone has noted that this patch changes the API/ABI.
The other would be (say)
an indication from the appropriate documentation maintainer
that the ABI changes have been documented in
man-pages (or elsewhere if appropriate);
details of the actual documentation could be included elsewhere
in the patch's log message.
Design and adopt a new mark-up language (?)
Currently, the pages in man-pages are created with
using one of two macro packages:
man, or the BSD derived mdoc.
(The vast majority of pages in
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:
is unintrusive: the raw page source should remain very readable
applies mark-up 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.
(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):
Blank lines in natural language text in the page sources
should be replaced by .PP or .IP directives.
This produces better PostScript and PDF output,
since blank lines generate a large vertical space.
(The problem can be seen by using
gs(1) to view the
PostScript output produced by
Consider using the .EX/.EE macros around
code samples and shell scripts,
to have code rendered in a fixed-width font
for PostScript/PDF output.