mirror of https://github.com/mkerrisk/man-pages
294 lines
9.8 KiB
Plaintext
294 lines
9.8 KiB
Plaintext
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.
|