Skip to content

Commit cd53050

Browse files
lacatoirelacatoire
authored
Remove empty <xi:fallback/> from skeletons and docgen (#274)
Empty xi:fallback elements silently swallow XInclude failures. Removing them ensures missing includes surface as errors instead of being ignored. Relates to #199.
1 parent 7a829a4 commit cd53050

3 files changed

Lines changed: 13 additions & 31 deletions

File tree

‎scripts/docgen/docgen.php‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -605,7 +605,7 @@ function gen_class_markup(ReflectionClass $class, $content) { /* {{{ */
605605
}
606606
$markup .= '<classsynopsisinfo role="comment">&InheritedProperties;</classsynopsisinfo>'. PHP_EOL;
607607
foreach ($inherited as $declaring_class) {
608-
$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;
608+
$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;
609609
}
610610
}
611611

@@ -643,22 +643,22 @@ function gen_class_markup(ReflectionClass $class, $content) { /* {{{ */
643643

644644
/* {PROPERTY_XINCLUDE} */
645645
$content = preg_replace('/\{PROPERTY_XINCLUDE\}/',
646-
"<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,
646+
"<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,
647647
$content, 1);
648648

649649
/* {METHOD_XINCLUDE} */
650650
$ident = get_ident_size('METHOD_XINCLUDE', $content);
651651
$content = preg_replace('/\{METHOD_XINCLUDE\}/',
652652
PHP_EOL . str_repeat(' ', $ident) . "<classsynopsisinfo role=\"comment\">&Methods;</classsynopsisinfo>". PHP_EOL.
653-
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>",
653+
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 . "'])\"/>",
654654
$content, 1);
655655

656656
/* {INHERITED_XINCLUDE} */
657657
if ($parent) {
658658
$ident = get_ident_size('INHERITED_XINCLUDE', $content);
659659
$content = preg_replace('/\{INHERITED_XINCLUDE\}/',
660660
PHP_EOL . str_repeat(' ', $ident) ."<classsynopsisinfo role=\"comment\">&InheritedMethods;</classsynopsisinfo>". PHP_EOL.
661-
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,
661+
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,
662662
$content, 1);
663663
} else {
664664
$content = preg_replace('/^\s*\{INHERITED_XINCLUDE\}.*?\n/m', '', $content, 1);

‎skeletons/classname.xml‎

Lines changed: 5 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -57,24 +57,16 @@
5757

5858
<!-- Edit the parentclass below -->
5959
<classsynopsisinfo role="comment">&InheritedProperties;</classsynopsisinfo>
60-
<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;']]))">
61-
<xi:fallback/>
62-
</xi:include>
60+
<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;']]))"/>
6361

6462
<!-- Edit the classname below and ClassName in the @role='ClassName' XPath query -->
6563
<!-- If has a constructor -->
6664
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
67-
<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'])">
68-
<xi:fallback/>
69-
</xi:include>
65+
<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'])"/>
7066
<!-- If has a destructor -->
71-
<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'])">
72-
<xi:fallback/>
73-
</xi:include>
67+
<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'])"/>
7468
<!-- If has methods -->
75-
<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'])">
76-
<xi:fallback/>
77-
</xi:include>
69+
<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'])"/>
7870

7971
<!-- Edit the parentclass below -->
8072
<!--
@@ -83,9 +75,7 @@
8375
i.e. class XYZ extends class XY and class XY extends class X
8476
-->
8577
<classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo>
86-
<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'])">
87-
<xi:fallback/>
88-
</xi:include>
78+
<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'])"/>
8979
</classsynopsis>
9080

9181
</section>

‎skeletons/exceptionname.xml‎

Lines changed: 4 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -29,17 +29,11 @@
2929
<!-- Edit the classname below -->
3030
<!-- If has a constructor -->
3131
<classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
32-
<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'])">
33-
<xi:fallback/>
34-
</xi:include>
32+
<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'])"/>
3533
<!-- If has a destructor -->
36-
<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'])">
37-
<xi:fallback/>
38-
</xi:include>
34+
<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'])"/>
3935
<!-- If has methods -->
40-
<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'])">
41-
<xi:fallback/>
42-
</xi:include>
36+
<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'])"/>
4337

4438
<!-- Edit the parentclass below -->
4539
<!--
@@ -48,9 +42,7 @@
4842
i.e. class XYZ extends class XY and class XY extends class X
4943
-->
5044
<classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo>
51-
<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'])">
52-
<xi:fallback/>
53-
</xi:include>
45+
<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'])"/>
5446
</classsynopsis>
5547
</section>
5648

0 commit comments

Comments
 (0)