Macro for parameterized text substitution

[oliviercailloux]

I would like a parameterized macro (I mean, some function of a parameter that produces content) that, for example, given the JsonbTransient value, renders: https://javaee.github.io/javaee-spec/javadocs/javax/json/bind/annotation/JsonbTransient.html[`@JsonbTransient`]. (Which would then be further processed by Asciidoc and transformed into a link in the final output.)

This would spare me from writing each time the link to the Java EE API.

As I understand this kind of things currently requires writing an extension. And as I understand the general philosophy behind this is that the macro should be not defined in the same document as its use, for otherwise it “goes against the philosophy of Asciidoctor to keep the content and configuration/behavior separate” (from a related discussion).

While I understand the general philosophy, I suspect that it does not apply to my simple use case, as I see my macro as defining and producing itself more content, not as a formatting or behavior configuration device. My use case looks to me more similar to defining attributes, which can be done in the same document as its use (as should be, for simplicity and for reason of keeping all “content-related” information together).

Thus I wonder if I missed something obvious here. Is there some simple way of defining such a parameterized substitution macro in the document itself, similar to the Macro definition mechanism of the Python asciidoc version?

Underlying this question is the fact that I publish Asciidoctor documents to GitHub, so using the extension mechanism would require furthermore to add an intermediate processor step before publication to GitHub, as suggested in the related discussion. While I certainly agree that it makes sense to keep content and rendering logic separate, all of this seems overkill and (arguably?) not appropriate for simple text substitution.

[mojavelinux]

What you're asking for is handled by the extension mechanism. Perhaps you are interested in this extension, which happens to cover exactly your use case (as far as I can tell).

https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/implicit-apidoc-inline-macro.rb

You're free to take that and evolve it into something more advanced, perhaps even into a dedicated gem.

[mojavelinux]

FYI, this is the repository for the website. To broaden the discussion, you might want to post this to the mailinglist (http://discuss.asciidoctor.org) or perhaps to the extensions lab I linked to.

[mojavelinux]

Is there some simple way of defining such a parameterized substitution macro in the document itself, similar to the Macro definition mechanism of the Python asciidoc version?

Simple answer. No. That's not in the philosophy of this project. You can define reusable text in attributes (which is what I often use for recurring URLs), but that's as far as what the document itself can do.

[oliviercailloux]

Sorry for posting at the wrong place; and thanks for the information anyway. (For the record, no, it doesn’t exactly address my concern, if I understand correctly, specifically this part: “using the extension mechanism would require furthermore to add an intermediate processor step before publication to GitHub, as suggested in the related discussion. While I certainly agree that it makes sense to keep content and rendering logic separate, all of this seems overkill and (arguably?) not appropriate for simple text substitution.” But I take note of the fact that “this is not the philosophy of this project”, I understand that features must be bounded somehow.)

[mojavelinux]

Unfortunately, GitHub does not allow the use of extensions. But I don't think you should view GitHub as a final publishing destination. It's intended for low-fidelity preview. If you want publish your documents in high-fidelity, you should use a static web host like GitHub Pages, GitLab Pages, Netlify, or now.sh (which is just as easy, btw). Trying to do everything inside the GitHub repository is prohibitively limiting.