Replacing Docbook

Geert Janssens geert.gnucash at kobaltwit.be
Sat Aug 29 10:52:48 EDT 2015


On Saturday 29 August 2015 06:38:53 John Ralls wrote:
> > On Aug 29, 2015, at 5:43 AM, Mike Evans <mikee at saxicola.co.uk>
> > wrote:
> > 
> > Another random thought then.
> > 
> > I use asciidoc for pretty much all the docs I write, not much
> > admittedly but it's easy to learn and can produce many output
> > formats.  I just used
> > https://github.com/oreillymedia/docbook2asciidoc to convert the
> > guide to asciidoc using:
> > 
> > $ java -jar /home/mikee/Projects/docbook2asciidoc/saxon9he.jar -s
> > gnucash-guide.xml -o gnucash-guide.asc
> > /home/mikee/Projects/docbook2asciidoc/d2a.xsl  chunk-output=true
> > 
> > This produces an asccidoc file for each chapter plus the master
> > page.  Converting this to html using
> > 
> > $ asciidoc  gnucash-guide.asc
> > 
> > produces the entire guide as html, of course many other output
> > formats are possible including docbook.  The only issue is that
> > *none* of the figures are included.  I'm not an expert on XML
> > parsing using .xsl stylesheets but I suspect this could be
> > easily(?) remedied by editing the d2a.xsl to correctly include the
> > figures, as I say I'm no expert here.  Some of the (inevitable)
> > minor formatting issues can be solved manually.
> > 
> > If solving the figures issue is possible then the documenters would
> > need to learn asciidoc markup.  This is a lot easier than docbook
> > though and since all the files are just plain ascii tracking
> > changes in GIT are straightforward.  The concept of separate files
> > for each chapter is also preserved.
> > 
> > As I say, just a thought.
> > 
> > Incidentally LibreOffice can also use multi-file documents/books,
> > but I agree that change tracking is a barrier.
> Mike,
> 
> Gee, deja-vu:
> http://lists.gnucash.org/pipermail/gnucash-devel/2013-December/036626
> .html and following.
> 
Informative thread... :)

It seems we're still rather stuck at the same spot.

The only new element so far is the detail that started this whole discussion again: doxigen 
can now parse markdown.

So yesterday I also did some first research on markdown as possible alternative.

Pros:
- relatively simple language so fairly easy to learn
- It's widely used so it seems to attract several developers to write tools for it. While I haven't 
immediately found true wysiwyg editors there are several editors available (both online and 
offline) that show live previews for all OS's we currently support.
- Convertible into most formats we care about, including docbook (via doxigen).

Cons:
- still a language to learn
- no true wysiwyg editors (at least I haven't found one yet)

What I haven't investigated yet is how easy/hard it would be to convert the existing 
documentation, nor how it deals with images and links when used in offline mode.

Geert


More information about the gnucash-devel mailing list