Unexpected warnings "Duplicated destination found: overwriting file: ..."

[kriegaex]

Thank you for taking your time to talk with us!

What is this issue about?

• Bug report
• Feature request
• Question (or bug report, not sure yet)

Description

My POM looks like this:

<pluginManagement>
  <plugins>
    <plugin>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoctor-maven-plugin</artifactId>
      <version>2.2.4</version>
      <configuration>
        <attributes>
          <source-highlighter>coderay</source-highlighter>
          <toc>left</toc>
          <icons>font</icons>
        </attributes>
      </configuration>
      <!-- TODO: Remove dependency after https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/553 fix -->
      <dependencies>
        <dependency>
          <groupId>org.jruby</groupId>
          <artifactId>jruby</artifactId>
          <version>9.4.5.0</version>
        </dependency>
      </dependencies>
    </plugin>
  </plugins>
</pluginManagement>

<plugins>
  <plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <executions>
      <execution>
        <id>create-asciidoc</id>
        <phase>generate-resources</phase>
        <goals>
          <goal>process-asciidoc</goal>
        </goals>
        <configuration>
          <sourceDirectory>${project.basedir}</sourceDirectory>
          <outputDirectory>${project.build.directory}/html</outputDirectory>
          <preserveDirectories>true</preserveDirectories>
          <relativeBaseDir>true</relativeBaseDir>
          <resources>
            <resource>
              <!-- Mandatory, even though identical to 'sourceDirectory' -->
              <directory>${project.basedir}</directory>
              <excludes>
                <!-- Generally excluded file extensions -->
                <exclude>**/*.doc</exclude>
                <exclude>**/*.vsd</exclude>
                <!-- Files excluded in root directory -->
                <exclude>*.iml</exclude>
                <exclude>pom.xml*</exclude>
                <exclude>build.xml</exclude>
                <exclude>docs.build.properties</exclude>
                <!-- Files excluded in subdirectories -->
                <exclude>developer/*.txt</exclude>
                <exclude>developer/ajdt/**</exclude>
                <exclude>developer/traces/**</exclude>
                <exclude>install/**</exclude>
                <exclude>sandbox/**</exclude>
                <exclude>src/**</exclude>
                <exclude>teaching/**</exclude>
                <exclude>test/**</exclude>
              </excludes>
            </resource>
          </resources>
        </configuration>
      </execution>
    </executions>
  </plugin>
</plugins>

There are a few ADOC file in the module root and a few dozen more in several subdirectories. Per subdirectory, there usually is one main ADOC creating a TOC and simply linking to subpages via xref: and another variant of the main ADOC using include::directives. As far as I can see, the output HTML files are created correctly. Anyway, I see several log messages like this:

...
[INFO] Converted C:\Users\alexa\Documents\java-src\AspectJ\docs\devguide\devguide.adoc
[WARNING] Duplicated destination found: overwriting file: C:\Users\alexa\Documents\java-src\AspectJ\docs\index.adoc
[INFO] Converted C:\Users\alexa\Documents\java-src\AspectJ\docs\devguide\index.adoc
[WARNING] Duplicated destination found: overwriting file: C:\Users\alexa\Documents\java-src\AspectJ\docs\ltw.adoc
[INFO] Converted C:\Users\alexa\Documents\java-src\AspectJ\docs\devguide\ltw.adoc
[INFO] Converted C:\Users\alexa\Documents\java-src\AspectJ\docs\devguide\tools-intro.adoc
[INFO] Converted C:\Users\alexa\Documents\java-src\AspectJ\docs\examples\spacewar\README.adoc
[INFO] Converted C:\Users\alexa\Documents\java-src\AspectJ\docs\faq\faq.adoc
[WARNING] Duplicated destination found: overwriting file: C:\Users\alexa\Documents\java-src\AspectJ\docs\index.adoc
[INFO] Converted C:\Users\alexa\Documents\java-src\AspectJ\docs\index.adoc
[INFO] Converted C:\Users\alexa\Documents\java-src\AspectJ\docs\LICENSE-AspectJ.adoc
[INFO] Converted C:\Users\alexa\Documents\java-src\AspectJ\docs\pdguide\ajcore.adoc
[WARNING] Duplicated destination found: overwriting file: C:\Users\alexa\Documents\java-src\AspectJ\docs\index.adoc
...

This is irritating for several reasons:

• The paths in the warnings are from the source directory, not the target directory.
• The paths are mostly fantasy paths, i.e. while e.g. ltw.adoc exists in several subdirectories, it certainly does not exist directly in the source base path C:\Users\alexa\Documents\java-src\AspectJ\docs´. Only an index.adoc is there (and also in some subdirectories).
• If anything would be overwritten - which does not seem to be the case - it should be under C:\Users\alexa\Documents\java-src\AspectJ\docs\target\html, as specified in the config.

IMO, the warnings are just false. Even if they were not, the printed fantasy paths do not make any sense. I strongly hope that the plugin does not write any intermediary output into the source folder.

Environment information

• asciidoctor-maven-plugin version: 2.2.4

• asciidoctorj version: ?

• Maven, Java and OS version: Maven 3.6.3, 3.9.5, Java 21, Windows 10 Pro

[abelsromero]

Thanks! The issue is with the validation, not the real paths. Internally it's comparing with the source filename only "index.adoc" because the plugin is still checking the deprecated destinationDir instead of toDir and that changed for newer AsciidoctorJ versions and destionationDir is empty now, hence only comparing with the filename...it's funny when innocent changes come back to bite you 😅

If you are wondering "why a deprecation is breaking things", the plugin uses the internal asciidoctor Map to check the configuration and we haven't been able to find a solution to provide a safe Java API but also provide the information for users needing it. Precisely to avoid these cases.

The issue is already fixed in main branch in which we already removed deprecated references, for 2.2.x we'd still need to support using destinationDir.

Btw, a suggestions, don't use the basedir as in <sourceDirectory>${project.basedir}</sourceDirectory> this means all files will be scanned for sources (both "src" and "target" will be treated as candidates). Better put docs in a sub-directory. If there's something in the root you cannot move, define another plugin execution using sourceDocumentName.

[abelsromero]

Btw, if you already have "modules" with dedicated TOC, you may want to have a look at Antora. Seems you are already halfway through the requirements.

The docs site is built with it https://docs.asciidoctor.org/.

[kriegaex]

The issue is with the validation, not the real paths.

Well, then why are those paths - partly fantasy paths, like I said, which makes it worse - displayed in the warnings? You cannot expect users to understand the problem like this. Warnings ought to help users to solve problems, not confuse them.

Internally it's comparing with the source filename only "index.adoc"

That does not sound so helpful.

because the plugin is still checking the deprecated destinationDir instead of toDir and that changed for newer AsciidoctorJ versions and destionationDir is empty now, hence only comparing with the filename...

Sorry, I think I do not fully understand that explanation, because I actually never have used Asciidoctor or Asciidoctorj from the command line. The Maven plugin is my first contact. I.e., I only know the options described here. How exactly they map to lower-level CLI options, I have no idea.

Btw, a suggestions, don't use the basedir as in <sourceDirectory>${project.basedir}</sourceDirectory> this means all files will be scanned for sources (both "src" and "target" will be treated as candidates).

😱

Better put docs in a sub-directory.

That might help, but I wanted to avoid it and not change the directory structure in place since 2004 or so a lot. FYI, I am converting docs generation from a mix of ancient XML DocBook files and another bunch of hand-written HTML to asciidoc. The docs are converted already and looking fine, now I just want to add HTML and PDF generation to the build (again). Anyway, I have come so far already, maybe in the end I will have to transition to a "convention over configuration" approach with a more standardised directory layout. Thank you so much for your advice.

[kriegaex]

Looking good in 2.2.5, the warnings are gone. Thank you very much. 😊🎈