Montana Department of Transportation

Main Content

Document Building HowTo

Introduction

The document subsystem is based on XML source files and XSLT (Extensible Stylesheet Language Transaction) processing. The XML documents use a simple language to describe a document that can be processed into either an HTML help file, or a Word document. The advantage is that only a single source file needs to be maintained and it is much easier to maintain synchronization between the Help documents and the Word documents.

XML Language
The XML language consists of the following tags. Tags are of two types: containers that serve only to contain other tags for organizational purposes and those that provide data.

Tag Name Type Usage
<FORM> Container Organizes the entire document
<HEADING> Container Container for heading information
<TITLE> HEADING data The visible title for the document.
<VERSION> HEADING data The version for the document. This can be any text.
<OVERVIEW> Container Contains an overview of the document. It appears only in the Help document.
<PAR> Various data Used to contain text information for various tags in the document.
<DOCUMENTFLOW> Data Contains the document flow for the document. This appears only in the help document and can be any desired text.
<CONTENT> Container Contains the content portion of the document. Essentially the body of a document.
<SECTION> CONTENT Container A outer or major subdivision of a document.
<SUBSECTION> SECTION Container A secondary subdivision of a document.
<SUBSUBSECTION> SUBSECTION Container A tertiary subdivision of a document.
<SUBSUBSECTION> SUBSECTION Container A tertiary subdivision of a document.
<NAME> Subdivision data The name of a subdivision or other entity.
<DESC> Subdivision data The description of the subdivision for the help document.
<INSTR> Instruction data An instruction to be placed on the form
<STYLE> Subdivision container Container for the format of a subdivision. The style only affects the Word document.
<BOX> Format container Indicator for a box format.
<TABLE> Format container Contains a table format description.
<CHECKBOX> Format container Container for a checkbox format.
<ROW> Table container Container for a table row.
<COL> Table data Descriptor for a table column. The possible attributes are the width and the color. Width can be described as in any HTML document. Colors must be WHITE or GRAY.
XSLT Definitions

XSLT processing uses a matching algorithm to convert an XML document into another form. It is too complex too describe in detail, but to convert an XML file into HTML, you provide a set of outputs for each XML tag encountered. Microsoft has provided a language for performing this operation for Word documents called WordML.

The XSL transactions are described in Form-html.xsl for the HTML documents and in Form-word.xsl for the Word documents. Form-word-include.xsl is an include file of xsl procedures. Form-word-header.xml is a necessary xml header that is required for the WordML processing.

If changes are desired in processing, you will need to acquire resources for XSLT and for WordML. For XSLT, there a many good references. For WordML, the choices seem to be more limited.

Building Documents
To build the documents, you simply need to execute a batch or script file. In the Build directory, there is a script for Linux named BUILD-LINUX and a Windows batch file named BUILDWIN.BAT. Go to the Build subdirectory and execute the appropriate script. These scripts process every file in the XML directory. If you want to process a single file, you will have to extract the command from the script and execute it on that file.

For Linux or Unix, xsltproc is typically included in a distribution or is easily available, so it is an excellent choice.

For Windows, there are a number of freeware solutions that work well. xsltproc is available, but it requires the installation of a number of libraries or Cygwin. An easier choice is the Saxon XML processor, so that is used here. The saxon executable file SAXON.EXE is included in the Build directory. As currently configured, the saxon.exe file can be left in the Build directory with the BUILWIN.BAT batch file. Alternatively, the saxon.exe file can be copied into the \Windows\System32 directory or any other directory that is in the system environment path variable.

The MDT-Help-and-Forms-Build Instructions contains instructions developed by MDT for building the help files and word forms documents.