[asciidoc-lang-dev] Extension hooks in Asciidoc

[Sylvain Leroux <sylvain@xxxxxxxxxxx>]

On 13/03/2021 18:06, David Jencks wrote:
>>> Maybe…. perhaps in the other direction I've considered trying to refactor Asciidoctor so that anything that looks syntax-wise like a 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 :-)
>>
>> I have close to zero experience with extensions. Could you be more
>> explicit regarding the standard features "that looks syntax-wise like an
>> extension"?
>>
>
> I'm thinking of things such as `image:…`, `xref:…` which look like inline macros and `image::…` that looks like a block macro.>
> `include::…` needs to stay special as it does not necessarily introduce block content.

Thanks for the reply, David.

TL;DR:

Macro-like directives make good extension points. And not all processors
might want to implement those features. So I support the idea of making
them extensions.


For the long message now:

This WE, I studied a little bit more AsciiDoc extensions. There appear
([1]) to have much more extension points than I believed it.

FWIW, the `image:…`, `xref:…` and `image::…` have in common to link to
(or include from) external sources. I can imagine a situation where a
client application might want to limit or filter what's allowed here.
Say, for example, in the case of a Forum application using AsciiDoc as
its message input format: the processor might want to enforce a forum's
policy restricting the allowed image format or origin.


On 13/03/2021 18:06, David Jencks wrote:
> `include::…` needs to stay special as it does not necessarily introduce block content.


As far as I understand, `include::...` are different because they are
resolved before the document is parsed (in the pure tradition of the C
pre-processor). That being said, a processor might want to limit or
filter those directives at a finer granularity than currently allowed by
the "safe-mode" security-level control [2].

Conditional directive [3] (`ifdef::..., endif::...`) should probably
remain part of the core specs.



On 13/03/2021 02:50, David Jencks wrote:
> 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.

Could there be a set of "standard extensions" whose behavior is defined
in the specs but whose implementation is not mandatory?


Regards,
- Sylvain Leroux



[1]:
https://www.rubydoc.info/github/asciidoctor/asciidoctor/Asciidoctor/Extensions
[2]: https://docs.asciidoctor.org/asciidoctor/latest/safe-modes/
[2]: https://docs.asciidoctor.org/asciidoc/latest/directives/conditionals/