Edit online

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 can 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 output format, you can edit the XSLT stylesheet used to generate the documentation, or create your own stylesheet.

To open the XSLT Stylesheet Documentation dialog box, select XSLT Stylesheet Documentation from the Tools > Generate Documentation menu or from the Generate Documentation submenu in the contextual menu of the Project view. You can also open the tool by using the Generate Documentation toolbar button.

Figure 1. XSLT Stylesheet Documentation Dialog Box

The XSL URL field of the dialog box 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 file. You can specify the path to the stylesheet by entering it in the text field, or by using the Insert Editor Variables button or the options in the Browse drop-down menu.

Output Tab

The following options are available in the Output tab:
  • Format - Allows you to choose between the following formats:
    • HTML - The documentation is generated in HTML output format.
    • Custom - The documentation is generated in a custom output format, allowing you to control the output. Click the Options button to open a Custom format options dialog box where you can specify a custom stylesheet for creating the output. There is also an option to Copy additional resources to the output folder and you can select the path to the additional Resources that you want to copy. You can also choose to keep the intermediate XML files created during the documentation process by deselecting the Delete intermediate XML file option.
  • Output file - You can specify the path of the output file by entering it in the text field, or by using the Insert Editor Variables button or the options in the Browse drop-down menu.
  • Split output into multiple files - Instructs the application to split the output into multiple files. For large XSLT stylesheets, choosing another split criterion may generate smaller output files, providing faster documentation browsing. You can choose to split them by namespace, location, or component name.
  • Open in Browser/System Application - Opens the result in the system application associated with the output file type.
    Note:
    To set the browser or system application that will be used, open the Preferences dialog box (Options > Preferences), go to Global, and set it in the Default Internet browser field. This will take precedence over the default system application settings.

Settings Tab

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.

Figure 2. Settings Tab of the XSLT Stylesheet Documentation Dialog Box

The Settings tab allows you to choose whether or not to include the following components: Templates, Functions, Global parameters, Global variables, Attribute sets, Character maps, Keys, Decimal formats, Output formats, Referenced stylesheets.

You can choose whether or not to include the following other details:

  • 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 or not 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. 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 the XSL transformation specifications.
  • Generate index - Creates an index with all the XSLT elements included in the documentation.

Export settings - Save the current settings in a settings file for further use (for example, if you need the exported settings file for generating the documentation from the command-line interface).

Import settings - Reloads the settings from the exported file.

Generate - Use this button to generate the XSLT documentation.

Tip:
This function can be executed from an automated command-line script, for more details, see Scripting Oxygen.