Add Custom XML Documentation Capability To Your SQL Code : Page 6

Step 2—Run the Extractor
After you instrument your SQL files, the next step is to run the XML extractor sqldoc2xml.pl, which extracts the documentation from each SQL file into its own XML file. To execute sqldoc2xml.pl:

• Load Perl (5.6 or later). For Windows systems ActiveState offers a free Perl interpreter. For Linux, Perl comes standard.
• Load thel cleancode-perl open source library.
• Set your PERL5LIB environment variable to reference both the library from the previous bullet plus the lib-external directory provided with the sample project files. (See the perlrun manual page.)

Test the installation by invoking the program with no arguments or with -h or -H for usage information and documentation, as you see here:

   > cd sqlDocProject\code
   > perl sqldoc2xml.pl --h

   Usage:
       sqldoc2xml [ -lhH ] dirs target-directory
   
   Options:
       -h  Option help.
       -H  Long help (manual page).
       -l  List actions but do not make any changes (simulation).
   
   

Following that syntax, experiment with the "sandbox" included in the sample project:

   > cd sqlDocProject\sandbox\sqldoc2xml
   
   > mkdir test-output-NEW
   
   > perl ..\..\code\sqldoc2xml.pl test test-output-NEW

The sqldoc2xml.pl invocation reads the test directory as input and sends output to test-output-NEW. The sandbox includes a previously generated output directory called test-output, which you could compare your results to. This sample shows how sqldoc2xml handles an entire directory tree.

To actually process the real SQL files included with the sample project, use arguments similar to this:

   > perl sqldoc2xml.pl src XMLsrc
   

This command extracts the XML documentation comments you have embedded in SQL source files in the src source directory and creates similarly named files in the XMLsrc target directory.

Step 3—Copy Support Files
With the XML output from sqldoc2xml in place in the XMLsrc directory, you can run XmlTransform. First, you need to make sure the XSLT file (translate.xsl, in the code directory in the sample download) that specifies how to map the XML to XHTML resides in the same place as the XML files. Simply copy that file into the XMLsrc directory and proceed with the next step.

Step 4—Run the Transformer
To execute XmlTransform:

• Load Java (version 1.5 or later). You only the need Java run-time engine, which you probably already have. If not, download it from Sun.
• Load the Xerces library for XML parsing.
• Load the Xalan library for XSLT transformations.
• Load the cleancode-java open source library.
• Add the following JAR files to your Java classpath: the CleanCode library (cleancode.jar), the Xerces library (xml-apis.jar and xercesImpl.jar), and the Xalan library (serializer.jar and xalan.jar).

Test the installation by invoking the program with no arguments or with —help for further usage information. If you invoke XmlTransform with no parameters, you get a warning message:

   > cd sqlDocProject\code\customJar
   > java com.cleancode.xml.XmlTransform
   XmlTransform> +++ WARNING: must select at least one of these operations:
   xslTransform, validateInputToSchema, validateOutputToSchema
   Use '--help' option to see allowable parameters.
   

Invoked with the —help option, XmlTransform displays the myriad command-line options available. The main options are shown here, but you can see the full list in the related article "XmlTransform—A General-Purpose XSLT Pre-Processor:"

     contentsBaseName       -- base name for contents file (e.g. 'index')
     contentsToParent       -- boolean indicating to place contents
                               in parent or same dir
     debug                  -- enable all diags if true (including libraries)
     diagList               -- string of single-character diags to activate
     dirList                -- comma-separated list of dirs to process
     enable                 -- do processing if true; just report if false
     generateContents       -- boolean switch to generate contents
     generatorNode          -- tag name of node to replace with generator info
     groupIdXpath           -- simple Xpath pointing to group id node in each file
     groupPlaceHolder       -- tag name in contents file to put file list
     help                   -- show this list
     inExtension            -- extensions of files to process
     inputSchemaSource      -- global Schema file for input validation
     outExtension           -- extensions for translated files
     outputSchemaSource     -- global Schema file for output validation
     processAll             -- process without checking date stamps if true
     sourcePath             -- root of source XML tree
     startDepth             -- number of directories from the top of your tree back
                               to your own relative root
     targetPath             -- root of target XML tree
     validateInputToSchema  -- boolean switch to validate input
     validateOutputToSchema -- boolean switch to validate output
     validateXslBySchema    -- boolean switch to validate needed XSL files
     xslName                -- primary XSL file in each directory
     xslParmList            -- comma-separated list of XSL parameters
     xslSchema              -- name of Schema file for XSL files
     xslTransform           -- boolean switch to do XSL translation

As you can see, XmlTransform has a lot of options. You may be familiar with the epigram, "With great power comes great responsibility." The corollary here is: With great flexibility comes a great number of options. While I'm not going to go into great detail on XmlTransform, its options, and their effects in this article, you can find out more about how the general-purpose XmlTransform tool works, as well as more information on the various options in the article, "XmlTransform—A General-Purpose XSLT Pre-Processor."

To experiment with the "sandbox" included in the sample project, try running these commands:

   > cd sqlDocProject\sandbox\XmlTransform\sameLevelIndexTest
   > java com.cleancode.xml.XmlTransform @xdoc.conf
   
   > cd sqlDocProject\sandbox\XmlTransform\parentLevelIndexTest
   > java com.cleancode.xml.XmlTransform @xdoc.conf
   
   > cd sqlDocProject\sandbox\XmlTransform\parentGroupIndexTest
   > java com.cleancode.xml.XmlTransform @xdoc.conf
   

Each of these commands transforms files from a source directory (srcdir) to a destination directory (destdir). Because of the large number of options available for XmlTransform, the options are stored in the different directories specified above in files named xdoc.conf. Each command uses a different options file, which changes the output as follows:

• The sameLevelIndexText example shows non-grouped items on the contents page; the contents page is stored in the same directory as the contents.
• The parentLevelIndexText example shows non-grouped items on the contents page as above, but the contents page itself is stored in the parent directory.
• The parentGroupIndexText example shows grouped items on the contents page; again, the contents page itself is stored in the parent directory.

Which version you'd want to use depends on how you prefer to arrange your source files and how you prefer to arrange your top-level index pages (those that provide lists of links to the documentation details for your SQL-stored procedures and functions).

Previous Page

Next Page