Linux man-pages:   home | contributing | bugs | patches | download   ||   online pages

Maintaining Linux man-pages

The current man-pages maintainer is (since 2004) Michael Kerrisk (mtk.manpages@gmail.com; blog).

One day, someone else will be the maintainer. So, to make life easier for the next person: some tips on how to maintain the Linux man-pages project (also useful for anyone who wants to help with work on man-pages).

Read some man pages

Read at least the following:

All of these pages are relevant for maintaining man-pages. Some of them are part of packages other than man-pages.

Get the source code

History matters. The man-pages project documents not just the current state of the Linux kernel and glibc APIs, but also how they have changed over time.

Once upon a time, man-pages also used to document Linux libc details (libc4, libc5), and there are still some vestiges of that intent in existing pages, but Linux libc has been dead for quite a long time now (see here and here for some details), and there is no longer much need to keep documenting its peculiarities.

Your time is valuable, and disk space is cheap, so set aside a few gigabytes of disk space...

Kernel source code

You can find nearly every kernel release ever made at http://www.kernel.org/. At the very least, you will probably find it useful to:

For browsing the kernel source code, lxr can be useful. (Online browsable versions of various free kernels can be found at http://fxr.watson.org/.)

Glibc source code

Same story as the kernel:

A lot of glibc tarballs can be found at http://ftp.gnu.org/gnu/glibc/. Many older tarballs can be found at ftp://ftp.win.tue.nl/pub/linux-local/libc.archive/. Snapshots of the latest glibc development tree can be obtained via git:

git clone git://sourceware.org/git/glibc.git 

To obtain the code of a particular glibc release, use a command such as the following to check out that release from the git repository cloned in the previous command (here, getting the source of glibc 2.10):

 git checkout glibc-2.10 

Keeping up

One of the biggest challenges is keeping up to date with changes in the kernel and glibc. There are a few ways to do this.

Looking ahead: linux-next

The linux-next tree is the holding area for patches aimed at the next kernel merge window. It can be useful to track what's going on there, in order to get some idea of upcoming changes to the kernel. (Some notes on working with linux-next.)

Git

If you are looking for a specific kernel commit, or a commit log message containing a particular string, then searching Linus' Git tree can be useful.

Mailing lists

Linux API

The linux-api mailing list (linux-api@vger.kernel.org) discusses changes that affect the Linux programming interface (API or ABI). In theory, all patches that change the interface should be CCed to this list. To subscribe, send a message containing the following body to majordomo@vger.kernel.org:

    subscribe linux-api 

An archive of this list can be found on gmane.

Linux Kernel (LKML)

This list (linux-kernel@vger.kernel.org) 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. I find gmane nice to use.

Linux Kernel Announce

This low-volume list (linux-kernel-announce@vger.kernel.org) announces releases of new versions of various kernel branches, including release candidates for the mainline kernel and new -mm kernels. To subscribe, send a message containing the following body to majordomo@vger.kernel.org:

    subscribe linux-kernel-announce 

netdev

The netdev list, (netdev@vger.kernel.org), is the list used by the developers of the Linux networking subsystem.

To subscribe, send a message containing the following body to majordomo@vger.kernel.org:

    subscribe netdev 

Archives of this list can be found on gmane and marc.

Linux Test Project (LTP)

The LTP produces test suites for the Linux kernel. Subscribe to the discussion list here. There are list archives on gmane and here. (Pointers to the old project pages on Sourceforge can be found here.)

Kernel Newbies

Can be useful for asking questions on aspects of the kernel source that you don't understand.

To subscribe, send a message containing the following body to listar@nl.linux.org:

    subscribe kernelnewbies 

Archives of this list can be found on gmane and marc. See the kernelnewbies web site for more information.

libc-announce

This list announces each glibc release. Subscribe by sending an email to libc-announce-subscribe@sourceware.org or visiting this page. There is a list archive here.

libc-alpha

This is the development list for glibc. Subscribe by sending an email to libc-alpha-subscribe@sourceware.org or visiting this page. There is a list archive here.

libc-help

This list is for asking general questions and getting help on glibc. Subscribe by sending an email to libc-help-subscribe@sourceware.org or visiting this page. There is a list archive here.

Websites

These websites are useful because they in part include attempts by others to summarize changes to the Linux kernel.

Kernel releases

When a new kernel release is made, 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 ARM).

Glibc releases

Just as for the kernel, when a new glibc release comes out, scan the Changelog and the differences in the source code tree. Reading the NEWS file in the glibc root directory also provides information about important changes in a glibc release.

