Using AsciiDoc for Documentation

[Geert Janssens]

On Thursday 03 September 2015 01:28:59 Buddha Buck wrote:
> On Wed, Sep 2, 2015 at 10:20 AM Geert Janssens
> <geert.gnucash at kobaltwit.be>
> wrote:
> > 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.
> 
> By "markup" here do you mean "Markdown"?
> 
Indeed. I don't know why I started using it markup all of a sudden...

> If so, there are a number of wysiwyg-like editors available, presuming
> that two panes, one with the plain markdown, the other a real-time
> rendered preview, is sufficient.
> 
As I briefly mentioned in another part of this thread, I think it helps but I'm not sure it will be 
sufficient for new contributors to learn.

I had seen those editors with previews (and mentioned them in the preceding thread (Replacing 
Docbook).

> Atom (http://www.atom.io) is a very capable "hackable" editor which
> supports Markdown with preview pane out of the box. It's open source
> and supports Linux, Mac, and Windows
> 
> Remarkable (https://remarkableapp.github.io/
> <https://remarkableapp.github.io/linux.html>) is a Windows/Linux open
> source Markdown editor with live preview, and also will export HTML
> and PDF out of the box. It does not claim MacOS support.
> 
> CuteMarkEd (https://cloose.github.io/CuteMarkEd/) uses Qt as it's
> platform, and thus supports Linux, Windows, and possibly Mac if
> compiled from source. It has similar features as the others.
> 
>  I also haven't been paying close attention so I don't know if pandoc
> ( http://pandoc.org/index.html) has been evaluated for document
> conversion. It seems to support converting every input file format
> under discussion to every output file format under discussion. Did I
> miss the discussion?

I didn't know about pandoc. A very interesting tool at first sight.

I quickly used it to run some tests.

Conversion of our docbook to latex ran successfully but LyX can't open the document.

I also ran a conversion to opendocument format (.odt). It does better than the outdated 
docbook2odt in that it resizes the images. Links are still missing though and are replaced with 
question marks.

Next I tried a conversion to asciidoc. Again the links were acting up. I wonder if we're 
improperly using them in our original docbook format already. Other than that the document 
looked fine on first glance.


Perhaps we're just trying to find a solution that's too rigid. If a tool such as pandoc really works 
well we may be able to choose one base document format and accept patches from different 
formats that just need one conversion step to apply to the base format. Oh well, that's just 
dreaming out loud for now...

I'll probably continue to play with pandoc to study it's potential. Thanks for bringing it up.

Geert.