Add block macro

[brunchboy]

It would be nice if you could also create a diagram using a block macro to reference the source file, along the lines of:

bytefield::packet.edn[]

I considered adding this, following the example of the PlantUML extension, but there is far too much code in there that I don’t understand at all, for interacting with the Antora virtual filesystem, I think. If anyone who is comfortable in both Javascript and the Asciidoctor and Antora APIs could add this feature, a pull request would be lovely.

[brunchboy]

Well, @Mogztter and @djencks, I spent a while trying to get this to work, and then realized it was going to have to also pull in the node-fs.js and node-http.js files from the PlantUML extension, as well as possibly fetch.js, and then I would need a more robust build process (and it looks like for some reason it gets built for browsers as well as for node, which I can’t begin to understand), and this rapidly exceeds my competency and interest, as a non-Javascript developer. So I am going to leave this as an exercise for a kind soul to contribute.

Since it looks like you two took part in doing that for the PlantUML extension, if you would ever care to do the same for this one it would be most appreciated. Otherwise, it works nicely as a block processor without all that complexity.

[ggrossetie]

and it looks like for some reason it gets built for browsers as well as for node, which I can’t begin to understand

In this case, the target of the block macro is a file and the block macro extension is responsible for:

• Applying substitutions to the target. For instance, if we are using bytefield::{diagramsdir}/packet.edn[], the block macro extension needs to apply substitutions to resolve diagramsdir.
• Reading the content of the file from a path

At first, reading the content of a file from a path seems easy, right? But depending of the context you need to provide the proper implementation.

Antora

if you are using this extension in Antora then, you want to resolve the target from the catalog because the target is a resource identifier include::example$packet.edn[]

Node

Here we can use the Node module fs to read the entire contents of a file with readFileSync: https://nodejs.org/api/fs.html#fs_fs_readfilesync_path_options

Browser

We cannot use the Node module fs in the browser and the only way to read the contents of a file synchronously is to use XMLHttpRequest

GraalVM

We could go on step further and use this extension in GraalVM. In this case, you cannot use XMLHttpRequest or the fs module... one way to do it is to define a "resource resolver" in Java and bind/import this function in your JavaScript context. I'm using this technique in Asciidoctor.js to resolve include in GraalVM: https://github.com/asciidoctor/asciidoctor.js/blob/1bae0173bbf90712d963767fe8d9cfd85fb2a885/packages/core/spec/graalvm/AsciidoctorConvertWithGraalVM.java#L23-L38

We had a related discussion with @djencks and Dan and I think that Asciidoctor should provide an API and/or provide a Virtual File System. Basically, you will ask Asciidoctor to read the content of a path and depending on the context Asciidoctor will return the content.

and then I would need a more robust build process

Yes because you need to produce a "browser-compatible" version of the library. The main part is to produce a single JavaScript file because the browser won't resolve the Node require directive.

@brunchboy Does it make sense?

[brunchboy]

Thanks for the details! I still can’t understand how a browser would get involved though? And this is definitely more than I want to develop or maintain. 😞 @djencks’ Antora pipeline extension made it seem so easy!