One day, it won't be me any more, so to make life easier for the next maintainer: some tips on how to maintain the Linux manual pages Get the source code =================== History matters. The manual pages document not just the current state of the Linux kernel and glibc, but also how it has changed over time. So, set aside a few gigabytes of disk space... Kernel source code ------------------ You can find nearly every kernel release ever made at www.kernel.org. At the very least, you should: -- keep up-to-date trees for the 2.2.x, 2.4.x, and 2.6.x kernels. These trees can be grepped to look for differences across major kernel versions. -- Keep a directory that contains every minor release patch ever made. (e.g. patch-2.6.15, patch-2.6.0, patch-2.5.38, patch-2.4.1, patch-2.4.0-test7, patch-1.2.16, etc.) Grepping these patches can help determine in which minor release a kernel change occurred, e.g.: grep 'epoll_create' patch-* to see when epoll_create was added as a system call. -- Keep all the ChangeLogs too -- they can be checked to look for explanations of patches found via grepping as described in the previous point. Glibc source code ----------------- Same story as the kernel. -- Keep up-to-date trees for all 2.x, x >= 0 releases. -- Keep diff files for all minor releases of the glibc tree. As with kernel, these can be grepped to help determine when a particular change occurred in glibc. A lot of glibc tarballs can be found at http://ftp.gnu.org/gnu/glibc/. A lot of older tarballs can be found at ftp://ftp.win.tue.nl/pub/linux-local/libc.archive/. Keeping up ========== One of the biggest challenges is keeping up to date with changes in the kernel and glibc. A few ways to do this are: Mailing lists ------------- Linux Kernel (LKML) This list 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-kernel The 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. Websites -------- These websites are useful because they in part include attempts by others to summarise LKML traffic. http://lwn.net/ The weekly kernel page is especially useful, since it summarises a lot of current and planned changes to the kernel. http://wiki.kernelnewbies.org/LinuxChanges Summarises major internal and interface changes for each kernel release (starting sometime in the 2.6.x series). http://kerneltrap.org/news Reports on recent changes in various free kernels. Kernel releases --------------- When a new minor kernel release is made (e.g., 2.6.22), 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). Glibc releases -------------- Just as for the kernel, when a new glibc release comes out. The following is useful to get a rough idea of what symbols were new or changed in various glibc releases -- execute it at the root of a glibc tree: 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 Distribution bug tracking systems --------------------------------- Debian makes it easy for upstream maintainers to subscribe to bug reports for manual pages. To do this, visit http://packages.qa.debian.org/ and look for the Debian source package "manpages". A current list of Debian "manpages" bug reports can be found at http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=manpages. Debian even provides an email interface which 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: https://bugzilla.redhat.com/bugzilla/buglist.cgi?component=man-pages&&order=bugs.bug_id and it is 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. Testing New Features ==================== Test programs ------------- Writing test programs (in C) is an essential part of writing manual 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 manual pages themselves. Testing new kernel features --------------------------- 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 test new features with test programs. 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) manual page. All the world is not Linux ========================== 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. Test programs ------------- 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/. Standards --------- Join the Austin group. It's free. See http://www.opengroup.org/austin/. Get electronic copies of current and past Unix standards, especially the current POSIX.1/SUSv3 standard. Note also that section 3p of the manual pages includes manual pages containing the specifications for all functions specified 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. There are electronic versions of near final drafts available on the net, if one searches on the net. And have a look at the LSB, http://www.linux-foundation.org/en/LSB. Other Manual Pages ------------------ Get manual pages for as many other Unix systems (including past and current versions) as you can find. Check those manual pages to see what differences there are from Linux. They'll also provide ideas about topics that should covered in corresponding Linux manual pages. Glibc info ---------- 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... Header files on other implementations ------------------------------------- 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. Source code ----------- The source code of some other Unix implementations is available, and useful to study 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")): http://dlc.sun.com/osol/on/downloads/hg-build-snapshots/ The FreeBSD source code is avaiulable via anonymous CVS as described here: http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/anoncvs.html You'll want a command something like the following: cvs -d freebsdanoncvs@anoncvs.FreeBSD.org:/home/ncvs co src Release Philosophy ================== If you make sweeping *formatting* changes on 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 (such as the dedicated Alain Portal, in recent times) sometimes like to do this. Being a good free software citizen ================================== Reporting kernel and glibc bugs ------------------------------- Testing kernel and glibc features while writing manual pages will inevitably uncover bugs. Report them. For the kernel, a report can either go into the bugzilla (http://bugzilla.kernel.org), or, if the report is of general interest (e.g., a significant bug a new system call), it may be worthwhile submitting a note the author of the system call and CCing LKML. 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 documents there. Some History ============ 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, 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, took over in November 2004, starting with release 2.00.