Add link to the header to the synopsis in reference documentation.

Refs #2214

[SVN r49669]

xsl/docbook.xsl

@@ -474,4 +474,25 @@ Error: XSL template 'link-or-anchor' called with invalid link-type '<xsl:value-o
   <xsl:template match="part/part/chapter/chapterinfo|part/part/appendix/appendixinfo">
     <sectioninfo><xsl:apply-templates/></sectioninfo>
   </xsl:template>
+
+  <!-- Header link comment to be inserted at the start of a reference page's
+       synopsis -->
+  <xsl:template name="header-link">
+    <xsl:if test="ancestor::header">
+      <xsl:call-template name="highlight-comment">
+        <xsl:with-param name="text">
+          <xsl:text>// In header: &lt;</xsl:text>
+          <xsl:call-template name="internal-link">
+            <xsl:with-param name="to">
+              <xsl:call-template name="generate.id">
+                <xsl:with-param name="node" select="ancestor::header[1]"/>
+              </xsl:call-template>
+            </xsl:with-param>
+            <xsl:with-param name="text" select="ancestor::header[1]/@name" />
+          </xsl:call-template>
+          <xsl:text>&gt;&#10;&#10;</xsl:text>
+        </xsl:with-param>
+      </xsl:call-template>
+    </xsl:if>
+  </xsl:template>
 </xsl:stylesheet>

xsl/function.xsl

@@ -895,6 +895,7 @@
           <xsl:call-template name="generate.id"/>
         </xsl:with-param>
         <xsl:with-param name="synopsis">
+          <xsl:call-template name="header-link"/>
           <xsl:call-template name="function">
             <xsl:with-param name="indentation" select="0"/>
             <xsl:with-param name="is-reference" select="true()"/>
@@ -976,6 +977,7 @@
           <xsl:call-template name="generate.id"/>
         </xsl:with-param>
         <xsl:with-param name="synopsis">
+          <xsl:call-template name="header-link"/>
           <xsl:for-each select="signature">
             <xsl:call-template name="function">
               <xsl:with-param name="indentation" select="0"/>

xsl/global.xsl

@@ -39,6 +39,7 @@
         </xsl:call-template>
       </xsl:with-param>
       <xsl:with-param name="synopsis">
+        <xsl:call-template name="header-link"/>
         <xsl:call-template name="global-synopsis-impl">
           <xsl:with-param name="link-type" select="'none'" />
         </xsl:call-template>

xsl/macro.xsl

@@ -38,6 +38,7 @@
         </xsl:call-template>
       </xsl:with-param>
       <xsl:with-param name="synopsis">
+        <xsl:call-template name="header-link"/>
         <xsl:call-template name="macro-synopsis">
           <xsl:with-param name="link-type" select="'none'"/>
         </xsl:call-template>

xsl/type.xsl

@@ -410,6 +410,7 @@ Unknown type element "<xsl:value-of select="local-name(.)"/>" in type.display.na
           </xsl:call-template>
         </xsl:with-param>
         <xsl:with-param name="synopsis">
+          <xsl:call-template name="header-link"/>
           <xsl:call-template name="type.typedef.display.aligned">
             <xsl:with-param name="compact" select="false()"/>
             <xsl:with-param name="indentation" select="0"/>
@@ -1056,6 +1057,7 @@ Unknown type element "<xsl:value-of select="local-name(.)"/>" in type.display.na
         <xsl:call-template name="type.display.name"/>
       </xsl:with-param>
       <xsl:with-param name="synopsis">
+        <xsl:call-template name="header-link"/>
         <xsl:call-template name="class-type-synopsis">
           <xsl:with-param name="indentation" select="$indentation"/>
           <xsl:with-param name="allow-synopsis-anchors" select="true()"/>
@@ -1300,6 +1302,7 @@ Unknown type element "<xsl:value-of select="local-name(.)"/>" in type.display.na
           </xsl:call-template>
         </xsl:with-param>
         <xsl:with-param name="synopsis">
+          <xsl:call-template name="header-link"/>
           <xsl:call-template name="type.enum.display"/>
         </xsl:with-param>