search

asciidoctor / asciidoctor-maven-plugin

A Maven plugin that uses Asciidoctor via JRuby to process AsciiDoc source files within the project.
http://asciidoctor.org
Apache License 2.0
318 stars 122 forks source link

Inconsistent directory base path when using include #605

Open PowerStat opened 2 years ago

PowerStat commented 2 years ago

What is this issue about?

Description

Regarding the description at:

https://docs.asciidoctor.org/asciidoc/latest/directives/include/

"Include file resolution If the include directive is used in the primary (top-level) document, relative paths are resolved relative to the base directory. (The base directory defaults to the directory of the primary 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."

I have found a bug regarding the above specification:

As an example please have a look at:

https://github.com/PowerStat/TemplateEngine/tree/master/src/ 

main/
site/asciidoc/
    index.adoc
    architecture/
      images/
      ...
      06_runtime_view.adoc
      ...
      config.adoc
test/java/de/powerstat/phplib/templateengine/test/
  TemplateEngineTests.java

When I now add the following include to 06_runtime_view.adoc:

include::../../../test/java/de/powerstat/phplib/templateengine/test/TemplateEngineTests.java[tag=NonAppendBlock] this results in the following output:

[INFO] --- asciidoctor-maven-plugin:2.2.2:process-asciidoc (output-html) @ templateengine ---
2022-11-06T09:30:47.104+01:00 [main] WARN FilenoUtil : Native subprocess control requires open access to the JDK IO subsystem
Pass '--add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED' to enable.
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] Using 'UTF-8' encoding to copy filtered properties files.
[INFO] Copying 1 resource
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\01_introduction_and_goals.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\02_architecture_constraints.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\03_system_scope_and_context.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\04_solution_strategy.adoc
[INFO] asciidoctor: DEBUG: Finding 'dot' in attributes
[INFO] asciidoctor: DEBUG: Finding 'dot' in environment
[INFO] asciidoctor: DEBUG: Found 'D:\Programme\Graphviz\bin/dot.EXE' in environment
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\05_building_block_view.adoc
[INFO] asciidoctor: DEBUG: Finding 'dot' in attributes
[INFO] asciidoctor: DEBUG: Finding 'dot' in environment
[INFO] asciidoctor: DEBUG: Found 'D:\Programme\Graphviz\bin/dot.EXE' in environment
[INFO] asciidoctor: ERROR: architecture\06_runtime_view.adoc: line 51: include file not found: D:/work/eclipse/java/TemplateEngine/test/java/de/powerstat/phplib/templateengine/test/TemplateEngineTests.java
[INFO] asciidoctor: DEBUG: architecture\06_runtime_view.adoc: line 51: unknown name for block macro:
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\06_runtime_view.adoc
[INFO] asciidoctor: DEBUG: Finding 'dot' in attributes
[INFO] asciidoctor: DEBUG: Finding 'dot' in environment
[INFO] asciidoctor: DEBUG: Found 'D:\Programme\Graphviz\bin/dot.EXE' in environment
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\07_deployment_view.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\08_concepts.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\09_architecture_decisions.adoc
[INFO] asciidoctor: DEBUG: Finding 'dot' in attributes
[INFO] asciidoctor: DEBUG: Finding 'dot' in environment
[INFO] asciidoctor: DEBUG: Found 'D:\Programme\Graphviz\bin/dot.EXE' in environment
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\10_quality_requirements.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\11_technical_risks.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\12_glossary.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\about-arc42.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\config.adoc
[INFO] asciidoctor: DEBUG: Finding 'dot' in attributes
[INFO] asciidoctor: DEBUG: Finding 'dot' in environment
[INFO] asciidoctor: DEBUG: Found 'D:\Programme\Graphviz\bin/dot.EXE' in environment
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\index.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\TemplateEngine.adoc

So now I change the include to (one less dir level up):

include::../../test/java/de/powerstat/phplib/templateengine/test/TemplateEngineTests.java[tag=NonAppendBlock]

This results in the following output:

