[DOC-CVS] [doc-en] master: XML Entities by example (#5634)

Author: alfsb (alfsb)
Committer: GitHub (web-flow)
Pusher: alfsb
Date: 2026-07-08T08:56:18-03:00

Commit: https://github.com/php/doc-en/commit/bd3f9a8c0412e902be8fc1c1ff9acac906826aa6
Raw diff: https://github.com/php/doc-en/commit/bd3f9a8c0412e902be8fc1c1ff9acac906826aa6.diff

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

Changed paths:
  A  entities/entities-remove.ent
  A  entities/entities.ent
  A  reference/entities.md
  D  contributors.ent
  M  docbookcs.xml


Diff:

diff --git a/contributors.ent b/contributors.ent
deleted file mode 100644
index efa9ec9ce992..000000000000
--- a/contributors.ent
+++ /dev/null
@@ -1,12 +0,0 @@
-<!-- $Revision$ -->
-
- <!--
-   This file should only be present in the English doc tree. If you
-   copy it over to your translation tree you will be hunted down
-   relentlessly! You have been warned! :)
- -->
-
-<!-- Authors and editors displayed on the manual frontpage -->
-<!ENTITY frontpage.authors ''>
-
-<!ENTITY frontpage.editors ''>
diff --git a/docbookcs.xml b/docbookcs.xml
index a5f428f2483d..7c874f321686 100644
--- a/docbookcs.xml
+++ b/docbookcs.xml
@@ -21,7 +21,6 @@
  </paths>
 
  <entities>
-  <file>contributors.ent</file>
   <file>extensions.ent</file>
   <file>language-defs.ent</file>
   <file>language-snippets.ent</file>
diff --git a/entities/entities-remove.ent b/entities/entities-remove.ent
new file mode 100644
index 000000000000..eb2a4c29e358
--- /dev/null
+++ b/entities/entities-remove.ent
@@ -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>
\ No newline at end of file
diff --git a/entities/entities.ent b/entities/entities.ent
new file mode 100644
index 000000000000..f38152e10545
--- /dev/null
+++ b/entities/entities.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>
diff --git a/reference/entities.md b/reference/entities.md
new file mode 100644
index 000000000000..23d34cbeb72e
--- /dev/null
+++ b/reference/entities.md
@@ -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>
+```
\ No newline at end of file