Login | Register   
Twitter
RSS Feed
Download our iPhone app
TODAY'S HEADLINES  |   ARTICLE ARCHIVE  |   FORUMS  |   TIP BANK
Browse DevX
Sign up for e-mail newsletters from DevX


advertisement
 

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

By adding XML-based documentation capability to your SQL code, you can automatically extract and format tagged comments into a complete API documentation set for your SQL libraries.


advertisement
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.

Table 4: The <cc:see> Element: Use this element to insert reference hyperlinks to either internal (other function/procedure) or external (any link) documentation.
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.


Table 5: The <cc:seealso> Element: Use this element to render a "See also" hyperlink in a separate paragraph.
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>



Comment and Contribute

 

 

 

 

 


(Maximum characters: 1200). You have 1200 characters left.

 

 

Sitemap