Re: man-pages-2.08 is released
From: Michael Kerrisk
Date: Thu Oct 13 2005 - 03:53:59 EST
> Von: Jesse Barnes <jbarnes@xxxxxxxxxxxxxxxx>
> On Wednesday, October 12, 2005 9:26 am, Michael Kerrisk wrote:
> > This is a request to kernel developers: if you make a change
> > to a kernel-userland interface, or observe a discrepancy
> > between the manual pages and reality, would you please send
> > me (at mtk-manpages@xxxxxxx ) one of the following
> > (in decreasing order of preference):
> Would it make sense for some of the man pages (or maybe all of them) that
> correspond directly to kernel interfaces (e.g. syscalls, procfs & sysfs
> descriptions) to be bundled directly with the kernel? Andrew is
> generally pretty good about asking people to update the stuff in
> Documentation/ when necessary, so maybe the man pages would be kept more
> up to date if developers were forced to deal with them more directly.
Recently, I was just wondering the same thing. However, there
are complexities to consider. C libraries (okay, glibc is the
main one I concern myself with) sometimes add some functionality
in the wrapper function for a particular system call. This also
needs to be documented in the Secion 2 page.
Nevertheless, I think the idea of binding the kernel sources and
Sections 2 and 4 of the manual pages a bit more tightly bears
some consideration. In the ideal world, when a change is made to
the kernel, the patch could include adjustments to the man
pages (if relevant) -- then the changes could follow the patch
through the -mm tree and then into Linus's tree.
> OTOH, they comprise a fairly large package, so adding them to the kernel
> tarball would increase its size a lot.
I'd guess that the uncompressed source of the relevant pages
would be around 3 MB.
> The man pages are great;
Thanks. But the greatest part of credit must go to Andries,
the maintainer for nearly 10 years. I'm shortly coming up to my
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7
Want to help with man page maintenance? Grab the latest
tarball at ftp://ftp.win.tue.nl/pub/linux-local/manpages/
and grep the source files for 'FIXME'.
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/