Replacing Docbook

[Mike Evans]

On Sat, 29 Aug 2015 16:52:48 +0200
Geert Janssens <geert.gnucash at kobaltwit.be> wrote:

> 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

Some potentially useful asciidoc editors http://asciidoctor.org/docs/editing-asciidoc-with-live-preview/

Mike E

-- 
PGP key:
http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x00CDB13500D7AB53