1 2 3 4 Previous Next 50 Replies Latest reply on Jul 9, 2012 11:30 PM by sboscarine Go to original post
      • 15. Re: Asciidoc is the way forward
        dan.j.allen

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

        • 16. Re: Asciidoc is the way forward
          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)

          • 17. Re: Asciidoc is the way forward
            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.

            • 18. Re: Asciidoc is the way forward
              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.

              • 19. Re: Asciidoc is the way forward
                lightguard

                Have updated links?

                • 20. Re: Asciidoc is the way forward
                  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.

                  • 21. Re: Asciidoc is the way forward
                    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.

                    • 22. Re: Asciidoc is the way forward
                      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?

                      • 23. Re: Asciidoc is the way forward
                        lightguard

                        First question: Yes

                         

                        Second question: On Dan's computer for the moment

                        • 24. Re: Asciidoc is the way forward
                          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.

                          • 25. Re: Asciidoc is the way forward
                            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?

                            • 26. Re: Asciidoc is the way forward
                              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.

                              • 27. Re: Asciidoc is the way forward
                                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.

                                • 28. Re: Asciidoc is the way forward
                                  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.

                                  • 29. Re: Asciidoc is the way forward
                                    lightguard

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