From a75f54f3722fa2005777cc38aebf3448e4e2b0fc Mon Sep 17 00:00:00 2001
From: Louis-Arnaud Catoire <la.catoire@gmail.com>
Date: Tue, 10 Feb 2026 09:51:57 +0100
Subject: [PATCH] Remove empty <xi:fallback/> from skeletons and docgen

Empty xi:fallback elements silently swallow XInclude failures.
Removing them ensures missing includes surface as errors
instead of being ignored. Relates to #199.
---
 scripts/docgen/docgen.php   |  8 ++++----
 skeletons/classname.xml     | 20 +++++---------------
 skeletons/exceptionname.xml | 16 ++++------------
 3 files changed, 13 insertions(+), 31 deletions(-)

diff --git a/scripts/docgen/docgen.php b/scripts/docgen/docgen.php
index 09fdf9b80c..7aca5f87a3 100644
--- a/scripts/docgen/docgen.php
+++ b/scripts/docgen/docgen.php
@@ -605,7 +605,7 @@ function gen_class_markup(ReflectionClass $class, $content) { /* {{{ */
 			}
 			$markup .= '<classsynopsisinfo role="comment">&InheritedProperties;</classsynopsisinfo>'. PHP_EOL;
 			foreach ($inherited as $declaring_class) {
-				$markup .= str_repeat(' ', $ident) ."<xi:include xpointer=\"xmlns(db=http://docbook.org/ns/docbook) xpointer(id('" . strtolower($declaring_class) . ".synopsis')/descendant::db:fieldsynopsis)\">" . PHP_EOL . str_repeat(' ', $ident + 1) . "<xi:fallback/>" . PHP_EOL . str_repeat(' ', $ident) . "</xi:include>". PHP_EOL;
+				$markup .= str_repeat(' ', $ident) ."<xi:include xpointer=\"xmlns(db=http://docbook.org/ns/docbook) xpointer(id('" . strtolower($declaring_class) . ".synopsis')/descendant::db:fieldsynopsis)\"/>". PHP_EOL;
 			}
 		}
 
