(Formerly “About TKB’s Home Page”.)
I used to build this collection of pages largely from a single SGML/XML document (expressed as several separate files) using Jade and Norm Walsh‘s Website DTD and his Website Stylesheet, a customization of the DSSSL DocBook Stylesheet for HTML. There are a few links to legacy HTML pages.
I liked building these pages from XML using DSSSL for a number of reasons:
I used DSSSL long after the DSSSL stylesheets for the Website DTDs were no longer maintained because the build process was considerably simpler than that of the XML/XSLT replacement. Unfortunately, the setup I was using stopped working properly when I moved from FreeBSD 4.11 to FreeBSD 6.2, and at the time I didn’t have the patience to figure out what had gone wrong with the variety of FreeBSD pacakges I was using to build the site.
Reluctantly I turned to the currently supported Website DTD and XSL stylesheets, along with the DocBook DTD and XSL stylesheets they build upon, along with an XSL processor, xsltproc. There had been a number of changes to the DTD, which required many changes to my website xml files. Most annoying was that at some point during the development of the XSL stylesheets for the Website DTD the organization as a single XML document had been abandoned, and replaced by a multiple document model that required processing each XML file separately and maintaining a separate multiple-document database of linking information. This meant that instead of including my entities once in the original master file I had to include them in each and every xml file. This also meant that all the internal links I had used previously had to be replaced with interdocument links using olink . Unfortunately, I found that FreeBSD’s ports of the Website DTD and XSL stylesheets and the DocBook XSL Stylesheets were each a revision behind, which caused linking between documents to not work. After downloading and installing current copies of these I finally got things to work.
Unfortunately, I found that, at least using xsltproc, the new process using XSL was much slower and more resource intensive: the old DSSSL-based process took about 2.5 minutes and never exceed 40 megabytes of resident memory, while the new XSL-based process took 20 minutes (on a faster machine) and uses 70 or more megabytes of resident memory for each file, and during processing the interdocument link database reaches over 300 megabytes of resident storage. Admittedly, some of this was due to the change in the Website DTD from the one document model to the multiple document model, but still it seems excessive.
I’ve since switched the source for my website over to ReStructuredText (ReST). It’s much simpler than DocBook. I miss the more structured DocBook approach, and the checking of cross-references, but ReST has enough structure to be useful, without having an complicated syntax, and the tools used to process it are considerably simpler, faster, and more approachable. I just wish ReST had nested interpreted text roles and easier subscripts and superscripts. I actually use Sphinx to build it, as you can see at the bottom of each page. I’m very happy with how simple it is to maintain now.