Date: Wed, 30 May 2001 16:33:42 -0700 From: Brooks Davis <brooks@one-eyed-alien.net> To: Sheldon Hearn <sheldonh@starjuice.net> Cc: Jesper Skriver <jesper@skriver.dk>, Greg Lehey <grog@FreeBSD.ORG>, Dima Dorfman <dd@FreeBSD.ORG>, cvs-committers@FreeBSD.ORG, cvs-all@FreeBSD.ORG Subject: Re: Documenting sysctls (was: cvs commit: src/sbin/sysctl sysctl.8) Message-ID: <20010530163342.A3209@Odin.AC.HMC.Edu> In-Reply-To: <25323.991263026@axl.fw.uunet.co.za>; from sheldonh@starjuice.net on Thu, May 31, 2001 at 12:50:26AM %2B0200 References: <20010531003943.E78414@skriver.dk> <25323.991263026@axl.fw.uunet.co.za>
next in thread | previous in thread | raw e-mail | index | archive | help
--17pEHd4RhPHOinZp Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Thu, May 31, 2001 at 12:50:26AM +0200, Sheldon Hearn wrote: > Last time this came up, there were two schools of thought: >=20 > 1) Document all the sysctls in one place so they're easy to find. >=20 > 2) Document each sysctl in the documentation for the device that it > controls. >=20 > The second option is great for thorough documentation, because it means > that the description can rely on the surrounding text of the manual > page. The problem is that not all sysctl's belong to a specific device. >=20 > I think a balance can be struck, where sysctls that belong to a device > are documented in the documentation for that device, while sysctls that > don't can be documented in sysctl(8) (or some other common place). I think all sysctls need to be listed somewhere so you can find the documentation for them. That documentation doesn't have to live in that location, but we really do need some sort of index of sysctl documentation since the man system provides not real practical fulltext search mechanism. I would suggest that all sysctls should have an entry appear in sysctl(8). In the case of sysctls with no other logical place for documentation it should be documentation. For things like the ioctls documented in tcp(4) it should just say "see tcp(4)". It will have the worlds longest SEE ALSO section, but at least that would mean there would be a way to find an answer to those questions like: "I wonder what hw.foo.bar.baz does?" This seems like a reasionable compromise. -- Brooks --=20 Any statement of the form "X is the one, true Y" is FALSE. PGP fingerprint 655D 519C 26A7 82E7 2529 9BF0 5D8E 8BE9 F238 1AD4 --17pEHd4RhPHOinZp Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.4 (GNU/Linux) Comment: For info see http://www.gnupg.org iD8DBQE7FYNWXY6L6fI4GtQRAhA0AJ9PXaHbFOLAIhNxaW96r2C9Nt1hQQCg1qQK 3JyXu43fy/k25iZ9w/jUUzU= =srb1 -----END PGP SIGNATURE----- --17pEHd4RhPHOinZp-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe cvs-all" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010530163342.A3209>