This PR enables the use of individual entity files. It searches for an $lang/entities/ dir when building the manual, and for each file it creates an <!ENTITY> element on a doc-base/.entities.ent file, that is included in manual.xml.in. It also accepts more than one input dir as argument, as to generate the .entities.ent file with complementary or overwriting translated entities.
This will make entity experimentation a lot easier, and is the enabling step into splitting language-entities.ent file. It's already in working state, with a file splinting tool included. Tested on all languages.
Splinting language-entities.ent is hard work. What is good for?
First, with it will be possible to have entity level formal validation (and avoid mysterious, hard to debug breakages):
XML load failed on entity file.
Path: phpdoc-test/it/entities/pecl.bundled.xml
Error: Namespace prefix xlink for href on link is not defined
It's also enables revision tracking at a entity level and separates this frequently changed big file. "frequent changing" and "big file" in one sentence is real PITA for all translations. And by consequence, it would be possible to more easily see what parts of this big file is missing translations:
This works, and works well. But I do not plan to push for this until 2025, or the PHP 8.4 doc changes slows down.
I plan to also to create a new XML format for "small" entities, to replace other .ent files with a more normal format (that is, a XML namespacing aware format). See the comments on entities.php file for more information.
This PR enables the use of individual entity files. It searches for an
$lang/entities/
dir when building the manual, and for each file it creates an<!ENTITY>
element on adoc-base/.entities.ent
file, that is included inmanual.xml.in
. It also accepts more than one input dir as argument, as to generate the.entities.ent
file with complementary or overwriting translated entities.This will make entity experimentation a lot easier, and is the enabling step into splitting
language-entities.ent
file. It's already in working state, with a file splinting tool included. Tested on all languages.Splinting
language-entities.ent
is hard work. What is good for?First, with it will be possible to have entity level formal validation (and avoid mysterious, hard to debug breakages):
It's also enables revision tracking at a entity level and separates this frequently changed big file. "frequent changing" and "big file" in one sentence is real PITA for all translations. And by consequence, it would be possible to more easily see what parts of this big file is missing translations:
This works, and works well. But I do not plan to push for this until 2025, or the PHP 8.4 doc changes slows down.
I plan to also to create a new XML format for "small" entities, to replace other .ent files with a more normal format (that is, a XML namespacing aware format). See the comments on
entities.php
file for more information.