Documentation file format

[Mike Evans]

On Fri, 13 Dec 2013 07:03:26 -0800
John Ralls <jralls at ceridwen.us> wrote:

> 
> 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?

Advantages: The WIKI way seems prone to the problems already
discussed.  Why Acsiidoc?  I can't give specific technical advantages
over markdown but there are easy-to-use tools to produce html, docbook,
e-book files etc.  I've not used markdown enough to make a meaningful comparison.

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.


Mike E

http://www.methods.co.nz/asciidoc/index.html

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