[INFO] --- asciidoctor-maven-plugin:2.2.2:process-asciidoc (output-html) @ templateengine ---
2022-11-06T09:33:27.087+01:00 [main] WARN FilenoUtil : Native subprocess control requires open access to the JDK IO subsystem
Pass '--add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED' to enable.
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] Using 'UTF-8' encoding to copy filtered properties files.
[INFO] Copying 1 resource
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\01_introduction_and_goals.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\02_architecture_constraints.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\03_system_scope_and_context.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\04_solution_strategy.adoc
[INFO] asciidoctor: DEBUG: Finding 'dot' in attributes
[INFO] asciidoctor: DEBUG: Finding 'dot' in environment
[INFO] asciidoctor: DEBUG: Found 'D:\Programme\Graphviz\bin/dot.EXE' in environment
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\05_building_block_view.adoc
[INFO] asciidoctor: DEBUG: Finding 'dot' in attributes
[INFO] asciidoctor: DEBUG: Finding 'dot' in environment
[INFO] asciidoctor: DEBUG: Found 'D:\Programme\Graphviz\bin/dot.EXE' in environment
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\06_runtime_view.adoc
[INFO] asciidoctor: DEBUG: Finding 'dot' in attributes
[INFO] asciidoctor: DEBUG: Finding 'dot' in environment
[INFO] asciidoctor: DEBUG: Found 'D:\Programme\Graphviz\bin/dot.EXE' in environment
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\07_deployment_view.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\08_concepts.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\09_architecture_decisions.adoc
[INFO] asciidoctor: DEBUG: Finding 'dot' in attributes
[INFO] asciidoctor: DEBUG: Finding 'dot' in environment
[INFO] asciidoctor: DEBUG: Found 'D:\Programme\Graphviz\bin/dot.EXE' in environment
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\10_quality_requirements.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\11_technical_risks.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\12_glossary.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\about-arc42.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\architecture\config.adoc
[INFO] asciidoctor: DEBUG: Finding 'dot' in attributes
[INFO] asciidoctor: DEBUG: Finding 'dot' in environment
[INFO] asciidoctor: DEBUG: Found 'D:\Programme\Graphviz\bin/dot.EXE' in environment
[INFO] asciidoctor: ERROR: architecture\06_runtime_view.adoc: line 51: include file not found: D:/work/eclipse/java/TemplateEngine/src/site/test/java/de/powerstat/phplib/templateengine/test/TemplateEngineTests.java
[INFO] asciidoctor: DEBUG: index.adoc: line 65: unknown name for block macro:
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\index.adoc
[INFO] Converted D:\work\eclipse\java\TemplateEngine\src\site\asciidoc\TemplateEngine.adoc

So now lets compare the error (path) from both outputs:

[INFO] asciidoctor: ERROR: architecture\06_runtime_view.adoc: line 51: include file not found: D:/work/eclipse/java/TemplateEngine/test/java/de/powerstat/phplib/templateengine/test/TemplateEngineTests.java src is missing in the path [INFO] asciidoctor: ERROR: architecture\06_runtime_view.adoc: line 51: include file not found: D:/work/eclipse/java/TemplateEngine/src/site/test/java/de/powerstat/phplib/templateengine/test/TemplateEngineTests.java site is to much in the path

What you can see is that in both cases the path is wrong! But the interesting thing is that this happens at two different positions in the output. So I assume that a two phase processing happens. That results to a bug, because in both phases you are working with different base directories!

In the first pass with: projectBase/src/site/asciidoc/ (like set in sourceDirectory - the only correct value) In the second pass with: projectBase/src/site/asciidoc/architecture/ (Not sure if this is the config.adoc path or the one of the 06_runtime_view.adoc - wrong in both cases)

Would be nice to fix this bug to allow asciidoc includes within subdirectory structures. Might be an upstream issue for the maven plugin.

The same happens under Windows as well as on MacOS (so I assume also on Linux).

My plugin configuration looks as follows:

    <plugin>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoctor-maven-plugin</artifactId>
      <version>2.2.2</version>
      <executions>
        <execution>
          <id>output-html</id>
          <phase>generate-resources</phase>
          <goals>
            <goal>process-asciidoc</goal>
          </goals>
          <configuration>
            <sourceDirectory>src/site/asciidoc</sourceDirectory>
            <backend>xhtml5</backend>
            <sourceHighlighter>coderay</sourceHighlighter>
            <attributes>
              <toc>left</toc>
            </attributes>
            <requires>
              <require>asciidoctor-diagram</require>
            </requires>
          </configuration>
        </execution>
      </executions>

      <dependencies>
        <dependency>
          <groupId>org.asciidoctor</groupId>
          <artifactId>asciidoctorj-pdf</artifactId>
          <version>2.3.3</version>
        </dependency>

        <dependency>
          <groupId>org.asciidoctor</groupId>
          <artifactId>asciidoctorj-diagram</artifactId>
          <version>2.2.3</version>
        </dependency>

      </dependencies>

    </plugin>

Environment information

abelsromero commented 2 years ago

Thanks a lot for the thorough detail, this helps a lot!

This case is expected behaviour but can be improved and changed since we are working towards 3.x.x. The maven-plugin and site modules work differently than the Ruby cli because the nature is slightly different. Here the goal is converting sets of documents, so some common configurations are kept across them to simplify. Similar to how you have a single catalog for all images with a well-defined root path. But I admit this can be opinionated and it's normal to get confused.

You can see in the note below the Configuration example https://docs.asciidoctor.org/maven-tools/latest/site-integration/setup-and-configuration/#configuration. There it's mentioned all sources use the same base_dir 'src/site/asciidoc'.

Would be nice to fix this bug to allow asciidoc includes within subdirectory structures. Might be an upstream issue for the maven plugin.

The maven-plugin (that is the maven-plugin when used ouside maven-site-plugin) has an additional option close to what I think you expect called relativeBaseDir https://docs.asciidoctor.org/maven-tools/latest/plugin/goals/process-asciidoc/#configuration-relativeBaseDir. I am thinking we could port that over to the site module(s).

Said that, the conversion runs once, so the log appearing twice is a surprise. I need to look further into that.