1 2 3 4 Previous Next 50 Replies Latest reply: Jul 9, 2012 11:30 PM by Steven Boscarine RSS

AsciiDoc is the way forward

Dan Allen Master

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:

 

 

If you have any questions, feel free to ask.

  • 1. Re: Asciidoc is the way forward
    Dan Allen Master

    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.

  • 2. Re: Asciidoc is the way forward
    Steven Boscarine Novice

    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?

  • 3. Re: Asciidoc is the way forward
    Jason Porter Master

    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.

  • 4. Re: Asciidoc is the way forward
    Jason Porter Master

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

  • 5. Re: Asciidoc is the way forward
    Steven Boscarine Novice

    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).

  • 6. Re: Asciidoc is the way forward
    Jason Porter Master

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

  • 7. Re: Asciidoc is the way forward
    Jason Porter Master

    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?

  • 8. Re: Asciidoc is the way forward
    Steven Boscarine Novice

    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.

  • 9. Re: Asciidoc is the way forward
    Dan Allen Master

    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.

  • 10. Re: Asciidoc is the way forward
    Jason Porter Master

    Wow. Full of win!

  • 11. Re: Asciidoc is the way forward
    Dan Allen Master

    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.

  • 12. Re: Asciidoc is the way forward
    Jason Porter Master

    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

  • 13. Re: Asciidoc is the way forward
    Steven Boscarine Novice

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

  • 14. Re: Asciidoc is the way forward
    Dan Allen Master

    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'.

1 2 3 4 Previous Next