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

Error reported during pdf generation on Windows 10 #614

Closed draithbal closed 1 year ago

draithbal commented 1 year ago

Thank you for taking your time to talk with us!

What is this issue about?

We are getting an ERROR report when generating a PDF from .adoc files on Windows 10. The PDF is in fact generated successfully. No error is reported when building on Linux from the same sources.

Description

We have a similar build which does not exhibit this behaviour, but we have not been able to find what the difference is. We can work around the problem by using the mvn -fae option, but we need to address this problem, as it will be customer visible.

The Error report text is as follows:

[ERROR] Failed to execute goal org.asciidoctor:asciidoctor-maven-plugin:2.2.2:process-asciidoc (create-main-pdf) on project codegen.cmd: Execution create-main-pdf of goal org.asciidoctor:asciidoctor-maven-plugin:2.2.2:process-asciidoc failed: org.jruby.exceptions.RuntimeError: (RuntimeError)
[ERROR] Ghostscript not found in your system environment (mswin32).
[ERROR] Install it and set the variable RGhost::Config::GS[:path] with the executable.
[ERROR] Example: RGhost::Config::GS[:path]='/path/to/my/gs' #unix-style
[ERROR]  RGhost::Config::GS[:path]="C:\\gs\\bin\\gswin32c.exe"  #windows-style

Installing Ruby and Ghostscript in the host environment, and updating the RGhost::Config::GS[:PATH] variable as suggested, has no effect. In any case, I understand that the host installation should not be used, as the asciidoctor plugin includes jruby.

Environment information

draithbal commented 1 year ago

Plugin configuration from the pom.xml:

      <plugin>
        <groupId>org.asciidoctor</groupId>
        <artifactId>asciidoctor-maven-plugin</artifactId>
        <version>2.2.2</version>
        <dependencies>
          <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-diagram</artifactId>
            <!-- there is an error with the 2.2.3 version of the plugin for a diagram for ComponentTypeService -->
            <version>2.2.1</version>
          </dependency>
          <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>2.1.6</version>
          </dependency>
        </dependencies>
        <executions>
          <execution>
            <id>create-diagrams</id>
            <phase>compile</phase>
            <goals>
              <goal>process-asciidoc</goal>
            </goals>
            <configuration>
              <sourceDirectory>${project.basedir}/../../Documentation/MetaModel/src</sourceDirectory>
              <requires>
                <require>asciidoctor-diagram</require>
              </requires>
              <outputDirectory>${project.basedir}/../../Documentation/MetaModel</outputDirectory>
              <backend>html5</backend>
            </configuration>
          </execution>
          <execution>
            <id>create-html</id>
            <phase>process-classes</phase>
            <goals>
              <goal>process-asciidoc</goal>
            </goals>
            <configuration>
              <sourceDirectory>${project.basedir}/../../Documentation/MetaModel/src</sourceDirectory>
              <requires>
                <require>asciidoctor-diagram</require>
              </requires>
              <outputDirectory>${project.basedir}/../../Documentation/MetaModel</outputDirectory>
              <backend>html5</backend>
            </configuration>
          </execution>
          <execution>
            <id>create-main-pdf</id>
            <phase>process-classes</phase>
            <goals>
              <goal>process-asciidoc</goal>
            </goals>
            <configuration>
              <sourceDirectory>${project.basedir}/../../Documentation/MetaModel/src</sourceDirectory>
              <sourceDocumentName>main.adoc</sourceDocumentName>
              <attributes>
                <!-- path for the generated diagrams -->
                <imagesdir>${project.basedir}/../../Documentation/MetaModel</imagesdir>
                <pdf-theme>bal-theme.yml</pdf-theme>
                <pdf-themesdir>${project.basedir}/../docgen-plugin/src/main/resources/themes/theme</pdf-themesdir>
                <pdf-fontsdir>${project.basedir}/../docgen-plugin/src/main/resources/themes/fonts</pdf-fontsdir>
              </attributes>
              <requires>
                <require>asciidoctor-diagram</require>
              </requires>
              <backend>pdf</backend>
              <doctype>book</doctype>
              <outputDirectory>${project.basedir}/../../Documentation/MetaModel</outputDirectory>
            </configuration>
          </execution>
        </executions>
      </plugin>
abelsromero commented 1 year ago

Thanks for the thorough detail! It seems related to https://docs.asciidoctor.org/pdf-converter/latest/optimize-pdf/, could it be the attribute optimize is being set somewhere else?

draithbal commented 1 year ago

Thanks for the quick response! - We don't have any instances of 'optimize' in our pom files (I'm assuming that's how it would be set?) I've also tried the solutions set out in https://github.com/asciidoctor/asciidoctor-maven-plugin/issues/527 but they have no effect.

abelsromero commented 1 year ago

Thanks for the quick response! - We don't have any instances of 'optimize' in our pom files (I'm assuming that's how it would be set?)

Would be odd, but maybe in a doc header like :optimize: ? I am trying to make sure it's not being enabled somehow, which would mean this is a "no issue".

I've also tried the solutions set out in #527 but they have no effect.

It's actually the opposite, you want to disable it. But I need to set up a Windows machine to test and see why the message is being reported.

draithbal commented 1 year ago

Aha! - The ":optimize:" attribute is set in some of the .adoc sources. These sources are generated, so we will have to update the generating code to eliminate those, to see if it fixes our problem. When you say it would be a "no issue", do you mean that optimization is not supported in Windows?

draithbal commented 1 year ago

Confirmed: Removing the :optimize: attribute solves the problem. It didn't make the pdf significantly bigger, either. Thanks for your help - we are unblocked.

abelsromero commented 1 year ago

Glad it was solved quickly.

When you say it would be a "no issue", do you mean that optimization is not supported in Windows?

No 😄 I meant that it's not really an issue (bug) in the code. If optimize is being enabled and then Asciidoctor complains it cannot find the required software, this is expected behavior.

draithbal commented 1 year ago

OK thanks - it's a mystery why this error wasn't reported on our Linux builds, though.

mojavelinux commented 1 year ago

Because the Linux machines likely have the requisite software (namely Ghostscript). See https://docs.asciidoctor.org/pdf-converter/latest/optimize-pdf/#convert-and-optimize

By the way, you can override an attribute set in a document from the plugin configuration. Though, in this case I would agree that the right choice is to remove the attribute from the documents as its something you want to control globally.

abelsromero commented 1 year ago

By the way, you can override an attribute set in a document from the plugin configuration.

Indeed. If you need the optimized way for the final build from CI, you can have a profile with the attribute and activate it on some condition https://maven.apache.org/guides/introduction/introduction-to-profiles.html.

draithbal commented 1 year ago

Thanks both. I don't know of any reason why we would need the 'optimize' setting, so having to set up the environment in Windows looks like an unnecessary hassle for users (and fragile, given that I failed to hit on the right setup).

mojavelinux commented 1 year ago

The reason optimize might be necessary is because the PDF generator that Asciidoctor PDF uses (Prawn) creates PDFs which are not very optimized (meaning larger than they need to be). Ghostscript comes along and cleans that up. The result is usually (but not always) smaller PDF files. The reader, however, would never notice a difference.