Documentation file format

[John Ralls]

On Dec 13, 2013, at 2:41 AM, Mike Evans <mikee at saxicola.idps.co.uk> wrote:

> On Fri, 13 Dec 2013 08:26:42 +0100
> Christian Stimming <christian at cstimming.de> wrote:
> 
>> 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.
>> 
> 
> 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.
> 
> It's just a thought because I use it for pretty much all the documentation I write.  It's not WYSIWYG but it's a lot better than directly editing docbook.xml.  I guess LibreOffice can be used as long as it doesn't introduce artifacts into the plain text, although a plain text editor would be better, vi|emacs|geany perhaps.
> 
> Anyway, my 2p|2c

Looks like it would work. What do you see as the advantages over better-known markups like markdown and wiki? How would we get the existing DocBook documents into ascitext format?

Regards,
John Ralls