Re: [asciidoc-lang-dev] Extension hooks in Asciidoc

[David Jencks <david.a.jencks@xxxxxxxxx>]

> On Mar 12, 2021, at 4:49 PM, Lex Trotman <exciidoc@xxxxxxxxx> wrote:
> 
> > 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 ...
> 
> Well if the DOM/extension API is _specified_ to be a single language, say Java, then the current alternative implementations will not be standards compliant, even Asciidoctor Ruby.  So any implementations that can't present a Java interface can't be standards compliant and become AsciiDoc "like" implementations which don't bother to follow the standard since they have no chance to claim to be compliant anyway, because their extension API isn't Java, or Js, or Ruby ...

Since Jay is using Java and I know something about it I was using Java as an example. To be more generic, I think that it’s reasonable for the spec to, for any language where it’s reasonable, to specify interfaces for calling each kind of extension.  Depending on the facilities of the language, I think it’s less reasonable to specify how to assemble an AsciiDoc processing environment including extensions.
It’s easy in Java to have a nice comprehensible completely typed interface that clearly documents what you get and what you need to do.  To exaggerate a bit, my impression so far is that in javascript and ruby that goal is regarded as an anti-pattern :-(.

> 
> Still it would save a lot of work since the standard could just be "Use Asciidoctor Ruby" (or whichever implementation uses the specified language) :-).
> 
> [end strawman argument]
> 
> David, I think you are overstating the effort for a language independent definition, I looked at your extension docs (well the latest commit as I write 5ee7df anyway) and thats language independent so far.  Some language is still implementation specific such as "reading into an array of lines", language that might preclude my experimental processor that memory maps input files, but those sorts of things can be fairly easily changed to "process by line" or similar if that in fact actually needs to be specified.  Obviously you have yet to specify what/how "extension points" pass information to the extension code.  Since I don't understand Java/Ruby/much Js or the Asciidoctor implementation (other than what Dan has explained over the years) I'm a good test for language independence.
> 
> Similarly the API to the DOM only needs to specify functions to be available and what they do "The `combob()` function combobulates the `Section` node and leaves it in the AST" and leave it up to the implementation to define what that maps to in their language, be it `combob(Section*)` in C or `Section.combob()` in OO languages.  Similarly for functions to provide access to or modification of node attribute/fields/members/properties and mutation of the AST (adding/deleting/moving nodes).
> 
> I said in the other thread "It would be best to specify the API in a human readable but still formal enough language to be machine readable.", that is _best_ case, at least human readable is needed since there must be a description of the functionality, but the more formal the language the better.

I think a language-independent text explanation is a minimum requirement, and I think we should explore whether specifying language-specific interfaces for a variety of languages is workable and a good idea.  Having, say, java extensions that work with any java AsciiDoc processor would be pleasant :-)

Thanks,
David Jencks
> 
> Cheers
> Lex
> 
> PS any extensions delivered with Asciidoctor and always available might just be said to be part of the language, and the fact they are extensions is just an implementation detail.

Maybe…. perhaps in the other direction I’ve considered trying to refactor Asciidoctor so that anything that looks syntax-wise like an extension is implemented as an extension.  I wonder if requiring this in the spec is reasonable.  Being able to replace behavior could be useful.  There could be a set of required extensions.  As usual, needs more thought :-)
> _______________________________________________
> asciidoc-lang-dev mailing list
> asciidoc-lang-dev@xxxxxxxxxxx
> To change your delivery options, retrieve your password, or unsubscribe from this list, visit
> https://dev.eclipse.org/mailman/listinfo/asciidoc-lang-dev