php / doc-base

Tools for the PHP documentation
Other
347 stars 88 forks source link

Infrastructure for individual entity files #183

Open alfsb opened 4 days ago

alfsb commented 4 days ago

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:

$  php zpr-doc-base/scripts/entities.php --detail en/entities fr/entities
659 files on en/entities
673 files on fr/entities
Expected translated, replaced 0 times:  mongodb.throws.session-readwriteconcern
Expected translated, replaced 0 times:  strings.errors.vsprintf
Expected translated, replaced 0 times:  xml.changelog.handler-param

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.