RFC: Automated process for documenting tunables/variables.

[Tom Rhodes]

Greetings,

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.

But anyway, onward to the subject at hand.  Enclosed in this email
is three files:  run.sh, the main file which builds the manual page;
sysctl.sh, the file that sets up the structure of the tunables
section in our manual page; and tunables.mdoc, a list of all the
tunables that I threw together along with documentation that
is more user-friendly than the sysctl -d output.

This was designed to mainly work with a make universe, using nm(1)
to parse the LINT kernels and grab all the tunables from them.  If
you don't wish to run make universe, don't worry.  The -installed
option will parse the installed kernel in /boot/kernel.

As it stands now, a default manual page will be committed with
the work we have done.  The tunables/sysctls without descriptions
and which I cannot find documentation for will be left blank in
hopes that someone can document it or submit documentation to
me.  I will then update the manual page(s) once a month/bi-monthly
or before a release is cut.

We also support multi-architecture LINT kernels using the nm(1)
built for that architecture.  David O'Brien informed me that
the nm(1) does not like working on different architectures than
it was built for, thanks David.

There are some Caveats to this method:

We are using hard coded paths in the script in place of detecting
them.

I'm not sure how it could be integrated with or why it should be
integrated with a buildworld.

On a slow machine the make universe target could take hours, an
overnight project for some machines.

Duplication of documentation may occur, i'm unsure of how to
handle this other than just adding either an Xref from the generated
manual page or the ones that tunables are documented in.  Special
cases given to manual pages like security(7).

Some duplication cannot be avoided as we have tunables/sysctls which
can go in rc.conf, sysctl.conf, and passed on the command line.  There
is already duplication there and it isn't my job to redesign that part
of FreeBSD.  :)

Positives:

A central manual page for all architectures which hold many of the
tunable options FreeBSD has.

We avoid making substantial changes to sysctl(8) and the build in
general by not adding the extra C macros that the original idea
offered.

Users are more happy because we have (hopefully) good documentation
in place on hacks that are either undocumented or have difficult
to comprehend documentation provided by sysctl -d.

We aren't adding line upon line of documentation in source files.

Bruce Evans will be happy that no mdoc(7) exists in source files,
which is a style violation.  (This is just a little inside joke between
him and I.)

Apologies in advance for the length of this email, mistakes i've
made in this implementation, and the lack of a README or Makefile. :)

Thank you in advance for comments/suggestions.

-- 
Tom Rhodes
-------------- next part --------------
A non-text attachment was scrubbed...
Name: run.sh
Type: application/octet-stream
Size: 8725 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20040122/fb919f06/attachment.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: sysctl.sh
Type: application/octet-stream
Size: 1114 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20040122/fb919f06/attachment-0001.obj>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: tunables.mdoc
Type: application/octet-stream
Size: 30313 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20040122/fb919f06/attachment-0002.obj>