GNOME Bugzilla – Bug 722016
We should change the Documentation file format
Last modified: 2018-06-29 23:24:36 UTC
See http://www.mail-archive.com/gnucash-devel@gnucash.org/msg33704.html ff. for the beginning. Eventually http://www.sagehill.net/docbookxsl/Olinking.html could be a solution. It should allow to add our global/macro entities to every chapter and xml processing programs should no longer be confused. Questions: do we get proper index pages? ...
Some snippets from the long mailing list thread to summarize the situation: Christian Stimming wrote: <quote> 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. <end quote> Current issue is non-technical potential contributors are scared away by the format our documentation is currently maintained in (along with the challenging process of version management that surrounds it). Several suggestions were made as alternatives: * wiki based - this raised concerns about concurrent editing conflicts and how to go from a wiki to a document that can be added to the release. * asciidoc - was not considered easier to learn for non-technical people * traditional office document formats (ms-office, libreoffice,...) - easy to use for non-technical people - concern was raised about manageability via software change management - and I'll directly add here that to get this right, styles should be used rather strictly. From experience I know this can easily be a roadblock as well for non-technical users * stick to docbook xml but find a decent wysiwyg editor - libreoffice can (at least more or less) import docbook xml, but there are issues regarding export and others - there are commercial docbook editors which are very expensive - of the few free ones that were listed serna-free may be viable http://sourceforge.net/projects/sernafree.mirror/
Serna no longer seems to be available unless you build it yourself from source (github) which makes it too hard for non technical people.
Some abstract of this thread http://lists.gnucash.org/pipermail/gnucash-devel/2015-September/038984.html * Libre-/Open-Office does not behave well with git. * Markdown doesn't support tables, but Doxygen’s Markdown is extended to create tables
GnuCash bug tracking has moved to a new Bugzilla host. The new URL for this bug is https://bugs.gnucash.org/show_bug.cgi?id=722016. Please continue processing the bug there and please update any external references or bookmarks.