Node:Step 1, Next:Step 2, Previous:Tutorial, Up:Tutorial

Step 1: Creating the source tree

The first step is to create the source tree. This is a single directory that contains the files and subdirectories to be transformed. In this document, we will refer to a directory and everything nested under it as a "tree," and use the term "directory" to mean a single directory.

Before you begin a new site, there are three main decisions you should make. You could change your mind later on, but deciding these issues early on will make your site easier to manage. The issues are:

• The navigation structure of the Web site and how it is logically laid out. This will influence the directories you create under the source tree. Getting the directory structure right will make it easy for the site to automatically generate the navigation links.
• The types of pages in the site and the XML vocabularies used in the source files. Transbuild does not restrict the types of source documents you use: for example, you could use a standard schema like DocBook, use something very close to the site pages like XHTML, use a standard data oriented schema, or create your own XML vocabulary. A site may use only one XML schema for all its files, or have many different types - it's your choice.
• The naming convention for the files in the source tree. This is important, especially when using more than one XML schema, so that Transbuild can distinguish between the types of files and process them differently. Each directory should have a master file (with exactly the same name) which will be used as the destination when generating navigation links. This master file is usually the same one that will generate the index.html file of that directory.

In this tutorial, we will be creating a Web site for a small company. The site will have a number of major sections, some (such as the hardware and software sections) will be further divided into subsections. The directory structure used is shown below. The symbol ~source~ will be used to refer to the top directory of the source tree, and ~target~ for the top directory of the target tree.

~source~
 +- about/
 +- hardware/
 |   +- omp/
 |   +- mp100/
 |   +- mp110/
 |   +- mp120/
 |   +- mp130/
 +- software/
 |   +- nos10/
 |   +- nos11/
 |   +- nos13/
 +- contact/

Initially, there will be only one type of page, but later on in the tutorial we will add more. A very simple XML vocabulary has been invented for this tutorial. It's DTD is shown below:

<!ELEMENT article (title, para*)>
<!ATTLIST article status CDATA #IMPLIED>
<!ELEMENT title (#PCDATA)>
<!ELEMENT para (#PCDATA | ulink)>
<!ELEMENT ulink (#PCDATA)>
<!ATTLIST ulink url CDATA #REQUIRED>

We have decided to give all our source XML files names with .xml extensions (even if they contain different XML vocabularies). This is a good choice if your editor only recognises files with that extension. The other alternative is to use different extensions for files containing different XML vocabularies. The master file in each directory will be called index.xml. An example of one of these files, the file ~source~/hardware/index.xml, is shown below. (The mysterious status attribute will be explained later in the tutorial.)

<?xml version="1.0"?>
<article status="2">
<title>Hardware</title>
<para>Our products incorporate leading edge technology with award
winning design which is both beautiful and functional.
</article>

In the tutorial directory, you'll find this source tree in a directory called source-a. It has the directory structure described above, one index.xml file under each directory, and a site.css file under the source tree root directory.

Transbuild takes the source tree and generates a target tree from it. The generating process is controlled by a build script file. The first build script is very basic, and is found in the file tb-step01.xml.

<?xml version="1.0"?>

<build-script
 xmlns="http://hoylen.com/ns/xmlns/2002/transbuild/buildscript"
 version="1.0"
 source="source-a"
 target="target">

<rule source-suffix=".xml">
  <file-copy/>
</rule>

<rule source-suffix=".css">
  <file-copy/>
</rule>

<rule source-suffix="~"/>

</build-script>

The build script is an XML file containing elements from the Transbuild build script namespace of http://hoylen.com/ns/xmlns/2002/transbuild/buildscript. The root element is the build-script element. It contains a mandatory version attribute, which should have the value of 1.0. It also contains the source and target attributes which specifies the source tree and target tree. Their values are directory names, specified relative to the location of the build script file. These values can be overridden by options on the command line. The contents of the build-script element is an ordered sequence of rules.

There are three rules in this first build script. A rule is represented by a rule element. The contents of the rule element is an ordered sequence of processing steps which determine how the contents of a file will be processed. The attributes of the rule element determines which files from the source tree will use that rule (and will be discussed in the next step of the tutorial).

The most basic rule is a rule element with empty content. Files in the source tree which match this empty rule are ignored - they do not cause any file to be generated in the target tree. In this example, the last rule is used to ignore backup files created by the emacs editor - these backup files have names ending in a tilde (~).

The next basic rule is one that contains a single file-copy element in it. This causes matching files in the source tree to be copied to the target tree. The file contents are not changed in any way. In this example, the other two rules copy the XML and CSS files to the target tree.

This first step can be performed by running Transbuild with the following command:

$ transbuild -a -f tb-step01.xml

The output printed by Transbuild will show that it first creates the target directory and all the directories under it, and then builds the files under the target tree. The directories will only be created if they do not already exist, so if you run this command a second time the directories won't be recreated (unless you have deleted them).

If you get an error about character encodings, see the section on character sets in the reference section.

The fundamental behaviour of Transbuild is to take the source tree and to generate the target tree from it. The directory structure is always replicated exactly. One target file is built from each source file. This simple one-to-one relationship is Transbuild at its purist. There are advanced ways to break it, but they are beyond the scope of this tutorial.

This first step has used Transbuild to create a target tree that is an exact replica of the source tree. Basically, it performs a recursive copy (minus any backup files). Not very useful, but it is a start that will be built upon in the next step.