Using HTMLGen Version 1.0

HTMLGen is a C++ text-processing utility that lets users quickly generate HTML testcases. While HTMLGen is not restricted to generating HTML files, the program does understand the set of known HTML tags. HTMLGen takes user supplied file fragments and command line arguments as input, and automatically generates a series of derived HTML files.

Here's a quick example: Let's say you want to create a series of tests to verify that Gecko correctly renders every tag inside the <BODY> element. To accomplish this, begin with a small HTML fragment file given below:

<html> <body> <$0>text</$0> </body> </html>

Notice that the file looks like a typical HTML file, except for the tags that read <$0> and </$0>. These are macros, which are content that will be replaced by arguments provided on the HTMLGen command line. To finish our example, simply run HTMLGen with the following command line arguments:

    HTMLGen -f test1.html a-z

This instructs HTML to read the test1.html file and use it as a template. Next, the tag-range argument "a-z" instructs HTMLGen to autogenerate a file for each HTML tag between A and Z. HTMLGen uses this argument as the 0th element of its macro substitution process. The macros <$0> and </$0> will be replaced in each autogenerated file with the current value of the $0 argument. So, the first file will contain <A> where it sees <$0>, the second will use <B> and so on.

The result of running HTMLGen against the given template with these arguments is that you'll get a new file for each tag we see in the range between A..Z. Note that in this example we're emitting valid HTML, but that is not a requirement. You can use HTMLGen to generate lots of illegal content for testing as well.

HTMLGen Command Line Arguments

The arguments you use for controlling HTMLGen always have the same form, as shown:

`HTMLGen -f test1.html [-o outfile name] taglist0 [,taglist1, ..., taglist9]`

The first argument is always the name of the template file to read.
The (optional) second argument is the name of the output file.
The 3rd argument on represent represent tag sequences to be used in macro substitution. These can have one of three forms: 1) a single tag; 2) a list of tags (a,b,c); 3) a range of tags (a-z).

HTMLGen Embedded Text Commands

In addition to the command line arguments, HTMLGen can also respond to special markup found inside your template files. Commands you can use inside your templates include:

@file -- this gets replaced with the name of the current output file.
@next -- this gets replaced with the name of the next output file (useful for creating links between files).
@import filename -- this causes the contents of filename to be inserted into the current document.

Notes and Cautions

> - The first note of caution is that HTMLGen can produce a large number of test files in very little time. You should be careful when you specify arguments because the combinatorics add up to a potentially big document set.