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.
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
NOTES
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 (mtk) 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
two packages?
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
stat(2)
manual page.
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
(respectively
ipc(2)
and
socketcall(2)).
Status:
In my (mtk) opinion, the disadvantages outweigh the advantages.
Furthermore, making the necessary changes would entail significant
time, and it's unproven whether the claimed
benefits would be borne out in practice (the state of
much of the material in the kernel
Documentation directory
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
"Signed-off-by:".
One of these could be (say)
"ABI-changes-noted-by:", indicating
that someone has noted that this patch changes the API/ABI.
The other would be (say)
"ABI-changes-doc-acked-by:",
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
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:
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 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.)