Messages in this thread | | | Date | Sat, 14 Aug 1999 18:13:29 +0200 (MET DST) | From | Andries.Brouwer@cwi ... | Subject | Re: info format (was Re: Linux 2.2.11pre4) |
| |
Returning from Tibet I find in my mailbox some discussion on man pages and the documentation of libc6 (glibc).
My point of view is the following: Ideally a Linux man page should discuss the behaviour of any library routine on all Unix platforms, with special attention to the Linux details. It should tell how much of the behaviour is prescribed by POSIX, X/Open, Susv2 etc. It should give the Linux kernel version that first implemented a system call. Should mention the kernel versions where the behaviour changed significantly. Should describe libc5 and glibc differences.
Some man pages really attain this ideal. Many just describe libc5.
Sometimes people submit patches to man pages, changing the description of what libc5 does into a description of what libc6 does. I always try to describe all environments, so that people can program portably.
But in fact rather few people submit improvements. Most people have just enough energy to complain that the man pages are of low quality, but have not enough energy to mail the maintainer mentioning what flaw is present in which man page (or even submitting a patch).
Let me answer a random letter from this discussion:
From rgb@phy.duke.edu Fri Aug 6 23:41:50 1999
One of the things that started my involvement in this discussion is irritation that BOTH "man crypt" and "info crypt" display the same, obsolete man page, dated September of 1994.
The program info will give you the man page if it cannot find the info page.
"info libc", on the other hand, if searched for "MD5" or "crypt" and the associated "crypt" link followed, reveals a totally different behavior for crypt.
The man page is accurate for certain environments. An improved man page would probably delete some of the details since the standard these days says that these are implementation dependent, so that it would be unwise to know too much.
So perhaps the right thing to call for is that the information in the libc texinfo source be propagated into individual documents in such a way that the associated man pages are correct.
The glibc texinfo source generally has a very different aim, namely to describe the routines as implemented by a given version of glibc. It does not have enough information to allow one to program for an arbitrary Linux system.
Right now, there are WAY too many man pages that are just broken.
But there are no people pointing out flaws.
Heck, "man man" references "man.conf(5)" which no longer seems to exist.
Then you made a mistake while installing the man package, or you used a distribution that patches the man package in an inconsistent way.
But, in this discussion, `man pages' refer to `Section 2 and 3 man pages' and man(1) or man.conf(5) are irrelevant.
Andries - aeb@cwi.nl
- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.rutgers.edu Please read the FAQ at http://www.tux.org/lkml/
| |