[dan.j.allen]

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

[dan.j.allen]

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)

[dan.j.allen]

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.

[lightguard]

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.

[lightguard]

Have updated links?

[dan.j.allen]

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.

[dan.j.allen]

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

[sboscarine]

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?

[lightguard]

First question: Yes

Second question: On Dan's computer for the moment

[dan.j.allen]

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.

[dan.j.allen]

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?

[lightguard]

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.

[dan.j.allen]

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.

[dan.j.allen]

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.

[lightguard]

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