To anyone who's interested ...
TOPCAT's help system is now XML-based.
The source document is a single XML file (sun178.xml) which is
processed at build/install time to produce:
(1) a single-page HTML version
(2) a multi-file HTML version, looking rather like a
traditional HTX-type SUN
(3) a JavaHelp set of files (multiple HTML files, plus the other
two or three XML files that JavaHelp needs to keep track of stuff)
The STIL document SUN/252 is produced in a similar way, though it
doesn't need a JavaHelp set.
It would be nice to have a printable (ps or pdf, but probably in
practice latex) output version too, but I haven't written the
XSLT for this as yet. In the mean time it would be possible to
print out the single HTML file from mozilla or something.
This is all done using XSLT and java, so works under ant control - in
particular there's no LaTeX/latex2html/star2html business, neither
is there DSSSL or dependence on the Starlink SGML system (SSN/70).
The actual work is done using XSLT plus one new java class
uk.ac.starlink.util.MultiXML, which assists in turning a single XML
document into multiple documents, which can't be done within XSLT itself.
Where it makes sense to do so, I've used a DTD which resembles
that from the SGML package, but there are discrepancies becuase
of different requirements, and there are certainly large parts
of the SGML DTDs which my XSLT stylesheets would not cope well with.
I've done this because I was getting seriously fed up with writing
and keeping up to date a mess of raw HTML + XML files for TOPCAT's
help system. I didn't use the SGML set or LaTeX/star2html
because I wanted it to work within starjava without external
dependencies. An alternative way forward would have been to
write a set of downconverters in XSLT which match the existing
DSSSL ones in the SGML set. I've done it like I have partly as
a proof of concept and partly because I wanted something I could use
in short order. I don't rule out throwing this lot away and doing
it properly from scratch at some point.
The conversion machinery (mostly XSLT files) is currently in a
not-particularly-public part of the TOPCAT package (topcat/src/docs
if you want to know), i.e. it's not really set up for use by other
packages. This is largely because it's not very well documented
and it may undergo changes as I see things I want it to do that
it's not doing yet.
I mention this here just in case anyone else is planning to do something
similar; at such a time it would probably make sense to think about
where this is going. However, at the moment I'm not particularly
encouraging use of this, since as I say it's not much beyond test
stage.
Mark
--
Mark Taylor Starlink Programmer Physics, Bristol University, UK
[log in to unmask] +44-117-928-8776 http://www.star.bris.ac.uk/~mbt/
|