Using AsciiDoc for Documentation

[Geert Janssens]

On Wednesday 02 September 2015 10:55:34 Mike Evans 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.
> 
> Mike E

Mike, Rob,

Thanks for enthusiastically evaluating asciidoc. Until now I haven't had the chance to look at it 
and just did so superficially. 

In general I'm open for all alternatives if they represent a step forward in our documentation 
needs.

I remember Christian Stimming rejecting asciidoc in the original discussion because it still 
requires the user to learn a markup structure, which he considered too much of a barrier for 
new contributors.

Having said that, it seems asciidoc has more or less the same advantages and disadvantages 
as markup. It looks to be slightly more expressive than markup.

As with markup the primary drawback I currently see is the lack of a wysiwyg capable editor 
that's present on all platforms we support.

I agree with John we should ask the opinion of those users that are currently expressing interest 
in contributing to the documentation.

Regards,

Geert