Enable XML Text Entities

configure.php

@@ -551,10 +551,11 @@ function git_status()
     echo "\n" , trim( $output ) . "\n\n";
 }
 
-// DTD layer before first XML loading
+// DTD entity layer before first XML loading
 
 dtd_conf_entities();
 dtd_file_entities();
+dtd_text_entities();
 
 function dtd_conf_entities()
 {
@@ -564,22 +565,16 @@ function dtd_conf_entities()
 
     $conf[] = "<!ENTITY LANG '$lang'>";
 
-    if ( $lang == 'en' )
-    {
-        realpain( __DIR__ . "/temp/empty" , touch: true );
-        $trans1 = realpain( __DIR__ . "/temp/empty" );
-        $trans2 = realpain( __DIR__ . "/temp/empty" );
-        $trans3 = realpain( __DIR__ . "/temp/empty" );
-    }
-    else
+    if ( $lang != 'en' )
     {
         $trans1 = realpain( __DIR__ . "/../$lang/language-defs.ent" );
         $trans2 = realpain( __DIR__ . "/../$lang/language-snippets.ent" );
         $trans3 = realpain( __DIR__ . "/../$lang/extensions.ent" );
+
+        $conf[] = "<!ENTITY % translation-defs       SYSTEM '$trans1'>";
+        $conf[] = "<!ENTITY % translation-snippets   SYSTEM '$trans2'>";
+        $conf[] = "<!ENTITY % translation-extensions SYSTEM '$trans3'>";
     }
-    $conf[] = "<!ENTITY % translation-defs       SYSTEM '$trans1'>";
-    $conf[] = "<!ENTITY % translation-snippets   SYSTEM '$trans2'>";
-    $conf[] = "<!ENTITY % translation-extensions SYSTEM '$trans3'>";
 
     if ( $ac['CHMENABLED'] == 'yes' )
     {
@@ -589,7 +584,7 @@ function dtd_conf_entities()
     else
         $conf[] = "<!ENTITY manual.chmonly ''>";
 
-    file_put_contents( __DIR__ . "/temp/manual.conf" , implode( "\n" , $conf ) );
+    file_put_contents( __DIR__ . "/temp/manual.inc" , implode( "\n" , $conf ) );
 }
 
 function dtd_file_entities()
@@ -620,6 +615,30 @@ function dtd_file_entities()
     }
 }
 
+function dtd_text_entities()
+{
+    global $ac;
+    $php = $ac['PHP'];
+    $lang = $ac["LANG"];
+
+    $parts = [ $php
+             , __DIR__ . "/scripts/text-entities.php"
+             , "en" ];
+    if ( $lang != "en" )
+        $parts[] = $lang;
+
+    foreach ( $parts as & $part )
+        $part = escapeshellarg( $part );
+    $cmd = implode( ' ' , $parts );
+    $ret = 0;
+    passthru( $cmd , $ret );
+
+    if ( $ret != 0 )
+    {
+        echo "doc-base/scripts/entities.php FAILED.\n";
+        exit( 1 );
+    }
+}
 
 checking("for if we should generate a simplified file");
 if ($ac["GENERATE"] != "no") {

entities/normal.ent-dist

@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="utf8" ?>
+<!-- $Revision:$ -->
+<!--
+
+# Description
+
+This is a "normal" 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.
+
+# 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 one. Mind the XML namespaces of the root XML
+ element below.
+</entity>
+
+-->
+
+<entities xmlns       = "http://docbook.org/ns/docbook"
+          xmlns:xlink = "http://www.w3.org/1999/xlink"
+          translate   = "yes">
+
+
+</entities>

entities/remove.ent-dist

@@ -1,20 +1,36 @@
-<?xml version="1.0" encoding="utf8" ?>
+<?xml version="1.0" encoding="utf8" ?><?phprevcheck no ?>
+<!-- $Revision:$ -->
 <!--
-    This is a "remove" XML Entity file.
-    See doc-base/script/entities.php for details.
 
-    Place here only deprecated entities that are expected NOT
-    be being used in any part of the manual.
+# Description
 
-    DO NOT COPY OR TRANSLATE THIS FILE.
+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.
+
+DO NOT COPY OR TRANSLATE THIS FILE.
+
+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.
+
+# Examples
+
+<entity name="name"></entity>
+
+<entity name="name.name">
+ It may be necessary to preserve the original body to avoid
+ breakage in manual translations.
+</entity>
 
-    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. Consult the original text file
-    and apply changes accordly.
 -->
-<entities xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 
-<!-- <entity name="ent.name">XML fragment</entity> -->
+<entities xmlns       = "http://docbook.org/ns/docbook"
+          xmlns:xlink = "http://www.w3.org/1999/xlink"
+          translate   = "remove">
+
+
 
 </entities>

entities/unique.ent-dist

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="utf8" ?><?phprevcheck no ?>
+<!-- $Revision:$ -->
+<!--
+
+# Description
+
+This is a "unique" XML Entity file.
+See doc-base/script/text-entities.php for details.
+
+Place here only small entities that are expected NOT
+being translated in any part of the manual.
+
+DO NOT COPY OR TRANSLATE THIS FILE.
+
+If you want/need to translate some entity placed here,
+open an issue on doc-base or doc-en repository, so the
+translatable entity is moved to a normal entity file.
+
+# 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 one. Mind the XML namespaces of <entities>
+ XML element below.
+</entity>
+
+-->
+
+<entities xmlns       = "http://docbook.org/ns/docbook"
+          xmlns:xlink = "http://www.w3.org/1999/xlink"
+          translate   = "no">
+
+
+
+</entities>

manual.xml

@@ -2,7 +2,7 @@
 <!DOCTYPE PHPDOC [
 
 <!-- Parameter entities used to configure manual.xml -->
-<!ENTITY % configure         SYSTEM "./temp/manual.conf">
+<!ENTITY % configure         SYSTEM "./temp/manual.inc">
 %configure;
 
 <!-- Entities collected by entities.php -->