RFC: Automated process for documenting tunables/variables.

[Simon L. Nielsen]

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>