AsciiDoc is the way forward

[dan.j.allen]

I've done extensive research on lightweight markup languages (Markdown, Textile, reStructuredText, AsciiDoc) to determine which is best for writing tutorials. Without a doubt, AsciiDoc is the clear winner. I strongly recommend adopting for this project.

See my assessment of AsciiDoc for details and a comprehensive example.

Below are the key resources for AsciiDoc:

• AsciiDoc homepage
• AsciiDoc cheat sheet (a good place to start)
• AsciiDoc user guide
• AsciiDoc download (tar.gz or zip)
• Another AsciiDoc cheat sheet
• Neo4j writing guide with AsciiDoc
• AsciiDoc FAQ
• AsciiDoc discussion list (Google Groups)
• AsciiDoc issue tracker
• AsciiDoc source
• git-scribe (for aggregating asciidoc files into a book like w/ docbook)
• Custom themes (styles) for AsciiDoc
• Docbook to AsciiDoc converter (sponsered by O'Reilly Media)
• Early draft of an AsciiDoc port to Ruby (required templates can be found in this project)
• More promising port of AsciiDoc to Ruby (used for the git-scm.org website)
• How to create handsome PDF documents without frustration (nice overview of the "why?" part of AsciiDoc)
  • The gist: In the beginning there was TeX. Many theses were written it. But the syntax is quirky. We tried XML. It's standard, but painful. AsciiDoc has the full package. It's simple and easy to learn, has brilliant typesetting through TeX/LaTeX and offers portability, archiving and processing via DocBook export.

If you have any questions, feel free to ask.

[dan.j.allen]

Here are the commands I used to generate the HTML, PDF and Docbook outputs with AsciiDoc 8.6.6.

HTML:

asciidoc -b html5 -a icons -a iconsdir=$HOME/opt/asciidoc/images/icons -a theme=flask -a data-uri -a toc2 -a pygments tutorial.asciidoc

PDF:

a2x -fpdf -dbook --fop --icons --icons-dir=$HOME/opt/asciidoc/images/icons tutorial.asciidoc

Docbook:

a2x -fdocbook -dbook --fop --icons --icons-dir=$HOME/opt/asciidoc/images/icons tutorial.asciidoc

Btw, yelp (the Gnome help browser) is a pretty good Docbook viewer.

[sboscarine]

How did you integrate it with the build?  From a very quick Google search, I didn't see any Maven plugins.  Did I miss something?

[lightguard]

I liked what I saw of asciidoc when I did a quick scan of their cheatsheet. It seems like a great way to do things. I'm very impressed that it's featured in git, big help for that. The PDF looks like it had some issues with images and call outs. I wonder if that's something that's wrong with the fop sheet or something else.

[lightguard]

You could of course use an ant-run in a maven pom, or we could simply build a plugin.

[sboscarine]

Ant-run call to a native OS command or is there a Java version out there?   The language looks great. 

If native binaries are the only option, I am personally motivated enough to go out and install special windows binaries, but I wonder if some contributors you'd want help from may be hesitant. 

Also, isn't there discussion of setting up the quickstart examples in CI?  I assume it wouldn't be an issue if you had SSH access to the machine hosting Jenkins (or whatever CI server RedHat ends up choosing).

[lightguard]

It'll run on Jython. Couldn't be that difficult to create a maven plugin and run it off jython.

[lightguard]

Slight correction, HEAD should run on Jython. Looks like they had something that didn't work. If we're going to be using this, might I suggest extending a hand of friendship and setting up a Jenkins instance on OpenShift to do CI against Jython?

[sboscarine]

Jason Porter wrote:

It'll run on Jython. Couldn't be that difficult to create a maven plugin and run it off jython.

If it's that simple and asciidoc is the way to go, I think it's worth creating a plugin.  I'd be happy to help and do most of legwork for the Maven plugin if you want to focus on the Jython (never touched it before).

A lot of us have employers that won't let us run Linux and aren't too keen on us installing native programs, so having something that runs with Java and Maven alone is huge.

[dan.j.allen]

Oops, I pointed to the wrong icon directory when I moved things around to publish. They do work nicely. I'll upload a fix when I get home.

Btw, the pdf is created from the docbook output, so we can reuse all pressgang styles for producing the final, polished artifacts.

[lightguard]

Wow. Full of win!

[dan.j.allen]

Good news! I discovered a port to Ruby (search asciidoc Ruby github). From my experience, Ruby code runs flawlessly on the Jvm via jruby. If that port works well, that may be the best solution for a maven plugin.

However, for development, I strongly suggest leaving Maven out of this. That's one of the reasons I don't like docbook (or our setup). It's just too cumbersome. Of course it's find for ci, but trust me, we'll get that worked out. It's possible.

[lightguard]

Looks like it hasn't been touched in a couple of months and it's in it's early stages. https://github.com/runemadsen/asciidoc

[sboscarine]

The Maven plugin suggestion was more for casual users and CI.  I assume power users would choose the other tools. 

[dan.j.allen]

I get your point, I should have clarified that those commands are just python scripts.

I gave jython a try the other day for the first time. Easy to get running (just as easy as jruby) but man is it slow.

For a ci build it's fine. Just not ideal for quick turnaround. I'm praying this Ruby port is good. I can hack Ruby as well as Java, so I can fix things if necessary.

Did I mention I'm excited. This is rockin'.