RFC: Automated process for documenting tunables/variables.
Simon L. Nielsen
simon at FreeBSD.org
Sat Jan 24 23:24:04 UTC 2004
On 2004.01.22 02:47:29 -0500, Tom Rhodes wrote:
> Greetings,
As threatened, here are some comments :-).
> 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... :-).
> 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.
Sounds like a OK way to handle it.
> There are some Caveats to this method:
>
> We are using hard coded paths in the script in place of detecting
> them.
Since only a few people is actually going to run this script, I don't
think that is a big problem.
> 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.
> Thank you in advance for comments/suggestions.
In general I think it looks good, but some suggestions:
- There are some EOL whitespace in the files which should be removed.
- 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,"
- All the documented variables in tuneables.mdoc ends with .Pp. How
about just defaulting to adding .Pp after each entry in the scripts?
- Some variables are already described well in their current context,
e.g. security.mac.portacl.rules. In those cases I think it's much
better just to make a Xref to the original manual page instead of doing
copy/paste.
- 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.
- 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...
I think this manual page will make it much simpler for users to find
documentation for sysctls.
--
Simon L. Nielsen
FreeBSD Documentation Team
-------------- next part --------------
--- sysctl.sh.orig Sun Jan 25 00:05:18 2004
+++ sysctl.sh Sun Jan 25 00:08:33 2004
@@ -40,8 +40,10 @@
fi ; \
\
echo ".It Va ${tmpname}" ; \
- echo ".Pq Vt ${type}" ; \
+ if [ X"${type}" != X"" ]; then \
+ echo ".Pq Vt ${type}" ; \
+ fi ; \
grep -v '^[[:space:]]*$' | \
sed -e "s/@default@/${value}/g" | \
sed -e "s/@type@/${type}/g" ; \
-}
\ No newline at end of file
+}
-------------- 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/20040125/36e79a31/attachment.sig>
More information about the freebsd-doc
mailing list