Date: Wed, 13 Jan 2010 16:33:09 -0500 From: John Baldwin <jhb@freebsd.org> To: Doug Barton <dougb@freebsd.org> Cc: svn-src-head@freebsd.org, svn-src-all@freebsd.org, src-committers@freebsd.org, freebsd-arch@freebsd.org Subject: Re: INCLUDE_CONFIG_FILE in GENERIC Message-ID: <201001131633.09669.jhb@freebsd.org> In-Reply-To: <4B4E2ECA.90905@FreeBSD.org> References: <alpine.BSF.2.00.1001110348100.92627@serrsnyy.serrofq.bet> <201001131515.08602.jhb@freebsd.org> <4B4E2ECA.90905@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201001131633.09669.jhb>