Generate a nested hierarchy of Devhelp chapters

* util/tagfile-to-devhelp2.xsl (chapters): Turn the flat structure of
the Doxygen tag file into hierarchies of modules and classes.  At the
top-level, select only those compounds which are not a member of any
other compound, and then process the nested compounds recursively to
create the tree structure.
(functions): Refactor and canonicalize the template logic.  No longer
attempt to sort the keyword list, because it is not a requirement and
unnecessarily complicates the transformation.
(xsl:strip-space): Strip excess whitespace from source elements.

1 files changed, 57 insertions, 29 deletions

diff --git a/util/tagfile-to-devhelp2.xsl b/util/tagfile-to-devhelp2.xsl
index 67b64da..0eb145a 100644
--- a/util/tagfile-to-devhelp2.xsl
+++ b/util/tagfile-to-devhelp2.xsl
@@ -19,12 +19,19 @@
   You should have received a copy of the GNU General Public License
   along with this script.  If not, see <http://www.gnu.org/licenses/>.
   -->
+  <xsl:strip-space elements="*"/>
   <xsl:output method="xml" version="1.0" indent="yes" encoding="UTF-8"/>
 
   <xsl:param name="book_title"/>
   <xsl:param name="book_name"/>
   <xsl:param name="book_base"/>
 
+  <!-- Define keys to filter compounds that are members of other compounds -->
+  <xsl:key name="nested-group" match="compound[@kind='group']" use="subgroup"/>
+  <xsl:key name="nested-scope" match="compound[@kind='namespace']" use="namespace|class"/>
+  <xsl:key name="nested-scope" match="compound[@kind='class' or @kind='struct' or @kind='union']"
+           use="class"/>
+
   <xsl:template match="/">
     <book title="{$book_title}" name="{$book_name}" base="{$book_base}"
           link="index.html" version="2" language="c++">
@@ -32,7 +39,9 @@
         <xsl:variable name="modules" select="tagfile/compound[@kind='group']"/>
         <xsl:if test="$modules">
           <sub name="Modules" link="modules.html">
-            <xsl:apply-templates select="$modules" mode="module">
+            <!-- Select the top-level group compounds -->
+            <xsl:apply-templates select="$modules[not(key('nested-group', name))]"
+                                 mode="module-list">
               <xsl:sort lang="en" select="title"/>
             </xsl:apply-templates>
           </sub>
@@ -40,62 +49,81 @@
         <xsl:variable name="namespaces" select="tagfile/compound[@kind='namespace']"/>
         <xsl:if test="$namespaces">
           <sub name="Namespaces" link="namespaces.html">
-            <xsl:apply-templates select="$namespaces" mode="sub">
+            <!-- Generate a flat list of fully qualified namespaces -->
+            <xsl:for-each select="$namespaces">
               <xsl:sort lang="en" case-order="upper-first" select="name"/>
-            </xsl:apply-templates>
+              <sub name="{name}" link="{filename}"/>
+            </xsl:for-each>
           </sub>
         </xsl:if>
-        <xsl:variable name="classes" select="tagfile/compound[@kind='class' or @kind='struct']"/>
-        <xsl:if test="$classes">
+        <xsl:if test="tagfile/compound[@kind='class' or @kind='struct' or @kind='union']">
           <sub name="Classes" link="classes.html">
-            <xsl:apply-templates select="$classes" mode="sub">
+            <!-- Select the top-level C++ compounds -->
+            <xsl:apply-templates select="tagfile/compound[not(key('nested-scope', name))]"
+                                 mode="class-list">
               <xsl:sort lang="en" case-order="upper-first" select="name"/>
             </xsl:apply-templates>
           </sub>
         </xsl:if>
       </chapters>
       <functions>
-        <xsl:apply-templates select="tagfile/compound" mode="compound">
-          <xsl:sort lang="en" case-order="upper-first" select="name"/>
-        </xsl:apply-templates>
+        <xsl:apply-templates select="tagfile/compound" mode="keyword-list"/>
       </functions>
     </book>
   </xsl:template>
 
