INCLUDE_CONFIG_FILE in GENERIC

[M. Warner Losh]

In message: <201001131633.09669.jhb at freebsd.org>
            John Baldwin <jhb at 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