Date: Fri, 10 Nov 2000 00:50:05 -0800 (PST) From: Nik Clayton <nik@freebsd.org> To: freebsd-doc@freebsd.org Subject: Re: docs/22676: No man pages for Make.conf or /usr/src/sys/Makefile Message-ID: <200011100850.AAA91699@freefall.freebsd.org>
index | next in thread | raw e-mail
The following reply was made to PR docs/22676; it has been noted by GNATS.
From: Nik Clayton <nik@freebsd.org>
To: Sheldon Hearn <sheldonh@uunet.co.za>
Cc: freebsd-doc@freebsd.org
Subject: Re: docs/22676: No man pages for Make.conf or /usr/src/sys/Makefile
Date: Thu, 9 Nov 2000 11:25:54 +0000
On Wed, Nov 08, 2000 at 04:20:04AM -0800, Sheldon Hearn wrote:
> > >Number: 22676
> > >Category: docs
> > >Synopsis: No man pages for Make.conf or /usr/src/sys/Makefile
>
> Oh dear. You've put a lot of work into this.
>
> As someone who spends a lot of time pulling his hair out over stale
> manual pages, these two scare me.
>
> I honestly think that it's a bad idea to import these two. They
> basically just duplicate the commentary in the files they document, and
> I don't think it's too much to ask for folks to read the files
> themselves.
I'm inclined to disagree. Otherwise we could ditch rc.conf(5),
periodic.conf(5), and others -- fstab(5) could be lost if we made sure
that /etc/fstab was sufficiently well commented, for example.
I understand that keeping them up to date is a chore, but I think as long
as they include a caveat that says something like
BUGS
This man page may lag behind the actual contents of the file, please
read the comments in the file for any new functionality.
then we should be OK. I'm also more than happy to support any committer
whacking you want to do when someone commits to /etc/make.conf without
updating make.conf(5) (and we should probably put a comment in the top of
/etc/make.conf saying exactly that.
N
--
Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95.
Telephone line, $24.95 a month. Software, free. USENET transmission,
hundreds if not thousands of dollars. Thinking before posting, priceless.
Somethings in life you can't buy. For everything else, there's MasterCard.
-- Graham Reed, in the Scary Devil Monastery
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
help
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200011100850.AAA91699>