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. > > 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. _______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
