XMLmind DITA Converter Manual

1. Create and configure the PreProcessor.

   Console console = new Console() {
       public void showMessage(String message, MessageType messageType) {
           System.err.println(message);
       }
   };
   
   PreProcessor preProc = new PreProcessor(console);
   preProc.setChunking(Chunking.SINGLE);
   preProc.setMedia(Media.SCREEN);
   
   ResourceCopier resourceCopier = new ResourceCopier();
   resourceCopier.parseParameters("img");
   preProc.setResourceHandler(resourceCopier);

   • Console is a very simple interface. Implementing this interface allows to do whatever you want with the messages reported by a PreProcessor.
   • Specifiying preProc.setChunking(Chunking.SINGLE) allows to generate a single HTML page using a DITA map designed to generate multiple HTML pages.
   • A PreProcessor is not concerned about the exact output format. However its behaves differently depending on the target Media .
   • A PreProcessor handles to an ResourceHandler all the resource files, typically image files, referenced in the DITA source using relative URLs. An ResourceHandler is registered with a PreProcessor using method setResourceHandler .
     In the case of the Embed2 sample, we use the simplest possible ResourceHandler which is ResourceCopier .
2. Pre-process the DITA source files.

   URL inFileURL = null;
   try {
       inFileURL = inFile.toURI().toURL();
   } catch (MalformedURLException cannotHappen) {}
   
   File[] preProcFiles = null;
   try {
       preProcFiles = preProc.process(new URL[] { inFileURL }, outFile);
   } catch (IOException e) {
       console.showMessage(e.toString(), Console.MessageType.ERROR);
   }
   if (preProcFiles == null) {
       return false;
   }

   The process method of a PreProcessor returns null if an error other than an IOException has caused the pre-processing to fail. When this is the case, errors messages are displayed on the Console.
   Note that a PreProcessor is not thread-safe. Each thread must own its PreProcessor. However, the process method of a PreProcessor may be invoked several times.

Invoke the Saxon XSLT 2.0 engine, in order to transform all the .ditac files. Note that this is done using the standard JAXP API.

1. Pass required system parameters to the XSLT stylesheets, in addition to the normal, user, parameters.

   String ditacListsURI = "";
   
   int count = preProcFiles.length;
   for (int i = 0; i < count; ++i) {
       File ditacFile = preProcFiles[i];
   
       if (ditacFile.getPath().endsWith(".ditac_lists")) {
           ditacListsURI = ditacFile.toURI().toASCIIString();
           break;
       }
   }
   
   String[] params = {
       "ditacListsURI", ditacListsURI,
       "xsl-resources-directory", "res",
       "use-note-icon", "yes",
       "default-table-width", "100%"
   };

   These required system parameters are:
   • ditacListsURI, always required.
   • foProcessor, required by the XSLT stylesheets that generate XSL-FO.
   • chmBasename, hhpBasename, required by the XSLT stylesheets that generate HTML Help.
2. Use the Saxon XSLT 2.0 engine to create a TransformerFactory, then configure this TransformerFactory.

   private static
   TransformerFactory createTransformerFactory(URIResolver uriResolver, 
                                               ErrorListener errorListener) 
       throws Exception {
       Class<?> cls = Class.forName("net.sf.saxon.TransformerFactoryImpl");
       TransformerFactory transformerFactory = 
           (TransformerFactory) cls.newInstance();
   
       ExtensionFunctions.registerAll(transformerFactory);
   
       transformerFactory.setURIResolver(uriResolver);
       transformerFactory.setErrorListener(errorListener);
   
       return transformerFactory;
   }

   • Creating an instance of Saxon 11 is absolutely needed. XMLmind DITA Converter is not designed to work with any other XSLT engine (e.g. the Xalan XSLT 1.0 engine, which is part of the Java™ runtime).
   • The ditac XSLT 2.0 stylesheets make use of a few XSLT extension functions written in Java™. These extension functions must be registered with Saxon. This is done using ExtensionFunctions.registerAll .
3. Create and configure a Transformer.

   private static Transformer createTransformer(String[] params, 
                                                Console console) 
       throws Exception {
       URIResolver uriResolver = Resolve.getURIResolver();
       ErrorListener errorListener = new ConsoleErrorListener(console);
   
       TransformerFactory factory = createTransformerFactory(uriResolver,
                                                             errorListener);
   
       File xslFile = AppUtil.getXSLResourceFile("xhtml/html.xsl");
       Transformer transformer = 
           factory.newTransformer(new StreamSource(xslFile));
   
       transformer.setURIResolver(uriResolver);
       transformer.setErrorListener(errorListener);
   
       for (int i = 0; i < params.length; i += 2) {
           transformer.setParameter(params[i], params[i+1]);
       }
   
       return transformer;
   }

   • Resolve is a helper class making it easy to use the services of XML Catalog resolvers .
     By default, Resolve automatically loads all the XML catalogs specified using the xml.catalog.files Java™ system property. Excerpts of the ant build.xml file:

     <target name="embed2" depends="compile,clean_embed2">
       <java classpathref="cp" fork="yes" classname="Embed2">
         <sysproperty key="xml.catalog.files" 
                      value="${ditac.dir}/schema/catalog.xml" />
         <arg value="${ditac.dir}/docsrc/manual/manual.ditamap" />
         <arg value="manual.html" />
       </java>
     </target>

     However, static method setXMLResolver allows to configure this thread-safe utility class (used by ditac in many places) differently.
   • ConsoleErrorListener is an implementation of ErrorListener which displays its messages on a Console.
   • AppUtil.getXSLResourceFile is a utility function used to locate files found in the XSL directory (normally ditac_install_dir/xsl/).
4. Invoke the Transformer to transform each .ditac file.

   for (int i = 0; i < count; ++i) {
       File ditacFile = preProcFiles[i];
   
       String ditacFilePath = ditacFile.getPath();
       if (ditacFilePath.endsWith(".ditac")) {
           File transformedFile = new File(
               ditacFilePath.substring(0, ditacFilePath.length()-5) + 
               "html");
   
           try {
               transformer.transform(new StreamSource(ditacFile), 
                                     new StreamResult(transformedFile));
           } catch (Exception e) {
               console.showMessage(e.toString(), 
                                   Console.MessageType.ERROR);
               cleanUp(preProcFiles);
               return false;
           }
       }
   }

   In the case of Embed2, the above loop is not strictly needed. We specified preProc.setChunking(Chunking.SINGLE) and therefore the PreProcessor generates a single .ditac file.

File dstDir = new File("res");
if (!dstDir.exists()) {
    File srcDir = AppUtil.getXSLResourceFile("xhtml/resources");
    try {
        FileUtil.copyDir(srcDir, dstDir, false);
    } catch (IOException e) {
        console.showMessage(e.toString(), Console.MessageType.ERROR);
        cleanUp(preProcFiles);
        return false;
    }
}

cleanUp(preProcFiles);