Generate Modular Documentation for Modular Schemas

[tf-rstokoe]

I am working on a family of schemas that share common elements. To reduce duplication, types that are commonly reused are extracted out to a separate schema that can then be included in multiple schemas. One example is a type for US counties, which has a list of over 3000 enumerations. If this schema is included in another, such as one for addresses, then the documentation for that schema will include all 3k enumerations, which makes it much bigger than necessary.

I would like to either not list facets for types that come from an schema that has been imported, or limit the number shown to just a few values for external types. Documentation for the common schema will be published as a separate document, so the information will still be available. I just don't want it duplicated in the documentation for every schema that uses it.

There are a few settings that are close to what I want but still fall short of the desired result:

One is that facets can be excluded from the documentation, but I still want them to be included for types in the schema being documented, just not included for types that have been imported from another schema.

Another setting is whether to include referenced schemas. Unchecking this makes it so that not all of the definitions from any referenced schemas get included, but ones that are referenced are still included. I would want to exclude all definitions from referenced schemas, even if they are referenced.

I also looked at putting the common types in a separate namespace from the dependent schema. There is a setting for generating separate files based on namespace, but it isn't available for PDF documentation, and I would like to generate a PDF.

Is there some combination of settings that would allow me to accomplish this?

[adrian]

Hello,

I'm afraid there are no user options that can help you achieve these things. It might be possible to achieve them by customizing the stylesheet used to publish the schema documentation. But it can take some significant tinkering and XSL knowledge to filter facets for a specific schema (or all imported?).
A copy of the stylesheets that Oxygen uses for publishing the schema documentation is located in:
Oxygen/frameworks/schema_documentation/xsl
Their names should indicate what each one does:

• xsdDocDita.xsl for publishing to DITA
• xsdDocDocbook.xsl for publishing to DocBook (Oxygen uses this for publishing to PDF in two steps)
• xsdDocHtml.xsl for publishing to HTML

Note that modifying these is not sufficient to affect the builtin schema documentation.
To use a custom XSL in the Schema Documentation dialog you have to use Format: Custom, press the Options button and choose as Custom XSL: Oxygen/frameworks/schema_documentation/xsl/xsdDocDocbook.xsl (or xsdDocHtml.xsl for HTML) (this is a copy of the Oxygen builtin stylesheet).
Also enable the option "Copy additional resources...". Note that this will not output directly to PDF, this will generate an XML document(DocBook) that you can then open in Oxygen and transform to PDF(Document -> Transformation -> Configure Transformation Scenario, choose Docbook PDF and press "Transform now").

To obtain a transformation scenario with the same PDF styling, duplicate the DocBook PDF transformation scenario and:
- Give the new scenario a proper name e.g. DocBook XSD Doc PDF
- Change the stylesheet(XSL URL) to: <Oxygen>/frameworks/docbook/oxygen/xsdDocDocbookCustomizationFO.xsl
Applying this transformation scenario will yield the same styling as when generating the PDF directly from the Schema Documentation dialog.

I also looked at putting the common types in a separate namespace from the dependent schema. There is a setting for generating separate files based on namespace, but it isn't available for PDF documentation, and I would like to generate a PDF.

For HTML it's a hierarchy of files linked together, but it's still considered a single output (a single index.html). For PDF that's not possible, you can't make references to other PDFs and navigate them, so a single PDF is always published.

Regards,
Adrian