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!

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:

• Matthew McCullough
• Scott Chacon - created the original AsciiDoc toolchain for book publishing, git-scribe
• ...keep an eye on news from GitHub

Publishers:

• O'Reilly Media - they have both a toolchain and a web-based editor for editing AsciiDoc
• ...any O'Reilly author that's used or is using AsciiDoc to write a book, including yours truly

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