Date: Sun, 25 Jan 2004 00:24:00 +0100 From: "Simon L. Nielsen" <simon@FreeBSD.org> To: Tom Rhodes <trhodes@FreeBSD.org> Cc: FreeBSD-doc@FreeBSD.org Subject: Re: RFC: Automated process for documenting tunables/variables. Message-ID: <20040124232359.GJ41072@arthur.nitro.dk> In-Reply-To: <20040122024729.2944fada@localhost> References: <20040122024729.2944fada@localhost>
next in thread | previous in thread | raw e-mail | index | archive | help
--ibq+fG+Ci5ONsaof
Content-Type: multipart/mixed; boundary="yhze8HlyfmXt1APY"
Content-Disposition: inline
--yhze8HlyfmXt1APY
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
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:
>=20
> 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.
--=20
Simon L. Nielsen
FreeBSD Documentation Team
--yhze8HlyfmXt1APY
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="sysctl.sh-no-empty-type.patch"
--- 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
+}
--yhze8HlyfmXt1APY--
--ibq+fG+Ci5ONsaof
Content-Type: application/pgp-signature
Content-Disposition: inline
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (FreeBSD)
iD8DBQFAEv6Ph9pcDSc1mlERAlFhAKCvlWD+a37yqBzzdsT/djDzu/HySwCeMMAQ
5Fl1YvDrubNFEZFdRDD1P2E=
=WGLk
-----END PGP SIGNATURE-----
--ibq+fG+Ci5ONsaof--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20040124232359.GJ41072>