On Dec 14, 2013, at 1:32 PM, Christian Stimming <christ...@cstimming.de> wrote:
> 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 >> one. > > 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. > Well, the friendliest format for documenters is Microsoft Word, since pretty much any word processor will read it. We’ll get a lot of noise from the Open Source fanatics though. Shouldn’t be too hard to make a toolchain to convert it into whatever distribution formats we want. Complexity there isn’t an issue because devs handle releases. Regards, John Ralls _______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
