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