Schema Documentation Element Order

[jonpstatemn]

Can I customize the schema documentation generation. I want to produce a user-friendly report that only displays xsd:elements to use for training purposes. However, oxygen xml appears to start at the top of the schema and moves down.

So it starts at Report root then delves into the report complex type. There are 5 different types of reports. The generation tool then delves into all of the 1st Report type elements. The pdf document displays the elements in order that the elements were discovered.

It would be better if I could define a sort order. My preference would be Report elements, Report Type elements, Entity Choice elements, Entity elements, All other elements.

I have created my own cvs export using the desired order. However, excel does not make the data very pretty.

I believe that documentation generation tool first converts the schema into docbook file and then creates the pdf. Can I customize the docbook file?

Thank you for your assistance,

Jon Peterson

[adrian]

Hello,

You can find a copy of the stylesheet that generates the documentation in DocBook format in Oxygen/frameworks/schema_documentation/xsl/xsdDocDocbook.xsl
Note that this is just a copy of the stylesheet that Oxygen uses to generate the documentation in DocBook format, not the actual stylesheet used by Oxygen(that one is builtin).

After making your modifications to the xsl file, in the Schema Documentation dialog you have to use Output: Custom, press the Options button and choose as Custom XSL the one modified.
You will also want to 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).


One idea for using a custom sorting order is to declare a variable with the order, something like the example below. In this example the key attribute represents the element qualified name and the value represents its priority:

Code: Select all

<xsl:variable name="sortOrder">

  <entry key="elemB">1</entry>

  <entry key="elemC">1</entry>

  <entry key="elemA">2</entry>

</xsl:variable>

Next you must intervene in template "main". You should replace each occurrence of the following block (there are 3 such blocks, each one for a specific grouping)

Code: Select all

<xsl:for-each select="current-group()">

  <xsl:apply-templates select="."/>

</xsl:for-each>

with a :

Code: Select all

<xsl:for-each select="current-group()">

  <xsl:sort select="$sortOrder/*[current()/qname/text() = @key]/text()"/>

  <xsl:sort select="qname/text()" order="ascending"/>

  <xsl:apply-templates select="."/>

</xsl:for-each>

This will sort all elements after the given priority first and after the qualified name second(when they have the same priority). If this is not exactly what you want, you should change it to meet your needs.

Regards,
Adrian

[jonpstatemn]

What should I use for mainFile parameter?

[adrian]

Hi,

You don't have to set the mainFile parameter. The schema documentation tool will set it when running the transformation with the stylesheet.

Note that you can't really use the stylesheet independently from the schema documentation tool since it's designed to be applied on an XML generated internally by the schema documentation tool.

Regards,
Adrian

[jonpstatemn]

I was not able to get your suggestions to work to my satisfaction. However, I used the schema documentation tool to generate a docbook xml file. Then I did an identity transform on that xml file in order to change the sort order (sort by section/@xml:id). Finally, the new docbook xml file is transformed to pdf.

Could this suggestion be implemented in a future version?

Thanks for steering me in the right direction.

[sorin_ristache]

Hello,

Thank you for your suggestion for sorting the elements in the output of the schema documentation. We will consider it for a future version.


Thank you,
Sorin