From 4216a08b964207d2c7f588489de7c0da4388e7f7 Mon Sep 17 00:00:00 2001
From: Pekka Paalanen <pq@iki.fi>
Date: Sun, 28 Dec 2025 12:36:40 +0200
Subject: [PATCH] doc/xsl: rearrange member doc generation

Creating an empty <variablelist> is illegal. This can already be seen in
the XSL anywhere it is generated. The used XSL programming pattern
requires the look-up conditions to be repeated between the <xsl:if> and
<xsl:apply-templates> tags. Usually this is not a problem, but the
conditions for memberdef is too much to copy around.

The conditions between the if and the apply-templates have already
diverged, causing validation errors (that are currently suppressed).

Rearrange the XSL so that the applicable memberdef are stored in a
variable, so that both the if and the apply-templates operate on the
exact same set of matches. This avoids emitting empty <variablelist>.

As a result, the members of structures wl_argument, wl_interface,
wl_message, and wl_listener newly appear in the documentation.

Signed-off-by: Pekka Paalanen <pq@iki.fi>
---
 doc/publican/xsl/doxygen-to-publican.xsl | 31 ++++++++++++++----------
 1 file changed, 18 insertions(+), 13 deletions(-)

diff --git a/doc/publican/xsl/doxygen-to-publican.xsl b/doc/publican/xsl/doxygen-to-publican.xsl
index 0387372f..d7f29597 100644
--- a/doc/publican/xsl/doxygen-to-publican.xsl
+++ b/doc/publican/xsl/doxygen-to-publican.xsl
@@ -9,9 +9,7 @@
   <section id="{$which}-Functions">
     <title>Functions</title>
     <para />
-    <variablelist>
-      <xsl:apply-templates select="/doxygen/compounddef[@kind='file']/sectiondef/memberdef" />
-    </variablelist>
+    <xsl:apply-templates select="/doxygen/compounddef[@kind='file']/sectiondef" />
   </section>
 
 </xsl:template>
@@ -99,9 +97,10 @@
   <xsl:apply-templates select="para" />
 </xsl:template>
 
-<!-- methods -->
-<xsl:template match="memberdef" >
-  <xsl:if test="(@kind = 'function' and
+<xsl:template match="sectiondef">
+  <xsl:variable name="docitems"
+        select="memberdef[
+                (@kind = 'function' and
                  (@static = 'no' or
                   substring(location/@bodyfile,
                             string-length(location/@bodyfile) - 1,
@@ -110,7 +109,18 @@
                  and @prot = 'public'
                 )
                 or
-                (@kind != 'function' and normalize-space(briefdescription) != '')">
+                (@kind != 'function' and normalize-space(briefdescription) != '')
+                ]" />
+  <xsl:if test="$docitems">
+    <variablelist>
+      <!-- Apply memberdef template -->
+      <xsl:apply-templates select="$docitems" />
+    </variablelist>
+  </xsl:if>
+</xsl:template>
+
+<!-- methods -->
+<xsl:template match="memberdef" >
     <varlistentry id="{$which}-{@id}">
         <term>
           <xsl:value-of select="name"/>
@@ -125,7 +135,6 @@
           <xsl:apply-templates select="detaileddescription" />
         </listitem>
     </varlistentry>
-  </xsl:if>
 </xsl:template>
 
 <!-- classes -->
@@ -145,11 +154,7 @@
             <para />
           </xsl:otherwise>
         </xsl:choose>
-        <xsl:if test="sectiondef/memberdef[@kind='function' and @static='no']">
-          <variablelist>
-            <xsl:apply-templates select="sectiondef/memberdef" />
-          </variablelist>
-        </xsl:if>
+        <xsl:apply-templates select="sectiondef" />
     </section>
 </xsl:template>
 </xsl:stylesheet>