After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 722016 - We should change the Documentation file format
We should change the Documentation file format
Status: RESOLVED OBSOLETE
Product: GnuCash
Classification: Other
Component: Documentation
git-master
Other All
: Normal enhancement
: ---
Assigned To: gnucash-documentation-maint
gnucash-documentation-maint
Depends on:
Blocks:
 
 
Reported: 2014-01-12 00:31 UTC by Frank H. Ellenberger
Modified: 2018-06-29 23:24 UTC
See Also:
GNOME target: ---
GNOME version: ---



Description Frank H. Ellenberger 2014-01-12 00:31:33 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?
...
Comment 1 Geert Janssens 2014-02-17 11:22:05 UTC
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/
Comment 2 Chris Good 2015-09-13 12:16:10 UTC
Serna no longer seems to be available unless you build it yourself from source (github) which makes it too hard for non technical people.
Comment 3 Frank H. Ellenberger 2016-08-16 12:25:07 UTC
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
Comment 4 John Ralls 2018-06-29 23:24:36 UTC
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.