Documentation file format

John Ralls jralls at
Sat Dec 14 16:58:43 EST 2013

On Dec 14, 2013, at 1:32 PM, Christian Stimming <christian at> wrote:

> Am Freitag, 13. Dezember 2013, 15:47:18 schrieb Mike Evans:
>>>>> Given these priorities, I think both our current documentation file
>>>>> format and also a potential wiki workflow might not be the best
>>>>> solution. Instead of the current file format (docbook xml, split into
>>>>> several files using xml entities) we should very well think to switch
>>>>> to some other solution that makes the text much more accessible for
>>>>> documentation writers. 
>>>> Since no-one has mentioned it yet, what about asciidoc?  It's much
>>>> simpler that the xml we have now, is very easy to learn, it is plain
>>>> text, it handles multi-part books, and AFAIK the current docbook can be
>>>> converted to asciidoc without *too* much effort.
> I consider asciidoc also not very accessible for non-programmer writers. IMHO 
> a new file format for our documentation should be much easier accessible for 
> documentation writers. Those people are by definition almost surely no 
> programmers. I don't think the mindset of asciidoc meets their approach to 
> writing documentation. So: no, I don't think asciidoc is an improvement of the 
> current docbook format. Sorry.
>> Conversion: I found a conversion tool that I *thought* might do the job,
>> SaxonHE9, a java tool (ugh), but it doesn't do it very well.  I tried a
>> couple of pages.  Some post conversion cleanup was needed to remove
>> artifacts but, the major issue was that image placeholders went missing. So
>> not good enough to make it an easy convert.  More research required on that
>> one.
> A proper conversion needs to be found for sure, but on the other hand, some 
> manual work for a switch-over is fine as well. But the main reason for a new 
> file format is what I've discussed before.

Well, the friendliest format for documenters is Microsoft Word, since pretty much any word processor will read it. We’ll get a lot of noise from the Open Source fanatics though.  Shouldn’t be too hard to make a toolchain to convert it into whatever distribution formats we want. Complexity there isn’t an issue because devs handle releases.

John Ralls

More information about the gnucash-devel mailing list