-  <xsl:template match="compound" mode="module">
-    <sub name="{title}" link="{filename}"/>
+  <xsl:template match="compound" mode="module-list">
+    <xsl:variable name="children" select="subgroup"/>
+    <sub name="{title}" link="{filename}">
+      <!-- Select any subgroup compounds by name -->
+      <xsl:apply-templates select="../compound[@kind='group' and name=$children]"
+                           mode="module-list">
+        <xsl:sort lang="en" select="title"/>
+      </xsl:apply-templates>
+    </sub>
   </xsl:template>
 
-  <xsl:template match="compound" mode="sub">
-    <sub name="{name}" link="{filename}"/>
+  <xsl:template match="compound[@kind='namespace' or @kind='class' or @kind='struct' or @kind='union']"
+                mode="class-list">
+    <!-- The scope prefix to strip from the name -->
+    <xsl:param name="scope"/>
+    <xsl:variable name="fullname" select="name"/>
+    <xsl:variable name="children" select="namespace|class"/>
+    <sub name="{substring-after($fullname, $scope)}" link="{filename}">
+      <!-- Select any nested C++ compounds by name -->
+      <xsl:apply-templates select="../compound[name=$children]" mode="class-list">
+        <xsl:sort lang="en" case-order="upper-first" select="name"/>
+        <xsl:with-param name="scope" select="concat($fullname, '::')"/>
+      </xsl:apply-templates>
+    </sub>
   </xsl:template>
+  <!-- Ignore any other kind of compound -->
+  <xsl:template match="*" mode="class-list"/>
 
-  <xsl:template match="compound[@kind='namespace']" mode="compound">
-    <xsl:apply-templates select="member" mode="keyword">
-      <xsl:sort lang="en" case-order="upper-first" select="name"/>
-    </xsl:apply-templates>
+  <xsl:template match="compound[@kind='namespace']" mode="keyword-list">
+    <!-- Process members, but do not list the namespace itself as a keyword -->
+    <xsl:apply-templates select="member" mode="keyword-list"/>
   </xsl:template>
-  <xsl:template match="compound[@kind='class' or @kind='struct']" mode="compound">
+  <xsl:template match="compound[@kind='class' or @kind='struct' or @kind='union']"
+                mode="keyword-list">
+    <!-- List the compound type itself as a keyword and process its members -->
     <keyword type="struct" name="{name}" link="{filename}"/>
-    <xsl:apply-templates select="member" mode="keyword">
-      <xsl:sort lang="en" case-order="upper-first" select="name"/>
-    </xsl:apply-templates>
+    <xsl:apply-templates select="member" mode="keyword-list"/>
   </xsl:template>
-  <!-- Ignore compounds of unknown type -->
-  <xsl:template match="*" mode="compound"/>
-
-  <xsl:template match="member[@kind='function' or @kind='typedef']" mode="keyword">
+  <!-- Match leaf compound members -->
+  <xsl:template match="member[@kind='function' or @kind='typedef']" mode="keyword-list">
     <keyword type="{@kind}" xsl:use-attribute-sets="keyword-member"/>
   </xsl:template>
-  <xsl:template match="member[@kind='enumeration']" mode="keyword">
+  <xsl:template match="member[@kind='enumeration']" mode="keyword-list">
     <keyword type="enum" xsl:use-attribute-sets="keyword-member"/>
   </xsl:template>
-  <xsl:template match="member[@kind='enumvalue' or @kind='define']" mode="keyword">
+  <xsl:template match="member[@kind='enumvalue' or @kind='define']" mode="keyword-list">
     <keyword type="macro" xsl:use-attribute-sets="keyword-member"/>
   </xsl:template>
-  <!-- Ignore keywords of unknown type -->
-  <xsl:template match="*" mode="keyword"/>
+  <!-- Ignore unknown keyword types -->
+  <xsl:template match="*" mode="keyword-list"/>
 
+  <!-- Qualify member name and link anchor -->
   <xsl:attribute-set name="keyword-member">
     <xsl:attribute name="name">
       <xsl:value-of select="concat(../name, '::', name)"/>