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

[Jay Bryant <jbryant@xxxxxxxxxx>]

I mean the author of the document - the person writing content for publication.

J

---

From: asciidoc-lang-dev <asciidoc-lang-dev-bounces@xxxxxxxxxxx> on behalf of Lex Trotman <exciidoc@xxxxxxxxx>
Sent: Wednesday, March 17, 2021 6:05 PM
To: AsciiDoc developer discussions <asciidoc-lang-dev@xxxxxxxxxxx>
Subject: Re: [asciidoc-lang-dev] Extension hooks in Asciidoc

 

> I hesitate to say it, because it makes things even more complex, but substitution could be controlled by a switch in the defined block. Then the author would have control of when (and even whether) to substitute.

Do you mean the author of the macro or the author using the macro?  For use-cases like documents being developed with change suggestions on github these are likely to be two different people and its easy for one to miss the others use of attributes.  Thats why I preferred non-capturing as default based on experience of many of the programming languages that provide this feature.  Essentially I'm suggesting what is known as "hygenic" macros.

On Thu, 18 Mar 2021 at 03:21, David Jencks <david.a.jencks@xxxxxxxxx> wrote:

Since this is easy to implement now as an extension, I would oppose adding something like this as new syntax to the language, without a strong argument explaining why it’s a good idea.

The basic argument is that extensions are not portable, and (IIUC) your extension does not support more than a block.  The intention is for this to be performed in preprocessing so it can bridge syntax elements, that means it should be distinct syntax so its recognisable before parsing.

 

Also if its required by the standard, its a new part of AsciiDoc syntax, no matter if its called an "extension" and will have to be implemented by all implementations, so its irrelevant that it happens to have been implemented that way for Asciidoctor.

The one feature I would like is to be able to define a bunch of these custom templates once for a set of documents, such as for an Antora or jekyll-asciidoc site.  I don’t think this requires or would be influenced by a syntax change however.

First suggestion would be to include:: your list.

 

Cheers

Lex

David Jencks

...