@@ -643,14 +643,14 @@ function gen_class_markup(ReflectionClass $class, $content) { /* {{{ */
 
 	/* {PROPERTY_XINCLUDE} */
 	$content = preg_replace('/\{PROPERTY_XINCLUDE\}/',
-		"<xi:include xpointer=\"xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.". $id ."')/db:refentry/db:refsect1[@role='description']/descendant::db:fieldsynopsis[1])\"><xi:fallback/></xi:include>". PHP_EOL,
+		"<xi:include xpointer=\"xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.". $id ."')/db:refentry/db:refsect1[@role='description']/descendant::db:fieldsynopsis[1])\"/>". PHP_EOL,
 		$content, 1);
 
 	/* {METHOD_XINCLUDE} */
 	$ident = get_ident_size('METHOD_XINCLUDE', $content);
 	$content = preg_replace('/\{METHOD_XINCLUDE\}/',
 		PHP_EOL . str_repeat(' ', $ident) . "<classsynopsisinfo role=\"comment\">&Methods;</classsynopsisinfo>". PHP_EOL.
-		str_repeat(' ', $ident) ."<xi:include xpointer=\"xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.". $id ."')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='" . $escapedName . "'])\">" . PHP_EOL . str_repeat(' ', $ident + 1) . "<xi:fallback/>" . PHP_EOL . str_repeat(' ', $ident) . "</xi:include>",
+		str_repeat(' ', $ident) ."<xi:include xpointer=\"xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.". $id ."')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='" . $escapedName . "'])\"/>",
 		$content, 1);
 
 	/* {INHERITED_XINCLUDE} */
@@ -658,7 +658,7 @@ function gen_class_markup(ReflectionClass $class, $content) { /* {{{ */
 		$ident = get_ident_size('INHERITED_XINCLUDE', $content);
 		$content = preg_replace('/\{INHERITED_XINCLUDE\}/',
 			PHP_EOL . str_repeat(' ', $ident) ."<classsynopsisinfo role=\"comment\">&InheritedMethods;</classsynopsisinfo>". PHP_EOL.
-			str_repeat(' ', $ident) ."<xi:include xpointer=\"xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.". format_id($parent->getName()) ."')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='" . $escapedName . "'])\">" . PHP_EOL . str_repeat(' ', $ident + 1) . "<xi:fallback/>" . PHP_EOL . str_repeat(' ', $ident) . "</xi:include>". PHP_EOL,
+			str_repeat(' ', $ident) ."<xi:include xpointer=\"xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.". format_id($parent->getName()) ."')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='" . $escapedName . "'])\"/>". PHP_EOL,
 			$content, 1);
 	} else {
 		$content = preg_replace('/^\s*\{INHERITED_XINCLUDE\}.*?\n/m', '', $content, 1);
diff --git a/skeletons/classname.xml b/skeletons/classname.xml
index 774d945cf6..a02f1aafaf 100644
--- a/skeletons/classname.xml
+++ b/skeletons/classname.xml
@@ -60,24 +60,16 @@
 
     <!-- Edit the parentclass below -->
     <classsynopsisinfo role="comment">&InheritedProperties;</classsynopsisinfo>
-    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.parentclass')/db:partintro/db:section/db:classsynopsis/db:fieldsynopsis[preceding-sibling::db:classsynopsisinfo[1][@role='comment' and text()='&Properties;']]))">
-     <xi:fallback/>
-    </xi:include>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.parentclass')/db:partintro/db:section/db:classsynopsis/db:fieldsynopsis[preceding-sibling::db:classsynopsisinfo[1][@role='comment' and text()='&Properties;']]))"/>
 
     <!-- Edit the classname below and ClassName in the @role='ClassName' XPath query -->
     <!-- If has a constructor -->
     <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
-    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.classname')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='ClassName'])">
-     <xi:fallback/>
-    </xi:include>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.classname')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='ClassName'])"/>
     <!-- If has a destructor -->
-    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.classname')/db:refentry/db:refsect1[@role='description']/descendant::db:destructorsynopsis[@role='ClassName'])">
-     <xi:fallback/>
-    </xi:include>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.classname')/db:refentry/db:refsect1[@role='description']/descendant::db:destructorsynopsis[@role='ClassName'])"/>
     <!-- If has methods -->
-    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.classname')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='ClassName'])">
-     <xi:fallback/>
-    </xi:include>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.classname')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='ClassName'])"/>
 
     <!-- Edit the parentclass below -->
     <!--
@@ -86,9 +78,7 @@
         i.e. class XYZ extends class XY and class XY extends class X
     -->
     <classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo>
-    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.parentclass')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='ParentClass'])">
-     <xi:fallback/>
-    </xi:include>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.parentclass')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='ParentClass'])"/>
    </classsynopsis>
    <!-- }}} -->
 
diff --git a/skeletons/exceptionname.xml b/skeletons/exceptionname.xml
index 2de970e89b..e6402edf8a 100644
--- a/skeletons/exceptionname.xml
+++ b/skeletons/exceptionname.xml
@@ -33,17 +33,11 @@
     <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
     <!-- If has a constructor -->
     <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
-    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exceptionname')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='ExceptionName'])">
-     <xi:fallback/>
-    </xi:include>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exceptionname')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='ExceptionName'])"/>
     <!-- If has a destructor -->
-    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exceptionname')/db:refentry/db:refsect1[@role='description']/descendant::db:destructorsynopsis[@role='ExceptionName'])">
-     <xi:fallback/>
-    </xi:include>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exceptionname')/db:refentry/db:refsect1[@role='description']/descendant::db:destructorsynopsis[@role='ExceptionName'])"/>
     <!-- If has methods -->
-    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exceptionname')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='ExceptionName'])">
-     <xi:fallback/>
-    </xi:include>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exceptionname')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='ExceptionName'])"/>
 
     <!-- Edit the parentclass below -->
     <!--
@@ -52,9 +46,7 @@
         i.e. class XYZ extends class XY and class XY extends class X
     -->
     <classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo>
-    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.baseexceptionname')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='BaseExceptionName'])">
-     <xi:fallback/>
-    </xi:include>
+    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.baseexceptionname')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='BaseExceptionName'])"/>
    </classsynopsis>
   </section>