From a8ed01738f47198c678441aecfea2ce7b4e51269 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20L=20F=20S=20Bacci?= <ae@php.net>
Date: Fri, 26 Jun 2026 14:19:22 -0300
Subject: [PATCH 1/7] Example of transforming DTD entities into XML entities

---
 contributors.ent             | 12 ------------
 docbookcs.xml                |  1 -
 entities/entities-remove.ent | 31 +++++++++++++++++++++++++++++++
 entities/entities.ent        | 33 +++++++++++++++++++++++++++++++++
 4 files changed, 64 insertions(+), 13 deletions(-)
 delete mode 100644 contributors.ent
 create mode 100644 entities/entities-remove.ent
 create mode 100644 entities/entities.ent

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..761979e0ed0d
--- /dev/null
+++ b/entities/entities-remove.ent
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="utf8" ?>
+<!-- $Revision:$ -->
+<!--
+
+This is a "remove" XML Entity file.
+See doc-base/script/text-entities.php for details.
+
+Place here only deprecated 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 a 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>
diff --git a/entities/entities.ent b/entities/entities.ent
new file mode 100644
index 000000000000..61948b52e515
--- /dev/null
+++ b/entities/entities.ent
@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="utf8" ?>
+<!-- $Revision:$ -->
+<!--
+
+# Description
+
+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.
+
+Keep the lines strictly under 79 columns, to make the process of
+manual translation easier, and to not wrap around on automatic
+emails.
+
+-->
+
+<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>
\ No newline at end of file

From fc1d921e222f2af9a0d7d0414081c83ecf7d2fd1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20L=20F=20S=20Bacci?= <ae@php.net>
Date: Fri, 26 Jun 2026 14:44:54 -0300
Subject: [PATCH 2/7] Per extension entities example

---
 entities/entities-remove.ent |  8 ++++----
 entities/entities.ent        | 10 ++++++----
 reference/entities.ent       | 37 ++++++++++++++++++++++++++++++++++++
 3 files changed, 47 insertions(+), 8 deletions(-)
 create mode 100644 reference/entities.ent

diff --git a/entities/entities-remove.ent b/entities/entities-remove.ent
index 761979e0ed0d..5ea5eb7ee0fa 100644
--- a/entities/entities-remove.ent
+++ b/entities/entities-remove.ent
@@ -5,8 +5,8 @@
 This is a "remove" XML Entity file.
 See doc-base/script/text-entities.php for details.
 
-Place here only deprecated entities that are expected NOT
-be being used in any part of the manual.
+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
@@ -15,7 +15,7 @@ removed, or already was removed.
 DO NOT TRANSLATE THIS FILE.
 
 This file is tracked by revcheck, so translations have a heads up
-when a entity is removed from doc-en. On translations, leave an
+when an entity is removed from doc-en. On translations, leave an
 empty <entities/> element at the end of file, only updating the revtag.
 
 -->
@@ -28,4 +28,4 @@ empty <entities/> element at the end of file, only updating the revtag.
 <entity name="frontpage.authors"/>
 <entity name="frontpage.editors"/>
 
-</entities>
+</entities>
\ No newline at end of file
diff --git a/entities/entities.ent b/entities/entities.ent
index 61948b52e515..97c699d45e2f 100644
--- a/entities/entities.ent
+++ b/entities/entities.ent
@@ -2,8 +2,6 @@
 <!-- $Revision:$ -->
 <!--
 
-# Description
-
 This is a translatable XML Entity file.
 See doc-base/script/text-entities.php for details.
 
@@ -11,9 +9,13 @@ 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 not wrap around on automatic
-emails.
+manual translation easier, and to avoid wrap-around in some other
+contexts.
 
 -->
 
diff --git a/reference/entities.ent b/reference/entities.ent
new file mode 100644
index 000000000000..38ee50cce865
--- /dev/null
+++ b/reference/entities.ent
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="utf8" ?>
+<!-- $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">
+
+<!-- Examples:
+
+<entity name="name">Direct text</entity>
+
+<entity name="name.name">
+ Single-, multi- or text rooted XML fragment, as long as it is
+ a well-balanced region.
+</entity>
+
+-->
+
+</entities>
\ No newline at end of file

From b44182684a82141302c391aedad70284d7918499 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20L=20F=20S=20Bacci?= <ae@php.net>
Date: Fri, 26 Jun 2026 14:56:50 -0300
Subject: [PATCH 3/7] Remove example file

---
 reference/entities.ent | 37 -------------------------------------
 1 file changed, 37 deletions(-)
 delete mode 100644 reference/entities.ent

diff --git a/reference/entities.ent b/reference/entities.ent
deleted file mode 100644
index 38ee50cce865..000000000000
--- a/reference/entities.ent
+++ /dev/null
@@ -1,37 +0,0 @@
-<?xml version="1.0" encoding="utf8" ?>
-<!-- $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">
-
-<!-- Examples:
-
-<entity name="name">Direct text</entity>
-
-<entity name="name.name">
- Single-, multi- or text rooted XML fragment, as long as it is
- a well-balanced region.
-</entity>
-
--->
-
-</entities>
\ No newline at end of file

