Date: Thu, 9 Nov 2000 11:25:54 +0000 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 Message-ID: <20001109112554.B425@canyon.nothing-going-on.org> In-Reply-To: <200011081220.EAA13896@freefall.freebsd.org>; from sheldonh@uunet.co.za on Wed, Nov 08, 2000 at 04:20:04AM -0800 References: <200011081220.EAA13896@freefall.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20001109112554.B425>