Documentation file format
mikee at saxicola.idps.co.uk
Fri Dec 13 05:41:39 EST 2013
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
Please remember to CC this list on all your replies.
You can do this by using Reply-To-List or Reply-All.
More information about the gnucash-devel