Documentation file format

Christian Stimming christian at
Fri Dec 13 02:26:42 EST 2013

I know I'm jumping in rather late in this thread, but here's my take  
on the ever-long question of our documentation file formats:

I think the priority of the documentation file format should be:
- to generate HTML and PDF output from it
- and to make it easy for documentation writers to edit the text

As secondary goals, I think it is nice to be able to generate epub and  
mobi output and also yelp's output from this (or does yelp read  
docbook natively?!), but I think those are not as important.

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. For example, if libreoffice/openoffice would be  
able to use the docbook xml file, except for the fact that it's split  
into multiple files using xml entities, then we should just as well  
drop the split file approach and merge the full text into one single  
docbook xml document.

However, this wasn't the only problem with libreoffice, IIRC, but I'm  
not sure. If we just don't fine any up-to-date word processor that can  
work with the docbook xml, I would suggest to switch to a different  
file format instead, such as ODF or similar, and just continue working  
on the document with libreoffice et al.

If a wiki approach is possible without too many extra steps in a  
workflow, that's fine as well, but I'm afraid it adds a whole lot of  
extra problems into the process. For example, what would be the  
process to generate a new gnucash-docs release package so that gnucash  
can be installed with at least as much offline available documentation  
as we have today? If there are solutions for this, then fine, a wiki  
based solution might be a good way to continue. Otherwise I'd suggest  
to simply switch to a better file format.



More information about the gnucash-devel mailing list