From owner-freebsd-doc Tue Dec 21 4:24:57 1999 Delivered-To: freebsd-doc@freebsd.org Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66]) by hub.freebsd.org (Postfix) with ESMTP id 956F81548A for <doc@freebsd.org>; Tue, 21 Dec 1999 04:24:46 -0800 (PST) (envelope-from nik@nothing-going-on.demon.co.uk) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.9.3/8.9.3) id MAA69106; Tue, 21 Dec 1999 12:22:24 GMT (envelope-from nik) Date: Tue, 21 Dec 1999 12:22:24 +0000 From: Nik Clayton <nik@freebsd.org> To: bortzmeyer@debian.org, doc@freebsd.org, docbook@lists.oasis-open.org, sgml-tools@via.ecp.fr, dssslist@mulberrytech.com, oswg-discuss@oswg.org Subject: Including OS Version information on DocBook elements Message-ID: <19991221122224.B75275@catkin.nothing-going-on.org> Reply-To: doc@freebsd.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary=wRRV7LY7NUeQGEoC X-Mailer: Mutt 0.95.4i Organization: FreeBSD Project <URL:http://www.freebsd.org/> Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org --wRRV7LY7NUeQGEoC Content-Type: text/plain; charset=us-ascii Hi folks, There's quite a wide distribution on this message. Sorry about that, but quite a few people have expressed an interest in this sort of thing, so I'm trying to catch all of them. My apologies to those of you who receive this message multiple times. I've set followups to the FreeBSD Doc. Proj. mailing list, doc@freebsd.org. You don't need to be a subscriber to post there, and most people are in the habit of doing 'Reply to all', so you should stay in the discussion. Feel free to override this if you think your comment is only applicable to a particular list. In the FreeBSD and Linux documentation communities the problem of how to represent information that is only appropriate for one release of the code, or a limited range of releases, comes up occasionally. The common link is that we're all using DocBook (or modifications thereof) as our base DTD. Rather than reinvent the wheel for all our documentation projects, we wanted to come up with a mechanism that we could all use, to promote document interchange. The last time we discussed this, the general consensus was to add three attributes to every element in DocBook in our customisation layers. osversionmin osversionmax osversionequal The allowed content of these attributes was up to the individual projects concerned. For example, FreeBSD will probably use the CVS tags we lay down to denote individual releases, so sample DocBook text might look like <note osversionequal="RELENG_3_0_0_RELEASE"> <para>This note contains text that is only appropriate for FreeBSD 3.0.</para> </note> or <screen osversionmin="RELENG_2_1_0_RELEASE" osversionmax="RELENG_2_2"> This example consists of text that only applies to FreeBSD 2.1 through all versions in the 2.2 branch. </screen> Debian might use <note osversionequal="SLINK"> <para>Information only for the SLINK release.</para> </note> [ Apologies if that's a bad example, I'm not too cognescent of Debian release naming schemes ] We would then have a pre-processor that, given the name of a specific release, would run through the documentation, stripping out all the elements whose osversion* attributes didn't match that release, before handing the SGML over to a formatter like Jade. Attached is my first cut at implementing this preprocessor, for further comment. The processor is written in Perl, but should be fairly easy to understand. In addition, the processor uses some *SGML* modules from CPAN, not XML modules. You will need to download and install SGMLSpm-1.03ii.tar.gz from http://www.cpan.org/ first. You will also need DocBook 3.1 installed. This is probably not the best approach. My DSSSL isn't up to it, but I imagine that a DSSSL (or XSL) script to do the same thing would be better, in that it would reduce the number of tools required in order to build the docs. I would be very interested in someone reimplementing the logic of the code in DSSSL. Included is a customised DocBook DTD to add the new attributes, a sample book.sgml, the script, and a Makefile. Running the Makefile should generate new-book.sgml, with certain elements from book.sgml removed. Alter the Makefile to adjust the idea of which release you're building. Customising the script is trivial. For example, Debian users can 1. Duplicate create_freebsd_tags() as create_debian_tags(). 2. Replace the *ordered* list of FreeBSD tags in the new create_debian_tags() with an equivalent list of *ordered* Debian release tags (or release names, or whatever). 3. Alter book.sgml as necessary. 4. Alter the Makefile, replace '-o freebsd' with '-o debian', and change the -v value to reflect a Debian release name or tag. 5. make There are probably bugs. I haven't tested this preprocessor on a wide range of documents yet. Comments welcome. N -- If you want to imagine the future, imagine a tennis shoe stamping on a penguin's face forever. --- with apologies to George Orwell --wRRV7LY7NUeQGEoC Content-Type: application/x-tar-gz Content-Disposition: attachment; filename="osversion.tar.gz" Content-Transfer-Encoding: base64 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 --wRRV7LY7NUeQGEoC-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message