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
