Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [asciidoc-lang-dev] Extension hooks in Asciidoc

OK, as I understand it the goal for the spec v1 is primarily to formalize and specify what Asciidoctor does now.  Among other things Asciidoctor has document and syntax processor extensions, such as docinfo and block processors, and converter extensions.  My very quick look at your repo found these and nothing else, so I presume the spec will mandate supporting these, although possibly as an optional component rather than some sort of ‘minimal’ implementation.

As I’ve mentioned before, I think that considering cross-language extensions would assure that the spec never gets to v1 and would be unusable should it succeed in getting there.  Within java, my personal opinion is that it’s probably reasonable to define typed interfaces for different kinds of extensions, but that we should leave the component assembly mechanism out of the spec, so that implementations can use for instance OSGI declarative services, Spring, or just hard coding stuff to assemble an Asciidoc processor environment.

Are you asking for something beyond the current Asciidoctor capabilities for extensions?

David Jencks

p.s. Processor extensions are not well documented currently in Asciidoctor.  Although it is definitely still WIP, I’ve made what I consider a considerable improvement here:

On Mar 12, 2021, at 2:00 PM, Jay Bryant <jbryant@xxxxxxxxxx> wrote:

We use AsciidoctorJ. Spring is written in Java, so we prefer other things that are written in Java. Part of the team's excitement about the Working Group is that there will be a Java implementation.

That shouldn't matter, though. IMO, the Asciidoc specification should provide extension mechanisms regardless of the language that implements the specification. In other words, I would like the specification to call out extension mechanisms. The XSLT specification does so, for example: (and did so in its previous versions, though each one did it differently).


From: asciidoc-lang-dev <asciidoc-lang-dev-bounces@xxxxxxxxxxx> on behalf of David Jencks <david.a.jencks@xxxxxxxxx>
Sent: Friday, March 12, 2021 3:30 PM
To: AsciiDoc developer discussions <asciidoc-lang-dev@xxxxxxxxxxx>
Subject: Re: [asciidoc-lang-dev] Extension hooks in Asciidoc
Hi Jay,

Looking at the repo, it appears to be a mix of ruby and java code.  Which “dialect(s)” of Asciidoctor are you (Spring) using, called how?

I’m much more familiar with the _javascript_ and ruby dialects than java.  It looks like it is considerably more awkward to implement processor extensions in java than other languages.
I think it’s possible that there are existing more efficient ways to implement some extensions in current Asciidoctor, such as using the template converter system for your converter extension.

Other than the possible difficulty of implementing string manipulation in java, and relating java extensions to a ruby backend, I’m curious what specifically you would like to be easier.

I always like looking at what people do to extend Asciidoctor :-)

David Jencks

On Mar 12, 2021, at 11:54 AM, Jay Bryant <jbryant@xxxxxxxxxx> wrote:

Hi, all,

First, some background (I must tell you this bit so the rest might make sense): The Spring Framework is really more than 50 different projects. Almost all of those projects use Asciidoc (and Asciidoctor). We have gotten into the all-too-common state of different projects doing very similar things in different (or even the same but copied) way.s To that end, we have started a project to provide one source for the features we want (code folding, tabbed content, copy-to-clipboard, dark mode, and others). Here's that project:

I mention it here to point out the kinds of things that people try to do. I do not expect the Asciidoc WG or any implementation to do these things for us. However, I would like us to think about any "hooks" we can put in the spec and the resulting implementations to make implementing these kinds of features easier.


asciidoc-lang-dev mailing list
To change your delivery options, retrieve your password, or unsubscribe from this list, visit

asciidoc-lang-dev mailing list
To change your delivery options, retrieve your password, or unsubscribe from this list, visit

Back to the top