[DOC-CVS] [doc-base] master: Third-party manual, doc-base side (#324)

Author: alfsb (alfsb)
Committer: GitHub (web-flow)
Pusher: alfsb
Date: 2026-07-31T09:47:52-03:00

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

Third-party manual, doc-base side (#324)

* Expose errors at XML assembly.
* Omit non-fixable warnings on first load.
* Prepare for file deletions.
* Move DOCTYPE configuration into doc-en/temp/.

Changed paths:
  M  configure.php


Diff:

diff --git a/configure.php b/configure.php
index 0c89f4b775..312aa2a5ab 100755
--- a/configure.php
+++ b/configure.php
@@ -192,6 +192,22 @@ function find_file($file_array) // {{{
     return '';
 } // }}}
 
+function print_dom_errors()
+{
+    $errors = libxml_get_errors();
+    foreach( $errors as $error )
+    {
+        $file = $error->file;
+        $line = $error->line;
+        $clmn = $error->column;
+        $prefix = $error->level === LIBXML_ERR_FATAL ? "FATAL" : "error";
+        $message = rtrim( $error->message );
+
+        if ( $file != '' )
+            print "[$prefix $file {$line}:{$clmn}] {$message}\n";
+    }
+}
+
 function print_xml_errors()
 {
     global $ac;
@@ -292,7 +308,6 @@ function find_xml_files($path) // {{{
     'OUTPUT_FILENAME' => $srcdir . '/.manual.xml',
     'GENERATE' => 'no',
     'STDERR_TO_STDOUT' => 'no',
-    'INPUT_FILENAME'   => 'manual.xml',
     'TRANSLATION_ONLY_INCL_BEGIN' => '',
     'TRANSLATION_ONLY_INCL_END' => '',
     'XPOINTER_REPORTING' => 'yes',
@@ -541,6 +556,8 @@ function git_clean()
 function git_status()
 {
     global $ac;
+    if ( $ac['quiet'] == 'yes' )
+        return;
 
     $repos = array();
     $repos['doc-base']  = $ac['basedir'];
@@ -564,38 +581,75 @@ function git_status()
 
 // DTD entity layer before first XML loading
 
-dtd_conf_entities();
 dtd_file_entities();
 dtd_text_entities();
+dtd_conf_entities();
 
 function dtd_conf_entities()
 {
+    function dtd_pe_body( string $filename = '' )
+    {
+        if ( file_exists( $filename ) )
+        {
+            $filename = realpain( $filename );
+            return "SYSTEM '$filename'";
+        }
+        return "''";
+    }
+
     global $ac;
     $lang = $ac["LANG"];
-    $conf = [];
 
-    $conf[] = "<!ENTITY LANG '$lang'>";
+    // When all is converted to XML Entities,
+    // all this can be reduced to:
+    // $ent1 = dtd_pe_body( __DIR__ . '/temp/text-entities.ent' );
+    // $ent2 = dtd_pe_body( __DIR__ . '/temp/file-entities.ent' );
 
-    if ( $lang != 'en' )
-    {
-        $trans1 = realpain( __DIR__ . "/../$lang/language-defs.ent" );
-        $trans2 = realpain( __DIR__ . "/../$lang/language-snippets.ent" );
-        $trans3 = realpain( __DIR__ . "/../$lang/extensions.ent" );
+    $baseEnt1 = dtd_pe_body( __DIR__ . '/entities/global.ent' );
+    $baseEnt2 = dtd_pe_body( __DIR__ . '/temp/file-entities.ent' );
+    $baseEnt3 = dtd_pe_body( __DIR__ . '/temp/entities.ent' );
 
-        $conf[] = "<!ENTITY % translation-defs       SYSTEM '$trans1'>";
-        $conf[] = "<!ENTITY % translation-snippets   SYSTEM '$trans2'>";
-        $conf[] = "<!ENTITY % translation-extensions SYSTEM '$trans3'>";
-    }
+    $langOne1 = dtd_pe_body( __DIR__ . '/../en/language-defs.ent' );
+    $langOne2 = dtd_pe_body( __DIR__ . '/../en/language-snippets.ent' );
+    $langOne3 = dtd_pe_body( __DIR__ . '/../en/extensions.ent' );
 
-    if ( $ac['CHMENABLED'] == 'yes' )
+    if ( $lang == 'en ' )
     {
-        $chmpath = realpain( __DIR__ . "/chm/manual.chm.xml" );
-        $conf[] = "<!ENTITY manual.chmonly SYSTEM '$chmpath'>";
+        $langTwo1 = dtd_pe_body();
+        $langTwo2 = dtd_pe_body();
+        $langTwo3 = dtd_pe_body();
     }
     else
-        $conf[] = "<!ENTITY manual.chmonly ''>";
+    {
+        $langTwo1 = dtd_pe_body( __DIR__ . "/../$lang/language-defs.ent" );
+        $langTwo2 = dtd_pe_body( __DIR__ . "/../$lang/language-snippets.ent" );
+        $langTwo3 = dtd_pe_body( __DIR__ . "/../$lang/extensions.ent" );
+    }
 
-    file_put_contents( __DIR__ . "/temp/manual.ent" , implode( "\n" , $conf ) );
+    if ( $ac['CHMENABLED'] == 'yes' )
+        $chmpath = dtd_pe_body( __DIR__ . "/chm/manual.chm.xml" );
+    else
+        $chmpath = dtd_pe_body();
+
+    $conf = [];
+    $conf[] = "<!ENTITY LANG '$lang'>";
+    $conf[] = "<!ENTITY manual.chmonly           $chmpath>";
+
+    $conf[] = "<!ENTITY % base-entities          $baseEnt1>";
+    $conf[] = "<!ENTITY % file-entities          $baseEnt2>";
+    $conf[] = "<!ENTITY % text-entities          $baseEnt3>";
+
+    $conf[] = "<!ENTITY % language-defs          $langOne1>";
+    $conf[] = "<!ENTITY % language-snippets      $langOne2>";
+    $conf[] = "<!ENTITY % language-extensions    $langOne3>";
+
+    $conf[] = "<!ENTITY % translation-defs       $langTwo1>";
+    $conf[] = "<!ENTITY % translation-snippets   $langTwo2>";
+    $conf[] = "<!ENTITY % translation-extensions $langTwo3>";
+
+    $outdir = __DIR__ . '/../en/temp';
+    realpain( $outdir , mkdir: true );
+    file_put_contents( "{$outdir}/conf.dtd" , implode( "\n" , $conf ) );
 }
 
 function dtd_file_entities()
@@ -663,7 +717,7 @@ function dtd_text_entities()
 }
 checkvalue($ac["GENERATE"]);
 
-function dom_load( DOMDocument $dom , string $filename , string $baseURI = "" ) : bool
+function dom_load( DOMDocument $dom , string $filename , bool $firstLoad ) : bool
 {
     $filename = realpath( $filename );
     $options = LIBXML_NOENT | LIBXML_COMPACT | LIBXML_BIGLINES | LIBXML_PARSEHUGE;
@@ -677,7 +731,7 @@ function dom_saveload( DOMDocument $dom , string $filename = "" ) : string
 
     libxml_clear_errors();
     $dom->save( $filename );
-    dom_load( $dom , $filename );
+    dom_load( $dom , $filename , false );
 
     return $filename;
 }
@@ -685,10 +739,11 @@ function dom_saveload( DOMDocument $dom , string $filename = "" ) : string
 echo "Creating monolithic temp/manual.xml... ";
 $dom = new DOMDocument();
 
-if ( dom_load( $dom , "{$ac['srcdir']}/{$ac["INPUT_FILENAME"]}" ) )
+if ( dom_load( $dom , __DIR__ . '/../en/manual.xml' , true ) )
 {
-    dom_saveload( $dom ); // correct file/line/column on error messages
     echo " done.\n";
+    print_dom_errors();
+    dom_saveload( $dom ); // correct file/line/column on error messages
 }
 else
 {