Schema Documentation Element Order

This should cover W3C XML Schema, Relax NG and DTD related problems.
jonpstatemn
Posts: 7
Joined: Thu Aug 18, 2011 9:53 pm

Schema Documentation Element Order

Post by 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
Posts: 2850
Joined: Tue May 17, 2005 4:01 pm

Re: Schema Documentation Element Order

Post by 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
Adrian Buza
<oXygen/> XML Editor, Schema Editor and XSLT Editor/Debugger
http://www.oxygenxml.com
jonpstatemn
Posts: 7
Joined: Thu Aug 18, 2011 9:53 pm

Re: Schema Documentation Element Order

Post by jonpstatemn »

What should I use for mainFile parameter?
adrian
Posts: 2850
Joined: Tue May 17, 2005 4:01 pm

Re: Schema Documentation Element Order

Post by 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
Adrian Buza
<oXygen/> XML Editor, Schema Editor and XSLT Editor/Debugger
http://www.oxygenxml.com
jonpstatemn
Posts: 7
Joined: Thu Aug 18, 2011 9:53 pm

Re: Schema Documentation Element Order

Post by 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
Posts: 4141
Joined: Fri Mar 28, 2003 2:12 pm

Re: Schema Documentation Element Order

Post by 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
Post Reply