"Non-specialist" readable versions of schema files

[mlcook]

Our project has a moderate number of schema files, including type definitions and the main elements used by our developers.

Is it (fairly easily) possible to generate some human readable document that summarizes the main XML elements used by our developers?

They don't need to see all of the schema definitions, but mainly the ones they use daily to develop our XML files.

Some time ago, someone tried using XML Spy XSLT Designer to generate a stylesheet that would display elements in a tabular HTML format.

We're using Oxygen now, and I was wondering whether there was some existing feature that helps generate user documentation from schema files.

Our developers are using XML to write our source, but would not generally be skilled at reading and interpreting the "raw" schema files.

They'd like to know what main elements have been defined, and what attributes and sub-elements are associated with the main elements.

Oxygen auto-completion helps, but some would like to see ahead of time all of the attributes and sub-elements without having to try to expand elements, trial-and-error like, with the auto-completion.

We are not using FO or anything similar. Just basic schema and transformation files used by developers to write XML files to be processed.

Suggestions?

Thanks, Mike

[adrian]

Hello,

Oxygen does have an XML Schema Documentation tool(Tools -> Generate Documentation -> Schema Documentation). It generates a somewhat technical documentation but I believe you would find it useful.
More details can be found here:
http://www.oxygenxml.com/xml_schema_documentation.html
and here:
http://www.oxygenxml.com/doc/ug-oxygen/ ... chema.html

Regards,
Adrian

[mlcook]

Super.

I've been able to generate HTML and PDF outputs.

I'm going to try various settings on the output generation to possibly provide easier to read (less verbose) results.

Thanks, Mike

[mlcook]

I have a follow-up question:

I used the "Export Settings" button to save the settings I used for the schema documentation output.

How do I import those settings?

Thanks, Mike

[adrian]

Hi,

There is no import button for getting the settings back into the dialog. The "Export Settings" button is actually meant for saving a configuration file that can be later used by the command line schema documentation tool:
schemaDocumentation.bat - for Windows
schemaDocumentation.sh - for Linux
schemaDocumentationMac.sh - for Mac

Code: Select all

schemaDocumentation schemaFile [ [-cfg:configFile] | [[-out:outputFile] [-format:<value>] [-xsl:xslFile] [-split:<value>] [-openInBrowser:<value>]] | [--help | -help | --h | -h]



Where:

   schemaFile = the XML Schema file

   -cfg:configfile = the configuration file. It contains the output file, split method, output format options and some advanced options regarding the included components and components details.

     If an external configuration file is specified all other supplied arguments except the XML Schema file will be ignored.

     You can create such a file in the Oxygen "Schema Documentation" dialog. See the Oxygen user manual for additional information on how to create one.



   -out:outputFile = the file where the generated documentation will be saved.

     By default it is the name of the schema file with 'html' extension.

   -format:<value> = the output format type used when generating the documentation.

     value = [html | pdf | docbook | custom]

             html    = generate documentation in HTML format.

             pdf     = generate documentation in PDF format.

             docbook = generate documentation in DocBook format.

             custom  = generate documentation in a custom format.



   -xsl:<xslFile> = the XSL file to be applied on the intermediate xml format.

     If there is no xsl file provided then the result will be in the HTML format.

   -split:<value>  = the split method used when generating the documentation. Splitting is recommended for large schemas

     value = [none | namespace | | component | location].

             none      = generate one single output file.

             namespace = generate an output file for every namespace in the schema.

             component = generate an output file for every component in the schema.

             location  = generate an output file for every schema location.

     By default the used method is 'none'

   -openInBrowser:<value> = open the result of the transformation in browser.

     value = [true | false].

             true = open the resulted file in browser.

             false = do not open the resulted file in browser.

     By default the value is false.



   --help | -help | --h | -h = show this help.



Example: schemaDocumentation example.xsd -out:schemaDocumentation.html -format:custom -xsl:example.xsl -split:namespace

We've had some requests for adding the import button as well, so in the next version we will add it to the dialog.

Regards,
Adrian