Documentation file format

[Mike Evans]

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.
> 
> Regards,
> 
> Christian
> 
> _______________________________________________

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

Mike E

-- 
Please remember to CC this list on all your replies.
You can do this by using Reply-To-List or Reply-All.