Date: Wed, 8 Nov 2000 07:40:03 -0800 (PST) From: Mike Meyer <mwm@mired.org> To: freebsd-doc@freebsd.org Subject: Re: docs/22676: No man pages for Make.conf or /usr/src/sys/Makefile Message-ID: <200011081540.HAA44311@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
The following reply was made to PR docs/22676; it has been noted by GNATS.
From: Mike Meyer <mwm@mired.org>
To: Sheldon Hearn <sheldonh@uunet.co.za>
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/22676: No man pages for Make.conf or /usr/src/sys/Makefile
Date: Wed, 8 Nov 2000 09:30:32 -0600 (CST)
Sheldon Hearn <sheldonh@uunet.co.za> types:
> On 08 Nov 2000 01:26:36 GMT, mwm@mired.org 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.
Well, it's obvious to anyone who spends much time helping people in
-questions that better sources for this information is needed, but
doing the work doesn't mean it gets used. Which was why I asked jkh
about a make.conf man page *before* putting a lot of time into it. He
thought it was a good idea. In putting it together, I noticed that I
had what was essentially a parallel to the ports(7) man page, so
unbundled the build(7) man page from what I'd originally
planned. There really needs to be a doc(7) (docs?) man page as well,
but I don't know enough to write that one.
> As someone who spends a lot of time pulling his hair out over stale
> manual pages, these two scare me.
To quote jkh - "any man page is better than no man page". If you don't
have a man page, you have to check the sources. If you do and it's
stale, you have to check the sources - only you've got historical
clues to help you get started.
> 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.
First, build(7) doesn't document a single file, but a process. Of
course, it duplicates information in the files that take place in the
process - but what man page doesn't duplicate information from the
sources?
Second, the bulk of the work I did was in the make.conf man page. If
you look at /etc/defaults/make.conf - well, I'll do it for you:
guru$ grep -v '^#' /etc/defaults/make.conf
BDECFLAGS= -W -Wall -ansi -pedantic -Wbad-function-cast -Wcast-align \
-Wcast-qual -Wchar-subscripts -Wconversion -Winline \
-Wmissing-prototypes -Wnested-externs -Wpointer-arith \
-Wredundant-decls -Wshadow -Wstrict-prototypes -Wwrite-strings
Unlike rc.conf (which *is* documented), that file is pretty much *all*
comments. My suggestion would be to have someone with the commit bit
sync the two again, possibly bringing in more of the default values,
then replace everything but BDECFLAGS in /etc/defaults/make.conf with
a comment about "see (or update) the make.conf(5) man page". Come to
think of it, a similar pointer/reminder in /etc/defaults/rc.conf is
probably a good idea in any case, as that page already exists.
> It's great that you're getting stuck in and contributing, but I think
> that these two aren't a good idea. :-(
If you do what I suggested, then you've still got the source and one
bit of documentation - only the documentation can take advantage of
mdoc. As for the build(7) man page, it pulls together stuff that
requires reading more than one file.
<mike
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?200011081540.HAA44311>