lkml.org 
[lkml]   [1999]   [Aug]   [16]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: 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/

\
 
 \ /
  Last update: 2005-03-22 13:53    [W:0.052 / U:0.252 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site