Date: Tue, 11 Mar 2003 13:21:06 +0200 From: Peter Pentchev <roam@ringlet.net> To: David Schultz <das@FreeBSD.org> Cc: Sean Chittenden <seanc@FreeBSD.org>, "M. Warner Losh" <imp@bsdimp.com>, doc@FreeBSD.org, trhodes@FreeBSD.org, dwmalone@FreeBSD.org Subject: Re: your mail Message-ID: <20030311112105.GO578@straylight.oblivion.bg> In-Reply-To: <20030311045239.GA4369@HAL9000.homeunix.com> References: <20030310195323.GA2812@HAL9000.homeunix.com> <20030310204035.GU79234@perrin.int.nxad.com> <20030311045239.GA4369@HAL9000.homeunix.com>
next in thread | previous in thread | raw e-mail | index | archive | help
--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 <seanc@FreeBSD.org>: > > > 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" <?xml version="1.0" encoding="utf-8"?> <sysctl-list xmlns="http://www.FreeBSD.org/schemas/sysctl/1">; <category name="kern"> <description>General kernel control</description> <item name="ostype" readonly="yes"> <comment>OS name</comment> <description> A long-winded description of what an Operating System is, and why it needs a name. </description> </item> <item name="securelevel"> <comment>The current securelevel value</comment> <description>What do we need this for, how it operates, why it can only go up, never down.</description> </item> </category> <category name="vm"> <description>Virtual memory control</description> <item name="loadavg" readonly="yes"> <comment>The system load average</comment> <description>How hard could it be to bring the system down?</description> </item> <item name="swap_enabled"> <comment>Swap status or something</comment> <description>Do we want swap or not..</description> </item> </category> </sysctl-list> --sMkrXc3gAYLRVOjR Content-Type: text/plain; charset=windows-1251 Content-Disposition: attachment; filename="sysctl2mdoc.xsl" Content-Transfer-Encoding: quoted-printable <?xml version=3D"1.0" encoding=3D"utf-8"?> <xsl:stylesheet xmlns:xsl=3D"http://www.w3.org/1999/XSL/Transform" version= =3D"1.0" xmlns:sysctl=3D"http://www.FreeBSD.org/schemas/sysctl/1">; <xsl:output method=3D"text"/> <xsl:template match=3D"/sysctl:sysctl-list"> <xsl:text>.\" 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</xsl:text> <xsl:apply-templates match=3D"sysctl:category" /> </xsl:template> <xsl:template match=3D"sysctl:category"> <xsl:text>.Pp =2ESh </xsl:text> <xsl:value-of select=3D"concat(@name, ' - ')" /> <xsl:value-of select=3D"sysctl:description" /> <xsl:text> </xsl:text> =20 <xsl:text>.Bl -tag -width 6n </xsl:text> <xsl:apply-templates select=3D"sysctl:item" /> <xsl:text>.El </xsl:text> </xsl:template> <xsl:template match=3D"sysctl:item"> <xsl:text>.It Li </xsl:text> <xsl:value-of select=3D"@name" /> <xsl:text> </xsl:text> <xsl:value-of select=3D"sysctl:description" /> <xsl:text> </xsl:text> </xsl:template> </xsl:stylesheet> --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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20030311112105.GO578>