Edit online

Output Formats for Generating XML Schema Documentation

XML Schema documentation can be generated in HTML, PDF, DocBook, or a custom format. You can choose the format from the Schema Documentation dialog box. For the PDF and DocBook formats, the option to split the output in multiple files is not available.

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 Editor XSD editor panel.

Figure 1. 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.

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.

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.

Figure 4. Documentation for a Schema Component

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

Figure 5. 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 PDF or DocBook 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 built-in DocBook transformation scenario (such as, DocBook PDF or DocBook HTML) on the output file, or configure your own transformation scenario to convert it into whatever format you desire.

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

DITA Output Format

If you generate the documentation in DITA output format, each element of the schema is converted to a DITA Topic and all the generated topics are referenced in a DITA map file. You can then apply a built-in DITA transformation scenario (such as, DITA Map PDF or DITA Map XHTML), or configure your own DITA-OT transformation scenario to convert it into whatever format you desire.

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

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 built-in HTML, PDF, DocBook, and DITA 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.

Important: If you create a custom format for DITA, you must select the Split output into multiple files option in the Output tab and choose Split by component.