Output Formats for Generating XML Schema Documentation

HTML Output Format

The XML Schema documentation generated in HTML format contains images corresponding to the same schema definitions as the ones displayed by the schema diagram editor. These images are divided in clickable areas that are linked to the definitions of the names of types or elements. The documentation of a definition includes a Used By section with links to the other definitions that reference it. If the Escape XML Content option is unchecked, the HTML or XHTML tags used inside the xs:documentation elements of the input XML Schema for formatting the documentation text (for example, <b>, <i>, <u>, <ul>, <li>, etc.) are rendered in the generated HTML documentation.

The generated images format is PNG. The image of an XML Schema component contains the graphical representation of that component as it is rendered in the schema diagram panel of the Oxygen XML Author plugin XSD editor panel.

XML Schema Documentation Example

The generated documentation includes a table of contents. You can group the contents by namespace, location, or component type. After the table of contents there is some information about the main, imported, included, and redefined schemas. This information contains the schema target namespace, schema properties (attribute form default, element form default, version), and schema location.

Information About a Schema

If you choose to split the output into multiple files, the table of contents is displayed in the left frame. The contents are grouped in the same mode. If you split the output by location, each file contains a schema description and the components that you have chosen to include. If you split the output by namespace, each file contains information about schemas from that namespace and the list with all included components. If you choose to split the output by component, each file contains information about a schema component.

After the documentation is generated, you can collapse or expand details for some schema components by using the Showing options or the Collapse or Expand buttons.

Showing Options

For each component included in the documentation, the section presents the component type follow by the component name. For local elements and attributes, the name of the component is specified as parent name/component name. You can easily go to the parent documentation by clicking the parent name.

Documentation for a Schema Component

If the schema contains imported or included modules, their dependencies tree is generated in the documentation.

Example: Generated Documentation

PDF Output Format

For the PDF output format, the documentation is generated in DocBook format and a transformation using the FOP processor is applied to obtain the PDF file. To configure the FOP processor, see the FO Processors preferences page.

For information about customizing the PDF output, see Customizing the PDF Output of Generated XML Schema Documentation.

DocBook Output Format

If you generate the documentation in DocBook output format, the documentation is generated as a DocBook XML file. You can then apply a predefined transformation scenario (such as, DocBook PDF or DocBook HTML) on the output file, or configure your own transformation scenario for it to convert it into whatever format you desire.

Custom Output Format

For the custom format, you can specify a stylesheet to transform the intermediary XML file generated in the documentation process. You have to edit your stylesheet based on the schema xsdDocSchema.xsd from [OXYGEN_INSTALL_DIR]/frameworks/schema_documentation. You can create a custom format starting from one of the stylesheets used in the predefined HTML, PDF, and DocBook formats. These stylesheets are available in [OXYGEN_INSTALL_DIR]/frameworks/schema_documentation/xsl.

When using a custom format you can also copy additional resources into the output folder and choose to keep the intermediate XML files created during the documentation process.