Add Custom XML Documentation Capability To Your SQL Code : Page 4

Display an Inline Reference as a Hyperlink
The XSLT rule for this element shows some of the flexibility and power available from XSLT. Table 4 shows two variations on the element, but there are actually four because you can omit the reference-text in either variation. All variations get transformed into the HTML <a> element you can see in the last row of Table 4. If you do specify the reference-text, the text is used as the displayed portion of the hyperlink; if not, then whatever you supplied for the cref or href attribute serves double duty as both the link and the display text. The cref (short for code reference) attribute lets you specify other procedures or functions within your own documentation tree. As the example shows, that gets converted to the appropriate XHTML in the <a> element link. An href attribute, on the other hand, is used verbatim, and lets you specify any URL. Note that the XSLT rule for this element contains two templates because the <_see> template is shared by the <cc:seealso> element, which is discussed next.

XML element	<cc:see cref="reference-function-or-procedure-name">     reference-text </cc:see> - - OR - -<cc:see href="reference-URL">     reference-text </cc:see>
XML schema representation
XSLT rule	<xsl:template match="cc:see">   <xsl:call-template name="_see"/> </xsl:template> <xsl:template name="_see">   <a>     <xsl:attribute name="href">       <xsl:choose>         <xsl:when test="string-length(@cref)">           <xsl:value-of select="@cref"/>.html</xsl:when>         <xsl:otherwise>           <xsl:value-of select="@href"/>         </xsl:otherwise>       </xsl:choose>     </xsl:attribute>     <xsl:choose>       <xsl:when test="string-length(.)">         <xsl:value-of select="."/>       </xsl:when>       <xsl:when test="string-length(@cref)">         <xsl:value-of select="@cref"/>       </xsl:when>       <xsl:otherwise>         <xsl:value-of select="@href"/>       </xsl:otherwise>     </xsl:choose>   </a> </xsl:template>
SQL input sample	— Adapted from <cc:see href="http://stuff.com/text42"> — The Meaning Of Life</cc:see> — and <cc:see cref="MyOtherProc"/>.
Intermediate XML sample	Adapted from <cc:see href="http://stuff.com/text42"> The Meaning Of Life</cc:see> and <cc:see cref="MyOtherProc"/>.
XHTML output sample(see Figure 2, frame 4)	Adapted from <a href="http://stuff.com/text42">The Meaning Of Life</a> and <a href="MyOtherProc.html">MyOtherProc</a>.

Display a Reference Hyperlink
The XSLT rule for <cc:seealso> uses the same base code, the same parameters, and the same variations as <cc:see>. The only difference is in the final XHTML rendering: <cc:see> is for an inline reference, while <cc:seealso> renders as a separate paragraph, typically used at the end of a documentation page.

XML element	<cc:seealso cref="reference-function-or-procedure-name">     reference-text </cc:seealso> - - OR - -<cc:seealso href="reference-URL">     reference-text </cc:seealso>
XML schema representation
XSLT rule	<xsl:template match="cc:seealso"> <p>See also: <xsl:call-template name="_see"/> </p> </xsl:template> <xsl:template name="_see"> Omitted body . . . same as for <cc:see> element </xsl:template>
SQL input sample	— <cc:seealso href="http://stuff.com/text42"> — The Meaning Of Life</cc:seealso> — <cc:seealso cref="MyOtherProc"/>
Intermediate XML sample	<cc:seealso href="http://stuff.com/text42"> The Meaning Of Life</cc:seealso> <cc:seealso cref="MyOtherProc"/>
XHTML output sample(see Figure 2, frame 5)	<p> See also:     <a href="http://stuff.com/text42">The Meaning Of Life</a> </p> <p> See also:     <a href="MyOtherProc.html">MyOtherProc</a> </p>

Previous Page

Next Page