Diagram macro paths break with Includes

[KartikSoneji]

The asciidoc include preprocessor directive automatically handles relative includes.

But diagram macros break when included by another docuemnt.

Example

Folder Structure

index.adoc
chapter 1
  - index.adoc
  - diagram.mmd

Files

index.adoc

= Title
include::chapter 1/index.adoc[]

chapter 1/index.adoc

== Chapter 1
mermaid::diagram.mmd[]

chapter 1/diagram.mmd

graph
    a -> b

Building

> asciidoctor -r asciidoctor-diagram -o index.html index.adoc
asciidoctor: FAILED: index.adoc: Failed to load AsciiDoc document - No such file or directory @ rb_sysopen - diagram.mmd
  Use --trace to show backtrace

Allowing asciidoctor core to process the includes does work:

--- a/chapter 1/index.adoc
+++ b/chapter 1/index.adoc
- mermaid::diagram.mmd[]
+ [mermaid]
+ ----
+ include::diagram.mmd[]
+ ----

[KartikSoneji]

I'm not sure if it's possible to hook into the asciidoctor preprocessor and expand the macros the same way as include does.

[mojavelinux]

Your observation is by design. The include paths are relative to the current include file, but targets of macros are not. If Asciidoctor Diagram were to try to do that, it would not be following the design of the language.

[KartikSoneji]

Fair point, but that severely limits the usability of the diagram macros. Would it be possible to have a set of diagram preprocessor directives like include?

[pepijnve]

@mojavelinux what's the rationale for treating include macro targets and other macro targets differently though when it comes to file resolution? I can understand how this could be surprising.

Is this because include:: is handled in a preprocessing step before the other macros?

[mojavelinux]

The answer to your question is yes, macros have no awareness of includes. They work as though all the includes have been resolved and the document is then parsed (even though its slightly more nuanced than that). This has been true for as long as AsciiDoc has existed. Any change to this behavior would have to be discussed in the language itself. I'm not saying that this has never come up, but having this discussion in Asciidoctor Diagram isn't the right place IMO.

[KartikSoneji]

Is this because include:: is handled in a preprocessing step before the other macros?

I think so, the documentation states:

Although the include directive looks like a block macro, it’s not a macro and therefore isn’t processed like one. It’s a preprocessor directive; it’s important to understand the distinction.

[KartikSoneji]

The answer to your question is yes, macros have no awareness of includes. They work as though all the includes have been resolved and the document is then parsed (even though its slightly more nuanced than that). This has been true for as long as AsciiDoc has existed. Any change to this behavior would have to be discussed in the language itself. I'm not saying that this has never come up, but doing it in Asciidoctor Diagram isn't the place IMO.

Is there directive to make a path relative to the current file? Something like __dirname in node.

[pepijnve]

I'm not saying that this has never come up, but having this discussion in Asciidoctor Diagram isn't the right place IMO.

:100: just satisfying my curiosity; not asking for anything to change

[mojavelinux]

My point about it not being the right place wasn't directed at your question, but rather the original request.

[KartikSoneji]

@mojavelinux is there a better place to discuss this? Should I open an issue on the ascidoctor repo? or is there a dedicated discussion form?

[mojavelinux]

Something like __dirname in node.

No, there is not. There was something like this in AsciiDoc.py (infile and indir), but the change from a streaming converter to a two phase processor (load / convert) in Asciidoctor meant it wasn't possible to populate those attributes. They are essentially ephemeral to the parser.

The related issue is here: https://github.com/asciidoctor/asciidoctor/issues/2608#issuecomment-373896577

It's possible to emulate this behavior, as the linked extension does. Without the extension, you have two options that follow the standard behavior:

• Use an include directive if you want the behavior of an include
• Add the directory or directories in which the diagram source is located at the start of the macro target

There is a third option, which is to set a custom attribute in the document each time you enter or leave an include, making it available to the content in the include. This is how most people handle complex scenarios of image macro targets in manuscripts like books.

[mojavelinux]

Should I open an issue on the ascidoctor repo? or is there a dedicated discussion form?

There are already several issues open in Asciidoctor. I have linked to one of them, and the others are linked from there.

You're welcome to discuss it in the project chat at https://chat.asciidoctor.org, or you can wait until the language project gets further along and get involved in the discussion there when it comes up.

[KartikSoneji]

Thanks, I've left a comment there. I'll close this issue then.