1 2 3 4 Previous Next 50 Replies Latest reply on Jul 9, 2012 11:30 PM by sboscarine

    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:

       

       

      If you have any questions, feel free to ask.

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

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

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

              • 4. Re: Asciidoc is the way forward
                lightguard

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

                  • 6. Re: Asciidoc is the way forward
                    lightguard

                    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
                      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?

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

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

                          • 10. Re: Asciidoc is the way forward
                            lightguard

                            Wow. Full of win!

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

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

                                • 13. Re: Asciidoc is the way forward
                                  sboscarine

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

                                    1 2 3 4 Previous Next