[Boost-commit] svn:boost r41698 - trunk/tools/boostbook/xsl

From: fmhess_at_[hidden]
Date: 2007-12-04 14:55:50

Author: fmhess
Date: 2007-12-04 14:55:50 EST (Tue, 04 Dec 2007)
New Revision: 41698
URL: http://svn.boost.org/trac/boost/changeset/41698

Log:
Made generated ids for functions and overloaded functions human-readable 
which also results in (mostly) human-readable names for 
their .html output files. Made generate.id template properly use 
its node parameter (merge of parts of revision 41461 from sandbox/boost_docs). 

Made class name in synopsis a link to class reference page, which is useful 
for nested classes (merge of revision 41435 from sandbox/boost_docs). 

Removed spurious new line in synopisis between a nested class 
and the comment describing its purpose (merge of revision 41434 from
sandbox/boost_docs). 

Added a warning if an "inherit" element has 
no "type" child element (partial merge of revision 41463 from
sandbox/boost_docs). 

Text files modified: 
   trunk/tools/boostbook/xsl/annotation.xsl |    22 +++++++++++-------                      
   trunk/tools/boostbook/xsl/lookup.xsl     |    16 ++++++-------                           
   trunk/tools/boostbook/xsl/type.xsl       |    46 ++++++++++++++++++++++++++++++++------- 
   3 files changed, 57 insertions(+), 27 deletions(-)

Modified: trunk/tools/boostbook/xsl/annotation.xsl
==============================================================================
--- trunk/tools/boostbook/xsl/annotation.xsl	(original)
+++ trunk/tools/boostbook/xsl/annotation.xsl	2007-12-04 14:55:50 EST (Tue, 04 Dec 2007)
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!--
    Copyright (c) 2002 Douglas Gregor <doug.gregor -at- gmail.com>
-  
+
    Distributed under the Boost Software License, Version 1.0.
    (See accompanying file LICENSE_1_0.txt or copy at
    http://www.boost.org/LICENSE_1_0.txt)
@@ -21,10 +21,10 @@
   <xsl:template match="function|overloaded-function" mode="generate.id">
     <xsl:variable name="name" select="normalize-space(@name)"/>
     <xsl:variable name="translated-name"
-                  select="translate($name, 
-                                    '~!%^&amp;*()[].,&lt;&gt;|/ +-=', 
+                  select="translate($name,
+                                    '~!%^&amp;*()[].,&lt;&gt;|/ +-=',
                                     'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')"/>
-                      
+
     <xsl:choose>
       <xsl:when test="count(key('named-entities', $name))=1
                       and ($translated-name=$name)">
@@ -163,7 +163,7 @@
       <xsl:with-param name="name" select="$name"/>
       <xsl:with-param name="display-name" select="string(.)"/>
       <xsl:with-param name="unqualified-name" select="$unqualified-name"/>
-      <xsl:with-param name="nodes" 
+      <xsl:with-param name="nodes"
         select="key('functions', $unqualified-name)"/>
     </xsl:call-template>
   </xsl:template>
@@ -207,7 +207,7 @@
       <xsl:with-param name="name" select="$name"/>
       <xsl:with-param name="display-name" select="string(.)"/>
       <xsl:with-param name="unqualified-name" select="$unqualified-name"/>
-      <xsl:with-param name="nodes" 
+      <xsl:with-param name="nodes"
         select="key('enums', $unqualified-name)"/>
     </xsl:call-template>
   </xsl:template>
@@ -225,7 +225,7 @@
     </xsl:variable>
 
     <xsl:variable name="node" select="key('libraries', $name)"/>
-    
+
     <xsl:choose>
       <xsl:when test="count($node)=0">
         <xsl:message>
@@ -254,7 +254,7 @@
 
   <xsl:template match="macroname" mode="annotation">
     <xsl:param name="name" select="text()"/>
-    
+
     <xsl:variable name="node" select="key('macros', $name)"/>
     <xsl:choose>
       <xsl:when test="count($node) = 0">
@@ -290,7 +290,7 @@
 
   <xsl:template match="headername" mode="annotation">
     <xsl:param name="name" select="text()"/>
-    
+
     <xsl:variable name="node" select="key('headers', $name)"/>
     <xsl:choose>
       <xsl:when test="count($node) = 0">
@@ -350,6 +350,10 @@
     </emphasis>
   </xsl:template>
 
+  <xsl:template match="description" mode="annotation">
+    <xsl:apply-templates mode="annotation"/>
+  </xsl:template>
+
   <xsl:template match="comment()" mode="annotation">
     <xsl:copy/>
   </xsl:template>

Modified: trunk/tools/boostbook/xsl/lookup.xsl
==============================================================================
--- trunk/tools/boostbook/xsl/lookup.xsl	(original)
+++ trunk/tools/boostbook/xsl/lookup.xsl	2007-12-04 14:55:50 EST (Tue, 04 Dec 2007)
@@ -14,15 +14,13 @@
   <!-- Generate an ID for the entity referenced -->
   <xsl:template name="generate.id">
     <xsl:param name="node" select="."/>
