Documentation modules: 'administration-guide' and 'error-references-module' fail to build on Windows

[escay]

Environment Details

• GlassFish Version (and build number): glassfish master (7.0.13-SNAPSHOT 418e007)
• JDK version: openjdk version "17.0.10" 2024-01-16
• OS: Windows 11

---

Problem Description

mvn install fails on Windows for two modules:

/glassfish/docs/administration-guide
/glassfish/docs/error-messages-reference

Both fail the same:

djesc@Z13 MINGW64 /c/github/glassfish/docs/administration-guide (master)
$ mvn install
[INFO] Scanning for projects...
[INFO]
[INFO] ------------< org.glassfish.main.docs:administration-guide >------------
[INFO] Building Eclipse GlassFish Administration Guide, Release 7 7.0.13-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- enforcer:3.1.0:enforce (enforce-maven) @ administration-guide ---
[INFO]
[INFO] --- osgiversion:3.0.6:compute-osgi-version (generate-osgi-version-property) @ administration-guide ---
[INFO]
[INFO] --- compiler:3.11.0:compile (generate-hk2-config) @ administration-guide ---
[INFO] No sources to compile
[INFO]
[INFO] --- glassfish-doc:1.3:book (generate-book) @ administration-guide ---
[INFO]
[INFO] --- build-helper:3.4.0:add-resource (add-resource) @ administration-guide ---
[INFO]
[INFO] --- build-helper:3.4.0:add-resource (add-legal-resource) @ administration-guide ---
[INFO]
[INFO] --- dependency:3.6.1:unpack (unpack-resource) @ administration-guide ---
[INFO] Configured Artifact: org.glassfish.main:nucleus-parent:resources:7.0.13-SNAPSHOT:zip
[INFO]
[INFO] --- resources:3.3.1:resources (default-resources) @ administration-guide ---
[INFO] skip non existing resourceDirectory C:\github\glassfish\docs\administration-guide\src\main\resources
[INFO] skip non existing resourceDirectory C:\github\glassfish\docs\administration-guide\src\main\manpages
[INFO] Copying 2 resources from target\common-resources\legal to target\classes\META-INF
[INFO]
[INFO] --- compiler:3.11.0:compile (default-compile) @ administration-guide ---
[INFO] No sources to compile
[INFO]
[INFO] --- asciidoctor:2.2.4:process-asciidoc (generate-html-doc) @ administration-guide ---
2024-02-04T20:12:49.480+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 0 resource
feb. 04, 2024 8:12:59 P.M. org.asciidoctor.jruby.internal.JRubyAsciidoctor convertFile
SEVERE: (ArgumentError) invalid byte sequence in UTF-8
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  21.311 s
[INFO] Finished at: 2024-02-04T20:12:59+01:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.asciidoctor:asciidoctor-maven-plugin:2.2.4:process-asciidoc (generate-html-doc) on project administration-guide: Execution generate-html-doc of goal org.asciidoctor:asciidoctor-maven-plugin:2.2.4:process-asciidoc failed: org.jruby.exceptions.ArgumentError: (ArgumentError) invalid byte sequence in UTF-8 -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/PluginExecutionException

With-X debugging enabled:

Caused by: org.apache.maven.plugin.PluginExecutionException: Execution generate-html-doc of goal org.asciidoctor:asciidoctor-maven-plugin:2.2.4:process-asciidoc failed: org.jruby.exceptions.ArgumentError: (ArgumentError) invalid byte sequence in UTF-8
    at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo (DefaultBuildPluginManager.java:133)
...
    at org.codehaus.plexus.classworlds.launcher.Launcher.main (Launcher.java:348)
Caused by: org.asciidoctor.jruby.internal.AsciidoctorCoreException: org.jruby.exceptions.ArgumentError: (ArgumentError) invalid byte sequence in UTF-8
    at org.asciidoctor.jruby.internal.JRubyAsciidoctor.convertFile (JRubyAsciidoctor.java:412)
    at org.asciidoctor.jruby.internal.JRubyAsciidoctor.convertFile (JRubyAsciidoctor.java:378)
    at org.asciidoctor.maven.AsciidoctorMojo.convertFile (AsciidoctorMojo.java:451)
...
    at org.codehaus.plexus.classworlds.launcher.Launcher.main (Launcher.java:348)
Caused by: org.jruby.exceptions.ArgumentError: (ArgumentError) invalid byte sequence in UTF-8
    at org.jruby.RubyRegexp.match? (org/jruby/RubyRegexp.java:1170)
...
    at RUBY.content (uri:classloader:/gems/asciidoctor-2.0.18/lib/asciidoctor/block.rb:113)

Steps to reproduce

Follow steps from: https://glassfish.org/pr_workflow
and run mvn install on /docs module, or on the root and wait a bit longer.

Note: problem does not occur against exactly the same source code tree but building it inside Ubuntu in WSL (version 1) on Windows.
But I do not prefer to run it in WLS, since the build performance is a bit lower.

Note: my git config is using core.autocrlf=true

Note: "git for windows bash" locale is UTF-8:
$ locale
LANG=
LC_CTYPE="en_GB.UTF-8"
LC_NUMERIC="C.UTF-8"
LC_TIME="C.UTF-8"
LC_COLLATE="C.UTF-8"
LC_MONETARY="C.UTF-8"
LC_MESSAGES="C.UTF-8"
LC_ALL=

Impact of Issue

Cannot build documentation modules under Windows, not using "git for windows bash" and not when using cmd.exe console.

Fix

Looking for non UTF-8 characters in al *.adoc files and replacing them with an ASCII character solved the issue for me.
I did not pin it down to one exact character. I only tested administration-guide module to see if it solved the issue.

Note: there are many issues online of similar JRuby exceptions, Asciidoctor issues mention to use UTF-8 files with correct content. And that seems to work.

[escay]

I found the files in module 'administration-guide' using regular expression:
[^\x00-\x7F]+
and ran into:

replacing these fixes the issue.

[escay]

2 characters in logging.adoc file cause administration-guide to fail:

Changing ~cec to cec, like:

drwxrwxr-x 14 admin admin   4096 cec 29 21:21 ../
-rw-rw-r--  1 admin admin   2521 srp  3 18:18 server.log
-rw-rw-r--  1 admin admin 191391 cec 29 21:21 server.log_2022-07-29T21-21-54
-rw-rw-r--  1 admin admin  24920 srp  3 18:18 server.log_2022-08-03T18-18-38

makes building this module succeed.

[escay]

The 'error-references-module' module has:

Changing line:
”xref:administration-guide.adoc#administering-the-logging-service[Administering the Logging Service”] in {productName} Administration Guide.
to:
xref:administration-guide.adoc#administering-the-logging-service[Administering the Logging Service] in {productName} Administration Guide.
makes the module compile.