Idempotent build: file-entities.php

[alfsb]

There are two principal sources of non idempotence in PHP manuals. scripts/file-entities.php.in and configure.php This PR rewrites scripts/file-entities.php.in into idempotent scripts/file-entities.php.

scripts/file-entities.php.in comes a long way. It's almost as old as the first solid Docbook XML manual, and got heavily patched in its more than two decades of existence. It had and/or has code for idiosyncrasies of CVS, SVN and git, of Saxon, xsltproc and PhD, of all versions of PHP starting with PHP 4, of almost all operations systems starting with Windows 95... That is a lot of history, and that is a lot of accumulated anachronisms.

Tested on all languages with two behavior changes, listed below.

1. <!ENTITY> output order is changed in manual DTD preambule;
2. The commented out entities on https://github.com/php/doc-en/blob/master/reference/swoole/book.xml stop being rendered, in all languages.

The first one is insignificant, but the second one may be a real bug. It almost got me crazy because the commented out entities are rendered on the PHP manual main site, and the code itself hinted of some form of recursive cascading file inclusions.

But tests with PhD xhtml and bigxhtml showed that all differences are basically Swoole related, so there is no any (more?) automatic recursive file loading in reference/ or elsewhere.

[alfsb]

Conflict resolved. Passes CI, and yet I would like testing of Windows users. I'm trying to make the code as shell free as possible. In particular, I would like to hear if the git -C switch avoids the need for cd /d on Windows.

The Swoole bit may warrant opening an issue, if the docs are still actively developed.

[Girgias]

Haven't tried locally, but for Windows maybe @cmb69 could try?

[cmb69]

It almost got me crazy because the commented out entities are rendered on the PHP manual main site, and the code itself hinted of some form of recursive cascading file inclusions.

Well, there may be nested comments, which are not allowed in XML.

but for Windows maybe @cmb69 could try?

Gave it a quick try, and detected no issues.

[alfsb]

It's time. Merging.

The breakages of &reference.spl.entities.countable; are unrelated, as they occurs already.

[alfsb]

Gave it a quick try, and detected no issues.

Thanks for the testing. Building manual on Windows seems to be way more viable now (compared to 2000, at least).

php/doc-en#4288 is a thing everyone that builds on Windows should keep a eye, as it is a nasty thing that may caused so much... suffering, for many and many years. Bit me hard, today.