One day, someone else will be the maintainer. So, to make life easier for the next person: some tips on how to maintain the Linux man-pages project (also useful for anyone who wants to help with work on man-pages).
Read at least the following:
All of these pages are relevant for maintaining man-pages. Some of them are part of packages other than man-pages.
History matters. The man-pages project documents not just the current state of the Linux kernel and glibc APIs, but also how they have changed over time.
Once upon a time, man-pages also used to document Linux libc details (libc4, libc5), and there are still some vestiges of that intent in existing pages, but Linux libc is pretty much dead nowadays (see here and here for some details), and there is no longer much need to keep documenting its peculiarities.
Your time is valuable, and disk space is cheap, so set aside a few gigabytes of disk space...
You can find nearly every kernel release ever made at http://www.kernel.org/. At the very least, you will probably find it useful to:
$ grep 'epoll_create' patch-*
For browsing the kernel source code, lxr can be useful! (Online browsable versions of various free kernels can be found at http://fxr.watson.org/.)
Same story as the kernel:
A lot of glibc tarballs can be found at http://ftp.gnu.org/gnu/glibc/. Many older tarballs can be found at ftp://ftp.win.tue.nl/pub/linux-local/libc.archive/. Snapshots of the latest glibc development tree can be found at ftp://sources.redhat.com/pub/glibc/snapshots/.
One of the biggest challenges is keeping up to date with changes in the kernel and glibc. There are a few ways to do this.
Linux Kernel (LKML)
This list (linux-kernel-AT-vger.kernel.org) contains patches, bug reports, and general discussions about the kernel. To subscribe, send a message containing the following body to majordomo@vger.kernel.org:
subscribe linux-kernelThe problem with this list is that the volume is extremely high, so keeping close track of it all would require a lot of time. http://www.kernel.org/ provides the locations of a few searchable archives of this mailing list. I find gmane nice to use.
Linux Kernel Announce
This low-volume list (linux-kernel-announce-AT-vger.kernel.org) announces releases of new versions of various kernel branches, including release candidates for the mainline kernel and new -mm kernels. To subscribe, send a message containing the following body to majordomo@vger.kernel.org:
subscribe linux-kernel-announce
netdev
The netdev list, (netdev-AT-vger.kernel.org), is the list used by the developers of the Linux networking subsystem. To subscribe, send a message containing the following body to majordomo@vger.kernel.org:
subscribe netdevArchives of this list can be found on gmane and marc.
Linux Test Project (LTP)
The LTP produces test suites for the Linux kernel. Subscribe to the discussion list here here. There are list archives on gmane and marc.
Kernel Newbies
Can be useful for asking questions on aspects of the kernel source that you don't understand. To subscribe, send a message containing the following body to listar@nl.linux.org:
subscribe kernelnewbiesArchives of this list can be found on gmane and marc. See the kernelnewbies web site for more information.
libc-announce
This list announces each glibc release. Subscribe by sending an email to libc-announce-subscribe@sourceware.org or visiting this page. There is a list archive here.
libc-alpha
This is a development list for glibc -- sometimes release announcements actually get sent here. Subscribe by sending an email to libc-alpha-subscribe@sourceware.org or visiting this page. There is a list archive here.
libc-help
This list is for asking general questions and getting help on glibc. Subscribe by sending an email to libc-help-subscribe@sourceware.org or visiting this page. There is a list archive here.
These websites are useful because they in part include attempts by others to summarize changes to the Linux kernel.
When a new minor kernel release is made (e.g., 2.6.24), scan the patch and ChangeLog, to see what important changes there have been. This is quite a big job, and pretty much impossible to do thoroughly, unless doing man-pages is your full time job, but a bit of scripting can help (e.g., to discard device driver stuff and architecture-specific stuff other than for (say) x86 and PPC).
cat $(find . -name 'Versions' |
egrep -v '/(s390|alpha|sparc|hurd|sh4|bsd|ia64|powerpc|x86_64)') |
sed -n '/GLIBC/,/}/p' | sed 's/#.*//'| tr ';' '\012' |
sed 's/^ *//' | sed 's/ *$//' | sed '/^$/d' |
grep -v '^_' |
awk '{ if ($1 ~ "^GLIBC_2.*") {
tag = $1
} else if ($1 ~ "^[a-z].*") {
printf "%-32s %s\n", $1, tag
}
}' |
sort -u
Debian makes it easy for upstream maintainers to subscribe to bug reports for man pages. To do this, visit http://packages.qa.debian.org/ and look for the Debian source packages manpages and manpages-dev. (For reasons that don't really make sense to me, Debian splits the upstream man-pages package into two parts, one containing the Sections 4, 5, 7 pages, and the other containing Sections 2 and 3.)
A current list of Debian bug reports can be viewed for manpages and manpages-dev.
Debian even provides an email interface that allows an upstream maintainer to manipulate Debian bug reports (using the "tags" command; see http://www.debian.org/Bugs/server-control).
Red Hat provides a man-pages bugzilla component. It's possible to get subscribed to bug reports: ask the Red Hat downstream maintainers.
Perhaps some other distributions have similar facilities, but these are the only ones I know about so far.
Writing test programs (in C) is an essential part of writing man pages. It verifies the author's understanding of what is being documented and also finds bugs in the kernel and glibc. In some cases, example programs are also suitable for inclusion in the man pages themselves.
To follow the development curve closely, download release candidate (rc) kernels from http://www.kernel.org/pub/linux/kernel/v2.6/testing/. Build and install the kernel, and write programs to test new features. Since the declarations of new system calls probably won't yet be in your (g)libc, the use of syscall() may be required; see the syscall(2) man page.
It is not enough to document what Linux does. Programmers writing portable applications need to know about places where Linux differs from other Unix implementations, and about places where it doesn't adhere to standards.
If in doubt about portability, write a test program and run it on a few other systems. As a starting point, testing say Solaris, FreeBSD, and HP-UX is likely to reveal most of the range of differences that occur on other implementations. Bonus points for testing on other BSDs, on AIX, etc.
If you don't have access to other systems, there are shell guest accounts for various systems available on the net. See, especially, http://www.testdrive.hp.com/.
Join the Austin group. (Membership is free.)
Get electronic copies of current and past Unix standards, especially the current POSIX.1/SUSv3 standard, available in PDF format to members of the Austin group, and browsable online. Note also that section 3p of the man pages includes pages containing the specifications for all functions in POSIX.1-2001 (e.g., try man 3p stat).
Other standards to look out for are SUSv1, SUSv2, and the SVID (System V Interface Definition), all of which are available in electronic form.
And get the C99 standard.
And have a look at the LSB.
Get man pages for as many other Unix systems (including past and current versions) as you can find. Check those man pages to see what differences there are from Linux. They'll also provide ideas about topics that should covered in corresponding Linux man pages. Don't violate copyrights by copying text from man pages whose licenses prohibit re-use.
Sometimes there is useful information to be found in the info(1) document for a particular function (if the info document exists...). Always worth checking.
It can be handy to have a set of /usr/include trees from various other implementations. Grepping all of these trees can give some clues about interfaces that are/aren't present on other Unix implementations.
The source code of some other Unix implementations is available, and useful to study in order to determine undocumented details of behaviour on those systems.
Instructions on how to get the source code of Open Solaris can be found here. You'll need to install Mercurial ("hg").
The FreeBSD source code is available via anonymous CVS, as described here. You'll want a command something like the following:
$ cvs -d freebsdanoncvs@anoncvs.FreeBSD.org:/home/ncvs co src
New releases are copied (scp) to master.kernel.org:/pub/linux/docs/man-pages. All that needs to be copied there are the .tar.gz and the .lsm files. The files copied to this directory will be visible on the web at: http://www.kernel.org/pub/linux/docs/man-pages. Within a few minutes, automagic produces the .tar.bz2 files and the .sign files, and eventually gets all of the files out to the mirrors.
I currently have my own script set up as a cron job to update the LATEST-IS link, and update the links in the /pub/linux/docs/man-pages/Archive directory.
If you make sweeping formatting changes to a large number of pages, separate them out into their own release that contains minimal content changes. This makes it easier for the people that want to verify content changes independently of the change log. Yes, some people actually diff each release to see what changed; for example, downstream maintainers and translators of the man pages sometimes like to do this.
Testing kernel and glibc features while writing man pages will inevitably uncover bugs. Report them.
For the kernel, a report can either go into the kernel bugzilla, or, if the report is of general interest (e.g., a significant bug in a new system call), it may be worthwhile submitting a note to the relevant developer (e.g., the author of the system call) and CCing LKML (linux-kernel-AT-vger.kernel.org).
Bug reports for glibc go here: http://sourceware.org/bugzilla. If you are feeling in a good mood, you could even report bugs in glibc info(1) documents there.
The man-pages project was begun in 1993 by Rik Faith, who created releases 1.0 through to 1.5.
The man-pages maintainer par excellence was Andries Brouwer (aeb), who took over in June 1995, and continued for more than nine years, creating releases 1.6 through to 1.70.
The current maintainer, Michael Kerrisk (mtk), took over in November 2004, starting with release 2.00.