Browse DevX
Sign up for e-mail newsletters from DevX


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

By adding XML-based documentation capability to your SQL code, you can automatically extract and format tagged comments into a complete API documentation set for your SQL libraries.




Building the Right Environment to Support AI, Machine Learning and Deep Learning

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).

Thanks for your registration, follow us on our social networks to keep up-to-date