4 Replies Latest reply: Jun 5, 2012 6:05 PM by Dan Allen RSS

Considered supporting AsciiDoc?

Dan Allen Master

Has PressGang given any consideration for supporting AsciiDoc?

 

I wrote a post about my impressions of AsciiDoc in the trailblazer SIG, in which I included links to all the key AsciiDoc resources.

 

I also noticed that the Fedora Community is working on a "plain text" documentation tool that converts the input to docbook using a continous delivery cycle. The platform is a web-based docbook editor written using Seam 2 and running on JBoss AS 7.

 

http://www.fedorareloaded.com

 

I'd be psyched to see this webapp support input in AsciiDoc syntax (a git backend would be icing on the cake). I don't think it would be too much of a stretch.

 

The tough problem to solve is that the official AsciiDoc parser is written in Python. A port to Ruby is in progress, which is much more JVM friendly.

 

Anyway, this post is really to ask, have you considered supporting AsciiDoc. It's starting to pick up steam in the JBoss Community and I think the PressGang team should be at least aware of it, if not involved.

  • 1. Re: Considered supporting AsciiDoc?
    Jared Morgan Newbie

    Dan Allen wrote:

     

    Has PressGang given any consideration for supporting AsciiDoc?

     

    I wrote a post about my impressions of AsciiDoc in the trailblazer SIG, in which I included links to all the key AsciiDoc resources.

     

    I also noticed that the Fedora Community is working on a "plain text" documentation tool that converts the input to docbook using a continous delivery cycle. The platform is a web-based docbook editor written using Seam 2 and running on JBoss AS 7.

     

    http://www.fedorareloaded.com

     

    I'd be psyched to see this webapp support input in AsciiDoc syntax (a git backend would be icing on the cake). I don't think it would be too much of a stretch.

     

    The tough problem to solve is that the official AsciiDoc parser is written in Python. A port to Ruby is in progress, which is much more JVM friendly.

     

    Anyway, this post is really to ask, have you considered supporting AsciiDoc. It's starting to pick up steam in the JBoss Community and I think the PressGang team should be at least aware of it, if not involved.

     

    Hi Dan

     

    Thanks for posting. I also saw your thread in thecore.

     

    First of all, AsciiDoc looks great with regard to having a markup langauge and a supporting toolchain to output docs to multiple formats. I can see this being very useful for those companies that need to produce documentation quickly. I can also see the tool has quite good external support.

     

    To clarify, the system at www.fedorareloaded.com is actually using the CCMS developed in Red Hat Brisbane. It is a DocBook XML Component Content Management System, and while Josh Wulf is allowing people to enter in plain text if they can't use XML Markup, someone still has to go in and mark up their changes manually.

     

    Current AsciiDoc Plans

     

    At this stage, PressGang has no permanent team members (that is, no one in JBoss or Red Hat is funding PressGang in any way).

     

    For PressGang to consider looking at AsciiDoc, this situation would need to change.

     

    Alternatively, someone passionate about getting AsciiDoc working would need to join the PressGang project and lead this push.

     

    Have you talked to the JBoss Community infrastruture team about this. Perhaps they are working on something to support AsciiDoc?

     

    AsciiDoc Questions

     

    Regarding AsciiDoc, I've got a few questions that need to be cleared up. I think you would be the best person to ask given your extensive research into the markup language:

     

    Question 1:

     

    Does AsciiDoc have support for translation?

     

    For many projects, translation is done using the industry standard .po and .pot files. Does AsciiDoc support these formats as an output target.

     

    Question 2:

     

    How would AsciiDoc fit in with translation systems currently being used in JBoss Community?

     

    Upstream translation done on Zanata (https://translate.jboss.org/) relies on the format in Question 1 to allow community translators to import files and export translations.

     

    Question 3:

     

    AsciiDoc seems to support export to XML (which may make Question 1 and 2 moot).

     

    Does it produce well-formed and valid DocBooK?

  • 2. Re: Considered supporting AsciiDoc?
    Dan Allen Master

    Thanks for your reply Jared! I meant to get back to your right away, but I got sidetracked for a bit.

     

    I continue to be excited about AsciiDoc and the prospect it brings of time savings and efficiency. Each week, I'm discovering another place it's been adopted. It's especially popular amongst authors and publishers, esp where TeX / LaTeX were once used. Of course, the great part about AsciiDoc is that it complements TeX / LaTeX and DocBook rather than trying to be a complete replacement.

     

    AsciiDoc is already being adopted in the JBoss Community. The JBoss Way team is writing several of the Java EE tutorials in AsciiDoc.

     

    Jared Morgan wrote:

     

    ...

     

    To clarify, the system at www.fedorareloaded.com is actually using the CCMS developed in Red Hat Brisbane. It is a DocBook XML Component Content Management System, and while Josh Wulf is allowing people to enter in plain text if they can't use XML Markup, someone still has to go in and mark up their changes manually.

     

    Ah, I see. We can certainly do better than requiring a manual translation from plain text to XML Markup. People tend to instinctually invent a syntax if they don't have one to follow, so we might as well give them a reference to a syntax that can mostly be automated. I think AsciiDoc is an excellent choice

     

    Current AsciiDoc Plans

     

    At this stage, PressGang has no permanent team members (that is, no one in JBoss or Red Hat is funding PressGang in any way).

     

    For PressGang to consider looking at AsciiDoc, this situation would need to change.

     

    Alternatively, someone passionate about getting AsciiDoc working would need to join the PressGang project and lead this push.

     

    Have you talked to the JBoss Community infrastruture team about this. Perhaps they are working on something to support AsciiDoc?

     

    PressGang is a community project (or at least presents itself that way), so why not just engage the community to explore AsciiDoc instead of waiting to staff up or get funding? One community member has already come forward to work on a Maven plugin to process AsciiDoc files just like the docbook plugin works today (and it might even chain to the dobook plugin).

     

    I don't think the infrastructure team is working on anything to support AsciiDoc. If they were, I would expect them to be talking about it in in the PressGang forums anyway.

     

    As I mentioned, the JBoss Way team is using AsciiDoc and also integrating the rendered HTML into the new website.

     

    On to your questions:

    Question 1:

     

    Does AsciiDoc have support for translation?

     

    For many projects, translation is done using the industry standard .po and .pot files. Does AsciiDoc support these formats as an output target.

     

    We can continue to use the translation pipeline we have today, where translations are based on the Docbook Publican format. We're just adding one precursor step, converting AsciiDoc to DocBook using a2x. We then generate the .po and .pot files from there.

     

    When updates are made to the English AsciiDoc files, the DocBook Publican output will reveal the differences that need to be addressed in the translations.

     

    Editing the English AsciiDoc files and converting them to DocBook is no different than editing the English DocBook directly, except authoring is a whole lot easier. And we all win, since no one has to mess with the DocBook XML directly. It's effectively read-only.

     

    Question 2:

     

    How would AsciiDoc fit in with translation systems currently being used in JBoss Community?

     

    Upstream translation done on Zanata (https://translate.jboss.org/) relies on the format in Question 1 to allow community translators to import files and export translations.

     

    As I explained in my previous answer, nothing changes in the translation stage.

     

    Btw, I had no idea that http://translate.jboss.org existed until I read your post

     

    Question 3:

     

    AsciiDoc seems to support export to XML (which may make Question 1 and 2 moot).

     

    Does it produce well-formed and valid DocBooK?

     

    Yes it does. It prides itself on having very good DocBook export. It's also very easy to hack, so if there is something that isn't being generated correctly, we can edit the provided XSL file in the AsciiDoc installation that produces the DocBook (and even send patches up stream if it's a general bug).

     

    In summary, you can think of AsciiDoc as simply a shorthand for writing DocBook from the perspective of our documentation pipeline. All we really need is the Maven plugin I mentioned earlier and we could switch with almost no overhead to the project.

     

    The next step is to demonstrate a workflow from AsciiDoc to a translated published guide just to flesh out any details. (We could experiment on something like the Java EE tutorials or the Weld documentation). Anyone who wants to give it a shot is welcome.

     

    Here's to fun and easy documentation writing!

  • 3. Re: Considered supporting AsciiDoc?
    Jared Morgan Newbie

    From what you have told me so far Dan, AsciiDoc looks like something that might break down barriers for new community contributors. I think it is definitely something worth exploring in more detail for PressGang.

     

    PressGang as a project needs to become an assembly point for the different doc authoring formats used in the community. Currently PressGang really only talks about DocBook, however I think AsciiDoc would be a complimentary documentation option for projects given that it has its own toolchain.

     

    If you can introduce me to the AsciiDoc champions, and they are willing to invest some cycles into creating an initial community, I think PressGang would be a good place for them to assemble and discuss.

  • 4. Re: Considered supporting AsciiDoc?
    Dan Allen Master

    Jared Morgan wrote:

     

    From what you have told me so far Dan, AsciiDoc looks like something that might break down barriers for new community contributors. I think it is definitely something worth exploring in more detail for PressGang.

     

    Exactly. +1

     

    I'm calling it how I see. It's the first time I've seen people have fun writing documentation, and produce output like we're taking their keyboards away tomorrow.

     

    Just look at the massive amount of documentation that got composed for jdf in short order and the creative way it's being rendered on the site.

     

    PressGang as a project needs to become an assembly point for the different doc authoring formats used in the community. Currently PressGang really only talks about DocBook, however I think AsciiDoc would be a complimentary documentation option for projects given that it has its own toolchain.

     

    Indeed, I think we should see where this road takes us because we may discover that so many more things are possible. And if, by some unlikely chance, it falls flat, we can always rollback to DocBook. We can also roll forward to AsciiDoc using O'Reilly's DocBook->AsciiDoc converter (though anyone with light XML skills can turn DocBook into a lightweight markup language).

     

     

    If you can introduce me to the AsciiDoc champions, and they are willing to invest some cycles into creating an initial community, I think PressGang would be a good place for them to assemble and discuss.

     

    Absolutely. I can give you champions from numerious camps.

     

    Our resident AsciiDoc experts:

     

    • Pete Muir
    • Marius Bogoevici
    • Burr Sutter
    • ...and other jdf and JBoss developer contributors
    • Steven Boscarine - researching AsciiDoc adoption for his organization, interested in contributing Maven plugin

     

    Renown AsciiDoc champions and experts:

     

     

    Publishers:

     

     

    Lots of people are getting on board with AsciiDoc. It's definitely the right time to get involved.