Add --with-jing option and exercise both validators in CI (#328)

* Add --with-jing option and exercise both validators in CI
* harden jing/java error handling

Author: jordikroon

.github/workflows/integrate.yaml

@@ -58,5 +58,8 @@ jobs:
           php doc-base/scripts/qa/extensions.xml.php --check
           php doc-base/scripts/qa/section-order.php
 
-      - name: "Build documentation for ${{ matrix.language }}"
-        run: "php doc-base/configure.php --disable-libxml-check --enable-xml-details --redirect-stderr-to-stdout --with-lang=${{ matrix.language }}"
+      - name: "Build documentation for ${{ matrix.language }} (jing)"
+        run: "php doc-base/configure.php --disable-libxml-check --enable-xml-details --redirect-stderr-to-stdout --with-jing=yes --with-lang=${{ matrix.language }}"
+
+      - name: "Build documentation for ${{ matrix.language }} (libxml)"
+        run: "php doc-base/configure.php --disable-libxml-check --enable-xml-details --redirect-stderr-to-stdout --with-jing=no --with-lang=${{ matrix.language }}"

configure.php

@@ -85,6 +85,8 @@ function usage() // {{{
   --with-php=PATH                Path to php CLI executable [detect]
   --with-lang=LANG               Language to build [{$acd['LANG']}]
   --with-partial=my-xml-id       Root ID to build (e.g. <book xml:id="MY-ID">) [{$acd['PARTIAL']}]
+  --with-jing=auto|yes|no        Validate with Jing (requires Java) instead of
+                                 libxml [{$acd['JING']}]
   --disable-broken-file-listing  Do not ignore translated files in
                                  broken-files.txt
   --disable-xpointer-reporting   Do not show XInclude/XPointer failures. Only effective
@@ -294,6 +296,7 @@ function find_xml_files($path) // {{{
     'TRANSLATION_ONLY_INCL_BEGIN' => '',
     'TRANSLATION_ONLY_INCL_END' => '',
     'XPOINTER_REPORTING' => 'yes',
+    'JING' => 'auto',
 ); // }}}
 
 $ac = $acd;
@@ -425,6 +428,14 @@ function find_xml_files($path) // {{{
             $ac['XPOINTER_REPORTING'] = $v;
             break;
 
+        case 'jing':
+            if (!in_array($v, ['auto', 'yes', 'no'], true)) {
+                errbox("Invalid value for --with-jing: $v (expected auto, yes or no)");
+                errors_are_bad(1);
+            }
+            $ac['JING'] = $v;
+            break;
+
         case '':
             break;
 
@@ -989,11 +1000,20 @@ function xml_validate( $dom )
 
     // Jing is faster, but depends on Java.
 
-    $out = null;
-    $ret = null;
-    exec( "java -version 2>&1" , $out , $ret );
+    $jing = $GLOBALS['ac']['JING'];
 
-    if ( $ret == 0 )
+    if ( $jing !== 'no' )
+    {
+        exec( "java -version 2>&1" , $out , $ret );
+        if ( $ret !== 0 && $jing === 'yes' )
+        {
+            errbox( "--with-jing=yes was given, but no working java executable was found." );
+            errors_are_bad( 1 );
+        }
+        $jing = $ret === 0 ? 'yes' : 'no';
+    }
+
+    if ( $jing === 'yes' )
         xml_validate_jing();
     else
         xml_validate_libxml( $dom );
@@ -1006,16 +1026,11 @@ function xml_validate_jing()
 
     echo "Validating temp/manual.xml (jing)... ";
 
-    $out = null;
-    $ret = null;
     $schema = RNG_SCHEMA_FILE;
-    $cmdJing = "java -Djdk.xml.totalEntitySizeLimit=300000 -jar {$srcdir}/docbook/jing.jar {$schema} {$idempath}";
+    $cmdJing = "java -Djdk.xml.totalEntitySizeLimit=300000 -jar {$srcdir}/docbook/jing.jar {$schema} {$idempath} 2>&1";
     exec( $cmdJing , $out , $ret );
 
-    if ( ! is_array( $out ) )
-        $out = [];
-
-    if ( $ret == 0 )
+    if ( $ret === 0 )
     {
         echo "done.\n";
         return;