On 2004-04-09 wrstuden@NetBSD.org wrote:
> On Fri, Apr 09, 2004 at 04:08:09PM -0400, Matthew Orgass wrote:
> > On 2004-04-09 wrstuden@NetBSD.org wrote:
> >
> > > What you propose means going back to having the info in two places, and
> > > revisiting all of the issues we had before.
> >
> >   You do not need to compile the info into sysctl to have sysctl report
> > it.  Provide a simple text file that looks something like this:
> > foo.bar:
> > Short description (one line)
> > Long description
> >
> > foo.stuff.*:
> > Short/long description of what nodes under foo.stuff mean
> >
> > foo.stuff.*.a:
> > Description of the a node for each node under foo.suff
> >
> >   Install this file in a directory in SYSCTLDOC or such and sysctl can
> > load the files and use them to describe existing nodes.  You can even
> > write a simple script to generate the equivalent section of the man page.
> > Something is seriously wrong if you can't tell what a sysctl node means
> > with basic regular expressions before it is actually created.
>
> The problem is that we don't really know where something's going to be
> until it's there. Thus pre-made docs don't work very well.

  Why not?  Give an example.  I can't imagine why you would want to do
this.  The above file desription is probably a little more simplistic than
would be desireable, as you would probably want to be able to refer to
other descriptions to avoid duplicating descriptive text.  This would make
generating man pages more difficult if the description resides in a
different file, but would probably be worth it and it should still be
possible to arrange correct man page generation.  I think names that are
not able to be reliably determined ahead of time should be prohibited, as
they are likely to cause conflicts and be hard to use.  You should always
be able to use a naming scheme that can be identified prior to creation.
If there are really legitimate cases that I can't think of, sysctl should
provide the minimum amount of information needed to make the connection.

> > > > >i'd like to point out, again, that this is an option.
> > > >
> > > > As was already pointed out, "this is an option" is not an interesting
> > > > point. It is by essence something that users will become very aware of,
> > > > and it is thus not a feature that can just come and go depending on the
> > > > available amount of memory of the machine and the mood or habits of the
> > > > person compiling the kernels for it.
> > >
> > > Oh, come on! :-) If users become aware of this and they decide they want
> > > it, that means they feel it is more important than the X k of memory it
> > > costs. I'm accepting Andrew's analysis that as we add more descriptions we
> > > may grow from the ~5k noted so far.
> >
> >   "If you want sysctl descriptions, include option X or grep the source."
> >
> >   5k and growing is a high cost for mindless repetition like the example
> > below.  Actual documentation would take more space, and should be
> > available.  I think the idea of having sysctl able to document the nodes
> > is a good idea, but it should be actual documentation and it should be in
> > userland.
>
> I think that example was one of the more mindless ones. I think there are
> a number of ones that aren't as clear. Like kern.tkstat.rawcc or
> kern.memlock_range or net.inet.tcp.cwm or net.inet6.ip6.keepfaith. They
> are ones I wasn't immediately clear on. :-)

  How about this one: maxbigpipes: Maximum number of "Big" pipes.  I do
have a question about that one, but the description doesn't help (although
I admit it could without being much longer).  I do think being able to
match description to documentation quickly and easily is a good idea and
could be more helpful if the description could be longer.  It should be
possible to do this in userland without too much difficulty.

Matthew Orgass
darkstar@city-net.com