Products         Customers         News         Downloads         Licensing         Shop    

 DocFlex Technology
Overview
Features
Documentation
 DocFlex/XML
Overview
Features
Documentation
XSDDoc
WSDLDoc
Integrations
Apache Ant
Apache Maven
XMLSpy
Oxygen XML
Bundles
 DocFlex/Javadoc
Overview
Documentation
Basic Templates
JavadocPro
Examples
Tutorials
 DocFlex/Together
Overview
Examples
Basic Templates
Documentation
Tutorials
 Try
Downloads
Registration
Trial License
 Buy
Licensing
Shop
 Company
News
Products
Customers
About Us
Imprint
Legal
Contact
Links
 

DocFlex/XML - Integrations - Oxygen XML

  1. Overview
  2. Getting Started
  3. Settings Detail
  4. Generator Setups

1.  Overview

This integration will let you generated XML schema documentation (using DocFlex/XML XSDDoc templates) with the automatic insertion of component diagrams produced by Oxygen XML Editor, with the full support of diagram hyperlinks.

That, in effect, will turn the DocFlex/XML+OxygenXML combination into a single unique documentation generator not available in any of these products. Click on the following screenshot to see a sample documentation generated with it:

You can also download this demo documentation by the link: xslt20-xsddoc.zip (4.7 MB)

NOTE: The same will be extended later to the WSDLDoc -- the coming WSDL documentation generator.

Key Features

  • Possibility to run OxygenXML from DocFlex/XML templates to perform specific tasks, namely:
  • Associating the diagrams (and hyperlink image maps) generated by OxygenXML with the DSM elements representing the XML schema components in templates and making them available (via Image Control) to be inserted in the output documentation generated by DocFlex/XML.
  • Automatic insertion of XSD component diagrams produced by OxygenXML into the XML schema documentation generated by DocFlex/XML XSDDoc. The diagrams can be generated in the following formats:
    • PNG
    • GIF
    • JPEG
    which are fully supported both in HTML and RTF output.
  • Full support of diagram hyperlinks (in HTML output).
  • Processing of complex XML schemas with <xs:import>, <xs:include>, <xs:redefine> of other XML schemas and generating single documentation for all involved XML schemas together with all OxygenXML diagrams in place. (See also: Using XML Catalog.)
  • Possibility to run the unified DocFlex/XML+OxygenXML template-driven documentation generators from both:

Technical Requirements

  • Any edition of OxygenXML that includes its own XML Schema Documentation (for instance, “Oxygen XML Editor”).

    Concerning which versions are supported, we have tested this integration starting from Oxygen XML 13. Actually, all comes down to the following:

    • The schemaDocumentation.bat (or schemaDocumentation.sh under Linux) is included.
    • All parameters/options of the OxygenXML's own doc-generator can be set via a special config-file passed as the schemaDocumentation.bat argument.
    • It is also supported passing a custom XSLT style sheet, which receives as input some intermediate XML file (produced by OxygenXML) so as to generate from it any other type of output.
    • The structure of that intermediate XML file is backward compatible with the one generated by Oxygen XML 15.

      The XSLT style sheet passed by the integration converts the XML file generated by OxygenXML into another XML file convenient for further processing by the integration Java code.

    As long as those things remain the same in the future OxygenXML version, the current integration will work with them as well.
  • Java version 7.x, 6.x or 5.x (JDK or JRE) installed on your system.
  • A computer with 2 GB RAM (or more)

Licensing / Processing Modes

Being a complex piece of software, which took lots of efforts to develop, the OxygenXML Integration requires a separate licensing. Depending on your license, the integration may work in one of two different modes: full or trial, as described in the following table:

Processing

Description

Full Mode
The Full Mode is activated in the presence of a Commercial or Academic License for “DocFlex/XML OxygenXML Integration”.

This mode allows you to use the integration without any limitations. Once it is enabled, you may think about the integration as just another part of DocFlex/XML executables.

