On Thu, Apr 08, 2004 at 02:17:06PM -0400, Nathan J. Williams wrote:
>Andrew Brown <atatat@atatdot.net> writes:
>
>> putting anywhere that's not local to the code itself makes the
>> maintenance problem about an order of magnitude harder as is evidenced
>> by the fact that the documentation is not complete.  or, to put it the
>> other way around, putting the "documentation" next to the code makes
>> it easier.
>
>I agree with John. The fact that it's harder - even your claimed
>"order of magnitude" harder - to keep the documentation up-to-date
>when it's in a separate place is not by far sufficent justification
>for having the resulting documentation end up in kernel memory. That's
>a high bar, and you haven't met it.

okay, it's not that it's harder, it's just that people don't do it as
meticulously as we'd all like.  if sysctl(3) well and truly documented
*everything* that was instrumented, this would not be a problem.  but
it doesn't.  providing the option of a short note to give some sort of
hint as to what the knob (button, lever, dial, etc) does goes a long
way.

>> that said, unless you want to write a program that will scan the
>> *entire kernel source tree* looking for notes like these and determine
>> which ones are relevant (ie, the machdep subtree has different stuff
>> on every port), having them actually live in the tree so that they can
>> be queried ad hoc also makes more sense.  rely on the linker and the
>> kernel to find them automagically -- don't make work where you don't
>> need to.
>
>If you want to make the linker do the work, consider having the
>relevant text end up in a section that is not normally loaded. Or read
>up on "literate programming" tools.

i've read "literate programming".  it didn't convince me.  wrt this
stuff, i did consider making each of the sysctl descriptions be a
reference to a "thing" that a new utility could dig out of the "booted
kernel" (note: not available on all ports) from a link set of some
kind and stuff into a "database" that sysctl(8) could digest via a new
library routine, but that seemed like way overkill complexity.  and it
wouldn't help the case where a lkm gets loaded and adds new stuff.  by
then, the thingy has already done the thing with the thing and you
can't easily find out what frobbing foo.bar.wibble does.

that said, i'm still not unconvinced that some sort of message catalog
would not be out of line, where the description strings themselves
would provide the "default description", but could also contain
references to other language translations from the catalog, along with
man page references or pointers to other documentation.  this is all
easy to do now that the base mechanism is in place.

-- 
|-----< "CODE WARRIOR" >-----|
codewarrior@daemon.org             * "ah!  i see you have the internet
twofsonet@graffiti.com (Andrew Brown)                that goes *ping*!"
werdna@squooshy.com       * "information is power -- share the wealth."