Bug 22676

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.

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.

It's great that you're getting stuck in and contributing, but I think
that these two aren't a good idea. :-(

Ciao,
Sheldon.

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

On Wed, 08 Nov 2000 09:30:32 CST, Mike Meyer wrote:

> 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?

You're right.  I stand down for build(7) (in other words, I think it's a
good idea), but still don't think that make.conf(5) is a good idea.

Ciao,
Sheldon.

Comment 4 nik 2000-11-09 11:25:54 UTC

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

Sheldon Hearn <sheldonh@uunet.co.za> types:
> On Wed, 08 Nov 2000 09:30:32 CST, Mike Meyer wrote:
> > 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?
> You're right.  I stand down for build(7) (in other words, I think it's a
> good idea), but still don't think that make.conf(5) is a good idea.

Even though I've shown you how to do things so this doesn't make the
stale documentation problem any worse than it already is, and it
improves the accessibility of the documentation?

	<mike

On Thu, 09 Nov 2000 13:22:59 CST, Mike Meyer wrote:

> Even though I've shown you how to do things so this doesn't make the
> stale documentation problem any worse than it already is, and it
> improves the accessibility of the documentation?

Yup.  However, I do think that my argument is mostly emotional. :-)

I have this pretty deep-seated feeling that manpages that document the
obvious aren't good.

However, you can probably just ignore everything I've said, given Nik
Clayton's counter argument and the fact that I have nothing to say in
answer to it. :-)

Ciao,
Sheldon.

Sheldon Hearn <sheldonh@uunet.co.za> types:
> On Thu, 09 Nov 2000 13:22:59 CST, Mike Meyer wrote:
> > Even though I've shown you how to do things so this doesn't make the
> > stale documentation problem any worse than it already is, and it
> > improves the accessibility of the documentation?
> Yup.  However, I do think that my argument is mostly emotional. :-)

I actually expected that to be the case. Changing someone's mind via
email is nearly impossible.

> I have this pretty deep-seated feeling that manpages that document the
> obvious aren't good.

I actually agree with that - what you need in those cases is a man
page pointing out where "the obvious" can be found. For make.conf,
that information is the comments in /etc/defaults/make.conf, so you
might as well just maintain the man page as the comments. For
periodic.conf and rc.conf, that doesn't make as much sense - but we've
got man pages for those already.

> However, you can probably just ignore everything I've said, given Nik
> Clayton's counter argument and the fact that I have nothing to say in
> answer to it. :-)

I haven't seen that mail. It's not attached to the PR. Could you tell
me where it showed up, or possibly forward it to me?

	Thanx,
	<mike

Sheldon Hearn <sheldonh@uunet.co.za> types:
> On Fri, 10 Nov 2000 02:32:25 CST, Mike Meyer wrote:
> > I haven't seen that mail. It's not attached to the PR. Could you tell
> > me where it showed up, or possibly forward it to me?
> *grumble* *grumble*  It always annoys me when folks mail the responsible
> mailing list instead of copying their follow-up to the gnats handler.
> I'll get Nik's message into gnats.  For now, it's included in this
> message.

Thank you.

To reply to a comment from Nik Clayton:

> 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.

The man page references /etc/defaults/make.conf. And since Nik pointed
out the relation to periodic.conf & rc.conf, they could use the same
caveat.

> 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.

I hope you meant /etc/defaults/make.conf. /etc/make.conf isn't there
until someone creates it post-install. Similar comments would be even
more effective in the other file sin /etc/defaults.

	<mike

Comment 9 ben 2000-11-22 14:11:43 UTC

State Changed
From-To: open->closed

Committed, thanks!