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 _______________________________________________ svn-src-all@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/svn-src-all To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"