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 2.0.x, 2.1.x, 2.2.x, 2.3.x, 2.4.x. -- 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 track of it all would require a lot of time. http://www.kerenl.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.19), 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. 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. Perhaps some other distributions do the same, but Debian is the only one 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() or _syscallN() may be required; see the intro(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.freestandards.org/. 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. 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.