On Dec 13, 2013, at 2:41 AM, Mike Evans <mi...@saxicola.idps.co.uk> wrote:
> On Fri, 13 Dec 2013 08:26:42 +0100 > Christian Stimming <christ...@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 _______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
