Date: Wed, 13 Jan 2010 15:04:35 -0700 (MST) From: "M. Warner Losh" <imp@bsdimp.com> To: jhb@freebsd.org Cc: svn-src-head@freebsd.org, svn-src-all@freebsd.org, dougb@freebsd.org, src-committers@freebsd.org, freebsd-arch@freebsd.org Subject: Re: INCLUDE_CONFIG_FILE in GENERIC Message-ID: <20100113.150435.650865766805848595.imp@bsdimp.com> In-Reply-To: <201001131633.09669.jhb@freebsd.org> References: <201001131515.08602.jhb@freebsd.org> <4B4E2ECA.90905@FreeBSD.org> <201001131633.09669.jhb@freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
In message: <201001131633.09669.jhb@freebsd.org>
John Baldwin <jhb@freebsd.org> writes:
: On Wednesday 13 January 2010 3:36:26 pm Doug Barton wrote:
: > On 1/13/2010 12:15 PM, John Baldwin wrote:
: > > On Wednesday 13 January 2010 1:48:38 pm Doug Barton wrote:
: > >> To address the other responses, Tom, sorry, your suggested text doesn't
: > >> address my concern. John, I don't think that users would somehow
: > >> magically know to look in NOTES for more information about an option
: > >> that is already in GENERIC.
: > >
: > > You really think users do not already know to look in manpages or NOTES to
: > > find out more details about kernel options?
: >
: > That's not what I said.
:
: <quote>
: I don't think that users would [..] know to look in NOTES for more information
: about an option that is [...] in GENERIC.
: </quote>
:
: That seems really straight forward to me, or my English isn't good. I do
: think users "would know to look in NOTES for more information about an option
: that is in GENERIC".
Agreed. That's why I did what I did: I conformed to the usual practice.
: > > Put
: > > another way, what makes 'INCLUDE_CONFIG_FILE' sufficiently special that it
: > > deserves special treatment relative to other kernel options?
: >
: > Because the default behavior (not including the actual file) for the
: > option is contrary to user' reasonable expectation of how the option
: > should work .... and now I'm repeating myself.
:
: I think a better change would be to just change the default behavior of
: config(8) to do the reasonable thing.
-C should be the default, and we should invent a new
'--smaller-saved-config' option.
: > Seriously, don't you have anything better to do than argue against
: > including a comment in a config file? I know I do. What is the
: > overwhelming horror that will arise here if there are more comments
: > GENERIC than you deem to be absolutely necessary?
:
: What is the overwhelming horror about keeping a file readable and allowing
: users to find extended documentation for INCLUDE_CONFIG_FILE in the same place
: that they find extended documentation about every other kernel option?
Yes. That's why I did what I did: to keep things readable.
: > And yes, I read the part of your message that I snipped about "why do we
: > have these documents if users don't read them?" The answer is, that's
: > why I'm suggesting a comment that tells users what man page to read.
:
: I think adding comments that merely redirect the users to further
: documentation only serves to obfuscate. Left unchecked this approach will
: render files such as GENERIC with a very low signal-to-noise ratio making it
: harder to parse in a "big picture" way.
Yes.
Basically, I'm annoyed too: Our users aren't idiots, and we shouldn't
be treating them as such at every turn. If there are surprises with
how INCLUDE_CONFIG_FILE behaves, we should work to make it better, not
paper over it with a comment.
Warner
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20100113.150435.650865766805848595.imp>