E.1.3 DSSSL

The SGML processing part of this package is implemented in DSSSL, which is a standard [iso10179] for device independent formatting of SGML documents. DSSSL includes both a style language and a (DTD to DTD) transformation language.

I have used James Clark's Jade implementation of DSSSL. This implements the style language, but not the transformation language.[Note 13] Jade has back-ends which generate RTF, MIF and rather odd TeX requiring a specialised TeX format. Clark added an SGML-transformation back-end, as a Jade extension of the standard, which uses non-standard flow-object constructors to specify SGML elements, entities and the like. In addition, I added a back-end which generates LaTeX.

It follows that the stylesheets which implement this Starlink package are not standards-conforming, and are specific to Jade. This needs a little justification.

• There are not too many alternative ways of producing HTML. Perl is a contender, since the SGMLSpm package (see CPAN) can parse the output of nsgmls. This is perfectly legitimate, but I know from experience that it can become rather messy.[Note 14]
• DSSSL has very good access to the SGML grove, and processes the document in a generally `SGML-ish' way. This feels like keeping things in the family, as it were, even if the non-standard back-ends have something of the wicked stepmother about them.
• One alternative is through XML and XSLT, but this would require doing the work to transform the document from SGML to XML (which would lose the subdocument processing features), and using XSLT which, from what I've seen of it, looks like hell on earth.

This does not in any way affect the standards conformance of the rest of the SGML set - the various DTDs and the HyTime support - since the processing of documents is by design completely independent of the standards which define their markup.

See Appendix E.6 for online resources.

Appendix E.4 includes documentation for some of the important DSSSL stylesheets.

Notes on the code:

• In almost all cases, the code for the HTML stylesheet was developed first, then adapted for the LaTeX stylesheet. This makes sense in general, as the HTML stylesheet has to do much more elaborate formatting and rearrangement, whereas LaTeX can do much of the simple information-shuffling itself. It does, however, mean that some fragments of code are duplicated in the two stylesheets, even although the slcommon.dsl stylesheet is supposed to cover all of that - when it happens, this is typically an error, rather than some great subtlety.
• The code started off as adaptations to Norman Walsh's DocBook stylesheets. In some modules - primarily the slnavig.dsl code which was the section I began development with - there are still relics of this here and there. There isn't a lint for Jade, so it's not trivial to find and remove these.
• It's unattractive that the print-based stylesheet is so specific to LaTeX, and goes against the format-independent goals of DSSSL. If it becomes necessary to produce another output format at the same level of abstraction as LaTeX - 'roff would be an example, though that seems unlikely - the way to proceed would be to adapt the LaTeX stylesheet to produce output marked in some DTD which matches the abstraction level of LaTeX - that is, describing sections and paragraphs and so on, rather than the placement on the page which is characteristic of the standard DSSSL FOs - and then translate that to LaTeX and whatever. The latter translation would be easy, since there would likely be no information shuffling at all, but a translation task little more demanding than search and replace.

E.1.3.1 Jade and OpenJade

James Clark's Jade distribution, at <http://www.jclark.com/jade/>, has been frozen at Jade 1.2.1. Jade development has now forked, with `OpenJade' being developed by the community. This is based at <http://jade-cvs.avionitek.com/>. I hope to move to this distribution when time is available.

E.1.3.2 Customising the DSSSL source code.

The DSSSL source code which produces the HTML and LaTeX output has been parameterised to a limited extent. As described in Appendix E.4, it can therefore be customised either on the Jade command line, or by providing Jade with an alternative DSSSL parameters file.

Jade has a -V option which takes a DSSSL variable name as argument; this variable is then given the value #t (true), overriding any other definition in a stylesheet. Several of the stylesheets' parameters are designed to be settable this way. You can either give this option explicitly on a Jade command line, or pass it to Jade via the sgml2docs command line (see Section 6.2):

sgml2docs '--jadeflags=-Vshow-element-ids' ...

If this type of customising is insufficient, then you may take a copy of the appropriate parameters file in $STARLINK_SGML_DIR/dsssl/sl/html/slparams.dsl (or the corresponding .../latex file), call it, say my-params.dsl, and change what parameters you like. The stylesheets refer to the parameters files by the public identifiers PUBLIC "-//Starlink//TEXT DSSSL Common Parameterisation//EN", PUBLIC "-//Starlink//TEXT DSSSL HTML Parameterisation//EN" and PUBLIC "-//Starlink//TEXT DSSSL LaTeX Parameterisation//EN", and these are mapped to the real files by the catalogue file in $STARLINK_SGML_DIR/dtd/CATALOG.starlink. To direct the system to your own parameter file instead, create a catalogue file of your own (conventionally given the name CATALOG), and include the appropriate line like

PUBLIC "-//Starlink//TEXT DSSSL HTML Parameterisation//EN" my-params.dsl

SGML_CATALOG_FILES=./CATALOG:$SGML_CATALOG_FILES