Documentation file format
christian at cstimming.de
Sat Dec 14 16:32:52 EST 2013
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
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.
More information about the gnucash-devel