--- /dev/null
+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.
projects / thirdparty / man-pages.git / commitdiff
