Include directive does not find file relative to current file

[mrotteveel]

As a followup on #323, with asciidoctor-gradle-plugin 2.0 and higher, the include directive no longer works as documented in the Asciidoctor User Manual.

The workaround to add {includedir} to resolve includes correctly goes against the behavior of the include directive documented in the Asciidoctor User Manual, section File resolution:

If the path relative, the processor resolves the path using the following rules:

• If the include directive is used in the main (top-level) document, relative paths are resolved relative to the base directory. (The base directory defaults to the directory of the main document and can be overridden from the CLI or API).
• If the include directive is used in a file that has itself been included, the path is resolved relative to the including (i.e., current) file.

These defaults makes it easy to reason about how the path to the include file is resolved.

This change requires asciidoctor-gradle-plugin specific changes to sources, tightly coupling it to asciidoctor-gradle-plugin and breaking preview in authoring tools (eg resulting in "Unresolved directive in - include::{includedir}/chapters/introduction/introduction.adoc[]" in the preview of the Visual Studio Code Asciidoctor plugin), and hinders use of different asciidoctor (build) tools with these sources.

As the second rule (includes relative to included files) is supported, the workaround seems to be to define an asciidoctor-gradle-plugin specific root-document that only contains

include::{includedir}/real_root_document.adoc[]

When authoring using real_root_document.adoc, other tools will correctly render the files, but this is hardly a good solution in my opinion.

This is possibly a regression from #83.

[mojavelinux]

The workaround to add {includedir} to resolve includes correctly goes against the behavior of the include directive documented in the Asciidoctor User Manual, section File resolution:

I wouldn't say it goes against the behavior of the include directive. The target of an include directive is relative to the base directory (if set) or the document directory otherwise. If you alter those settings, you alter where the processor looks for the file.

The one exception are nested includes. These should always be resolved relative to the document that is including them. That's because changing this behavior would be non-portable.

Having said that, how top-level includes are resolved is a choice that should not be taken away from the author.

[mrotteveel]

@mojavelinux Maybe I should have written "against my expectations based on reading the Asciidoctor User Manual and the previous versions of the asciidoctor-gradle-plugin", but then again, the documentation says "The base directory defaults to the directory of the main document and can be overridden from the CLI or API", and asciidoctor-gradle-plugin no longer defaults to that location.

[mojavelinux]

The Gradle plugin has changed this default several times in its history, so it's always been an exception to the rule. The user manual describes what the core processor does, but it's not a mandate. I have no problem with the default. I would only have a problem if it's not configurable. (For example, consider what the Jekyll AsciiDoc plugin does: https://github.com/asciidoctor/jekyll-asciidoc#specifying-the-base-directory)

[mrotteveel]

@mojavelinux Thanks for the clarification. Such a solution (which is similar to what Schalk proposed in the other issue would be acceptable to me.

[ysb33r]

Fixed and scheduled for 2.2.0.

[mojavelinux]

I think you're missing one, which is that the basedir is not set (or it matches the docdir). That matches the default behavior of the processor.

(Keep in mind, the whole basedir needs to be rethought because in many ways it's unintuitive, but we'll address that in core first).

[ysb33r]

@mojavelinux I think basedir has always been set in the Gradle plugin - even before my time

[mojavelinux]

I get that. What I'm trying to communicate is that the processor doesn't work very consistently when basedir is set. It's a flaw in the design of core that needs addressing. It's purpose is just not very well defined.