Read acronyms from translatable acronym.* entities

[jordikroon]

Suggested by @alfsb

Moving Acronyms from doc-base to doc-en. This allows Acronyms to be translated, as well as to more easily phase out unused acronyms.

This is a set of 3 PRs
doc-en: php/doc-en#5695
doc-base: php/doc-base#325
phd: #262 (you are here)

[alfsb]

Cool. I did not know that $dom->doctype->entities was usable, but fickle. Instead of all this code having an indirect effect, I have a suggestion.

1. Rename the file doc-en/entities/acronyms.ent to doc-en/entities/entities.acronyms.ent (as all entities.*.ent files order nearby, this folder may have many other files, see the entities.md);
2. Read this file directly from doc-en, as an XML file.

It is improbable that this file will ever contain entity references, so SimpleXML loading will be safe and easy. And even if this file will ever contain other "direct" acronyms entities, they are not prefixed "acronym.". All these restrictions and automated uses of this file can be also commented on in the file itself, so it will be harder to forget / abuse it later.

For example, I did not know there is a qa script for it, so comments could mention its usage by doc-base/qa and PhD.

The prefix can further be specified, to make it very explicit: "acronym.expansion.$name".

[jordikroon]

I agree with most of your comments, but I am trying to understand acronym.expansion a bit more.
The only true benefit of that is that we can eventually rename the acronym entities like these, right?

<!ENTITY api '<acronym xmlns="http://docbook.org/ns/docbook">API</acronym>'>

to

<!ENTITY acronym.api '<acronym xmlns="http://docbook.org/ns/docbook">API</acronym>'>

If that's the case it does make sense to make these more explicit.

[alfsb]

That is a very nice encoding scheme. To be fair, I was not thinking about it. The addition of .expansion was only to "document" where this entity is used. I plan to only move the acronyms here, using actual names, with the only objective is to avoid PRs that cross repositories.

So the file would contain:

<!-- direct transformation -->
<entity name="api"><acronym>API</acronym></entity>
<entity name="ascii"><acronym>ASCII</acronym></entity>
...
<!-- new, used on PhD -->
<entity name="acronym.expansion.api">Application ...</entity>
<entity name="acronym.expansion.ascii">American ...</entity>

[jordikroon]

I have updated doc-en to include both. Also covered the other comments in the 3 PRs.

While I was doing changing this, I considered making the entity names lowercase, but it might break something unexpected.