One potential solution is produce documents directly in WordprocessingML, an XML encoding of Microsoft Word documents. The solution would be purely an exercise in XSLT development, and is extremely viable. Although XML encoded word is still fairly young in its life cycle, we believe that this option would have allowed us to meet most of the requirements laid out.

We did not select this option primarily because Word ML is a new feature of Microsoft Word 2003, and no licenses for this version were available.. Additional reasons for declining this approach include:

There are number of commercial off-the-shelf (COTS) solutions which attempt to address the base requirement of producing word documents from XML. Although there is a great maintenance reduction involved in using COTS software, none of the tools we evaluated were a close enough match to our base requirements to warrant selection. This was generally due to licensing costs, or lack of the type of sytling configuration that we required. A good resource for the evaluation of COTS solutions is http://www.xmlsoftware.com/convert.html.

The system design is very simple. It consists of three primary classes. Common library classes are not included in the diagram.

For the purposes of this paper, we are transforming documents conforming to the Simplified Docbook DTD[DOCBOOK]. Our test cases use various documents that exercise different document components such as ordered lists, tables, etc. The following is a representative example of the types of documents we are formatting:

<article>
  <title>The Article</title>
  <section>
    <title>The First Section</title> 
    <section>
      <title>Character styles</title>
      <para>A paragraph with a <quote>title</quote>, and 
      <emphasis role="italic">emphasis</emphasis>, and a:</para>
	<note role="note">
	  <para>note</para>
      </note>
    </section>
    <section>
      <title>Lists!</title>

      ...

	    <listitem>
	      <itemizedlist>
		<title>An three level embedded list</title>
		<listitem>
		  <para>This is a really, really, really, really, really, 
	  really, really, really, really, really, really, really, really, 
	  really, really, really, really, really, really, really, really, 
	  really, really, really, really, really, really, really long sentence. </para>
		</listitem>
	      </itemizedlist>

The initial document flow of the system was a two stage process. The input XML document was parsed and a pulldom (a hybrid SAX/DOM process) was used to dynamically send construction messages to the Word Writer.

For unit testing the Transformer, we used the Mock Object paradigm. This paradigm allowed us to create a "mock object" for the DocWriter, which enables presentation of an identical API. We could then query the mock object to verify the correct calls to it had been made. The mock DocWriter was used extensively in the construcion of our unit tests. As with all formatting concerns, unit testing the formatted results is extremely difficult. Given the simplicity of the DocWriter API we decided to forego unit testing of the actual formatting and focused instead on a manual testing process.

Because the system is fairly simple, hooking up the communication infrastructure was relatively easy. To test the infrastructure we simply passed the text through without the formatting information and verified that the Word Document was being created.

With the addition of table handling, the Transformer's logic for mapping input source to it's corresponding styles was getting fairly complex, and not as robust as we would like.

We decided to add in one more step in the process and push the mapping logic into a separate XSLT process before we actually construct the Word document. This would produce an interim form of XML that closely matches the Word Document Object Model. That document model is reflected by the API of the DocWriter.

There are three top level COM objects that we interact with in the course of our Word document construction:

Our refactored solution consisted of modeling these objects in our interim XML form. This XML form flattens all of the source XML and determines the correct styles for the different components. This approach greatly simplifies the Transformer. Now, instead of managing all of the mapping logic, the Transformer simply has to apply the stylesheet and use the interim form to generate calls to the DocWriter. Because we used a mock DocWriter in our unit tests, we were able to use the existing tests as is to verify that our refactored approach left the Transformer with the exact same behavior in constructing the Word documents.

The following is a template from the stylesheet which we used to achieve this flattening for itemized lists:

<xsl:template match="itemizedlist/listitem/para">
  <para>
    <xsl:choose>
      <xsl:when test="generate-id(../para[1]) = 
                      generate-id(.)">
        <xsl:call-template name="getParaAttrs">
          <xsl:with-param name="keyName" select="'itemizedlist'"/>
        </xsl:call-template>
        <xsl:if test="generate-id(../../listitem[1]) = 
                      generate-id(..)">
          <xsl:attribute name="restartList">
            <xsl:value-of select='1'/>
          </xsl:attribute>
        </xsl:if>
      </xsl:when>
      <xsl:otherwise>
        <xsl:call-template name="getParaAttrs"/>
      </xsl:otherwise>
    </xsl:choose>
    <xsl:apply-templates select="node()"/>
  </para>  
</xsl:template>

The getParaAttrs named template called above generates the parameters that match closely to the DocWriter API, namely the paragraph style to use and the level of indenting to use. An example of the interim form is shown below:

<wordBuilder>
   <docTitle charStyle="Default">The Article</docTitle>
   <para paraStyle="sectionStyle">The First Section</para>
   <para paraStyle="subsectionStyle">Character styles</para>
   <para paraStyle="Normal">A paragraph with a title, and 
      <text charStyle="emphasisitalicStyle">emphasis</text>, and a:</para>
   <para paraStyle="Normal">
      <text charStyle="notewarningStyle">Warning: </text>note</para>
   </para>
   <para paraStyle="subsectionStyle">Lists!</para>

   ...

   <para paraStyle="Normal" indent="2">
      <text charStyle="labelStyle">An three level embedded list</text>
   </para>
   <para paraStyle="itemizedlistStyle" indent="3" restartList="1">This is a really, really, really, really, 
	  really, really, really, really, really, really, really, really, 
	  really, really, really, really, really, really, really, really, 
	  really, really, really, really, really, really, really, really long sentence. </para>

In our system we use a Microsoft Word Template to define all of the styles we want. We used a fairly straightforward naming scheme which closely matches the semantics of the information item. From the example: itemizedListStyle for the paragraph style associated with the first 'list-item' paragraphs of an itemized list.

The client control of formatting is achieved by editing the word template itself. The formatting of the output can be changed by selecting the appropriately named style in the word template, and changing it's characteristics.

One of the advantages of this approach is that adding new styles no longer requires code changes (other than possibly adding unit tests). Stylistic and content changes are achieved by editing the interim stylesheet, and creating an appropriately named style in the word template. The abilty to effect fairly significant changes in this manner leaves the system open to a good deal of extension.