Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [asciidoc-wg] AsciiDoc implementation for the Java/JVM ecosystem / project proposal

Hello Alexander and all,

my name is Dirk Detering, a german software developer working on Java based standard software for the health insurance market.

Up to this point I was only a silent observer, being here out of curiosity, because I see Asciidoc gaining attraction in german development cycles, based on magazines (like Java Magazin) or initiatives like arc42 or other SW-Architecture movements here.

We are currently on the way to move our formerly MS Word, then Confluence based Developer Manual and Architecture Doc into Maven toolchain (following "docs-as-code" approach) using the maven asciidoc plugins.
And by the way harmonizing some smaller doc works too by going from markdown to asciidoc as well.

So starting to push asciidoc into the company processes, noticing the begin of a standardisation effort was a welcoming win.

Being a Java shop, looking for Maven plugins, Eclipse/IntelliJ plugins or an Editor like AsciidocFX was a logical step.
AsciidoctorJ being built upon JRuby is a logical step, considering the one-source-many-targets gain this offers.
But it always feels a bit "special" too, when -- as a Java developer -- thinking about broader use in our ecosystem.

Reading the question about use cases for a direct JVM implementation, many thoughts about doc transformation, report generation a.s.o. went through my head.

This was when a very basic question arose:
What indeed will be THE main -- and so most important - - benefit of the standardisation process?

Will it indeed be the syntax, so to say the UI part of Asciidoc?
Or will it be the standardised DOM/AST supported by an API, on which the syntax parser and the backend converters will work?

Currently I get the impression, that it is the latter.
So having a standardised DOM from which HTML, PDF or whatelse can be easily produced, while being able to create and manipulate a DOM instance via Asciidoc input OR programmatically by API seems the main point.

If we (in our build process) only create asciidoc text files and send it through a blackbox toolchain to produce e.g. a PDF, the language or implementation doesn't really matter. So be it JRuby.

But being able to really integrate Asciidoc in our applications, letting a user define e.g. a letter template in Asciidoc and then manipulate the DOM with business data in Java before applying a backend processor, that would be a reason to indeed want a tight Java integration.

(And I think the same is true for any other environment based on a different language platform, thinking about the debate around RustDoc)

Thanks for listening.


Alexander Schwartz <alexander.schwartz@xxxxxxx> schrieb am Mi., 10. Juni 2020, 17:09:
Hi AsciiDoc enthusiasts,

the AsciiDoc WG is an exciting effort to standardize the language and to
allow the ecosystem to grow on the basis of a common specification.

After talking to Dan Allen I volunteered to write a project proposal for
an AsciiDoc implementation for the Java/JVM ecosystem. As a maintainer
of the AsciiDoc plugin for IntelliJ I have experience in parsing
AsciiDoc and using AsciidoctorJ, but I also know he areas where parsing
and good tool support is difficult today.

What use cases do you see for an AsciiDoc JVM implementation? What
contributions do you want to make or see necessary?

Please collaborate with me on this draft:

To edit the document request access or discuss it on this mailing list.
Don't forget to add you and your company to the "Interested Parties"

For those who want to have a synchronous communication, please join me
on a Jitsi video conference call next week:

When: June 16th, 17:00 UTC - Convert to your time zone:

Please get in contact before the call with all the questions you might have.

Best regards,

Alexander Schwartz (alexander.schwartz@xxxxxxx)

asciidoc-wg mailing list
To unsubscribe from this list, visit

Back to the top