Anything else will depend on your other licenses.
Trial Mode
The Trial Mode is activated in the presence of a Trial License for “DocFlex/XML OxygenXML Integration”. In this mode, the integration will work the same as in the full mode. However, no matter what your other licenses are the following limitations will be enforced:
  • You may use the integration working in trial mode only during the limited period of time (30 days) provided by your Trial License.
  • Any output documents generated in trial mode will be specifically distorted. Such documents may be used only for evaluation of this software. Any other usage is prohibited!
The trial mode for OxygenXML Integration will not affect your possibility to create/modify templates. This is controlled by your license for DocFlex/XML SDK!

See Also:

2.  Getting Started

Since OxygenXML Integration is closely connected with the DocFlex/XML core, all Java classes implementing it are included in the general DocFlex/XML Java library: docflex-xml.jar.

However, to get it work, you will need to install a “DocFlex/XML OxygenXML Integration” license and specify a few additional settings.

Obtain a License

The OxygenXML Integration requires a separate license, which you should receive by e-mail. If you don't have it yet, you can

The license comes as a single 'docflex-xml-oxygenxml.license' file or it may be included in a combined 'docflex-xml.license' file (along with other licenses).

In either case, you should save the license file in the 'lib' directory of your DocFlex/XML (Full Edition) or DocFlex/XML RE installation:

{docflex-xml}/lib
where the license is searched for by default (near 'docflex-xml.jar' file).

It is also possible to specify any other location of your license file directly on the generator or template designer command line using the -license option.

Running on Windows

Here is a quick instruction how to run DocFlex/XML+OxygenXML on Windows (without much investigation):
  1. Download DocFlex/XML (any edition) and unpack the downloaded zip.

    You will get some directory: {docflex-xml}

  2. Save the docflex-xml.license file (containing the “OxygenXML Integration” license) in the directory:

    {docflex-xml}\lib

  3. Now, go to the directory:

    {docflex-xml}\integrations\OxygenXML

    Edit generator.bat found in that directory, in these lines:

    ::----------------------------------------------------------------------
    :: Specify the location of JRE/JDK 7.x, 6.x, 5.x or 1.4.x here
    ::----------------------------------------------------------------------
    set JAVA_HOME=C:\Program Files\Java\jre7
    
    ::----------------------------------------------------------------------
    :: Specify the location of OxygenXML home directory
    ::----------------------------------------------------------------------
    set OXYGENXML_HOME=C:\Program Files\Oxygen XML Editor 15
    

  4. Run the generator.bat. The Generator Dialog should appear:

    Now, you can test the generation of XML schema documentation with OxygenXML diagrams included.

    Check that everything is specified as shown on the screenshot. Then, click the <Run> button. When the generation finishes, the result documentation should be open automatically in the default HTML browser.

Running on Linux

Since OxygenXML is based on Java, it is equally easy to run on Linux (in fact, there is a special Linux distribution of it). So, setting up DocFlex/XML+OxygenXML on Linux is about the same as on Windows:
  1. Download DocFlex/XML (any edition) and unpack the downloaded zip.

    You will get some directory: {docflex-xml}

  2. Save the docflex-xml.license file (containing the “OxygenXML Integration” license) in the directory:

    {docflex-xml}/lib

  3. Now, go to the directory:

    {docflex-xml}/integrations/OxygenXML/linux

    Edit generator.sh found in that directory, in these lines:

    #!/bin/sh
    
    #----------------------------------------------------------------------
    # Specify the location of Sun JRE/JDK 7.x, 6.x, 5.x or 1.4.x here
    #----------------------------------------------------------------------
    JAVA_HOME="/home/user/jdk1.7"
    
    #----------------------------------------------------------------------
    # Specify the location of OxygenXML home directory
    #----------------------------------------------------------------------
    OXYGENXML_HOME="/home/user/Oxygen XML Editor 15"
    

    Then, specify a permission to allow executing it as a program.

  4. Run the generator.sh. The Generator Dialog should appear:

    Now, you can test the generation of XML schema documentation with OxygenXML diagrams included.

    Check that everything (i.e. the main template and the XML file) is specified similar as shown on the screenshot. Then, click the <Run> button. When the generation finishes, the result documentation should be open automatically in the default HTML browser (if not, you can find it in the output directory).

