<oXygen/> can generate detailed documentation for the elements (top-level elements whose names are in the XSLT namespace) of an XSLT stylesheet in HTML format similar with the Javadoc documentation for the components of a Java class. You can select the XSLT elements to be included and the level of detail to be presented for each. Also the elements are hyperlinked. The user can also use its own stylesheets to obtain a custom format.
To generate documentation for an XSLT stylesheet document use the dialog XSLT Stylesheet Documentation. It is opened with the action → → . It can be also opened from the Navigator contextual menu: The dialog enables the user to configure a large set of parameters for the process of generating the documentation.
The XSL URL field of the dialog panel must contain the full path to the XSL Stylesheet file you want to generate documentation for. The stylesheet may be a local or a remote one. You can also specify the path to the stylesheet using editor variables.
You can choose to split the output into multiple files using different split criteria. For large XSLT stylesheets being documented, choosing a different split criterion may generate smaller output files providing a faster documentation browsing.
The available split criteria are:
by location - each output file contains the XSLT elements from the same stylesheet.
by namespace - each output file contains information about elements with the same namespace.
by component - each output file will contain information about one stylesheet XSLT element.
When you generate documentation for an XSLT stylesheet you can choose what XSLT elements to include in the output (templates, functions, global parameters, global variables, attribute sets, character maps, keys, decimal formats, output formats, XSLT elements from referenced stylesheets) and the details to be included in the documentation:
Documentation Show the documentation for each the XSLT element. For HTML format, the user-defined data elements that are recognized and transformed in documentation blocks of the XSLT elements they precede, are the ones from the following schemas:
<oXygen/> built-in XSLT documentation schema. More detailed informations can be found here.
A subset of elements from Docbook 5. The recognized elements are: section, sect1 to sect5, emphasis, title, ulink, programlisting, para, orderedlist, itemizedlist.
A subset of elements from DITA. The recognized elements are: concept, topic, task, codeblock, p, b, i, ul, ol, pre, sl, sli, step, steps, li, title, xref.
Full XHTML 1.0 support.
XSLStyle documentation environment. XSLStyle uses Docbook or DITA languages inside its own user-defined data elements. The supported Docbook and DITA elements are the ones mentioned above.
Doxsl documentation framework. Supported elements are : codefrag, description, para, docContent, documentation, parameter, function, docSchema, link, list, listitem, module, parameter, template, attribute-set.
Other XSLT documentation blocks that are not recognized will just be serialized inside an HTML pre element. You can change this behaviour by using a custom format instead of the built-in HTML format and providing your own XSLT stylesheets.
Use comments The option controls whether or not the comments that precede a XSLT element will be treated as documentation for the element they precede. Comments that precede or succeed the xsl:stylesheet element are treated as documentation for the whole stylesheet. Please note that comments that precede an import or include directive are not collected as documentation for the included/imported module. Also comments from within the body of the XSLT elements are not collected at all.
Namespace Show the namespace for named XSLT elements.
Location Show the stylesheet location for each XSLT element.
Parameters Show parameters of templates and functions.
References Show the named XSLT elements that are referred from within the element.
Used by Show the list of all the XSLT elements that refer the current named element.
Supersedes Show the list of all the XSLT elements that are superseded the current element.
Overriding Show the list of all the XSLT elements that override the current element.
Return type Show the return type for functions.
Source Show the text stylesheet source for each XSLT element.
Import precedence Show the computed import precedence as declared in XSL transformation specifications.
Generate index Create an index with all the XSLT elements included in the documentation.
The generated documentation looks like the one from below:
The generated documentation include a table of contents. The contents can be grouped by namespace, location or component type. The XSLT elements from each group are sorted alphabetically(for templates the named templates are presented first and the match ones second). After the table of contents there is presented some information about the main stylesheet, the imported and included stylesheets. This information consists in the XSLT modules that are included or imported by the current stylesheet, the XSLT stylesheets where the current stylesheet is imported or included and the stylesheet location.
If you choose to split the output into multiple files, the table of contents will be displayed in the left frame. The contents will be grouped using the same criteria as the split.
After the documentation is generated you can collapse details for some stylesheet XSLT elements. This can be done using the Showing view
For each element included in the documentation the section presents the element type follow by the element name (the value of the name attribute or match attribute for match templates).