<oXygen/> offers built in support for documenting XSLT stylesheets. The xsl:stylesheet element may contain any element not from the
XSLT namespace, provided that the expanded QName of the element has a non-null namespace
URI. Such elements are referred to as user-defined data elements. Such elements can
contain the documentation for the stylesheet and its elements (top-level elements whose
names are in the XSLT namespace). <oXygen/> offers its own XML schema that defines such
documentation elements. The schema is named
stylesheet_documentation.xsd
and can be found in
{INSTALATION_DIRECTORY}/frameworks/stylesheet_documentation
. The
user can also specify its own schema in XSL Content Completion options.
When content completion is invoked inside an XSLT editor by pressing CTRL+Space, it will also offer elements from the XSLT documentation schema (either the built-in one or one specified by user). A contextual action for adding documentation blocks is also available for the Text mode in the editor contextual menu → or for the Author contextual menu → . Other documentation actions available in the Author page from the Component Documentation contextual sub menu are:
Paragraph - Insert a new documentation paragraph
Bold - Make the selected documentation text bold
Italic - Make the selected documentation text italic
List - Insert a new list
List Item - Insert a list item
Reference - Insert a documentation reference
If you are with the caret inside the xsl:stylesheet element context, documentation blocks will be generated for all XSLT elements. If you are with the caret inside a specific XSLT element (like a template or a function) a documentation block will be generated for that element only.
Example 4.14. Example of a documentation block using <oXygen/> built-in schema
<xd:doc> <xd:desc> <xd:p>Search inside parameter <xd:i>string</xd:i> for the last occurrence of parameter <xd:i>searched</xd:i>. The substring starting from the 0 position to the identified last occurrence will be returned. <xd:ref name="f:substring-after-last" type="function" xmlns:f="http://www.oxygenxml.com/doc/xsl/functions">See also</xd:ref></xd:p> </xd:desc> <xd:param name="string"> <xd:p>String to be analyzed</xd:p> </xd:param> <xd:param name="searched"> <xd:p>Marker string. Its last occurrence will be identified</xd:p> </xd:param> <xd:return> <xd:p>A substring starting from the beginning of <xd:i>string</xd:i> to the last occurrence of <xd:i>searched</xd:i>. If no occurrence is found an empty string will be returned.</xd:p> </xd:return> </xd:doc>
The tool for XSLT documentation will recognize the documentation language and will include the documentation in the generated HTML files. More information about the XSLT documentation tool can be found here.