Node:Annotated DTD, Previous:Reference, Up:Top

Annotated build script DTD

This section contains a DTD description of the build script file format along with annotated notes. The DTD can be found in the documentation directory. Public identifier for the build script is -//hoylen.com//DTD transbuild buildscript 1.0//EN. An XML Schema for the build script is also available.

The root element of a build script is the build-script element. Elements and attributes in the build script must be from the XML namespace of http://hoylen.com/ns/xmlns/2002/transbuild/buildscript. This element must have a version attribute, whose value currently should be 1.0.

The source and target attributes specify the source tree and target tree, respectively. Their values must be directories. Relative paths are in relation to the location of the build script file. If they are omitted, their values have to be supplied via the command line when running Transbuild. A build script contains zero or more rules.

<!ELEMENT build-script (rule*)>
<!ATTLIST build-script
          version CDATA #REQUIRED
          source CDATA #IMPLIED
          target CDATA #IMPLIED
          xmlns CDATA
  #FIXED "http://hoylen.com/ns/xmlns/2002/transbuild/buildscript">

Rules have a mandatory source-suffix attribute. The target-suffix attribute is optional: if it is not present the target suffix is made the same as the source suffix. An optional id attribute can be placed on the rule - currently this is only used for documentation purposes. The contents of the rule is a list of zero or more processing steps.

<!ELEMENT rule (file-copy | xml-load | xslt | system)*>
<!ATTLIST rule
          source-suffix CDATA #REQUIRED
          target-suffix CDATA #IMPLIED
          id ID #IMPLIED>

The file-copy processing step is an empty element. It is only useful if the source file is to be copied to the target file without any processing. Place it as the one and only processing step in a rule.

<!ELEMENT file-copy EMPTY>

The xml-load processing step has an optional annotate-with-source attribute. The value of yes is assumed if the attribute is not present. The xml-load element contains a list of zero or more annotations.

<!ENTITY % annot_elems "(dir | ancestors | children | members)*">

<!ELEMENT xml-load %annot_elems;>
<!ATTLIST xml-load
          annotate-with-source (yes | no) #IMPLIED>

The four type of annotations each have their own element: dir, ancestors, children, and members. They all support the annotate-with-source, and all except dir support the embed attribute. Both of these are assumed to be yes if they are not present. The annotation elements each have one mandatory attribute: either file-name, file-suffix , or path depending on the element)

<!ELEMENT dir %annot_elems;>
<!ATTLIST dir
          name CDATA #IMPLIED
          annotate-with-source (yes | no) #IMPLIED
          path CDATA #REQUIRED>

<!ELEMENT ancestors %annot_elems;>
<!ATTLIST ancestors
          name CDATA #IMPLIED
          annotate-with-source (yes | no) #IMPLIED
          embed (yes | no) #IMPLIED
          file-name CDATA #REQUIRED>

<!ELEMENT children %annot_elems;>
<!ATTLIST children
          name CDATA #IMPLIED
          annotate-with-source (yes | no) #IMPLIED
          embed (yes | no) #IMPLIED
          file-name CDATA #REQUIRED>

<!ELEMENT members %annot_elems;>
<!ATTLIST members
          name CDATA #IMPLIED
          annotate-with-source (yes | no) #IMPLIED
          embed (yes | no) #IMPLIED
          file-suffix CDATA #REQUIRED>

The xslt processing step has a single mandatory stylesheet attribute. Its value must be the file name of the XSLT script, relative paths are from the location of the build script. It contains a list of zero or more parameters in param elements. These param must have a name and one of value-xpath or value-string.

<!ELEMENT xslt (param)*>
<!ATTLIST xslt
          stylesheet CDATA #REQUIRED>

<!ELEMENT param EMPTY>
<!ATTLIST param
          name CDATA #REQUIRED
          value-xpath CDATA #IMPLIED
          value-string CDATA #IMPLIED>

The system processing step executes a system command. The command is placed in the mandatory command attribute.

<!ELEMENT system EMPTY>
<!ATTLIST system
          command CDATA #REQUIRED>