Document xml:id usage (#216)

Author: alfsb

configure.php

@@ -1057,6 +1057,7 @@ function xinclude_residual( DOMDocument $dom )
     // XInclude by XPath/XPointer may start causing duplications
     // (see docs/structure.md). Crude and ugly fixup ahead, beware!
 
+    $see = false;
     $list = array();
     $nodes = $xpath->query( "//*[@xml:id]" );
     foreach( $nodes as $node )
@@ -1065,11 +1066,16 @@ function xinclude_residual( DOMDocument $dom )
         if ( isset( $list[ $id ] ) )
         {
             if ( ! str_contains( $id , '..' ) )
+            {
                 echo "  Random removing duplicated xml:id: $id\n";
+                $see = true;
+            }
             $node->removeAttribute( "xml:id" );
         }
         $list[ $id ] = $id;
     }
+    if ( $see )
+        echo "  See: https://github.com/php/doc-base/blob/master/docs/structure.md#xmlid-structure\n";
 }
 
 echo "Validating {$ac["INPUT_FILENAME"]}... ";

docs/structure.md

@@ -46,16 +46,22 @@ There are some other important files:
 
 ## `xml:id` structure
 
-The PHP is complex, and uses `xml:id` extensively. For chunking,
-linking and XInclude purposes. So some care is necessary to avoid
-collisions. There are two pseudo-types of IDs used in manuals.
+The PHP Manual is complex, and uses `xml:id`s extensively, for various
+purposes. So some care is necessary to avoid failures.
+There are two types of `xml:id`s used in manuals.
 
 * **Structural IDs:** IDs that are present on structural elements of
-DocBook XML (like `<chapter>`, `<section>` and so on);
+DocBook XML (like `<chapter>`, `<section>` and so on), that are used for
+linking and chunking;
 
 * **XInclude IDs:** IDs that are used as target of XIncludes.
 
-Structural IDs are in the pattern `id.id`, while XInclude IDs use the
-pattern `structural.id..local.name`. That is, Structural IDs, the
-name parts are separated with a single dot, while XInclude IDs start
-with an Structural ID, an `..` separator, and a local path suffix.
+Structural IDs are in the pattern `id.id` (always one dot as separator),
+while XInclude IDs use the pattern `structural.id..local.name`. That is,
+for Structural IDs the name parts are separated with a *single* dot, while
+XInclude IDs are composed of an Structural ID prefix, a *double* dot separator,
+and a named suffix.
+
+The `configure.php` script will remove any duplicated IDs found. Without
+warnings in the case of XInclude IDs, so it is possible to use XInclude
+IDs elsewhere, and will warn about duplicate Structural IDs.