Quoting Michael Kerrisk ([EMAIL PROTECTED]): > On Wed, Jul 16, 2008 at 11:23 AM, Masatake YAMATO <[EMAIL PROTECTED]> wrote: > >> From now on, I'll be agitating more to get man pages provided more with new > >> syscalls and ther kernel-userland interfaces. That will mean either I > >> twist > >> developers arms to write pages ;-), or I write them myself, with help from > >> them. I do think that man-pages, if well written, are often sufficient as > >> (or at least a very good base for) a test specification. Here's an example > >> that I did with the timerfd API, finding two bugs in the process: > >> http://thread.gmane.org/gmane.linux.kernel/613442 . I did something > >> similar > >> while writing the utimensat(2) man page, finding 5 or 6 different bugs in > >> the end, see > >> http://linux-man-pages.blogspot.com/2008/06/whats-wrong-with-kernel-userland_30.html > > > > > > And from now on, I'll be agitating much more to report a mistake in > > man pages if you, a test case auther, found it during writing test > > cases. > > Yes, please! Now that I have more time for man-pages, I should > usually be able to respond quickly to such reports. > > > Generally we can expect a test case auther reads man pages very carefully. > > Such a person may have much chance to find mistake in man page (than kernel > > developers:-) > > Yes. > > > If a kernel developer writes both test cases, and man pages, it is very > > nice. > > However, checking each other by independent teams like test case authors and > > man page authors is also good. > > Yes; indeed it is better. An implementer can be inclined to make > assumptions about their own code, and then not test those asumptions; > implementers are also sometimes just lazy about testing. Having other > people involved in testing counteracts those problems. > > > When I received a bug report about my test case and I confirmed that there > > were no bug in my test case itself, I had to inspect both the kernel/libc > > code and man page. This is the most exciting experience during working on > > LTP for me. > > > > Once I concluded to send a patch to LKML: > > > > http://www.opensubscriber.com/message/[EMAIL PROTECTED]/8342264.html > > > > Once I concluded to report a mistake to Michael: > > > > http://www.mail-archive.com/ltp-list@lists.sourceforge.net/msg02730.html > > > > How about opposite direction? > > Tracking all discussion in LKML is hard. > > Yes, it is. > > > However, tracking changes in > > the section 2 of man pages are easier than tracking LKML. If the page > > in the section is changed, it may have impact on test cases for the > > system call. > > This is true. Of course, I'm still trying to solve the problem of how > *I* find out about all of the changes in the kernel so that the man > pages can be updated accordingly.
It might help to lobby for an addition to Documentation/SubmitChecklist or SubmittingPatches to mention checking whether changes to manpages are necessary. -serge ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Ltp-list mailing list Ltp-list@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/ltp-list