From ef0d750dee64bbaf0d47737ac00f3ff6e9c9f8ad Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20L=20F=20S=20Bacci?= <ae@php.net>
Date: Fri, 26 Jun 2026 15:47:41 -0300
Subject: [PATCH 4/7] EOF EOL

---
 entities/entities.ent | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/entities/entities.ent b/entities/entities.ent
index 97c699d45e2f..fc3452edffe1 100644
--- a/entities/entities.ent
+++ b/entities/entities.ent
@@ -32,4 +32,4 @@ contexts.
 <entity name="extcat.alphabetical"><title>Alphabetical</title></entity>
 <entity name="extcat.alphabetical"><title>Alphabetical</title></entity>
 
-</entities>
\ No newline at end of file
+</entities>

From c1dc55da580473d9bcd6d41a58c7e6746cf83df3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20L=20F=20S=20Bacci?= <ae@php.net>
Date: Fri, 3 Jul 2026 13:25:08 -0300
Subject: [PATCH 5/7] Reviews

---
 entities/entities-remove.ent | 4 ++--
 entities/entities.ent        | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/entities/entities-remove.ent b/entities/entities-remove.ent
index 5ea5eb7ee0fa..eb2a4c29e358 100644
--- a/entities/entities-remove.ent
+++ b/entities/entities-remove.ent
@@ -1,5 +1,5 @@
-<?xml version="1.0" encoding="utf8" ?>
-<!-- $Revision:$ -->
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
 <!--
 
 This is a "remove" XML Entity file.
diff --git a/entities/entities.ent b/entities/entities.ent
index fc3452edffe1..f38152e10545 100644
--- a/entities/entities.ent
+++ b/entities/entities.ent
@@ -1,5 +1,5 @@
-<?xml version="1.0" encoding="utf8" ?>
-<!-- $Revision:$ -->
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
 <!--
 
 This is a translatable XML Entity file.

From 514f7234f2381fc70f741774d7d51cfbf736caa4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20L=20F=20S=20Bacci?= <ae@php.net>
Date: Fri, 3 Jul 2026 14:00:18 -0300
Subject: [PATCH 6/7] Per extension entity example

---
 reference/entities.md | 52 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
 create mode 100644 reference/entities.md

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

From 8ee3aa024ee806e64120701f55c5e698b9aef47c Mon Sep 17 00:00:00 2001
From: lacatoire <la.catoire@gmail.com>
Date: Fri, 19 Jun 2026 09:40:32 +0200
Subject: [PATCH 7/7] Remove 11 unused entities still referenced by
 translations

Record them as tombstones in entities/entities-remove.ent (translate="remove")
so revcheck gives translations a heads up, instead of a plain deletion.
---
 entities/entities-remove.ent | 13 +++++++++++++
 language-snippets.ent        | 26 --------------------------
 2 files changed, 13 insertions(+), 26 deletions(-)

diff --git a/entities/entities-remove.ent b/entities/entities-remove.ent
index eb2a4c29e358..254047bc4f2d 100644
--- a/entities/entities-remove.ent
+++ b/entities/entities-remove.ent
@@ -28,4 +28,17 @@ empty <entities/> element at the end of file, only updating the revtag.
 <entity name="frontpage.authors"/>
 <entity name="frontpage.editors"/>
 
+<!-- Removed 2026-07, unused in doc-en, still referenced by some translations -->
+<entity name="changelog.randomseed"/>
+<entity name="date.timezone.errors.changelog"/>
+<entity name="example.outputs.53"/>
+<entity name="example.outputs.54"/>
+<entity name="no.constants"/>
+<entity name="no.resource"/>
+<entity name="note.func-callback"/>
+<entity name="warn.deprecated.alias-5-3-0.removed-7-0-0"/>
+<entity name="warn.deprecated.feature-5-3-0.removed-5-4-0"/>
+<entity name="warn.deprecated.feature-7-2-0"/>
+<entity name="warn.deprecated.function-7-4-0"/>
+
 </entities>
\ No newline at end of file
diff --git a/language-snippets.ent b/language-snippets.ent
index fbac1d5b12cb..2558eae27747 100644
--- a/language-snippets.ent
+++ b/language-snippets.ent
@@ -4,8 +4,6 @@
 <!ENTITY installation.enabled.disable 'This extension is enabled by default. It may be disabled by using the following option at compile time: '>
 
 <!-- Not used in EN anymore -->
-<!ENTITY changelog.randomseed '<row xmlns="http://docbook.org/ns/docbook"><entry>4.2.0</entry><entry>The random
-number generator is seeded automatically.</entry></row>'>
 
 <!ENTITY warn.deprecated.feature-5-3-0.removed-6-0-0 '<warning
 xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
@@ -92,9 +90,6 @@ do not support some characters in filenames, namely <literal>&lt;|&gt;*?":</lite
 are not supported either. Contrary to some extraction tools, this method does not replace these characters with
 an underscore, but instead fails to extract such files.</simpara></note>'>
 
