UPDATE: I now have a much faster and more memory efficient way of doing this. See DITA2HTML repo for a much simpler and more efficient way.
Although this proved the basic concept (you can convert DITA without DITA-OT and all that jazz), in retrospect looking over this old code it’s quite horrible. It’s WAY too complex. The idea of parsing ditamaps so that you only convert the necessary dita files for that build seemed sensible at the time, but it adds complexity. That whole business of recursively parsing ditamaps and pushing things to be processed later onto the stack was also unnecessarily complicated (and a somewhat daft way to do things).
In the simpler design I am planning, you can save on complexity by simply convert all DITA files. The PHP code (or whatever is used) is fed one file by a BASH shell script (basically something like find . -name "*.dita" | xargs — dita2html.sh) and it converts it. Job done. Because this is so fast it doesn’t matter if you convert files unnecessarily (err, note to self, use Make). There are some optimizations here too. The other script needed is a PHP script to process the Ditamap file. Again you do one at a time which is much simpler, and use a shell script to do them in bulk. The actual nature of this script depends on your target TOC control.
Everything below here should be considered junk!!
|
Note
|
See also docs/docs.adoc for more detailed information. |
|
Warning
|
This software is entirely experimental, with no warranties stated or implied - use at your own risk! |
DitaShark is a command-line PHP program that converts DITA XML source to HTML.
It does not use any of Java, XSLT, Ant, Maven, JDKs, JREs etc. and is small, fast and efficient, typically working with text files in 4K chunks.
This was designed to be a smaller, faster, more efficient alternative to the DITA Open Toolkit (DITA-OT), although as DitaShark requires no changes to the DITA source files, it works quite happily in conjunction with DITA-OT.
The other great advantage of DitaShark, besides efficiency, is that it generates HTML that is compatible with mobile devices. DITA-OT toolkit generates HTML that uses frames, and these documents do not display correctly on many mobile devices such as iPad and iPhone.
DitaShark processes DITA files by recursively processing a DitaMap. The recursion is carefully managed so as to keep stack usage reasonable.This has to be recursive as DitaMaps can reference DitaMaps and so on. DitaShark builds a list of all Dita files to be converted, and then converts them to (currently) HTML4 Strict. HTML5 was planned for the future.
A potentially faster option is rather than working through the tree of files referenced from the Ditamap to simply convert all files with the dita extension, working from a root directory. This is more efficient for root Ditamap builds.
No longer developed.
DitaShark was a proof-of-concept (POC) project to test the efficiency of rendering DITA XML source files directly into HTML, without using XSLT. The concept was successfully proved, but currently not all DITA tags are supported (just enough to support POC and create some simple documents). It would be straightforward, but quite time-consuming, to add support for all DITA elements, as there are several hundred of them!
You need PHP available on the command line. I have only tested with PHP version 5.5.20.
You also need to use a syntax highlighter if you want coloured codeblocks. I used Alex Gorbachev’s SyntaxHighlighter and was very pleased with it. There are several now widely available.
You need to install the SyntaxHighlighter project by Alex Gorbachev if you want to have syntax colouring in your code blocks. See the README in the highlighter directory for further information.
Copyright (c) 2013 - 2016 Tony Bedford. Free use of this software is granted under the terms of the MIT license.