-    <xsl:choose>
-      <xsl:when test="ancestor::class-specialization|ancestor::struct-specialization|ancestor::union-specialization">
-        <xsl:value-of select="generate-id(.)"/>
-        <xsl:text>-bb</xsl:text>
-      </xsl:when>
-      <xsl:otherwise>
-        <xsl:apply-templates select="$node" mode="generate.id"/>
-      </xsl:otherwise>
-    </xsl:choose>
+    <xsl:apply-templates select="$node" mode="generate.id"/>
+    <xsl:if test="$node/ancestor-or-self::class-specialization|
+      $node/ancestor-or-self::struct-specialization|
+      $node/ancestor-or-self::union-specialization">
+      <xsl:text>_</xsl:text>
+      <xsl:value-of select="generate-id($node)"/>
+    </xsl:if>
   </xsl:template>
 
   <xsl:template match="*" mode="generate.id">

Modified: trunk/tools/boostbook/xsl/type.xsl
==============================================================================
--- trunk/tools/boostbook/xsl/type.xsl	(original)
+++ trunk/tools/boostbook/xsl/type.xsl	2007-12-04 14:55:50 EST (Tue, 04 Dec 2007)
@@ -33,6 +33,13 @@
     </xsl:call-template>
   </xsl:template>
 
+  <xsl:template match="class-specialization|struct-specialization|union-specialization" mode="generate.id">
+    <xsl:call-template name="fully-qualified-name">
+      <xsl:with-param name="node" select="."/>
+      <xsl:with-param name="separator" select="'.'"/>
+    </xsl:call-template>
+  </xsl:template>
+
   <xsl:template match="typedef" mode="generate.id">
     <xsl:call-template name="fully-qualified-name">
       <xsl:with-param name="node" select="."/>
@@ -56,6 +63,15 @@
     <xsl:value-of select="@name"/>
   </xsl:template>
 
+  <xsl:template match="function | overloaded-function" mode="generate.id">
+    <xsl:call-template name="fully-qualified-name">
+      <xsl:with-param name="node" select="."/>
+      <xsl:with-param name="separator" select="'.'"/>
+    </xsl:call-template>
+    <xsl:text>_</xsl:text>
+    <xsl:value-of select="generate-id(.)"/>
+  </xsl:template>
+
   <!-- Display the full name of the current node, e.g., "Class
        template function". -->
   <xsl:template name="type.display.name">
@@ -518,6 +534,10 @@
           <xsl:apply-templates select="type/*|type/text()" mode="annotation"/>
         </xsl:when>
         <xsl:otherwise>
+          <xsl:message>
+            <xsl:text>Warning: missing 'type' element inside 'inherit'</xsl:text>
+          </xsl:message>
+          <xsl:call-template name="print.warning.context"/>
           <xsl:apply-templates mode="annotation"/>
         </xsl:otherwise>
       </xsl:choose>
@@ -540,8 +560,8 @@
         <xsl:call-template name="highlight-comment">
           <xsl:with-param name="text">
             <xsl:text>// </xsl:text>
-            <xsl:apply-templates select="purpose/*|purpose/text()"
-              mode="annotation"/>
+            <xsl:apply-templates select="purpose"
+              mode="comment"/>
           </xsl:with-param>
         </xsl:call-template>
       </xsl:if>
@@ -855,7 +875,6 @@
             <xsl:apply-templates select="purpose" mode="comment"/>
           </xsl:with-param>
         </xsl:call-template>
-        <xsl:text>&#10;</xsl:text>
       </xsl:if>
     </xsl:if>
 
@@ -878,7 +897,19 @@
       <xsl:with-param name="keyword" select="$class-key"/>
     </xsl:call-template>
     <xsl:text> </xsl:text>
-    <xsl:value-of select="@name"/>
+
+    <!--  Make the class name a link to the class reference page (useful for nested classes) -->
+    <xsl:call-template name="internal-link">
+      <xsl:with-param name="to">
+        <xsl:call-template name="generate.id">
+          <xsl:with-param name="node" select="."/>
+        </xsl:call-template>
+      </xsl:with-param>
+      <xsl:with-param name="text">
+        <xsl:value-of select="@name"/>
+      </xsl:with-param>
+    </xsl:call-template>
+
     <xsl:apply-templates select="specialization"/>
 
     <xsl:choose>
@@ -1190,7 +1221,7 @@
           <xsl:call-template name="highlight-comment">
             <xsl:with-param name="text">
               <xsl:text>// </xsl:text>
-              <xsl:apply-templates select="purpose/*|purpose/text()" mode="annotation"/>
+              <xsl:apply-templates select="purpose" mode="comment"/>
             </xsl:with-param>
           </xsl:call-template>
 
@@ -1415,10 +1446,7 @@
           </xsl:call-template>
         </term>
         <listitem>
-          <xsl:apply-templates
-            select="purpose/*|purpose/text()|
-                    description/*|description/text()"
-            mode="annotation"/>
+          <xsl:apply-templates select="purpose|description" mode="comment"/>
         </listitem>
       </varlistentry>
     </xsl:if>