1 2 3 4 Previous Next 50 Replies Latest reply: Jul 9, 2012 11:30 PM by Steven Boscarine Go to original post RSS
  • 15. Re: Asciidoc is the way forward
    Dan Allen Master

    Yep, clearly we have lots of options, well see what path works best.

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

    I gave the ruby port a try. It still has a long way to go. It can handle about the level of formatting that markdown allows...then it pretty much drops off there. The design seems pretty sound, but there's still a lot of stuff to fill in.

     

    I think that the jython approach is the way to go for getting a Maven plugin written. You'll likely get good support for that on the mailinglist anyway.

     

    AsciiDoc discussion list (Google Groups)

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

    I tested AsciiDoc with jython and I can confirm it works! (It's slow, but it gets the job done).

     

    Here's what I did.

     

    1. Download jython (I'm using 2.5.3b1)
    2. Run the installer to extract it to your home directory (in your folder of choice)
    3. Put jython on your PATH (%jython_install_dir%/bin)
    4. (optional) Download ez_setup.py from http://peak.telecommunity.com/dist/ez_setup.py
    5. (optional) Run
      jython ez_setup.py
      (this is like setting up Ruby gems)
    6. (optional) Install Pygments for syntax highlighting using
      easy_install Pygments
    7. Get AsciiDoc from trunk (has fixes for jython):
      hg clone https://code.google.com/p/asciidoc
    8. Switch to the asciidoc directory
    9. Run
      jython asciidoc.py -b html5 README.txt

     

    That should produce README.html.

     

    What I haven't yet done is create a Java application class that invokes the asciidoc.py using JSR-223. See Using JSR-233 in the jython user guide.

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

    I doubt there has been serious work done in the perf area of Jython like there has been in jRuby. I'm actually quite surprised they haven't at least done some invokeDynamic stuff on Java 7.

     

    EDIT: When calling from within Java, you'll probably see a perf increase as you won't have to spin up a new JVM. Also, for longer runs (more than a file) you'll probably also see JIT improvements.

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

    Have updated links?

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

    Sweet! I got it working from Java! And you're right, it's much, much faster. It executes only twice as slow as the native python script, roughly 15 seconds for the Java EE tutorial. I'll take it!

     

    I'll try to cleanup the script and paste it here with instructions. It took me awhile to figure out that passing arguments to the script isn't possible with the JSR-233 impl atm, so I had to switch to the python API.

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

    Oh yeah, and the JSR-233 API fails if the script is larger than 100K for some stupid reason. That bit me for awhile.

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

    I am a little fuzzy on overall goal...is it to use AsciiDoc as a means of writing tutorials for the trailblazer initiative?   Is there a project set up somewhere where I can see what has been written so far?

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

    First question: Yes

     

    Second question: On Dan's computer for the moment

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

    Here's a Java program that executes AsciiDoc from Java using the Jython interpreter.

     

    https://gist.github.com/1962755

     

    Victory. It was also fun to explore the scripting engines in Java. Lots of possibilities there.

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

    That's a good question, probably something that needs to be addressed in a dedicated thread (the process that is).

     

    The goal of the trailblazer SIG, in general, is to produce solid examples and documentation to help developers make use of JBoss and OSS technology. My perception is that a major hurdle to writing documentation is wrestling with docbook. At least, I have yet to find someone who actually wakes up in the morning excited to write in that over-engineered schema. I certainly don't. (You spend more time writing markup than you spend writing the actual documentation).

     

    We've seen already the impact that Markdown has had on the willingness of developers and community members to write documentation. That has been further supported by the broad participation in the Arquillian website content (namely blogs and tutorials).

     

    However, both textile and markdown don't give us enough power to be able to meet the documentation team (and their tools) half way. AsciiDoc is the first syntax I've seen that can provide the best of both worlds.

     

    Long story short, yes, I see AsciiDoc as being the syntax of choice for writing any documentation we create in the trailblazer SIG. With this Java processor I've hacked together, we can store the documentation in src/main/asciidoc and process it using Maven (eventually) just like DocBook files (or you can just render it whichever way you want during development).

     

    But that's just one pipeline. Since AsciiDoc is remarkably portable and readable, we can easily reuse it in many other areas. We can paste it into a gist, paste it into a github wiki page, paste it into a blog entry, paste it on Google+, and so on. The knowledge is extremely portable...and that's something I think will help set the trailblazer SIG on a path to success.

     

    So far, we don't have any of this setup in a project. The tutorials I've been working on have been standalone (call them warm-up exercises). I'm going to touch base with Pete and Marius and see if I can help them adopt this process, which we will of course document in the SIG's wiki.

     

    Make sense? Questions?

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

    The docbook output should be formatted a heck of a lot better than it is now. There's no indentation, same with the HTML version.

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

    A simple xmllint can take care of that:

     

    xmllint -format output.xml
    

     

    Same works for the HTML too, though who really cares about the HTML. Most webpages have horribly formatted HTML.

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

    It would be a nice options for AsciiDoc to have a post-processing formatting filter baked in. Perhaps file an issue report.

     

    Note that AsciiDoc does support a filter mechanism. That may apply here.

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

    xmllint won't work well for programlistings. It'll mess stuff up in the output.