3.  Settings Detail

This section describes all primary settings that are required (or may be needed) to setup and run the OxygenXML Integration. Once you know those settings, you will be able to adjust the combined DocFlex/XML+OxygenXML documentation generator for any particular environment you need (for examples, see Generator Setups).

OxygenXML Integration Main Class

This is a Java class implementing the integration entry point. Its full name must be specified on the Java command line (that runs generator or template designer) using -m option as follows:
-m:IMAGE_PROVIDER_CLASS=com.docflex.xml.OxygenXML.Kit
The integration main class implements an Element Image Provider, whose job is to provide some graphical representations of particular DSM elements (the data entities, with which templates operate). The image provider may be a separate interchangeable subsystem, adjusted for a particular generator setup. All other related settings are effectively the image provider parameters.

OS command to run OxygenXML's own DocGen

This setting specifies how to call from Java the OxygenXML's own XML schema documentation generator.

The integration works by calling OxygenXML's own documentation generator for the specified XML schemas, by which it generates the XSD diagrams along with some intermediate XML file (containing all the data, image references and hypertext image maps) supposed for further processing. That XML file is analyzed so as to associate the diagram images (and image map links) with particular DSM elements representing XML schema components in templates. That makes the diagrams and their hyperlinks available through Image Control (as “element images”) to be inserted in the output documentation generated by DocFlex/XML.

That generator is launched on Windows by:
{OxygenXML Home}\schemaDocumentation.bat
and on Linux by:
{OxygenXML Home}/schemaDocumentation.sh
Both are command/script files, which cannot be executed directly. Rather, they must be run by an interpreter:
  • cmd.exe on Windows
  • sh on Linux
So, the command file pathname must be passed to the interpreter as an argument.

On Windows, the whole command launching the OxygenXML's own doc-generator will look like this:

cmd.exe /C "C:\Program Files\Oxygen XML Editor 15\schemaDocumentation.bat"
On Linux, the same will be:
sh "/home/user/Oxygen XML Editor 15/schemaDocumentation.sh"
The double quotes enclosing the pathname are necessary because it contain spaces.

Such a command must be passed to the OxygenXML Integration on the Java command-line that runs DocFlex/XML. It is done using -m option. Here is the Windows variant:

