Documentation file format

Frank H. Ellenberger frank.h.ellenberger at gmail.com
Sun Dec 15 14:43:30 EST 2013


Hi,

I am still researching a few aspects.

Am 13.12.2013 08:26, schrieb Christian Stimming:
> 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.

I really like the feature of context sensitive help, although we
currently make much use of it.

Does or could this also work on other OSes than Linux with Yelp?

Gnome seems to switch
https://developer.gnome.org/platform-overview/stable/dev-help.html.de
"Use yelp-tools to build Mallard help which can be discrete or
integrated with other application help."

from docbook to mallard
http://www.projectmallard.org/

But according https://wiki.gnome.org/DocumentationProject/Contributing
that is focussing "topic based help - small chunks of help that focus on
one thing..." - Our Tutorial & Guide is different.

> 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.

I assume there are today ways, to do the modular docbook smarter than at
the time of the first writing. E.g.
http://www.sagehill.net/docbookxsl/ModularDoc.html
mentions XInclude and olink and has for each a chapter.

In some older documents I saw a variable sgml-parent-document:

<!--
Local Variables:
mode: sgml
sgml-default-dtd-file: "/local/share/sgml/ced/docbook-3.1-book.ced"
sgml-declaration:      "/local/share/sgml/docbook3.1/docbook.dcl"
sgml-parent-document: ("../jade/database_admin.sgml" "chapter" "sect1")
End:
-->


> 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.

IIRC ODF is gzipped XML - zipped files are bad for version control
systems (VCS).

> 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.

While wiki is easy to use, but there are too many dialects: Mediawiki,
tracwiki, TikiWiki, MoinWiki...
E.g. we never finished the move from linuxwiki.de to wiki.gnucash.org.
Only a few pages were ported.

> Regards,
> 
> Christian



More information about the gnucash-devel mailing list