RFC: Automated process for documenting tunables/variables.

[Simon L. Nielsen]

[I just merged the two mails]

On 2004.01.26 22:36:52 -0500, Tom Rhodes wrote:
> On Sun, 25 Jan 2004 00:24:00 +0100
> "Simon L. Nielsen" <simon at FreeBSD.org> wrote:
> 
> > On 2004.01.22 02:47:29 -0500, Tom Rhodes wrote:

> > > About three weeks ago Marc Silver kicked me in the butt to start
> > > working on this project again.  First off, I did not drop the front
> > > page; only working on that and other projects at the same time.
> > 
> > Good, I really miss my link to the events page... :-).
> 
> I want to put that into a 'community' section, but this email isn't
> about this.

Indeed, I just wanted to do a slight poke :-).

> > > I'm not sure how it could be integrated with or why it should be
> > > integrated with a buildworld.
> > 
> > If it should be integreated with buildworld it should be made much
> > faster.  The speed isn't a problem when just running the script once in
> > a while, but if all buildworlds had to wait for it, I think people would
> > complain.
> > 
> > It could be nice to integrate with buildworld to avoid having the
> > generated manual page in CVS, but I don't think it's that important.
> 
> I could be/would be, but require code changes which I don't like.
> Addition of macros and perhaps more functions in sysctl.h.
> 
> Not sure if that method is a good idea.  There should be no
> problem with me doing the general updating every now and again.

No, I think it's the best solution, at least I can't come up with a
better one.

> > - A lot of the mdoc lines in run.sh are broken up (which of course isn't
> > an error, but since it's a new file it might as well be done right).
> > 
> > 	E.g. :
> > 
> > 	"While some sysctls may be used
> > 	to alter the system behavior on-the-fly,"
> 
> Would rather not make them longer than 72 characters but I can
> see what you mean.  It might look a bit nicer to have them
> in more sentence length.

Indeed the shouldn't be longer than 72, but as short as they were in
your patch seemed a bit short.

> > - For undocumented variables, it looks odd with the '()' below.  I have
> > attached a patch which only prints '.Pq Vt ${type}' if there actually is
> > a type.
>
> Thanks for the patch, i'll give it a whirl.  I like this a little
> better than our previous incantation.

Great :).

> > - In the generated manual page "This manual page automatically generated
> > once a month by a script..." - I think that makes it sound like it's  
> > updated once a month on the end users systems.  I don't have a good  
> > suggestion for another wording right now though...
>
> Perhaps something similar to:    
>
> This manual page is generated for every release.
>
> But i'm sure that something else will be more realistic.

That sounds better to me.

If you have an updated patch just, feel free to throw a version my way.

-- 
Simon L. Nielsen
FreeBSD Documentation Team
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20040201/10bf87b4/attachment.sig>