[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: DOCBOOK: Including OS Version information on DocBook elements
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC