XInclude fixup to enable using xml:id targets

[alfsb]

This PR includes a fixup step on configure.php XInclude processing, to the effect to simulating XML Inclusions Version 1.1.

With this PR, an doc-en manual with this changes builds ok:

diff --git a/reference/filesystem/functions/fgetcsv.xml b/reference/filesystem/functions/fgetcsv.xml
index 279785ed00..66a2fda3c1 100644
--- a/reference/filesystem/functions/fgetcsv.xml
+++ b/reference/filesystem/functions/fgetcsv.xml
@@ -65 +65 @@
-    <varlistentry>
+    <varlistentry xml:id="xi..function.fgetcsv..parameters..separator">
@@ -73 +73 @@
-    <varlistentry>
+    <varlistentry xml:id="xi..function.fgetcsv..parameters..enclosure">
@@ -81 +81 @@
-    <varlistentry>
+    <varlistentry xml:id="xi..function.fgetcsv..parameters..escape">
diff --git a/reference/filesystem/functions/fputcsv.xml b/reference/filesystem/functions/fputcsv.xml
index f3a94fb1b1..edd1f42f8b 100644
--- a/reference/filesystem/functions/fputcsv.xml
+++ b/reference/filesystem/functions/fputcsv.xml
@@ -46,9 +46,9 @@
-    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='parameters']//db:varlistentry[db:term[db:parameter[text()='separator']]]/.)">
-     <xi:fallback/>
-    </xi:include>
-    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='parameters']//db:varlistentry[db:term[db:parameter[text()='enclosure']]]/.)">
-     <xi:fallback/>
-    </xi:include>
-    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.fgetcsv')/db:refsect1[@role='parameters']//db:varlistentry[db:term[db:parameter[text()='escape']]]/.)">
-     <xi:fallback/>
-    </xi:include>
+   <xi:include xpointer="xi..function.fgetcsv..parameters..separator">
+    <xi:fallback/>
+   </xi:include>
+   <xi:include xpointer="xi..function.fgetcsv..parameters..enclosure">
+    <xi:fallback/>
+   </xi:include>
+   <xi:include xpointer="xi..function.fgetcsv..parameters..escape">
+    <xi:fallback/>
+   </xi:include>
@@ -73 +73 @@

The xi prefix or .. separators are not special. They are only a suggestion for a convention for these structurally incorrect xml:ids, but the code works perfectly ok with any xml:id.

This will also enable putting some of language-snippets.ent entities that are tightly related to an extension, and XIncluding these "hosted" entities directly from their extension related xml:id.

Fun fact: The PHP manual has ~25.000 IDs at XInclude processing step. Inspecting they two times in a row takes almost no time.

[alfsb]

Typo fixed, also fixed an error condition. Two follow ups:

Suggested convention for XInclude xml:ids: {parent_id}..{local_xinclude_id}

I was experimenting with some reserved syntax for xml:id of includes, but as xml:id are NCName, their contents are severely restricted. I was worried about classes between structural ids, auto generated file ids and the new XInclude ids. But after a while, I got that any current id "reserves" a namespace of sorts, so using a convention like this will avoid collisions.

So in the examples above, the xml:ids created for XInclusion would be like function.fgetcsv..parameters..separator. This avoids collisions and also has a nice property of indicating where the referenced id is being defined, if some XIncludes fail (to help translators).

Suggested convention for XInclude : <xi:fallback><!--doc-en-fatal--></xi:fallback>

Speaking of failures, the other follow up is that <xi:fallback> presence effectively disables detecting XInclude failures. Tolerating XInclude failbacks is important for translations, but is a hard error on doc-en. So I propose another convention. On XInclude call sites:

<xi:include xpointer="function.fgetcsv..parameters..separator">
 <xi:fallback><!--doc-en-fatal--></xi:fallback>
</xi:include>

So that in the XInclude fixups, it would be possible to detect and report XInclude failures, and also make it fatal again on doc-en.

Instead of <!--doc-en-fatal-->, other suggestion is <!--xi:fallback-->, as no "xi:" is expect to survive $dom->xindluce().

[alfsb]

Scratch the thing about doc-en-fatal. The last commit added automatic xi:fallback for all manual!

• <xi:fallback/> can be removed completely
• failures on doc-en are hard errors
• failures on translations are soft errors
• detailed reporting

For example, an XInclude like this:

<xi:include xpointer="nothing"/>

Is reported as:

Failed xi:include at:        /set(index)/book(appendices)/appendix(ini)/section(ini.list)/para/table/tgroup/tbody
Failed xi:include target is: nothing