Generating Documentation for an XSLT Stylesheet

You can use Oxygen XML Editor to generate detailed documentation in HTML format for the elements (top-level elements whose names are in the XSLT namespace) of an XSLT stylesheet. You are able to select what XSLT elements to include in the generated documentation and also the level of details to present for each of them. The elements are hyperlinked. To generate documentation in a custom format, other than HTML, you can edit the XSLT stylesheet used to generate the documentation, or create your own stylesheet.

To open the XSLT Stylesheet Documentation dialog, select XSLT Stylesheet Documentation... from the Tools > Generate Documentation menu or from the Generate Documentation submenu in the contextual menu of the Project view.

Figure: The Output Panel of the XSLT Stylesheet Documentation Dialog Box

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 can be either a local or a remote one. You can also specify the path of 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 contains information about one stylesheet XSLT element.

You can export the settings of the XSLT Stylesheet Documentation dialog to an XML file by pressing the Export settings button. With the exported settings file, you can generate the same documentation from the command-line interface.

Figure: The Settings Panel of the XSLT Stylesheet Documentation Dialog

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 include in the documentation:

Documentation - Shows the documentation for each 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 XML Editor built-in XSLT documentation schema.
- A subset of DocBook 5 elements. The recognized elements are: section, sect1 to sect5, emphasis, title, ulink, programlisting, para, orderedlist, itemizedlist.
- A subset of DITA elements. 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 behavior by using a custom format instead of the built-in HTML format and providing your own XSLT stylesheets.
Use comments - Controls whether the comments that precede an XSLT element is 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 imported/included module. Also comments from within the body of the XSLT elements are not collected at all.
Namespace - Shows the namespace for named XSLT elements.
Location - Shows the stylesheet location for each XSLT element.
Parameters - Shows parameters of templates and functions.
References - Shows the named XSLT elements that are referenced from within an element.
Used by - Shows the list of all the XSLT elements that reference the current named element.
Supersedes - Shows the list of all the XSLT elements that are superseded the current element.
Overriding - Shows the list of all the XSLT elements that override the current element.
Return type - Shows the return type of the function.
Source - Shows the text stylesheet source for each XSLT element.
Import precedence - Shows the computed import precedence as declared in XSL transformation specifications.
Generate index - Creates an index with all the XSLT elements included in the documentation.
Load settings / Export settings - The current settings can be saved for further usage (for example for generating documentation from command-line interface) with the Export settings button, and reloaded when necessary with the Load settings button.