Replacing Docbook

Mike Evans mikee at saxicola.co.uk
Sat Aug 29 08:43:27 EDT 2015


On Fri, 28 Aug 2015 21:38:18 +0200
Geert Janssens <geert.gnucash at kobaltwit.be> wrote:
<<SNIP>>
> 
> I did the same exercise just now. Note that I used the latest svn revision of docbook2odf (r253) 
> which is slightly more recent than the ones found on the download page.
> 
> The screenshots are all there on my system, although many of them are improperly sized. 
> That's probably because we have been sloppy at that in our docbook version as well and just 
> relied on the images being viewed at 100% size. That's probably not ok in odt which is geared 
> towards printing.
> 
> During the conversion there was an error for 4 pnm image files not being found. I suspect 
> these are the images used to highlight warnings and tips and such. I didn't see those in the odt 
> file.
> 
> The image we had in multiple resolutions (the accounting equation) is added 3 times, probably 
> because we had specified it 3 times in our source.
> 
> The table of contents is missing as is the list of figures and tables.
> 
> It's getting worse: all cross-references are gone.
> 
> And worse: I did one single edit - remove the vertical docbook2odf banner. I did so by removing 
> the page header in the page settings.
> This resulted in a git diff of a whopping +1351/-1368 line changes. Most of the changes are 
> arbitrary like styles changing names, changing regional settings, adding soft-page-breaks,...
> 
> Of course this can all be easily committed into git. However it will be rather difficult to follow 
> changes made if the patches are so full of gratuitous changes.
> 
> If we can't get libreoffice to make less noisy diffs, it's very unlikely it will be in improvement 
> over the current situation.
> 
> Regards,
> 
> Geert

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 E


More information about the gnucash-devel mailing list