[DOC-CVS] [doc-base] master: Add --with-jing option and exercise both validators in CI (#328)

Author: Jordi Kroon (jordikroon)
Committer: GitHub (web-flow)
Pusher: jordikroon
Date: 2026-07-25T11:24:09+02:00

Commit: https://github.com/php/doc-base/commit/ba8225725f394cbff6d88490640965268e84a0c2
Raw diff: https://github.com/php/doc-base/commit/ba8225725f394cbff6d88490640965268e84a0c2.diff

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

Changed paths:
  M  .github/workflows/integrate.yaml
  M  configure.php


Diff:

diff --git a/.github/workflows/integrate.yaml b/.github/workflows/integrate.yaml
index ec7568bd84..cf0350c606 100644
--- a/.github/workflows/integrate.yaml
+++ b/.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 }}"
diff --git a/configure.php b/configure.php
index 1a07591639..047299e8c8 100755
--- a/configure.php
+++ b/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;