Using AsciiDoc for Documentation

[Geert Janssens]

On Wednesday 02 September 2015 06:45:38 John Ralls wrote:
> > On Sep 2, 2015, at 2:55 AM, Mike Evans <mikee at saxicola.co.uk> wrote:
> > 
> > On Tue, 1 Sep 2015 13:44:39 -0500
> > 
> > Rob Gowin <robg at gowin.net> wrote:
> >>> On Sep 1, 2015, at 4:56 AM, Mike Evans <mikee at saxicola.co.uk> wrote:
> >>>> [snip]
> >>> 
> >>> Hi Rob
> >>> 
> >>> Looks good to me. Still a few minor bugs with the Asciidoc.
> >>> 
> >>> Some of the Figure titles are missing
> >>> Second level bullet indents missing
> >>> 
> >>> But these are minor and some tweaking of the XSL should fix that. 
> >>> Speaking of which, I notice the XSL isn't in github can you make
> >>> that available somewhere so others can chip in with help? I'd
> >>> also like to generate the Asciidoc locally so I can ensure both
> >>> formats are from the same source for comparison purposes.
> >>> 
> >>> Now you (we) have to convince others to use Asciidoc!
> >>> 
> >>> I use Geany for my coding/writing and there is a Markdown plugin
> >>> for preview, no Asciidoc at the moment though.  I'm looking at
> >>> the PEG code to see how difficult it would be to produce an
> >>> Asciidoc previewer plugin.  It may be beyond my learning
> >>> tolerance though.
> >>> 
> >>> Mike E
> >> 
> >> Hi Mike,
> >> 
> >> Thanks for taking a look. I have put the XSL file and a python
> >> script to run the conversion process in a repository at
> >> https://github.com/codesmythe/asciidoc-conversion. See the README
> >> there for details.
> >> 
> >> As for editors, I just use a command line converter and then
> >> reload the generated HTML into a browser. I need to try some of the
> >> live preview editors mentioned in the link you sent out yesterday.
> >> 
> >> I'll look at the issues you mentioned in the next couple of days.
> >> 
> >> Thanks,
> >> 
> >> Rob
> > 
> > Hi Rob
> > 
> > Bearing in mind this would only ever need to be run once for each
> > document set and that Asciidoc may not be adopted anyway it's
> > probably not worth spending a lot of effort on those final issues
> > for the moment.  They can likely be easily(ish) fixed manually
> > after conversion.
> Well, let’s poll the person most likely to make use of the switch:
> 
> David Carlson, please have a look at
> http://asciidoc.org/userguide.html, starting at section 8, and tell
> us if you’d be able to easily edit documents in that format.
> 
David T. is currently actively working on the English documentation. And I also saw patches 
by Chris Good recently. Additionally Mechtilde Stehmann is working on the German 
translation as well.

All good candidates to let us know how they perceive asciidoc/markup versus the current 
docbook format. I'm not sure they are all subscribed to the devel list so exceptionally I have 
addressed them directly in addition to the list.

Regards,

Geert