docdir value inconsistent with gradle plugin

[jmini]

While I was comparing the maven and the gradle plugin with following structure:

project
├── docs
│   ├── index.adoc
│   └── other
│       └── other.adoc
├── pom.xml
└── build.gradle

And following config for pom.xml:

<plugin>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-maven-plugin</artifactId>
  <version>${asciidoctor.maven.plugin.version}</version>
  <configuration>
    <sourceDirectory>${project.basedir}/docs</sourceDirectory>

And build.gradle

asciidoctor {
    sourceDir = file('docs')

I got different docdir values.

---

For docs/other/other.adoc

With maven:

docfile: /<path to example>/docs/other/other.adoc
docdir: /<path to example>/docs

With gradle:

docfile: /<path to example>/docs/other/other.adoc
docdir: /<path to example>/docs/other

---

For docs/index.adoc

The value is the same for maven and gradle:

docfile: /<path to example>/docs/index.adoc
docdir: /<path to example>/docs

---

In my opinion the implementation of the gradle plugin is correct. It matches the definition:

Full path of the directory that contains the source document.

---

Related to this issue:

I also think that both plugins should provide access to the “sourceDirectory” as additional attribute. (See https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/292 for gradle) And in particular, what is useful is the relative path to the sourceDirectory (called {sourcedir} in my case).

If you are using working with <preserveDirectories>true</preserveDirectories> you can write:

:highlightjsdir: {sourcedir}highlight

The {sourcedir} value should be set to:

• empty string for docs/index.adoc
• ../ for docs/other/other.adoc

Until such a feature is available, I have developed a small preprocessor as a workaround. https://jmini.github.io/asciidoctorj-sourcedir/

[mojavelinux]

Don't hold me to this, but there may be a reason we did this. There's a complex interrelationship between docdir and the security mode, specifically the jail. The docdir effectively sets a jail that prevents you from including files in parent folders, but still within the project (when safe mode is safe or higher). Setting the docdir to the project root allows you to work anywhere inside the project.

There's an open issue in core to break this dependency so that you can set the jail independently from the docdir (which has other uses). But this at least explains the current situation.

[mojavelinux]

Btw, I'm not necessary arguing the value should remain the way it is. I just want to make you aware of the impact.

[abelsromero]

From testing, the value of docdir comes from base_dir which is always set by default to sourceDirectory. Even when sourceDirectory is not set in the pom, base_dir is set "${basedir}/src/main/asciidoc". This is to ensure resolution of includes, images, etc. work correctly regardless the configuration of preserveDirectories and relativeBaseDir. I could replicate the gradle plugin in your maven-example project simply by not setting the base_dir option.

Finally, I also replicated the maven and gradle behaviors setting/not-setting base_dir using the ruby CLI. Which makes me think that either there's an issue with docdir or I am missing something. After reading the docs (specially when you check the docs https://asciidoctor.org/docs/user-manual/#env-attributes) I understand that docdir should be independent of any other parameter.

The docdir effectively sets a jail that prevents you from including files in parent folders, but still within the project (when safe mode is safe or higher)

The plugin runs in UNSAFE, and is not configurable. This should probably be added as an option.

[abelsromero]

Finally, I also replicated the maven and gradle behaviors setting/not-setting base_dir using the ruby CLI. Which makes me think that either there's an issue with docdir or I am missing something. After reading the docs (specially when you check the docs https://asciidoctor.org/docs/user-manual/#env-attributes) I understand that docdir should be independent of any other parameter.

The docdir effectively sets a jail that prevents you from including files in parent folders, but still within the project (when safe mode is safe or higher)

@mojavelinux based on that, do you think this could be an issue in core?

[nobecutan]

The behaviour of the command line tools asciidoctor and asciidoctor-pdf is the same as in the gradle case

docfile: /<path to example>/docs/other/other.adoc
docdir: /<path to example>/docs/other

I very much think this should also be the case with maven, since otherwise many includes behave differently.

[mojavelinux]

It's a long-standing and well-known issue that base_dir is improperly linked to docdir. If you are going to modify these values, it's best to run in unsafe mode. Otherwise, you get strange behavior.