## Using gxml2html

by Josh Carter < josh@multipart-mixed.com >
May 10, 2001

## Welcome

Thanks for your interest in gxml2html. This tool uses the GXML engine to convert a tree of XML source files into a matching tree of HTML files, using templates and other GXML features for the XML->HTML transformation.

Since most of the gxml2html features are actually GXML features, many of the documentation pages are shared. This document covers the basics of gxml2html and links to the other shared docs.

## Running the Samples

gxml2html comes with example files and templates in the "examples" directory. Looking at the "article" example, this is how the directories are laid out:

- article: this contains the raw XML which the tool will process.
- article-templates: this contains the templates (obviously).
- article-output: this is where the resulting HTML files will wind up.

First, install GXML. (See the README file.) Next, to ensure that gxml2html is installed and working properly, switch to the examples directory and run:

`> ../gxml2html.pl --work=article --force`

You should wind up with a simple HTML file and images directory in the "article-output" directory. Try the same for the scoping example to see gxml2html's variable scoping rules in action. The inventory example shows off the gxml:foreach command.

## Configuring gxml2html

Here are the command line params and what they do:

- --templates=directory: changes the templates directory to directory.
- --work=directory: changes the work (source) directory to directory.
- --final=directory: changes the final (destination) directory to, you guessed it, directory.
- --debug: turns on lots of debugging messages. If you're having problems, email me a run of the program with --debug turned on.
- --force: forces all files to be processed. Normally files which have not been modified since the last time you ran gxml2html will get skipped. IMPORTANT: if you modify the .gxml2html file (more later) so that tag remappings are different, you'll have to use --force for the first run afterwards to ensure all files are updated.

You can also put configuration params in a file named ".gxml2html". The syntax is the same as above, just without the leading "--" on the configuration param. (See the included "sample_dot_gxml2html" file as an example.) The .gxml2html file should either reside in the same directory as gxml2html.pl, or in the work directory. In the latter case, you could provide the work directory as a command line param, and the rest of the configuration would be read from the .gxml2html file. This is how I generate the HTML versions of this documentation, in fact.

## Documents, Templates, and Variables

Now we get into the meat of writing templates, using variables, and so forth. The following pages go into detail on each topic.

Variables: First, dig into variable substitution in its various forms.

Templates: Templates are the meat of gxml2html -- this is what makes it useful.

Commands: Commands are a new feature to GXML 2.0, giving it the most-needed features from XSL.

Other Features: There's lots of extra stuff you can do with gxml2html. This is where we pick up all the rest.

## Other Notes

The work directory may contain a mix of .xml and other files. Only the .xml files will be parsed; everything else will be copied. As such, you can have images and whatnot in there, and these will get carried into the destination directory unharmed. Also, the .xml source will also get copied in case someone wants to grab the unmolested XML instead of the HTML.

The work directory can be a tree of files. The directory structure will be mirrored in the destination directory.

gxml2html tries to be smart about only processing files which need processing. Basically, if you modify a file, it'll get processed. Also, if you modify a template, all XML files will get processed even if they haven't been modified, since the template change could affect the final HTML file. If you suspect that something is out of date, run gxml2html with the "--force" option.

The XML::Parser module which provides the parser core for gxml2html is very strict about proper syntax in the XML sources, and it will barf on any errors. I consider this a feature, and intentionally let it stop gxml2html so you can fix the error.

While the included sample documents are extremely simple, gxml2html can (and should) be used in more ambitious ways. FWIW, the entire multipart-mixed.com web site is written in XML and makes extensive use of templates. To see the XML source for any HTML file, just change the ".html" part of the URL to ".xml", and then view the source.

Other comments, bug reports, feature requests, etc.: send me an email!

Back to GXML Home

Copyright (c) 2001-2002 Josh Carter