EDE Documentation System

...or: how writing docs can be fun (hopefully).

I'm aware that documentation in EDE 1.x sucked a lot. We had a few html pages with less content than official docs have (yes, I'm also aware how that web documentation sucks too). It contained something like: "Get EDE from", "Very quick install", "Join EDE...". Nothing fancy. But not good either.

Those html pages was quickly assembled with Mozilla Composer and Composer is not known for generating a nice html pages editable with ordinary text editor. At the end, no one had enough inspiration to update it, yielding a situation where some very cool things remained unknown.

You know, developers hate to write docs. It is true. Is it due laziness or because after 5-6 hours of coding you don't want to touch editor any more or, maybe, documentation tools are simply bad, I'm not sure. There could be an influence of each of them.

But, on other hand, zero documentation is not good either (or you will not be able to say: "RTFM!").

Today, when you say "documentation", you will hear instant reply: "DocBook". It is standard, well defined system with a lot of tools to convert it to almost any known documentation format. And is also a good system to inspire you for no writing it at all.

Without a good howto you will not be able to write anything and even after that, keeping reference book under your pillow is a good way to save you from errors and... to speed up writing. You don't want to spend the whole day on only one page, aren't you?

So to save my typing hours on something better and to have a good excuse to reject any program without documentation (or patches without docs updates) :), the only solution was some generator with sane markup. Or markup that most people already knows. And it should produce at least docbook files or something like that, so docbook can be generated.

A good candidate for this was Doxygen. Markup syntax is very easy to pick up and almost all distros already comes with it. Besides html output, doxygen can produce xml output too; theoretically, we could use some xslt processor and produce docbook files from these xml files (that is why xslt exists).

Since I'm not good with xslt (and don't plan to be), I tried to find something already done, or at least "almost done". Unfortunately there is no such a script (or xslt code; call it whatever), or I wasn't able to find it. Something very similar I found as part of Boost libraries and it was generating some intermediate format (named as boostbook or like that) which is then converted to docbook.

How is done, it still remains the mystery to me: they complicates everything, even a build system!

I tried a few more tools (really can't remember now), until I found it: AsciiDoc. It is a python script (a single file!) without external dependencies and does not mandate installation to be used (which is important too, so we can distribute asciidoc without thinking if user has it installed or not, which version and so on).

The first thing that appealed me is simple markup syntax it uses; almost like you are writing an ordinary text file (well, you are writing a text file ;)).

Here is the sample:

Some title
=======
Bla bla bla

Subtitle
--------
Bla bla bla

and so on. The best example is asciidoc user guide generated from this file.

Next is a number of outputs it supports: besides docbook (out of the box, man!) it can produce a html, xhtml and man files; plus everything else that docbook can spit out (for example to create pdf output, it will create docbook files first then will convert them to pdf via docbook toolchain). Almost perfect tool :)

The only thing left to be done was integration with our build system. I decided for straight html without docbook as intermediate format: asciidoc creates very nice html pages and (most important) docbook toolchain is often not installed (at least I don't install it ;)).

Due jam's flexibility, asciidoc jumped in fine; the only thing you should put in your Jamfile is this rule:

EdeManual foo.txt ;

That is it. When jam or jam doc is run in console, jam will, via asciidoc, convert given files, move them in the special directory assembling EDE Manual and installs it in appropriate directory, when jam install is given. Couldn't it be more simple ;)?

On other hand, documentation quality is story for itself...