-<!ENTITY note.func-callback '<note xmlns="http://docbook.org/ns/docbook"><simpara>Instead of a function name, an
-array containing an object reference and a method name can also be
-supplied.</simpara></note>'>
 
 <!ENTITY note.func-callback-exceptions '<note xmlns="http://docbook.org/ns/docbook"><simpara>Callbacks registered
 with functions such as <function>call_user_func</function> and <function>call_user_func_array</function> will not be
@@ -254,10 +249,6 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
 <emphasis>DEPRECATED</emphasis> as of PHP 5.3.0. Relying on this feature
 is highly discouraged.</simpara></warning>'>
 
-<!ENTITY warn.deprecated.feature-5-3-0.removed-5-4-0 '<warning
-xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
-<emphasis>DEPRECATED</emphasis> as of PHP 5.3.0 and <emphasis>REMOVED</emphasis>
-as of PHP 5.4.0.</simpara></warning>'>
 
 <!ENTITY warn.deprecated.function-5-3-0.removed-5-4-0 '<warning
 xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
@@ -300,10 +291,6 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
 <emphasis>REMOVED</emphasis> as of PHP 7.2.0. Relying on this function
 is highly discouraged.</simpara></warning>'>
 
-<!ENTITY warn.deprecated.feature-7-2-0 '<warning
-xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
-<emphasis>DEPRECATED</emphasis> as of PHP 7.2.0. Relying on this feature
-is highly discouraged.</simpara></warning>'>
 
 <!ENTITY warn.deprecated.feature-7-2-0.removed-8-0-0 '<warning
 xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
@@ -340,10 +327,6 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
 <emphasis>DEPRECATED</emphasis> as of PHP 7.4.0. Relying on this feature
 is highly discouraged.</simpara></warning>'>
 
-<!ENTITY warn.deprecated.function-7-4-0 '<warning
-xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
-<emphasis>DEPRECATED</emphasis> as of PHP 7.4.0. Relying on this function
-is highly discouraged.</simpara></warning>'>
 
 <!ENTITY warn.deprecated.function-7-4-0.removed-8-0-0 '<warning
 xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
@@ -447,8 +430,6 @@ xmlns="http://docbook.org/ns/docbook"><simpara>This function was
 xmlns="http://docbook.org/ns/docbook"><simpara>This function was
 <emphasis>DEPRECATED</emphasis> in PHP 5.3.0, and <emphasis>REMOVED</emphasis> as of PHP 7.0.0.</simpara></warning>'>
 
-<!ENTITY warn.deprecated.alias-5-3-0.removed-7-0-0 '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This alias was
-<emphasis>DEPRECATED</emphasis> in PHP 5.3.0, and <emphasis>REMOVED</emphasis> as of PHP 7.0.0.</simpara></warning>'>
 
 <!ENTITY warn.deprecated.feature-5-6-0.removed-7-0-0 '<warning
 xmlns="http://docbook.org/ns/docbook"><simpara>This feature was
@@ -636,9 +617,7 @@ is highly discouraged.</simpara></warning>
 
 <!ENTITY example.outputs.5 '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 5:</simpara>'>
 
-<!ENTITY example.outputs.53 '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 5.3:</simpara>'>
 
-<!ENTITY example.outputs.54 '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 5.4:</simpara>'>
 
 <!ENTITY example.outputs.55 '<simpara xmlns="http://docbook.org/ns/docbook">Output of the above example in PHP 5.5:</simpara>'>
 
@@ -1647,9 +1626,6 @@ It is strongly recommended to avoid timezone abbreviations.
 Every call to a date/time function will generate a <constant>E_WARNING</constant>
 if the time zone is not valid. See also <function>date_default_timezone_set</function></simpara>'>
 
-<!ENTITY date.timezone.errors.changelog '<row xmlns="http://docbook.org/ns/docbook"><entry>5.1.0</entry><entry><simpara>
-Now issues the <constant>E_STRICT</constant> and <constant>E_NOTICE</constant>
-time zone errors.</simpara></entry></row>'>
 
 <!ENTITY date.timestamp.description '
 <varlistentry xmlns="http://docbook.org/ns/docbook"><term><parameter>timestamp</parameter></term><listitem><simpara>
@@ -2177,8 +2153,6 @@ or <link linkend="functions.named-arguments">named arguments</link>.</simpara>
 
 <!-- Common pieces in partintro-sections -->
 <!ENTITY no.config '<simpara xmlns="http://docbook.org/ns/docbook">This extension has no configuration directives defined in &php.ini;.</simpara>'>
-<!ENTITY no.resource '<simpara xmlns="http://docbook.org/ns/docbook">This extension has no resource types defined.</simpara>'>
-<!ENTITY no.constants '<simpara xmlns="http://docbook.org/ns/docbook">This extension has no constants defined.</simpara>'>
 <!ENTITY no.requirement '<simpara xmlns="http://docbook.org/ns/docbook">No external libraries are needed to build this extension.</simpara>'>
 <!ENTITY no.install '<simpara xmlns="http://docbook.org/ns/docbook">There is no installation needed to use these
 functions; they are part of the PHP core.</simpara>'>