XML Entities by example (#5634)

* Example of transforming DTD entities into XML entities
* Per extension entities example
* Remove example file
* EOF EOL
* Reviews
* Per extension entity example

Author: alfsb

contributors.ent

@@ -21,7 +21,6 @@
  </paths>
 
  <entities>
-  <file>contributors.ent</file>
   <file>extensions.ent</file>
   <file>language-defs.ent</file>
   <file>language-snippets.ent</file>

docbookcs.xml

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<!--
+
+This is a "remove" XML Entity file.
+See doc-base/script/text-entities.php for details.
+
+Place here only deprecated or removed entities that are
+expected NOT be being used in any part of the manual.
+
+If an entity moved here is used in a language in your control,
+this means that the entity on the original file is planned to be
+removed, or already was removed.
+
+DO NOT TRANSLATE THIS FILE.
+
+This file is tracked by revcheck, so translations have a heads up
+when an entity is removed from doc-en. On translations, leave an
+empty <entities/> element at the end of file, only updating the revtag.
+
+-->
+
+<entities xmlns       = "http://docbook.org/ns/docbook"
+          xmlns:xlink = "http://www.w3.org/1999/xlink"
+          translate   = "remove">
+
+<!-- Erased in 2026-06, long time empty -->
+<entity name="frontpage.authors"/>
+<entity name="frontpage.editors"/>
+
+</entities>

entities/entities-remove.ent

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<!--
+
+This is a translatable XML Entity file.
+See doc-base/script/text-entities.php for details.
+
+Place here small entities that are expected to be translated.
+For big or complex entities, please create an individual entity
+file at doc-lang/entities/entityname.xml.
+
+No inline namespaces are necessary. In fact, they can make things
+complicated to debug later. Place any needed namespace in
+declaration of root <entities> element.
+
+Keep the lines strictly under 79 columns, to make the process of
+manual translation easier, and to avoid wrap-around in some other
+contexts.
+
+-->
+
+<entities xmlns       = "http://docbook.org/ns/docbook"
+          xmlns:xlink = "http://www.w3.org/1999/xlink"
+          translate   = "yes">
+
+<entity name="extcat.intro">
+ <title>Extension List/Categorization</title>
+ <simpara>This appendix categorizes more than 150 extensions documented
+ in the PHP Manual by several criteria.</simpara>
+</entity>
+
+<entity name="extcat.alphabetical"><title>Alphabetical</title></entity>
+<entity name="extcat.alphabetical"><title>Alphabetical</title></entity>
+
+</entities>

entities/entities.ent

@@ -0,0 +1,52 @@
+# Per extension entities
+
+For textual entities, related to specific extensions, new or migrated
+from `language-snippets.ent`, please use the following conventions.
+
+* Use an `ext.` prefix for all entity names;
+* Use model file below, for new entities files;
+* Place the entities in file named `doc-en/reference/$extension/entities.ent`;
+* Keep the entities sorted by name, one empty line separating each entity.
+
+If the entity is "big" or otherwise difficult to edit in a file
+with many others, it is possible to create a individual entity per file,
+saved as `doc-en/entities/name.$extension.$entname.xml`, whereas the
+content can be any valid [well-balanced
+region](https://www.w3.org/TR/xml-fragment/#defn-well-balanced).
+DTD entity names are also valid here, but XML declarations are not.
+
+XML namespaces are to be placed in the root `<entities>` element, and
+avoided in any `<entity>` child.
+
+To rename existing entities to use the `ext.` prefix, is possible to
+create temporary aliases, with the following format:
+```xml
+<entity name="old.name">&new.name;</entity>
+```
+
+Temporary aliases are better placed in
+`doc-en/entities/entities-remove.ent`, to avoid duplicated work in
+translations, but are acceptable here too.
+
+### Example file
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<!--
+    See `manual.xml` for XML namespaces defaults.
+    Keep the lines under 79 columns, to make the process of manual
+    translation easier, and to avoid wrap-around in some other contexts.
+-->
+<entities xmlns       = "http://docbook.org/ns/docbook"
+          xmlns:xlink = "http://www.w3.org/1999/xlink"
+          translate   = "yes">
+
+<entity name="ext.$extention.$entity-name">
+ <simpara>
+  Text.
+ </simpara>
+</entity>
+
+</entities>
+```