INCLUDE_CONFIG_FILE in GENERIC

[John Baldwin]

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

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

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

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

-- 
John Baldwin