Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Inconsistent directory base path when using include #605

Open
1 of 3 tasks
PowerStat opened this issue Nov 6, 2022 · 1 comment
Open
1 of 3 tasks

Inconsistent directory base path when using include #605

PowerStat opened this issue Nov 6, 2022 · 1 comment
Labels
enhancement

Comments

@PowerStat
Copy link

PowerStat commented Nov 6, 2022 •
edited
Loading

What is this issue about?

  • Bug report
  • Feature request
  • Question

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

  • asciidoctor-maven-plugin version:2.2.2
  • asciidoctorj version: ___
  • Maven, Java and OS version: 3.6.1, 11/17, Windows 10, MacOS ?
@abelsromero
Copy link
Member

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@abelsromero @PowerStat