mirror of https://github.com/mkerrisk/man-pages
How to maintain man-pages
This commit is contained in:
parent
e87c9d9746
commit
3b26077915
|
@ -0,0 +1,227 @@
|
|||
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.
|
Loading…
Reference in New Issue