From owner-freebsd-doc Tue Mar 11 3:22:50 2003 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 AF2F937B401 for ; Tue, 11 Mar 2003 03:22:45 -0800 (PST) Received: from gandalf.online.bg (gandalf.online.bg [217.75.128.9]) by mx1.FreeBSD.org (Postfix) with SMTP id 689EF43FA3 for ; Tue, 11 Mar 2003 03:22:41 -0800 (PST) (envelope-from roam@ringlet.net) Received: (qmail 28462 invoked from network); 11 Mar 2003 11:18:18 -0000 Received: from office.sbnd.net (HELO straylight.ringlet.net) (217.75.140.130) by gandalf.online.bg with SMTP; 11 Mar 2003 11:18:15 -0000 Received: (qmail 10913 invoked by uid 1000); 11 Mar 2003 11:21:06 -0000 Date: Tue, 11 Mar 2003 13:21:06 +0200 From: Peter Pentchev To: David Schultz Cc: Sean Chittenden , "M. Warner Losh" , doc@FreeBSD.org, trhodes@FreeBSD.org, dwmalone@FreeBSD.org Subject: Re: your mail Message-ID: <20030311112105.GO578@straylight.oblivion.bg> Mail-Followup-To: David Schultz , Sean Chittenden , "M. Warner Losh" , doc@FreeBSD.org, trhodes@FreeBSD.org, dwmalone@FreeBSD.org References: <20030310195323.GA2812@HAL9000.homeunix.com> <20030310204035.GU79234@perrin.int.nxad.com> <20030311045239.GA4369@HAL9000.homeunix.com> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="EqVOK5mkaJAMmtSx" Content-Disposition: inline In-Reply-To: <20030311045239.GA4369@HAL9000.homeunix.com> User-Agent: Mutt/1.5.3i Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org --EqVOK5mkaJAMmtSx Content-Type: multipart/mixed; boundary="sMkrXc3gAYLRVOjR" Content-Disposition: inline --sMkrXc3gAYLRVOjR Content-Type: text/plain; charset=windows-1251 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Mon, Mar 10, 2003 at 08:52:39PM -0800, David Schultz wrote: > Thus spake Sean Chittenden : > > > Very cool. I think it might be a better idea to move the > > > centralized list to the handbook, since hypertext is a better medium > > > for a list that will potentially be very long and contain many > > > cross-references. Short descriptions next to MIBs would be nice. > > > Also, sorting first by category and then by alphabetical order might > > > be more helpful. > >=20 > > ::shakes head violently in disagreement:: > >=20 > > NOOOOOOOOO!!!! :-P While I agree with you on the technological front > > regarding hyper-links, the whole point of having this in a man page is > > to be able to help the admin that's up late at night trying to figure > > out why a certain value is set to what and where to change it in the > > config. If we'd like to have this in the handbook, so be it, but I > > think the primary effort should be in mdoc for usability and ease of > > use (unless of course the mdoc sources are built from DocBook: see > > earlier post on the topic). -sc >=20 > Actually, I was thinking of the fact that properly laid out > DocBook can be converted into a (slightly more concise) mdoc file. > I have nothing against a manpage listing all of the sysctls, but I > think that centralizing the information in an SGML-based format > would be much more useful in the long run. And since you can make > a manpage out of that, the only disadvantage I see is the extra > work to put together the DocBook stuff and figure out how to do > the conversion. I wonder if plain XML and an XSL transformation would not be a bit easier to do (and possibly maintain) than all the additional hairiness that, with all due respect, DocBook would add. Attached is a simple example that still needs quite a lot of work on the formatting front, especially WRT trimming leading spaces, but it demonstrates the basic idea. G'luck, Peter --=20 Peter Pentchev roam@ringlet.net roam@sbnd.net roam@FreeBSD.org PGP key: http://people.FreeBSD.org/~roam/roam.key.asc Key fingerprint FDBA FD79 C26F 3C51 C95E DF9E ED18 B68D 1619 4553 This sentence no verb. --sMkrXc3gAYLRVOjR Content-Type: text/plain; charset=windows-1251 Content-Disposition: attachment; filename="sysctl.5.xml" General kernel control OS name A long-winded description of what an Operating System is, and why it needs a name. The current securelevel value What do we need this for, how it operates, why it can only go up, never down. Virtual memory control The system load average How hard could it be to bring the system down? Swap status or something Do we want swap or not.. --sMkrXc3gAYLRVOjR Content-Type: text/plain; charset=windows-1251 Content-Disposition: attachment; filename="sysctl2mdoc.xsl" Content-Transfer-Encoding: quoted-printable .\" Copyright line 1 =2E\" Copyright line 2 =2E\" =2E\" This is an automatically generated file, do not edit and stuff =2E\" =2EDd Hmm where do we get this from? =2EDd January 23, 2001 =2EDt SYSCTL 5 =2EOs =2ESh NAME =2ENm sysctl .Pp =2ESh =20 .Bl -tag -width 6n .El .It Li --sMkrXc3gAYLRVOjR Content-Type: text/plain; charset=windows-1251 Content-Disposition: attachment; filename=Makefile XSLTPROC?= xsltproc XSLTPROCOPTS?= -nonet XSLSHEET= sysctl2mdoc.xsl SOURCES= sysctl.5.xml RESULT= ${SOURCES:S/.xml//} ${RESULT}: ${SOURCES} ${XSLSHEET} ${XSLTPROC} ${XSLTPROCOPTS} -o ${RESULT} ${XSLSHEET} ${SOURCES} --sMkrXc3gAYLRVOjR-- --EqVOK5mkaJAMmtSx Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.1 (FreeBSD) iD8DBQE+bcah7Ri2jRYZRVMRAv2AAJ9DRhPfZqgikhW51OQRSeQB6WMeqACcCnVf xV1k7X6BhEznuInEs3n/Pn4= =80y6 -----END PGP SIGNATURE----- --EqVOK5mkaJAMmtSx-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message