Lately I was in need of a good documentation solution. Not just plain simple API documentation but more or less a tool which helps me to author technical manuals. There are a few approaches: the traditional solution with LaTeX and a number of converters (HTML, PDF, etc.), the more modern approach is DocBook which focuses on documentation not on typography and formatting as LaTeX does. Dita looked really promising too but the state of the toolchain explains fairly well why this is no option at all. One could say that there is just no state. The last option when nothing else fits is using a random Wiki technology or a simple text formatting tool like Textile or Markdown. I wanted to avoid that as I like to have a documentation toolkit with specific documentation semantics, not just a text formatter.
Back to DocBook: DocBook is first of all a huge grammar which scared me. The good thing is however, that most of the time you just need a rudimentary subset of it.
Until version 5.0 only DTDs were officially supported. I had have a hard time struggeling with DTDs in the past so I really wanted to avoid such trouble again. Additionally DTDs are painful to extend so having basic functionality like the XInclude extension is no fun.
Using 5.0 is also really brave from a toolchain perspective: xmllint from libxml2 insists on having a DTD even though modern format description grammars like Relax NG or XML Schema do not require them. I really like xmllint for – nobody would have guessed that – linting XML trees and resolving XML includes but it striked when not having a DTD. Finally the Sun MSV looked promising enough and worked out well, except that it is not willing to return with an exit code > 0 on failure. Also MSV is not capable of xincludes so I’m now having a three-step conversion of my DocBook 5 files: first of all sticking together the files via xincludes with xmllint (no validation, so no errors occur). Than validating the DocBook against a Relax NG scheme which is capable of Xincludes and finally running an XSLT transformation with good old xsltproc. PHPs DOMDocument theoretically provides relaxNGValidate() which could solve the problem as well but sadly there is no row/column information provided where the validation actually failed. Just knowing there is an error but not knowing where is somewhat useless for a validation tool.
After having solved the toolchain problem with the Sun Java Tool DocBook 5.0 was the way to go. No DTDs, specific semantics for technical documentation, even specific semantics for object documentation (like the ooclass- and ooexception-element).
While digging into DocBook 5.0 I found out that this version makes DocBook itself more XMLish, which is nice. A number of XML standards are now supported as is: the old “id” attribute for naming element references is now an xml:id-attribute from the XLink, there are default schemas for XInclude and MathML is incorporated. So far I’m happy with that.
Filed under DocBook, Documentation, LaTeX, OOP, PHP & 14 comments & no trackbacks
Trackback specific URI for this entry
Toby supposes:
published on January 9th 2008, 10:58:47 amHi!
Did you consider DocUtils and its fantastic "RST (ReStructured Text) format":http://docutils.sourceforge.net/rst.html?
We use it or every kind of documentation in eZ Components. It’s extremly comfortable to write and read and can be converted to any imaginable format.
Regards,
Toby
Reply
Lars Strojny answers:
published on January 9th 2008, 11:33:44 amNo, I forgot about that. Don’t know why I did not check how ezComponents does that. My concern with reStructured text and similiar text formatting tools are the job of validating/verifying it. XML is pretty straightforward: element missing, unknown element, compilation fails. reStructured text and the like use soft conventions like indenting for quotes, linebreaks for paragraphs etc. which are much harder to describe programatically. But I never used docutils so maybe my assumptions are baseless here. Nevertheless, I have now decided which format to use so I’m just to lazy to switch. But thank you very much for the tip, I fear there will be another documentation project somewhere in the future :-)
Reply
Rob Richards supposes:
published on January 9th 2008, 12:46:43 pmFor capturing detailed errors when working with XML in PHP, you should be using the libxml error handler: libxml_use_internal_errors(true)
If your operation fails, you can then go fetch the errors and iterate through them.
Although for relaxNG, the column information is not included (always 0), you get the line number, severity, code (which if you really need can be looked up within libxml2), as well as detailed message.
Reply
Jacob Santos responses:
published on January 9th 2008, 02:45:24 pmI just use PHP XSLT extension along with the DocBook XHTML XSL stylesheets. Looks terrible, but it works.
I haven’t had a problem with the failing syntax because the docbook isn’t that difficult. However, now that you mentioned it, I probably would need something that would tell me where I went wrong. I think there are tools to validate DocBook syntax against the Scheme.
Reply
Hannes Magnusson says:
published on January 9th 2008, 08:33:13 pmxmllint —xinclude —noout —relaxng docbook.rng db.xml?
Reply
Lars Strojny returns:
published on January 10th 2008, 10:21:31 amThat’s exactly what I did. But without a DTD in the docblock it prefers to throw errors.
Reply
Edward Z, Yang states:
published on January 9th 2008, 09:10:31 pmYou may be interested in checking out PHP.net’s new documentation system PhD, which is an extremely fast docbook renderer.
Reply
Lars Strojny reckons:
published on January 10th 2008, 10:26:32 amHow good is DocBook 5.0 supported there?
Reply
Edward Z. Yang reckons:
published on January 10th 2008, 07:13:01 pmVery well; we just finished upgrading our docs to Docbook 5.
However, I should note that PhD is a very "in-house" tool, so it only implements a subset of Docbook that PHP.net uses regularly. It is, however, very easy to extend and add support for other elements.
Reply
Lars Strojny states:
published on January 11th 2008, 01:24:37 pmThanks for addressing my questions. Are there any documentation bits about the documentation system? Sounds meta, but seems important.
Reply
Edward Z. Yang returns:
published on January 12th 2008, 01:35:07 amSure, just check out the CVS tree for PhD: http://cvs.php.net/viewvc.cgi/phd/
No one’s ever tried using it on anything besides the PHP documentation, but it should work.
Reply
Michael Priestley answers:
published on January 10th 2008, 04:35:03 amCan you expand a bit on the comment that there’s no toolchain for DITA? I’m assuming this means the DITA Open Toolkit is not doing what you need – was there also an issue on the editor front? I know there are lots of people using DITA productively, but there is no one-size-fits-all solution, just want to understand the gaps you encountered.
Reply
Lars Strojny responses:
published on January 10th 2008, 10:33:19 amI really like the DITA standard. From my point of view it is great improvement over DocBook, syntax- and semantics wise. However I was just not able to strip down the huge standard build process DITA offers with the toolchain distribution to a solution which fits my need. So maybe it is not the state of the toolchain but my state of mind. Nevertheless, as this is my blog, it is of course the toolchain. :-)
I guess the adoption rate would increase if the DITA project would provide a few case studies with example build- and documentation files. Complete books, smaller portions of documentation, etc. pp.
Reply
Michael Priestley reckons:
published on January 12th 2008, 08:02:07 pmThere’s definitely room for making the processing more consumable – right now it’s modular and flexible but not exactly intuitive. There are examples in the toolkit itself, including the source for the toolkit user guide and smaller demo samples for particular features (like map-based linking), but it sounds like there needs to be a clearer path from download/install to create first project/customize build process.
Reply