Post check individual XML files for know issues (#241)

* Post check individual XML files for know issues
* Autofix option for simple encoding issues
* Remove debug output
* Hint the complete script path
* Hint the effect of failed XInclude

Author: alfsb

configure.php

@@ -712,9 +712,28 @@ function dom_saveload( DOMDocument $dom , string $filename = "" ) : string
 {
     echo "failed.\n";
     print_xml_errors();
+    individual_xml_broken_check();
     errors_are_bad(1);
 }
 
+function individual_xml_broken_check()
+{
+    $cmd = array();
+    $cmd[] = $GLOBALS['ac']['PHP'];
+    $cmd[] = __DIR__ . "/scripts/broken.php";
+    $cmd[] = $GLOBALS['ac']['LANG'];
+    foreach ( $cmd as & $part )
+        $part = escapeshellarg( $part );
+    $ret = 0;
+    $cmd = implode( ' ' , $cmd );
+    passthru( $cmd , $ret );
+    if ( $ret != 0 )
+    {
+        echo "doc-base/scripts/broken.php FAILED.\n";
+        exit( 1 );
+    }
+}
+
 echo "Running XInclude/XPointer... ";
 
 $total  = xinclude_run_byid( $dom );
@@ -823,8 +842,11 @@ function xinclude_residual_fixup( DOMDocument $dom )
     foreach( $nodes as $node )
     {
         if ( $count === 0 )
-            echo "\nFailed XInclude, inspect {$debugFile} for context:\n";
-        echo "  {$node->getAttribute("xpointer")}\n";
+        {
+            echo "\nFailed XIncludes, manual parts will be missing.";
+            echo " Inspect {$debugFile} for context. Failed targets are:\n";
+        }
+        echo "- {$node->getAttribute("xpointer")}\n";
         $count++;
 
         $fixup = null;
@@ -1159,8 +1181,5 @@ function phd_version()
 
 CAT;
 
-if (function_exists('proc_nice') && !is_windows()) {
-    echo " (Run `nice php $_SERVER[SCRIPT_NAME]` next time!)\n";
-}
-
-exit(0); // Tell the shell that this script finished successfully.
+individual_xml_broken_check();
+exit(0); // Finished successfully.

scripts/broken.php

@@ -28,8 +28,19 @@
 
 if ( count( $argv ) < 2 )
     print_usage_exit( $argv[0] );
-
 array_shift( $argv );
+
+$dos2unix = false;
+foreach( $argv as & $arg )
+{
+    if ( $arg == "--dos2unix" )
+    {
+        $dos2unix = true;
+        $arg = null;
+    }
+}
+$argv = array_filter( $argv );
+
 foreach( $argv as $arg )
 {
     if ( file_exists( $arg ) )
@@ -46,7 +57,7 @@
 function print_usage_exit( $cmd )
 {
     fwrite( STDERR , "  Wrong paramater count. Usage:\n" );
-    fwrite( STDERR , "    {$cmd} path:\n" );
+    fwrite( STDERR , "    {$cmd} [--dos2unix] path\n" );
     exit;
 }
 
@@ -83,17 +94,21 @@ function testFile( string $filename , bool $fragment = false )
     if ( str_starts_with( $contents , b"\xEF\xBB\xBF" ) )
     {
         echo "Wrong XML file:\n";
+        echo "  Issue: XML file with BOM. Several tools may misbehave.\n";
         echo "  Path:  $filename\n";
-        echo "  Error: XML file with BOM. Several tools may misbehave.\n";
+        echo "  Hint:  You can try autofix this with 'doc-base/scripts/broken.php --dos2unix langdir'.\n";
         echo "\n";
+        autofix_dos2unix( $filename );
     }
 
     if ( PHP_EOL == "\n" && str_contains( $contents , "\r") )
     {
         echo "Wrong XML file:\n";
+        echo "  Issue: XML file contains \\r. Several tools may misbehave.\n";
         echo "  Path:  $filename\n";
-        echo "  Error: XML file contains \\r. Several tools may misbehave.\n";
+        echo "  Hint:  You can try autofix this with 'doc-base/scripts/broken.php --dos2unix langdir'.\n";
         echo "\n";
+        autofix_dos2unix( $filename );
     }
 
     static $prefix = "", $suffix = "", $extra = "";
@@ -128,10 +143,10 @@ function testFile( string $filename , bool $fragment = false )
         $lin = $error->line;
         $col = $error->column;
         echo "Broken XML file:\n";
+        echo "  Issue: $message\n";
         echo "  Path:  $filename [$lin,$col]\n";
-        echo "  Error: $message\n";
         if ( $hintFragDir )
-            echo "  Hint:  Dir is marked with .xmlfragmentdir on doc-en? If not, check entity references.\n";
+            echo "  Hint:  See source comments about '.xmlfragmentdir', or check entity references outside enclosing tags.\n";
         echo "\n";
         return;
     }
@@ -169,3 +184,13 @@ function testDir( string $dir )
     foreach( $subdirs as $dir )
         testDir( $dir );
 }
+
+function autofix_dos2unix( string $filename )
+{
+    if ( $GLOBALS['dos2unix'] )
+    {
+        $cmd = "dos2unix -r " . escapeshellarg( $filename );
+        system( $cmd );
+        echo "\n";
+    }
+}