OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[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.


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


    <screen osversionmin="RELENG_2_1_0_RELEASE"
    This example consists of text that only applies to FreeBSD 2.1 through
    all versions in the 2.2 branch.

Debian might use

    <note osversionequal="SLINK">
      <para>Information only for the SLINK release.</para>

[ 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

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.

    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