From owner-freebsd-questions Mon Nov 6 10:43:47 2000 Delivered-To: freebsd-questions@freebsd.org Received: from odin.acuson.com (odin.acuson.com [157.226.230.71]) by hub.freebsd.org (Postfix) with ESMTP id 6FF0437B4C5 for ; Mon, 6 Nov 2000 10:43:44 -0800 (PST) Received: from acuson.com ([157.226.47.12]) by odin.acuson.com (Netscape Messaging Server 3.54) with ESMTP id AAA739B; Mon, 6 Nov 2000 10:46:59 -0800 Message-ID: <3A06FB37.A6023AB@acuson.com> Date: Mon, 06 Nov 2000 10:40:55 -0800 From: David Johnson Organization: Acuson X-Mailer: Mozilla 4.7 [en] (X11; U; SunOS 5.5.1 sun4m) X-Accept-Language: en MIME-Version: 1.0 To: Sue Blake Cc: Gary Kline , Giorgos Keramidas , Rasputin , freebsd-questions@FreeBSD.ORG Subject: Re: better man pages [was: beginners with bsd] References: <000a01c043c3$942af1e0$1d24fc3e@knapp> <20001102093329.B14637@dogma.freebsd-uk.eu.org> <20001103003014.D4698@hades.hell.gr> <3A01F6D9.6320A0E5@acuson.com> <20001102170242.A14016@athena.sea.tera.com> <20001105130350.A7864@welearn.com.au> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Sender: owner-freebsd-questions@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG Sue Blake wrote: > I've been running a basic VMS to UNIX orientation course where we > compared man pages from several systems they were going to encounter: > FreeBSD, Slackware Linux, Dynix/PTX, Digital UNIX (now Tru64) > > We found the FreeBSD and Digital man pages to be much more readable and > informative than the others, and both had a consistency in structure > that made "getting the knack of it" fairly easy. While the Digital > man pages had more information, the FreeBSD man pages were > often the most usable, at least for the samples that we dissected. man pages should be written by those who wrote the command or function it refers to. In the case of Linux, most everything is borrowed from elsewhere. Although the Slackware pages come up short, I don't think it's Patrick Volkerding's responsibility to write man pages for ld, sleep, mtools, or any other command that he did not write. One of the biggest problems in this area is that GNU doesn't just neglect writing man pages, they actively discourage it. Thus, people who use GNU as an example of behavior won't write man pages either. Simply volunteering to write a man page for a GNU program will not do any good, because the developer still needs to maintain it, or it will rapidly become obsolete. The best solution would be a utility that creates man pages from the same files that info pages are created from. Not all of the information in info needs to be included in the man page, but there should be enough that it is complete. With such a utility it becomes no work at all to keep the man pages current and on par with the info pages. David To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-questions" in the body of the message