Return to main dbmstools documentation page.
xml2doc is used to generate HTML documentation for one or more target DBMS's, based on an XML description of your schema (see documentation of the schema format). By default you execute the tool from the command-line, passing it the name of the XML schema file and the name of one or more target DBMS's.
For each target DBMS, the tool generates either a single HTML file or an HTML frameset, to the current directory by default, unless you specify otherwise. If you don't ask for the CSS stylesheet to be embedded in the HTML, the stylesheet will be copied to the output directory as well (this option is not available when frames are used).
The tool can also generate schema diagrams as part of the HTML output, if you have the graphviz package installed (see the installation page for details). Diagrams can be for the whole schema, or only for incoming and outgoing foreign key connections to each table (frames-based HTML only). All diagrams are image maps, so you can click on an object to jump to its documentation.
As a general recommendation, the frame-based documentation is much easier to use online, while the single-page documentation prints better.
You use the tool like this:
main/xml2doc.py [options] -d <targetDBMS> <schema.xml>
| -b baseName | Specifies the base name for SQL files (defaults to the name of the database) |
| -c number | Number of columns in table index at start of page. Defaults to 4, incompatible with -f |
| -d dbms | Name of the DBMS to generate documentation for. Mandatory, may be repeated for multiple DBMS's. Values recognised are: postgres7, postgres8, mssql, oracle, mysql, hsql |
| -e | Embed CSS styles directly in the HTML document (otherwise uses a link to an external stylesheet). Incompatible with -f |
| -f | Generate documentation in frames, like Javadoc |
| -g | Generate schema diagram(s). Requires 'dot' (from Graphviz) |
| -h | Show help screen and exit |
| -n | Omit descriptions for columns etc. (default is to include) |
| -o | outputDir Write all files to the specified output directory (defaults to current directory) |
| -v | Verbose output |
| -w | Interpret Wiki markup in descriptions. |
| --help | Shows help screen, and exits |
| --var name_and_value | |
| Sets the variable for use in conditions and token replacement, where name_and_value is the variable name and value separated by a colon, e.g. myVar:foo | |
| --version | Print version number and exit |
No frames, no diagrams:
main/dbmstools/xml2doc.py -o output/docs -d postgres8 -d mssql -e ps.xml
This command will generate the following files in the output/dbscripts directory (assuming the schema name in ps.xml is 'ps'):
Frames-based output, with diagrams:
main/dbmstools/xml2doc.py -o output/docs -d postgres8 -fg ps.xml
This command will generate the following files in the output/dbscripts directory (assuming the schema name in ps.xml is 'ps'):
index-ps-postgres8.html
schema.css
Note that the 'dot' program from Graphviz must be in your path in order to generate diagrams.
See xml2doc-ant to run xml2doc from an ant build script.