The following is useful to get a rough idea of what symbols are 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
    

Kernel bugzilla

The kernel.org bugzilla can be used to report man-pages bugs. The list of unresolved bugs in the bugzilla can be seen here.

Distribution-specific bug tracking systems

Debian

Debian makes it easy for upstream maintainers to subscribe to bug reports for man pages. To do this, visit http://packages.qa.debian.org/ and look for the Debian source packages manpages.

A current list of Debian bug reports for man-pages can be viewed here. The Debian manpages patch tracker is here.

Debian even provides an email interface that allows an upstream maintainer to manipulate Debian bug reports (using the "tags" command; see http://www.debian.org/Bugs/server-control).

The Debian developer/upstream-centric view of manpages can be seen here.

Every now and then it may be worth reviewing the Debian downstream diff patches applied to man-pages, to see if there's anything they should have pushed upstream, but didn't. Have a look at the diff patches that are available by following the "unstable" release links at http://packages.debian.org/manpages and http://packages.debian.org/manpages-dev, and downloading the Debian tarballs. Or look at the web patchtracker.

The following mail address reaches people with an interest in man pages at Debian: manpages@packages.debian.org.

Ubuntu

Ubuntu uses Launchpad for manpages (bugs, package) and manpages-posix (bugs, package). There are links on the "bugs" pages to allow subscribing to bug reports.

Red Hat

Red Hat provides a man-pages bugzilla component.

URL for Fedora package: http://koji.fedoraproject.org/koji/packageinfo?packageID=401. From there, you can reach the RPM files, and unpack them to see the diffs from upstream, using:

    rpm2cpio foo.rpm | cpio -idmv --no-absolute-filenames 

Downstream Git repo for Red Hat patches:

    git clone git://pkgs.fedoraproject.org/man-pages.git 

Fedora

It is possible to subscribe to Fedora man-pages bug reports, as follows:

Other

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 man 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 man 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/v4.0/testing/. Build and install the kernel, and write programs to test new features. 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) man page.

Testing new glibc features

For information on building and testing glibc releases, see Appendix C Installing the GNU C Library in the glibc manual, Frequently Asked Questions about the GNU C Library on the glibc wiki, and especially Carlos O'Donell's Testing a glibc build page on the glibc wiki.

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.

Standards

Join the Austin group. (Membership is free.)

Get electronic copies of current and past UNIX standards, especially the current POSIX.1-2008/SUSv4 standard, available in PDF format to members of the Austin group, and browsable online. Note also that section 3p of the man pages includes pages containing the specifications for all functions 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.

And have a look at the LSB (LSB 4.0, LSB 3.2).

Read man pages for other systems

Get man pages for as many other UNIX systems (including past and current versions) as you can find. Check those man pages to see what differences there are from Linux. They'll also provide ideas about topics that should be covered in corresponding Linux man pages. Don't violate copyrights by copying text from man pages whose licenses prohibit re-use.

Glibc info

Sometimes there is useful information to be found in the info(1) documentation for a particular function (if the info documentation 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 in order 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").

The FreeBSD source code is available via anonymous CVS, as described here. You'll want a command something like the following:

    $ cvs -d freebsdanoncvs@anoncvs.FreeBSD.org:/home/ncvs co src 

Get set up on kernel.org infrastructure

Look here.

Making man-pages releases

Uploading files

Release tarballs are made available at http://www.kernel.org/pub/linux/docs/man-pages/. Files are uploaded using kup. Look here.

man-pages web page

The man-pages website resides at http://www.kernel.org/doc/man-pages/. Files are uploaded using kup. Look here.

Release notifications

Being a good free software citizen

Reporting kernel and glibc bugs

Testing kernel and glibc features while writing man pages will inevitably uncover bugs. Report them.

For the kernel, a report can either go into the kernel bugzilla, or, if the report is of general interest (e.g., a significant bug in a new system call), it may be worthwhile submitting a note to the relevant developer (e.g., the author of the system call) and CCing LKML (linux-kernel@vger.kernel.org).

Bug reports for glibc go here: http://sourceware.org/bugzilla. This is also the place for bug reports for glibc info(1) documents.

Some history

The man-pages project was begun in 1993 by Rik Faith, who created releases 1.0 through to 1.5 (February 1995).

Rik Faith was succeeded by Andries Brouwer (aeb), who continued in the role for more than nine years, creating releases 1.6 (June 1995) through to 1.70 (October 2004).

The current maintainer, Michael Kerrisk (mtk), took over in November 2004, starting with release 2.00.