Changeset 99513 in vbox for trunk/doc/manual/docbook-refentry-to-C-help.xsl

Timestamp:

Apr 21, 2023 9:59:02 PM (2 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

157010

Message:

manual,VBoxManage,isomaker/viso: Require all refsect1 and refsect2 elements to have @id attributes in manpages (refentry) to make these predictable and the split up topic files easier to handle for the docs team. Also requires these @id values to start with the refentry @id + '-'. Corrected a few bogus ones. Because 'controlvm' has too many sub-commands, HELP_SCOPE_ IDs will not be generated for 'See Also' and 'Examples' sections. bugref:10302

File:

• trunk/doc/manual/docbook-refentry-to-C-help.xsl (modified) (4 diffs)

trunk/doc/manual/docbook-refentry-to-C-help.xsl

@@ -149 +149 @@
     <!-- Then comes the description and other refsect1 -->
     <xsl:for-each select="./refsect1">
+      <!-- assertions -->
       <xsl:if test="name(*[1]) != 'title'"><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Expected title as the first element in refsect1.</xsl:message></xsl:if>
       <xsl:if test="text()"><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>No text supported in refsect1.</xsl:message></xsl:if>
+      <xsl:if test="not(@id)"><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>refsect1 must have an @id attribute.</xsl:message></xsl:if>
+      <xsl:if test="not(starts-with(@id, concat(../@id, '-')))"><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Wrong @id refsect1 prefix: '<xsl:value-of select="@id"/>', expected it to start with '<xsl:value-of select="../@id"/>-'</xsl:message></xsl:if>
+
+      <!-- .... -->
       <xsl:if test="not(./remark[@role='help-skip'])">
         <xsl:variable name="sTitle">
@@ -321 +326 @@
     <xsl:if test="text()"><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>refsect2 shouldn't contain text</xsl:message></xsl:if>
     <xsl:if test="count(./title) != 1"><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>refsect2 requires a title (<xsl:value-of select="ancestor-or-self::*[@id][1]/@id"/>)</xsl:message></xsl:if>
+    <xsl:if test="not(@id)"><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>refsect2 must have an @id attribute.</xsl:message></xsl:if>
+    <xsl:if test="not(starts-with(@id, concat(../../@id, '-')))"><xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Wrong @id refsect2 prefix: '<xsl:value-of select="@id"/>', expected it to start with '<xsl:value-of select="../../@id"/>-'</xsl:message></xsl:if>
 
     <!-- title / command synopsis - sets the scope. -->
@@ -731 +738 @@
   <xsl:template name="calc-scope-refsect1">
     <xsl:choose>
-      <xsl:when test="title[text() = 'Description']">
+      <xsl:when test="contains(@id, '-description') or title[text() = 'Description']">
         <xsl:text>RTMSGREFENTRYSTR_SCOPE_GLOBAL</xsl:text>
       </xsl:when>
-      <xsl:when test="@id or remark[@role='help-scope']">
+      <xsl:when test="(@id and not(contains(@id, '-see-also')) and not(contains(@id, '-examples'))) or remark[@role='help-scope']">
         <xsl:call-template name="calc-scope-from-remark-or-id"/>
       </xsl:when>
@@ -746 +753 @@
   <xsl:template name="calc-scope-refsect2">
     <xsl:choose>
-      <xsl:when test="@id or remark[@role='help-scope']">
+      <xsl:when test="(@id and not(contains(@id, '-see-also')) and not(contains(@id, '-examples'))) or remark[@role='help-scope']">
         <xsl:call-template name="calc-scope-from-remark-or-id"/>
       </xsl:when>