From 6eba1ec94fe6c95757ebecf487b4cbb1984fc933 Mon Sep 17 00:00:00 2001
From: "David B. Kinder" <david.b.kinder@intel.com>
Date: Fri, 27 May 2022 15:36:16 -0700
Subject: [PATCH] doc: properly handle empty and skipped acrn:title elements

(bringing fix on master over to release_3.0 branch)

Fix how the config option doc scripts behave when encountering elements
with blank titles (used to remove extraneous headings in the
configurator UI).

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
---
 doc/scripts/configdoc.xsl | 75 ++++++++++++++++++++++++++-------------
 1 file changed, 50 insertions(+), 25 deletions(-)

diff --git a/doc/scripts/configdoc.xsl b/doc/scripts/configdoc.xsl
index 2e1fbdf3d..435964083 100644
--- a/doc/scripts/configdoc.xsl
+++ b/doc/scripts/configdoc.xsl
@@ -56,22 +56,27 @@
     <!-- Only visit elements having complex types. Those having simple types are
          described as an option -->
     <xsl:choose>
+        <!-- don't document elements if not viewable -->
+        <xsl:when test="xs:annotation/@acrn:views=''">
+        </xsl:when>
       <xsl:when test="//xs:complexType[@name=$ty]">
         <!-- The section header -->
-        <xsl:if test="$level &lt;= 4">
-          <xsl:call-template name="section-header">
-            <xsl:with-param name="title" select="$dxnamePure"/>
-            <xsl:with-param name="label" select="concat($prefix, $dxname)"/>
-            <xsl:with-param name="level" select="$level"/>
-          </xsl:call-template>
-          <!-- Description of this menu / entry -->
-          <xsl:call-template name="print-annotation">
-            <xsl:with-param name="indent" select="''"/>
-          </xsl:call-template>
-          <xsl:value-of select="$newline"/>
-          <!-- use a glossary to show a (sorted) list of config options in this section -->
-          <xsl:value-of select="concat('.. glossary::',$newline,$newline)"/>
-              <!-- <xsl:value-of select="concat('.. glossary::',$newline,' :sorted:',$newline,$newline)"/> -->
+          <xsl:if test="$level &lt;= 4">
+              <xsl:if test="$dxnamePure!=''">
+              <xsl:call-template name="section-header">
+                <xsl:with-param name="title" select="$dxnamePure"/>
+                <xsl:with-param name="label" select="concat($prefix, $dxname)"/>
+                <xsl:with-param name="level" select="$level"/>
+              </xsl:call-template>
+              <!-- Description of this menu / entry -->
+              <xsl:call-template name="print-annotation">
+                <xsl:with-param name="indent" select="''"/>
+              </xsl:call-template>
+              <xsl:value-of select="$newline"/>
+              <!-- use a glossary to show a (sorted) list of config options in this section -->
+              <xsl:value-of select="concat('.. glossary::',$newline,$newline)"/>
+                      <!-- <xsl:value-of select="concat('.. glossary::',$newline,' :sorted:',$newline,$newline)"/> -->
+                  </xsl:if>
         </xsl:if>
         <!-- Visit the complex type to generate menus and/or entries -->
         <xsl:apply-templates select="//xs:complexType[@name=$ty]">
@@ -80,9 +85,6 @@
           <xsl:with-param name="parent" select="."/>
       </xsl:apply-templates>
       </xsl:when>
-      <xsl:when test="xs:annotation/@acrn:views=''">
-        <!-- don't document elements if not viewable -->
-      </xsl:when>
       <xsl:otherwise>
         <xsl:if test="$level = 3">
             <!-- No longer writing a section header for elements with a simple type
@@ -134,13 +136,28 @@
             <xsl:when test="xs:annotation/@acrn:views=''">
               <xsl:text>|icon-not-available| </xsl:text>
             </xsl:when>
+            <xsl:when test="$parent/xs:annotation/@acrn:views=''">
+              <xsl:text>|icon-not-available| </xsl:text>
+            </xsl:when>
             <xsl:otherwise>
-              <xsl:if test="count((ancestor-or-self::node()|$parent)[xs:annotation[contains(@acrn:views,'basic')]][1])!=0">
-                <xsl:text>|icon-basic| </xsl:text>
-              </xsl:if>
-              <xsl:if test="count((ancestor-or-self::node()|$parent)[xs:annotation[contains(@acrn:views,'advanced')]][1])!=0">
-                <xsl:text>|icon-advanced| </xsl:text>
-              </xsl:if>
+                <xsl:choose>
+                    <xsl:when test="count(ancestor-or-self::node()[xs:annotation[@acrn:views]])!=0">
+                      <xsl:if test="count((ancestor-or-self::node())[xs:annotation[contains(@acrn:views,'basic')]][1])!=0">
+                        <xsl:text>|icon-basic| </xsl:text>
+                      </xsl:if>
+                      <xsl:if test="count((ancestor-or-self::node())[xs:annotation[contains(@acrn:views,'advanced')]][1])!=0">
+                        <xsl:text>|icon-advanced| </xsl:text>
+                      </xsl:if>
+                    </xsl:when>
+                  <xsl:otherwise>
+                      <xsl:if test="count(($parent)[xs:annotation[contains(@acrn:views,'basic')]][1])!=0">
+                        <xsl:text>|icon-basic| </xsl:text>
+                      </xsl:if>
+                      <xsl:if test="count(($parent)[xs:annotation[contains(@acrn:views,'advanced')]][1])!=0">
+                        <xsl:text>|icon-advanced| </xsl:text>
+                      </xsl:if>
+                  </xsl:otherwise>
+              </xsl:choose>
             </xsl:otherwise>
           </xsl:choose>
         </xsl:variable>
@@ -189,9 +206,17 @@
     <xsl:param name="level"/>
     <xsl:param name="name"/>
     <xsl:param name="parent"/>
-    <!-- Visit the sub-menus -->
+        <!-- Visit the sub-menus -->
+    <xsl:variable name="newLevel">
+      <xsl:choose>
+        <xsl:when test=".//descendant::xs:annotation/@acrn:title=''">
+          <xsl:value-of select="$level"/>
+        </xsl:when>
+        <xsl:otherwise><xsl:value-of select="$level + 1"/></xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
     <xsl:apply-templates select="descendant::xs:element">
-      <xsl:with-param name="level" select="$level + 1"/>
+      <xsl:with-param name="level" select="$newLevel"/>
       <xsl:with-param name="prefix" select="concat($name, '.')"/>
       <xsl:with-param name="parent" select="$parent"/>
     </xsl:apply-templates>