[DOC-CVS] [doc-base] master: Minimize DTD subsystem (#336)
[email protected] (alfsb via GitHub)
| Newsgroups | php.doc.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: alfsb (alfsb) Committer: GitHub (web-flow) Pusher: alfsb Date: 2026-08-13T12:18:36-03:00 Commit: https://github.com/php/doc-base/commit/738f18cf429d45eed2698b8cd77d3364ea87f085 Raw diff: https://github.com/php/doc-base/commit/738f18cf429d45eed2698b8cd77d3364ea87f085.diff Minimize DTD subsystem (#336) * Minimize DTD subsystem * Note the soft exclusion of funcindex.xml Co-authored-by: André L F S Bacci <[email protected]> Co-authored-by: Louis-Arnaud <[email protected]> Changed paths: M configure.php M funcindex.xml M manual.xml M scripts/file-entities.php M scripts/text-entities.php Diff: diff --git a/configure.php b/configure.php index e244f9b14d..49cd55922d 100755 --- a/configure.php +++ b/configure.php @@ -611,73 +611,51 @@ function git_status() function dtd_conf_entities() { - function dtd_pe_body( string $filename = '' ) + function dtd_pe_load( string $name , string $filename ) : string { if ( file_exists( $filename ) ) { $filename = realpain( $filename ); - return "SYSTEM '$filename'"; + $ret = "<!ENTITY % $name SYSTEM '{$filename}'>\n"; + $ret .= "%{$name};\n\n"; + return $ret; } - return "''"; + return ""; } - global $ac; - $lang = $ac["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' ); - - $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' ); + // After DTD entities are converted to XML, all this can be reduced to: + // $contents .= dtd_pe_load( "text-entities" , __DIR__ . '/temp/text-entities.dtd' ); + // $contents .= dtd_pe_load( "file-entities" , __DIR__ . '/temp/file-entities.dtd' ); - $base = $ac['LANG_BASE_DIR']; + $base = $GLOBALS['ac']['LANG_BASE_DIR']; + $lang = $GLOBALS['ac']["LANG"]; - $langOne1 = dtd_pe_body( __DIR__ . "/../$base/language-defs.ent" ); - $langOne2 = dtd_pe_body( __DIR__ . "/../$base/language-snippets.ent" ); - $langOne3 = dtd_pe_body( __DIR__ . "/../$base/extensions.ent" ); + $contents = "<!ENTITY LANG '{$lang}'>\n\n"; - if ( is_single_language() ) - { - $langTwo1 = dtd_pe_body(); - $langTwo2 = dtd_pe_body(); - $langTwo3 = dtd_pe_body(); - } - else + if ( ! is_single_language() ) { - $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" ); + $contents .= dtd_pe_load( "translation-defs" , __DIR__ . "/../$lang/language-defs.ent" ); + $contents .= dtd_pe_load( "translation-snippets" , __DIR__ . "/../$lang/language-snippets.ent" ); + $contents .= dtd_pe_load( "translation-extensions" , __DIR__ . "/../$lang/extensions.ent" ); } + $contents .= dtd_pe_load( "language-defs" , __DIR__ . "/../$base/language-defs.ent" ); + $contents .= dtd_pe_load( "language-snippets" , __DIR__ . "/../$base/language-snippets.ent" ); + $contents .= dtd_pe_load( "language-extensions" , __DIR__ . "/../$base/extensions.ent" ); - if ( $ac['CHMENABLED'] == 'yes' ) - $chmpath = dtd_pe_body( __DIR__ . "/chm/manual.chm.xml" ); - else - $chmpath = dtd_pe_body(); - - $conf = []; - - $conf[] = "<!ENTITY LANG '$lang'>"; + $contents .= dtd_pe_load( "base-entities" , __DIR__ . '/entities/global.ent' ); + $contents .= dtd_pe_load( "text-entities" , __DIR__ . '/temp/text-entities.dtd' ); + $contents .= dtd_pe_load( "file-entities" , __DIR__ . '/temp/file-entities.dtd' ); - $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>"; + if ( $GLOBALS['ac']['CHMENABLED'] == 'yes' ) + $contents .= dtd_pe_load( "manual.chmonly" , __DIR__ . "/chm/manual.chm.xml" ); + else + $contents .= "<!ENTITY manual.chmonly ''>\n"; - $conf[] = "<!ENTITY % translation-defs $langTwo1>"; - $conf[] = "<!ENTITY % translation-snippets $langTwo2>"; - $conf[] = "<!ENTITY % translation-extensions $langTwo3>"; + $langTempDir = __DIR__ . "/../$base/temp"; + realpain( $langTempDir , mkdir: true ); - $outdir = __DIR__ . "/../$base/temp"; - realpain( $outdir , mkdir: true ); - file_put_contents( "{$outdir}/conf.dtd" , implode( "\n" , $conf ) ); + file_put_contents( __DIR__ . "/temp/lang" , $lang ); + file_put_contents( "{$langTempDir}/conf.dtd" , $contents ); } function dtd_file_entities() @@ -750,7 +728,10 @@ function dom_load( DOMDocument $dom , string $filename , bool $firstLoad ) : boo { $filename = realpath( $filename ); $options = LIBXML_NOENT | LIBXML_COMPACT | LIBXML_BIGLINES | LIBXML_PARSEHUGE; - return $dom->load( $filename , $options ); + $ret = $dom->load( $filename , $options ); + if ( $ret ) + $dom->documentElement->setAttribute( 'xml:lang' , $GLOBALS['ac']["LANG"] ); + return $ret; } function dom_saveload( DOMDocument $dom , string $filename = "" ) : string @@ -922,7 +903,7 @@ function xinclude_run_xpointer( DOMDocument $dom ) : int function xinclude_residual_fixup( DOMDocument $dom ) { - // XInclude failures are soft errors on translations, so we replace + // XInclude failures are soft errors on translations, so we erase // residual XInclude tags on translations to keep them validating. $fixups = 0; diff --git a/funcindex.xml b/funcindex.xml index 9f1e4c9ab9..4e0fdf51b3 100644 --- a/funcindex.xml +++ b/funcindex.xml @@ -1,4 +1,16 @@ <?xml version="1.0" encoding="UTF-8"?> + +<!-- + +This file is now being ignored, after DTD subsystem minimization. +Yet, it is mentioned by name in configure.php, file-entities.php +and in PhD repo. All cases are related to PhD, but configure.php +includes this file as is, before any PhD stuff has a chance to run. + +After it is removed by name from all these points, it can be deleted. + +--> + <!-- DO NOT EDIT THIS FILE. The index info comes from PhD --> <appendix xmlns="http://docbook.org/ns/docbook" xml:id="indexes"> <title>&IndexListing;</title> diff --git a/manual.xml b/manual.xml index 42ce09da9d..cae7b040b5 100644 --- a/manual.xml +++ b/manual.xml @@ -1,4 +1,19 @@ <?xml version="1.0" encoding="utf-8"?> + + + +This file is now being ignored, after third-party manual split. +Yet, it is mentioned by name in configure.php, on PhD related +code paths. + +After these code paths are updated or moved into PhD, this can +be deleted. + +Keep these comments outside SGML comment tags, as to make this +file invalid for XML loading. + + + <!DOCTYPE PHPDOC [ <!-- Parameter entities used to configure manual.xml --> diff --git a/scripts/file-entities.php b/scripts/file-entities.php index 4e4211cf06..a0b5a47da7 100644 --- a/scripts/file-entities.php +++ b/scripts/file-entities.php @@ -29,8 +29,9 @@ - doc-base/temp/file-entites.ent - doc-base/temp/file-entites/dir.dir.ent -The file entity for directories (file listings) are keep as individual -files, to avoid these libxml errors, in some OS/versions: +The file entity for directory listings is kept as an separate files, +instead of a monolithic one, to avoid these libxml errors, in some +OS and/or libxml versions: - Detected an entity reference loop [1] - Maximum entity amplification factor exceeded [2] @@ -317,23 +318,23 @@ function writeEntities( array $entities ) ksort( $entities ); - $outFile = realpain( __DIR__ . "/../temp/file-entities.ent" , touch: true ); - $lstFile = realpain( __DIR__ . "/../temp/file-entities.txt" , touch: true ); + $dtdFile = realpain( __DIR__ . "/../temp/file-entities.dtd" , touch: true ); + $txtFile = realpain( __DIR__ . "/../temp/file-entities.txt" , touch: true ); $sepPath = realpain( __DIR__ . "/../temp/file-entities" , mkdir: true ); - $singleFile = fopen( $outFile , "w" ); + $singleFile = fopen( $dtdFile , "w" ); if ( ! $singleFile ) { - print "Failed to open $outFile\n."; + print "Failed to open $dtdFile\n."; exit( 1 ); } - fputs( $singleFile , "<!-- DON'T TOUCH - AUTOGENERATED BY file-entities.php -->\n\n" ); + fputs( $singleFile , "<!-- AUTOGENERATED BY file-entities.php -->\n\n" ); // Life could be simpler, but the building of PHP Manual is already // triping some hardcoded limits of bundled libxml2. // Off loading DTD entities that expand to more DTD entities, - // as external files, somehow avoid these limits. + // as external files, to somehow avoid these limits. if ( LIBXML_LIMITS_HACK ) { @@ -363,7 +364,7 @@ function writeEntities( array $entities ) // entities. $contents = implode( "\n" , array_keys( $entities ) ); - file_put_contents( $lstFile , $contents ); + file_put_contents( $txtFile , $contents ); } function writeEntityIndirectSlow( $singleFile , string $extraFile , string $name , string $text ) diff --git a/scripts/text-entities.php b/scripts/text-entities.php index 05d79cbf4a..75f6bb79ec 100644 --- a/scripts/text-entities.php +++ b/scripts/text-entities.php @@ -12,7 +12,7 @@ +----------------------------------------------------------------------+ | Authors: André L F S Bacci <ae php.net> | +----------------------------------------------------------------------+ -| Description: Collect individual entities into an temp/entities.ent. | +| Description: Collect individual entities into an text-entities.dtd. | +----------------------------------------------------------------------+ # Mental model for DTD <!ENTITY>, @@ -39,7 +39,7 @@ This script collects grouped and individual XML Entity files (detailed below), at some expected relative paths, and generates an -doc-base/temp/entities.ent file with their respective DTD Entities. +doc-base/temp/text-entities.dtd file with their respective DTD Entities. The output file has no duplications, so collection order is important to create some operational semantics. Here, latter loaded entities @@ -175,7 +175,7 @@ public function __construct( class Entities { - private static string $filename = __DIR__ . "/../temp/entities.ent"; + private static string $filename = __DIR__ . "/../temp/text-entities.dtd"; private static array $merged = []; // All EntityData, merged by name, no duplications private static array $unique = []; // Any entity marked unique @@ -425,7 +425,6 @@ function loadEntitySingle( string $path ) function outputFiles( string $filename , array $entities ) { $file = fopen( $filename , "w" ); - fputs( $file , "\n<!-- DO NOT COPY / DO NOT TRANSLATE -->" ); fputs( $file , "\n<!-- Autogenerated by text-entities.php -->\n\n" ); $sepFileDir = __DIR__ . "/../temp/text-entities/";