From owner-freebsd-doc@FreeBSD.ORG Sat Jan 24 15:24:04 2004 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 887D316A4CE; Sat, 24 Jan 2004 15:24:04 -0800 (PST) Received: from arthur.nitro.dk (port324.ds1-khk.adsl.cybercity.dk [212.242.113.79]) by mx1.FreeBSD.org (Postfix) with ESMTP id 36B0343D2F; Sat, 24 Jan 2004 15:24:02 -0800 (PST) (envelope-from simon@arthur.nitro.dk) Received: by arthur.nitro.dk (Postfix, from userid 3000) id 01F4D1142B; Sun, 25 Jan 2004 00:24:00 +0100 (CET) Date: Sun, 25 Jan 2004 00:24:00 +0100 From: "Simon L. Nielsen" To: Tom Rhodes Message-ID: <20040124232359.GJ41072@arthur.nitro.dk> References: <20040122024729.2944fada@localhost> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="ibq+fG+Ci5ONsaof" Content-Disposition: inline In-Reply-To: <20040122024729.2944fada@localhost> User-Agent: Mutt/1.5.5.1i cc: FreeBSD-doc@FreeBSD.org Subject: Re: RFC: Automated process for documenting tunables/variables. X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 24 Jan 2004 23:24:04 -0000 --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--