-m:OXYGENXML_COMMAND="cmd.exe /C \"C:\Program Files\Oxygen XML Editor 15\schemaDocumentation.bat\""
Notice that the passed command is again enclosed in double quotes because it contains spaces, and the double quotes within it must be escaped using slash ('\').

On Linux, the same will look like this:

-m:OXYGENXML_COMMAND="sh \"/home/user/Oxygen XML Editor 15/schemaDocumentation.sh\""

Related Template Parameters

Besides the Java command-line settings required to setup the integration as a whole, there are other integration settings relevant only to a particular documentation generator (implemented as a template set). Those settings are exposed as template parameters. See:
DocFlex/XML | XSDDoc | Templates | Parameters | Integrations | Oxygen XML

4.  Generator Setups

This section provides full examples of how to setup a combined DocFlex/XML+OxygenXML documentation generator for some important cases.

Windows BAT File

Suppose, you want to generate a framed HTML documentation (with OxygenXML diagrams) using XSDDoc | Templates | FramedDoc.tpl template by the XML schema located at the URL: http://www.w3.org/2001/XMLSchema.xsd.

Here is a simple Windows BAT command file that would launch such a generation (with the red are highlighted settings related to the OxygenXML Integration):

xsddoc.bat

set  DFH=C:\docflex-xml
set 
CLASSPATH= %DFH%\lib\xml-apis.jar;%DFH%\lib\xercesImpl.jar;%DFH%\lib\resolver.jar;%DFH%\lib\docflex-xml.jar
 
set  OXYGENXML_HOME=C:\Program Files\Oxygen XML Editor 15
 
java  -Xmx512m -cp "%CLASSPATH%" com.docflex.xml.Generator -m:IMAGE_PROVIDER_CLASS=com.docflex.xml.OxygenXML.Kit -m:OXYGENXML_COMMAND="cmd.exe /C \"%OXYGENXML_HOME%\schemaDocumentation.bat\""
-template %DFH%\templates\XSDDoc\FramedDoc.tpl
-format HTML -d %DFH%\out -nodialog -launchviewer=false
http://www.w3.org/2001/XMLSchema.xsd

Linux Bash File

The same task on Linux.

The following shell script file will generate a framed HTML documentation (with OxygenXML diagrams) using XSDDoc | Templates | FramedDoc.tpl template by the XML schema located at the URL: http://www.w3.org/2001/XMLSchema.xsd

xsddoc.sh

#!/bin/sh

# DocFlex/XML home directory
DFH='/home/user/docflex-xml'

# DocFlex/XML class path
CLASSPATH="$DFH/lib/xml-apis.jar:$DFH/lib/xercesImpl.jar:$DFH/lib/resolver.jar:$DFH/lib/docflex-xml.jar"

# OxygenXML home directory
OXYGENXML_HOME='/home/user/Oxygen XML Editor 15'

# Specify OxygenXML Integration class as the element image provider
OPTIONS='-m:IMAGE_PROVIDER_CLASS=com.docflex.xml.OxygenXML.Kit'

# Specify the command to call OxygenXML's own XML schema doc-generator
OPTIONS="$OPTIONS -m:OXYGENXML_COMMAND='sh \"$OXYGENXML_HOME/schemaDocumentation.sh\"'"

# Specify the DocFlex main configuration file prepared for Linux
OPTIONS="$OPTIONS -docflexconfig '$DFH/linux/docflex.config'"

# Specify the template
OPTIONS="$OPTIONS -template '$DFH/templates/XSDDoc/FramedDoc.tpl'"

# Specify output format, output directory etc.
OPTIONS="$OPTIONS -format HTML -d '$DFH/out' -nodialog -launchviewer=false"

#-------------------------------------------------------------------------------------
# Run DocFlex/XML generator to document an XML schema (specified in the last argument)
#-------------------------------------------------------------------------------------
# The 'eval' is needed here to have the result string produced after the expansion of
# all variables to be interpreted as a Java command-line with correct arguments.
#-------------------------------------------------------------------------------------
eval  "java -Xmx512m -cp '$CLASSPATH' com.docflex.xml.Generator $OPTIONS http://www.w3.org/2001/XMLSchema.xsd"

Running with Apache Ant

You can easily integrate DocFlex/XML+OxygenXML with the Apache Ant automated build system.

As an example, here is an ANT build.xml file doing the same as the Windows BAT file described above.

build.xml

<?xml version="1.0"?>
<project basedir="." name="DocFlex/XML+OxygenXML+Ant Integration Demo">
<!-- This will generate an XML schema documentation -->
<target name="XSDDoc">
<!-- DocFlex/XML home directory -->
<property name="DFH" value="C:\docflex-xml"/>
<!-- DocFlex/XML Java class path -->
<property name="CLASSPATH" value="${DFH}\lib\xml-apis.jar;${DFH}\lib\xercesImpl.jar;${DFH}\lib\resolver.jar;${DFH}\lib\docflex-xml.jar"/>
<!-- OxygenXML home directory -->
<property name="OXYGENXML_HOME" value="C:\Program Files\Oxygen XML Editor 15"/>
<!--
Execute the DocFlex/XML generator.
-->
<java classname="com.docflex.xml.Generator" classpath="${CLASSPATH}" fork="true" maxmemory="512m">
<!--
All options you want to pass to the DocFlex/XML Generator should be specified
here with the <arg> elements in the same order as on the command line.
-->
<!-- specify OxygenXML Integration main class as the element image provider -->
<arg value="-m:IMAGE_PROVIDER_CLASS=com.docflex.xml.OxygenXML.Kit"/>
<!--
Pass the integration parameter: the OS command to call OxygenXML's own XML schema doc-generator.

The command arguments with spaces must be enclosed in quotes ('"') to be recognized
by the generator as a single argument. Here, such quotes are encoded with '\&quot;',
where the '&quot;' is to encode '"' in XML and '\' before it is to pass the quote
through Windows command line issued by Ant to launches DocFlex/XML.
-->
<arg value="-m:OXYGENXML_COMMAND=cmd.exe /C \&quot;${OXYGENXML_HOME}\schemaDocumentation.bat\&quot;"/>
<!-- specify the main template -->
<arg value="-template"/>
<arg value="${DFH}\templates\XSDDoc\FramedDoc.tpl"/>
<!-- pass the template parameter 'docTitle' (the documentation title) -->
<arg value="-p:docTitle"/>
<arg value="XML Schema for XML Schemas"/>
<!-- the output format -->
<arg value="-format"/>
<arg value="HTML"/>
<!-- the output directory -->
<arg value="-d"/>
<arg value="${DFH}\out"/>
<!-- do not launch the generator GUI -->
<arg value="-nodialog"/>
<!-- do not launch the default viewer for the output file -->
<arg value="-launchviewer=false"/>
<!--
Specify one or many data source XML files to be processed by the specified template.
Both local pathnames and URLs are allowed.
In this example, it is an XML schema to be documented.
-->
<arg value="http://www.w3.org/2001/XMLSchema.xsd"/>
</java>
</target>
</project>

To run that build.xml file, you can use a Windows BAT command file specified like the following:

set ANT_HOME=C:\apache-ant
set PATH=%ANT_HOME%\bin;%PATH%
set JAVA_HOME=C:\Program Files\Java\jdk1.7
call %ANT_HOME%\bin\ant.bat xsddoc
(Note that it should be started from the directory containing the Ant build.xml file!)

Running with Apache Maven

How to run DocFlex/XML with Maven is basically explained on this page: DocFlex/XML | Integrations | Apache Maven.

The following project POM file shows how to configure the DocFlex/XML Maven Plugin to generate a framed HTML XML schema documentation by the XML schema located at http://www.w3.org/2001/XMLSchema.xsd using DocFlex/XML | XSDDoc | FramedDoc.tpl + OxygenXML Integration, so that the result doc would appear on the “Project Reports” page of a Maven-generated project site.

pom.xml

<project>
...
<!-- Specify properties (i.e. variables for further usage) -->
<properties>
<!-- DocFlex/XML home directory -->
<DFH>C:\docflex-xml</DFH>
<!-- OxygenXML home directory -->
<OXYGENXML_HOME>C:\Program Files\Oxygen XML Editor 15</OXYGENXML_HOME>
</properties>
...
<!--
Reporting section.
All reports for "Project Reports" page of the Maven-generated site
should be specified here.
-->
<reporting>
<plugins>
<!-- Configure DocFlex/XML Maven plugin -->
<plugin>
<groupId>docflex</groupId>
<artifactId>docflex-xml-maven-plugin</artifactId>
<version>1.0</version>
<configuration>
<!-- Specifying command-line parameters for DocFlex/XML Generator -->
<generatorParams>
<!-- Specify OxygenXML Integration main class as element image provider -->
<param>-m:IMAGE_PROVIDER_CLASS=com.docflex.xml.OxygenXML.Kit</param>
<!--
Pass the integration parameter: the OS command to call OxygenXML's own XML schema doc-generator.
The command arguments with spaces must be enclosed in quotes ('"') to be recognized
by the generator as a single argument.
-->
<param>-m:OXYGENXML_COMMAND=cmd.exe /C "${OXYGENXML_HOME}\schemaDocumentation.bat"</param>
<!-- The main template -->
<param>-template</param>
<param>${DFH}\templates\XSDDoc\FramedDoc.tpl</param>
<!-- Pass template parameter -->
<param>-p:docTitle</param>
<param>XML Schema for XML Schemas</param>
<!-- Specify the output format -->
<param>-format</param>
<param>HTML</param>
<!-- Suppress showing up the generator GUI -->
<param>-nodialog</param>
<!-- Suppress most of the generator messages -->
<param>-quiet</param>
<!--
Specify one or many data source XML files to be processed by the specified template.
(Both local pathnames and URLs are allowed.)
In this example, it is an XML schema to be documented.
-->
<param>http://www.w3.org/2001/XMLSchema.xsd</param>
</generatorParams>
<!--
Specify the output directory name.
The plugin will convert it into the absolute pathname of the output directory,
which is passed further both to Maven and to DocFlex/XML Generator (via -d option).
-->
<outputFolder>xsddoc</outputFolder>
<!-- For the Maven project-reports page -->
<name>XSDDoc</name>
<description>XML Schema for XML Schemas</description>
</configuration>
</plugin>
</plugins>
</reporting>
...
</project>

To run that pom.xml file, you can use a Windows BAT command file specified like the following:

set JAVA_HOME=C:\Program Files\Java\jdk1.7
set M2_HOME=C:\apache-maven-2.0.9
set MAVEN_OPTS=-Xms256m -Xmx512m
call %M2_HOME%\bin\mvn.bat site:site
(Note that it should be started from the directory containing the Maven pom.xml file!)

Using XML Catalog

Some XML schemas may import or include other XML schemas, at that provide as a reference only the imported namespace URI, e.g.:
<import namespace="http://schemas.xmlsoap.org/wsdl/"/>
or the schema location may be specified with an opaque URI, e.g.:
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:glossaryGrp.xsd:1.1"/>
Processing of such imports/includes without additional information about physical schema locations is impossible. Yet, to generate a proper XML schema documentation, all referenced schema must be loaded and processed!

XML catalogs can help to resolve physical locations of XML schema files. They redirect abstract URIs to physical URLs. For more details about XML catalogs, please read: DocFlex/XML | Documentation | Installation / Configuration Files | XML Catalogs.

Both DocFlex/XML and Oxygen XML can use XML catalogs.

Example

As an example, let's see how to generate an XML schema documentation (with all OxygenXML-generated diagrams) for the XML schemas for WSDL 1.1:
http://schemas.xmlsoap.org/wsdl/
http://schemas.xmlsoap.org/wsdl/soap/
http://schemas.xmlsoap.org/wsdl/soap12/wsdl11soap12.xsd
http://schemas.xmlsoap.org/wsdl/http/
http://schemas.xmlsoap.org/wsdl/mime/
These are the URLs, by which those schemas are located physically. At the same time, they serve as the target namespace URIs of the respective schemas (except http://schemas.xmlsoap.org/wsdl/soap12/wsdl11soap12.xsd).

The XML schema:

http://schemas.xmlsoap.org/wsdl/
is imported by all other schemas, however always with the same <xs:import> element:
<xs:import namespace="http://schemas.xmlsoap.org/wsdl/"/>
which specifies only imported namespace URI, but no schema location.

That is not enough for Oxygen XML to process such an import (even though the schema file is located by the same URL as the target namespace URI). But, the problem can be fixed with the following XML catalog file:

catalog.xml

<?xml version="1.0"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<uri name="http://schemas.xmlsoap.org/wsdl/" uri="http://schemas.xmlsoap.org/wsdl/"/>
</catalog>

When that catalog.xml file has been specified in OxygenXML as shown on this screenshot:

we were able to generate this documentation (click on the screenshot):

DocFlex/XML also allows settings XML catalogs. See: DocFlex/XML | Documentation | Running Generator | Generator GUI | Assigning XML Catalog(s).

In this particular case it wasn't needed because XSDDoc is programmed to check automatically if a namespace URI points to the physical schema. But, for instance, to generate XML Schemas for DITA 1.1, setting the XML catalog (http://docs.oasis-open.org/dita/v1.1/OS/schema/catalog.xml) will be required for both OxygenXML and DocFlex/XML.

Copyright© 2003-2014 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.