<?xml version="1.0" encoding="ascii"?>
<article>
  <articleinfo>
    <title>Round-Tripping Specifications</title>
    <author>
      <firstname>Bob</firstname>
      <surname>Stayton</surname>
      <affiliation>
        <orgname>Sagehill Enterprises</orgname>
      </affiliation>
    </author>
    <author>
      <firstname>Steve</firstname>
      <surname>Ball</surname>
      <affiliation>
        <orgname>Explain</orgname>
      </affiliation>
    </author>
    <revhistory>
      <revision>
	<revnumber>1.5</revnumber>
	<date>2007-01-05</date>
	<authorinitials>SRB</authorinitials>
	<revremark>Reduce emphasis on WordML, add support for OpenOffice.</revremark>
      </revision>
      <revision>
	<revnumber>1.4</revnumber>
	<date>2005-11-11</date>
	<authorinitials>SRB</authorinitials>
	<revremark>Added bibliography.</revremark>
      </revision>
      <revision>
	<revnumber>1.3</revnumber>
	<date>2005-10-31</date>
	<authorinitials>SRB</authorinitials>
	<revremark>Added mediaobjectco, imageobjectco, programlistingco, areaspec, area, calloutlist.</revremark>
      </revision>
      <revision>
	<revnumber>1.2</revnumber>
	<date>2005-10-13</date>
	<authorinitials>SRB</authorinitials>
	<revremark>Version prior to using revhistory.</revremark>
      </revision>
    </revhistory>
  </articleinfo>
  <abstract>
    <para>This document specifies how DocBook elements can be mapped to paragraph and character styles in a word processor.  The specifications will be used to write conversions between DocBook XML and word processor XML formats, such as Microsoft's WordProcessingML (WordML), OpenOffice's OpenDocument and Apple's Pages.</para>
  </abstract>
  <section>
    <title>Introduction</title>
    <para>Microsoft Word 2003 introduced WordProcessingML (WordML), an XML vocabulary for Word documents.  Since then, other popular word processors have become available that use XML as their data representation, namely Apple's Pages and OpenOffice.  By converting Word (or OpenOffice or Pages) to XML, it becomes possible to convert a word processing document to DocBook and vice versa using XSL transformations. Such conversions would then enable the following.</para>
    <itemizedlist>
      <listitem>
        <para>DocBook content creators could write in their familiar wordprocessing application, rather than learning a new XML editing application.</para>
      </listitem>
      <listitem>
        <para>DocBook XML documents could be styled for output using the typesetting features of the word processor.</para>
      </listitem>
    </itemizedlist>
    <para>Word processors have a simple, flat data model; documents consist of paragraphs (and tables) and paragraphs contain text and character spans.  All word processors allow styles to be associated with paragraphs and spans.</para>
    <para>This specification describes how DocBook elements could map to a set of paragraph and character styles. It defines a specific set of style names for which a Word style template can be created. The style names would also be used in XSLT template match patterns for conversion.  Although originally targetted to MS Word, the system has subsequently been extended to use other word processors, notably Apple's Pages.</para>
  </section>
  <section>
    <title>Project goals</title>
    <para>The goal of this project is to enable a word processor, such as Microsoft Word, to be used with DocBook files.  The specific goals include:</para>
    <itemizedlist>
      <listitem>
        <para>Enable authoring of basic DocBook documents in the word processor.</para>
      </listitem>
      <listitem>
        <para>Enable importing of basic DocBook XML documents into the word processor.</para>
      </listitem>
    </itemizedlist>
    <para>To meet these goals, the project will produce a toolkit that can be immediately put to use.  The kit will include:</para>
    <itemizedlist>
      <listitem>
        <para>Templates for Microsoft Word, Apple Pages and OpenOffice with formatting styles attached to the style names.</para>
      </listitem>
      <listitem>
        <para>XSLT stylesheets that convert a word processing document that is authored with the corresponding template into a DocBook XML file.</para>
      </listitem>
      <listitem>
        <para>XSLT stylesheets that convert a DocBook document into a word processing document that can be opened in a word processor.</para>
      </listitem>
    </itemizedlist>
    <section>
      <title>Why basic DocBook?</title>
      <para>It isn't clear that this project will ever be able to support all DocBook elements and structure. The project will initially focus on a basic set of commonly used DocBook elements to demonstrate the feasibility and usefulness of using a word processor with DocBook. </para>
      <para>One problem facing this conversion project is the sheer number of DocBook elements, over 400 in DocBook 4.3. To support DocBook structural models, several of the elements will require more than one paragraph or character style. This could lead to a very long and unwieldy list of styles in the word processor interface. That would make authoring less efficient and discourage users.</para>
      <para>So this project assumes that authors who need the full set of DocBook elements will use an XML authoring tool that better supports them. This project will enable authors to write basic DocBook documents using a word processor. Because Microsoft Word is so widespread, this project will help a lot of new DocBook users get started with familiar tools.  They can then graduate to more advanced tools as their needs develop.</para>
    </section>
  </section>
  <section>
    <title>Project Non-Goals</title>
    <para>The following goals <emphasis>are not</emphasis> in the scope of this project:</para>
    <itemizedlist>
      <listitem>
        <para>Support of versions of Word that do not feature reading/writing WordML (XML).  That is, all versions prior to Word 11 (Office 2003).</para>
      </listitem>
      <listitem>
        <para>Supporting user-defined style names.  However, this system should not prevent, or make difficult, adding such support via a customisation layer.</para>
      </listitem>
      <listitem>
        <para>Support of arbitrarily defined styles.  This system may expect certain styles to be defined in a particular fashion (in particular, those defining the title of components and divisions).</para>
      </listitem>
    </itemizedlist>
  </section>
  <section>
    <title>Mapping elements to styles</title>
    <para>Although WordML, OpenDocument and DocBook are all XML, there several challenges when trying to convert between them.</para>
    <para>The basic problem in mapping paragraph/character styles to DocBook elements is that word processor documents support far less structure than DocBook.  DocBook permits nesting of elements within other elements, providing multiple levels of context for each element.  </para>
    <para>Word's only structural feature is the outlining mode. In Word outlining, certain paragraph styles are assigned outline levels.  When a user applies those styles, they effectively create logical structure in the Word document.  Unfortunately, Word itself attempts to automatically determine which paragraphs are headings, and so this method is unreliable.</para>
    <para>Instead of relying on Word's built-in outlining mode, this system uses only the names of paragraph styles to determine document structure.  Certain heuristics are applied to build the DocBook element structure from the (relatively flat) word processing structure.  Titles and other features are used to mark the beginning of a structure, and all paragraphs following that are included in that structure until the beginning of the next structure is found.  Problems may arise when a structure should end, but there is no word processor feature that marks the endpoint.</para>
    <para>Nesting of block elements is another commonly used feature of DocBook.  It is not possible to use Word's outline mode for blocks if it is being used for components and sections.  So in this specification, nesting of block elements is indicated by adding a number suffix to a style. So a paragraph with style <literal>orderedlist2</literal> is considered to be contained within a preceding paragraph with style <literal>listitem</literal>. In the word processor, paragraph indent levels will be used to visually indicate nesting of blocks. </para>
    <para>Nesting of inline DocBook elements is particularly difficult to support because word processors do not nest character styles. That means a nested inline would require a separate character style to indicate the parent-child relationship. Given the large number of combinations possible, a prohibitively large number of character styles would have to be created. In this project, nesting of character styles will not be supported in the first release. Nested inlines being imported from DocBook will be converted to a sequence of single-name character styles.</para>
    <para>In many cases, DocBook structure can be derived from the flat sequence of paragraphs based on sibling relationships. For example, when a paragraph styled as <literal>para</literal> is followed by a paragraph styled as  <literal>itemizedlist</literal>, the conversion to DocBook will output a <sgmltag class="element">para</sgmltag> element and then start an <sgmltag class="element">itemizedlist</sgmltag> element, with the second paragraph as its first <sgmltag class="element">listitem</sgmltag>. All <literal>itemizedlist</literal> paragraphs that follow without interruption are put in the same <sgmltag class="element">itemizedlist</sgmltag> element.</para>
    <para>Some combinations of elements cannot be supported (at least not with the techniques as described in this document).  An example is <sgmltag class="element">informalexample</sgmltag> and its permitted content; there is no title to mark the beginning of the element and no marker for the end of the element, also there are too many parent-child combinations to reasonably define style names.</para>
    <para>Here are the design principles used in this project for selecting paragraph/character style names:</para>
    <itemizedlist>
      <listitem>
        <para>Where Word (or OpenOffice or Pages), by default, has a style or feature that corresponds directly to a DocBook element then that style or feature will be used (and documented in this document).  For example, the <literal>Normal</literal> paragraph style maps to a DocBook <sgmltag>para</sgmltag> element, and a Word table (<sgmltag>w:tbl</sgmltag>) maps to a DocBook <sgmltag>table</sgmltag><footnote><para>In some cases Word may posess a feature, but it doesn't function in an acceptable manner.  For example, lists.  In these cases the feature is to be avoided, and a workaround provided.</para></footnote>.</para>
      </listitem>
      <listitem>
        <para>Paragraph and character style names will match DocBook element names as much as possible. This will enable authors to learn DocBook element names, and help debug problems with conversion.</para>
      </listitem>
      <listitem>
        <para>A style may indicate a parent-child relationship, but the paragraph for such an element may only occur after a paragraph that denotes the beginning of the parent structure.  In this case the element name is used as the style name.  For example, a <sgmltag>personblurb</sgmltag> paragraph may only occur after an <sgmltag>author</sgmltag>, <sgmltag>editor</sgmltag> or <sgmltag>othercontrib</sgmltag> paragraph.  If a paragraph occurs without the appropriate preceding paragraph, then an error is signalled.</para>
      </listitem>
      <listitem>
        <para>Some styles may also indicate a parent-child relationship, but either the parent structure is ambiguous or the paragraph starts the parent structure.  For example, <literal>chapter-title</literal> indicates that the paragraph is a <sgmltag>title</sgmltag> whose DocBook parent is a <sgmltag>chapter</sgmltag>.</para>
      </listitem>
      <listitem>
        <para>Some style names are simplified to make them easier to use in the word processor. For example, a paragraph in an orderedlist requires three elements in DocBook: <sgmltag class="element">orderedlist</sgmltag>, <sgmltag class="element">listitem</sgmltag>, and <sgmltag class="element">para</sgmltag>. The paragraph style name in Word is shortened from <literal>orderedlist-listitem-para</literal> to just <literal>orderedlist</literal>.   In the case of lists (see below), the list level is appended so this example becomes <literal>orderedlist1</literal></para>
      </listitem>
      <listitem>
        <para>Style names with a number suffix indicate a nesting level, as described above.</para>
      </listitem>
      <listitem>
        <para>Style names with <literal>continue</literal> indicate that the paragraph is part of the preceding element. For example, a <literal>para</literal> paragraph is used for a single paragraph <sgmltag class="element">para</sgmltag> element. This would cause any preceding list to be closed. If a list item in the preceding list is to contain more than one paragraph, then the subsequent paragraphs in the word processor document would get a <literal>para-continue</literal> style.</para>
      </listitem>
      <listitem>
        <para>Character styles map to elements that are children of the element for the paragraph, hence there is no need to encode parent-child relationships.  For example, a <sgmltag>surname</sgmltag> character style in an <sgmltag>author</sgmltag> paragraph becomes a <sgmltag>surname</sgmltag> child element of the <sgmltag>author</sgmltag> element.</para>
      </listitem>
      <listitem>
        <para>Empty paragraph and character styles are ignored.</para>
      </listitem>
      <listitem>
        <para>The first paragraph style in the word processor document is used to define the root element of the DocBook document. For example, if the document starts with <literal>book-title</literal>, then the DocBook document will have <literal>book</literal> as its root element.  All the rest of the document content will be contained in that root element.</para>
      </listitem>
    </itemizedlist>
    <para>Sequential structures are coalesced into a single parent element.  For example, a sequence of <sgmltag>itemizedlist</sgmltag> paragraphs becomes a single <sgmltag>itemizedlist</sgmltag> element with several <sgmltag>listitem</sgmltag> children.</para>
    <table>
      <title>DocBook to Paragraph/Character Styles</title>
      <tgroup cols="3">
        <colspec colnum="1" colname="col1" colwidth="1.00*"/>
        <colspec colnum="2" colname="col2" colwidth="1.89*"/>
        <colspec colnum="3" colname="col3" colwidth="1.97*"/>
        <thead>
          <row>
            <entry colname="col1">DocBook element</entry>
            <entry colname="col2">Style(s)</entry>
            <entry colname="col3">Comments</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry namest="col1" nameend="col3">
              <emphasis role="bold">Components and sections</emphasis>
            </entry>
          </row>
          <row>
            <entry colname="col1">book/bookinfo/title</entry>
            <entry colname="col2">book-title</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">book/bookinfo/subtitle</entry>
            <entry colname="col2">book-subtitle</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">book/bookinfo/titleabbrev</entry>
            <entry colname="col2">book-titleabbrev</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">chapter/chapterinfo/title</entry>
            <entry colname="col2">chapter-title</entry>
            <entry colname="col3">Assigned Word outline level 1.</entry>
          </row>
          <row>
            <entry colname="col1">chapter/chapterinfo/subtitle</entry>
            <entry colname="col2">chapter-subtitle</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">chapter/chapterinfo/titleabbrev</entry>
            <entry colname="col2">chapter-titleabbrev</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">appendix/appendixinfo/title</entry>
            <entry colname="col2">appendix-title</entry>
            <entry colname="col3">Assigned Word outline level 1.</entry>
          </row>
          <row>
            <entry colname="col1">preface/prefaceinfo/title</entry>
            <entry colname="col2">preface-title</entry>
            <entry colname="col3">Assigned Word outline level 1.</entry>
          </row>
          <row>
            <entry colname="col1">article/articleinfo/title</entry>
            <entry colname="col2">article-title</entry>
            <entry colname="col3">Assigned Word outline level 1.</entry>
          </row>
          <row>
            <entry colname="col1">article/articleinfo/subtitle</entry>
            <entry colname="col2">article-subtitle</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">article/articleinfo/titleabbrev</entry>
            <entry colname="col2">article-titleabbrev</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">bibliography/bibliographyinfo/title</entry>
            <entry colname="col2">bibliography-title</entry>
            <entry colname="col3">Assigned Word outline level 1.</entry>
          </row>
          <row>
            <entry colname="col1">bibliography/bibliodiv</entry>
            <entry colname="col2">bibliodiv-title</entry>
            <entry colname="col3"></entry>
          </row>
          <row>
            <entry colname="col1">biblioentry</entry>
            <entry colname="col2">biblioentry-title</entry>
            <entry colname="col3">Metadata elements after the biblioentry-title paragraph become part of the <sgmltag>biblioentry</sgmltag>.</entry>
          </row>
          <row>
            <entry colname="col1">glossary/glossaryinfo/title</entry>
            <entry colname="col2">glossary-title</entry>
            <entry colname="col3">Assigned Word outline level 1.</entry>
          </row>
          <row>
            <entry colname="col1">index/indexinfo/title</entry>
            <entry colname="col2">index-title</entry>
            <entry colname="col3">Assigned Word outline level 1.</entry>
          </row>
          <row>
            <entry colname="col1">sect1/sect1info/title</entry>
            <entry colname="col2">sect1-title</entry>
            <entry colname="col3">Assigned Word outline level 2.</entry>
          </row>
          <row>
            <entry colname="col1">sect1/sect1info/subtitle</entry>
            <entry colname="col2">sect1-subtitle</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">sect1/sect1info/titleabbrev</entry>
            <entry colname="col2">sect1-titleabbrev</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">sect2/sect2info/title</entry>
            <entry colname="col2">sect2-title</entry>
            <entry colname="col3">Assigned Word outline level 3.</entry>
          </row>
          <row>
            <entry colname="col1">sect2/sect2info/subtitle</entry>
            <entry colname="col2">sect2-subtitle</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">sect2/sect2info/titleabbrev</entry>
            <entry colname="col2">sect2-titleabbrev</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">sect3/sect3info/title</entry>
            <entry colname="col2">sect3-title</entry>
            <entry colname="col3">Assigned Word outline level 4.</entry>
          </row>
          <row>
            <entry colname="col1">sect3/sect3info/subtitle</entry>
            <entry colname="col2">sect3-subtitle</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">sect3/sect3info/titleabbrev</entry>
            <entry colname="col2">sect3-titleabbrev</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">sect4/sect4info/title</entry>
            <entry colname="col2">sect4-title</entry>
            <entry colname="col3">Assigned Word outline level 5.</entry>
          </row>
          <row>
            <entry colname="col1">sect4/sect4info/subtitle</entry>
            <entry colname="col2">sect4-subtitle</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">sect4/sect4info/titleabbrev</entry>
            <entry colname="col2">sect4-titleabbrev</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">sect5/sect5info/title</entry>
            <entry colname="col2">sect5-title</entry>
            <entry colname="col3">Assigned Word outline level 6.</entry>
          </row>
          <row>
            <entry colname="col1">sect5/sect5info/subtitle</entry>
            <entry colname="col2">sect5-subtitle</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">sect5/sect5info/titleabbrev</entry>
            <entry colname="col2">sect5-titleabbrev</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">section</entry>
            <entry colname="col2">sectN-title</entry>
            <entry colname="col3">Unnumbered sections are mapped to their numbered equivalent.  A parameter (named?) may be set to map numbered sections (<literal>sect1</literal>, etc) back to unnumbered sections.</entry>
          </row>
          <row>
            <entry namest="col1" nameend="col3">
              <emphasis role="bold">Block-level elements</emphasis>
            </entry>
          </row>
          <row>
            <entry colname="col1">para</entry>
            <entry colname="col2">para, Normal</entry>
            <entry colname="col3">Any Word paragraph with style <literal>Normal</literal> will also be converted to a <sgmltag class="element">para</sgmltag> element.</entry>
          </row>
          <row>
            <entry colname="col1">abstract</entry>
            <entry colname="col2">abstract,abstract-title</entry>
            <entry colname="col3"><sgmltag>abstract</sgmltag>/<sgmltag>para</sgmltag>.</entry>
          </row>
          <row>
            <entry colname="col1">note/para</entry>
            <entry colname="col2">note</entry>
            <entry colname="col3">Consecutive paragraphs with style "note" after the first note are to be treated as part of the same <sgmltag class="element">note</sgmltag> element.  That is, consecutive notes are coalesced.</entry>
          </row>
          <row>
            <entry colname="col1">note/title</entry>
            <entry colname="col2">note-title</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">caution/para</entry>
            <entry colname="col2">caution</entry>
            <entry colname="col3">Consecutive cautions are coalesced.</entry>
          </row>
          <row>
            <entry colname="col1">warning/para</entry>
            <entry colname="col2">warning</entry>
            <entry colname="col3">Consecutive warnings are coalesced.</entry>
          </row>
          <row>
            <entry colname="col1">important/para</entry>
            <entry colname="col2">important</entry>
            <entry colname="col3">Consecutive importants are coalesced.</entry>
          </row>
          <row>
            <entry colname="col1">tip/para</entry>
            <entry colname="col2">tip</entry>
            <entry colname="col3">Consecutive tips are coalesced.</entry>
          </row>
          <row>
            <entry colname="col1">itemizedlist/listitem/para</entry>
            <entry colname="col2">
              <literallayout class="monospaced">itemizedlist1
itemizedlist1
itemizedlist2
itemizedlist3
itemizedlist4</literallayout>
            </entry>
            <entry colname="col3">A number suffix indicates a nesting level within other lists.</entry>
          </row>
          <row>
            <entry colname="col1">orderedlist/listitem/para</entry>
            <entry colname="col2">
              <literallayout class="monospaced">orderedlist1
orderedlist1
orderedlist2
orderedlist3
orderedlist4</literallayout>
            </entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">variablelist/varlistentry/term</entry>
            <entry colname="col2">
              <literallayout class="monospaced">variablelist1-term
variablelist2-term
variablelist3-term
variablelist4-term
variablelist5-term</literallayout>
            </entry>
            <entry colname="col3">A <sgmltag class="element">variablelist</sgmltag> in Word should be a sequence of alternating paragraphs styled as <literal>variablelist-term</literal> and <literal>variablelist</literal>.</entry>
          </row>
          <row>
            <entry colname="col1">variablelist/varlistentry/listitem/para</entry>
            <entry colname="col2">
              <literallayout class="monospaced">variablelist1
variablelist1
variablelist2
variablelist3
variablelist4</literallayout>
            </entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">listitem/para[position() != 1]</entry>
            <entry colname="col2">para-continue</entry>
            <entry colname="col3">This paragraph is included in the immediately preceding listitem.</entry>
          </row>
          <row>
            <entry colname="col1">example with title and programlisting children</entry>
            <entry colname="col2">example-title followed by programlisting</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">example with title and literallayout children</entry>
            <entry colname="col2">example-title followed by literallayout</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">example with title and mediaobject children</entry>
            <entry colname="col2">example-title followed by image styled with example style</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">figure with title and programlisting children</entry>
            <entry colname="col2">figure-title followed by programlisting</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">figure with title and literallayout children</entry>
            <entry colname="col2">figure-title followed by literallayout</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">figure with title and mediaobject children</entry>
            <entry colname="col2">figure-title followed by image styled with figure style</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">informalfigure</entry>
            <entry colname="col2">image tagged as figure style</entry>
            <entry colname="col3">with no figure-title above or below</entry>
          </row>
          <row>
            <entry colname="col1">informalfigure/mediaobject/imageobject/imagedata/@fileref</entry>
            <entry colname="col2">informalfigure-imagedata</entry>
            <entry colname="col3">The content of the paragraph is taken as the URI for the image.  For use in cases where the image is not embedded in the Word document.</entry>
          </row>
	  <row>
	    <entry colname='col1'>mediaobject|imageobject</entry>
	    <entry colname='col2'>imageobject-imagedata, caption</entry>
	    <entry colname='col3'>The content of the imageobject-imagedata paragraph is taken as the URI for the image.  May be followed by a <sgmltag>caption</sgmltag> style paragraph.</entry>
	  </row>
          <row>
            <entry colname="col1">mediaobjectco/imageobjectco/*[self::imagedata/@fileref|areaspec|calloutlist]</entry>
            <entry colname="col2">mediaobjectco-title, imageobjectco-imagedata, areaspec, area, callout</entry>
            <entry colname="col3">The content of the imageobjectco-imagedata paragraph is taken as the URI for the image.  May be preceded by areaspec and area paragraphs, and followed by callout paragraphs (these are ignored if not associated with an imageobjectco or programlistingco).  areaspec and area are normally empty paragraphs, but may have attributes encoded in the usual fashion.  callout paragraphs are collected together into a calloutlist, and may have nested lists.</entry>
          </row>
          <row>
            <entry colname="col1">programlistingco/*[self::programlisting|areaspec|calloutlist]</entry>
            <entry colname="col2">programlistingco, areaspec, area, callout</entry>
            <entry colname="col3">programlistingco may be preceded by areaspec and area paragraphs, and followed by callout paragraphs (these are ignored if not associated with an imageobjectco or programlistingco).  areaspec and area are normally empty paragraphs, but may have attributes encoded in the usual fashion.  callout paragraphs are collected together into a calloutlist, and may have nested lists.</entry>
          </row>
          <row>
            <entry colname="col1">table</entry>
            <entry colname="col2">Word table</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">table/title</entry>
            <entry colname="col2">table-title</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">informaltable</entry>
            <entry colname="col2">Word table</entry>
            <entry colname="col3">with no table-title above or below</entry>
          </row>
          <row>
            <entry colname="col1">literallayout</entry>
            <entry colname="col2">literallayout</entry>
            <entry colname="col3">Inside a <literal>literallayout</literal> paragraph in Word, lines should be separated by  line break (Shift-Enter) rather than paragraph break (Enter).</entry>
          </row>
          <row>
            <entry colname="col1">programlisting</entry>
            <entry colname="col2">programlisting</entry>
            <entry colname="col3">Inside a <literal>programlisting</literal> paragraph in Word, lines should be separated by  line break (Shift-Enter) rather than paragraph break (Enter). Tabs are not supported.</entry>
          </row>
          <row>
            <entry colname="col1">blockquote/para</entry>
            <entry colname="col2">blockquote</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">blockquote/title</entry>
            <entry colname="col2">blockquote-title</entry>
            <entry colname="col3">Should immediately precede a <literal>blockquote</literal> paragraph in Word.</entry>
          </row>
          <row>
            <entry colname="col1">blockquote/attribution</entry>
            <entry colname="col2">blockquote-attribution</entry>
            <entry colname="col3">Should immediately follow a <literal>blockquote</literal> paragraph in Word.</entry>
          </row>
          <row>
            <entry colname="col1">highlights/para</entry>
            <entry colname="col2">highlights</entry>
            <entry colname="col3">Consecutive highlights paragraphs are coalesced into a single highlights parent.</entry>
          </row>
          <row>
            <entry colname="col1">highlights/itemizedlist/listitem/para</entry>
            <entry colname="col2">highlights-itemizedlist</entry>
            <entry colname="col3">Nested lists are not currently supported.</entry>
          </row>
          <row>
            <entry colname="col1">highlights/orderedlist/listitem/para</entry>
            <entry colname="col2">highlights-orderedlist</entry>
            <entry colname="col3">Nested lists are not currently supported.</entry>
          </row>
          <row>
            <entry colname="col1">highlights/caution</entry>
            <entry colname="col2">highlights-caution</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">highlights/important</entry>
            <entry colname="col2">highlights-important</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">highlights/note</entry>
            <entry colname="col2">highlights-note</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">highlights/tip</entry>
            <entry colname="col2">highlights-tip</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">highlights/warning</entry>
            <entry colname="col2">highlights-warning</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry namest="col1" nameend="col3">
              <emphasis role="bold">Inline elements</emphasis>
            </entry>
          </row>
          <row>
            <entry colname="col1">emphasis</entry>
            <entry colname="col2">emphasis</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">emphasis with @role="bold"</entry>
            <entry colname="col2">emphasis-bold</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">footnote</entry>
            <entry colname="col2">Word footnote</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">link</entry>
            <entry colname="col2">link</entry>
            <entry colname="col3">In Word, hyperlink properties identify the DocBook linkend.</entry>
          </row>
          <row>
            <entry colname="col1">xref</entry>
            <entry colname="col2">xref</entry>
            <entry colname="col3">In Word, hyperlink properties identify the DocBook linkend. Some placeholder text can be used in Word, but it will be discarded when exported to DocBook where xref is an empty element.</entry>
          </row>
          <row>
            <entry colname="col1">olink</entry>
            <entry colname="col2">olink</entry>
            <entry colname="col3">In Word, hyperlink properties identify the DocBook targetdoc and targetptr.</entry>
          </row>
          <row>
            <entry colname="col1">ulink</entry>
            <entry colname="col2">ulink</entry>
            <entry colname="col3">In Word, hyperlink properties identify the url.</entry>
          </row>
          <row>
            <entry colname="col1">glossterm</entry>
            <entry colname="col2">glossterm</entry>
            <entry colname="col3">In Word, hyperlink properties identify the DocBook linkend.</entry>
          </row>
          <row>
            <entry colname="col1">firstterm</entry>
            <entry colname="col2">firstterm</entry>
            <entry colname="col3">In Word, hyperlink properties identify the DocBook linkend.</entry>
          </row>
          <row>
            <entry colname="col1">computeroutput</entry>
            <entry colname="col2">computeroutput</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">literal</entry>
            <entry colname="col2">literal</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">replaceable</entry>
            <entry colname="col2">replaceable</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">userinput</entry>
            <entry colname="col2">userinput</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">command</entry>
            <entry colname="col2">command</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">filename</entry>
            <entry colname="col2">filename</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">option</entry>
            <entry colname="col2">option</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">parameter</entry>
            <entry colname="col2">parameter</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">systemitem</entry>
            <entry colname="col2">systemitem</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">releaseinfo</entry>
            <entry colname="col2">releaseinfo</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">author</entry>
            <entry colname="col2">author</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">bibliomisc</entry>
            <entry colname="col2">bibliomisc</entry>
            <entry colname="col3"/>
          </row>
          <row>
            <entry colname="col1">surname</entry>
            <entry colname="col2">surname</entry>
            <entry colname="col3">Character style.  Must occur in an appropriate parent paragraph, such as <sgmltag>author</sgmltag>.</entry>
          </row>
          <row>
            <entry colname="col1">firstname</entry>
            <entry colname="col2">firstname</entry>
            <entry colname="col3">Character style.  Must occur in an appropriate parent paragraph, such as <sgmltag>author</sgmltag>.</entry>
          </row>
          <row>
            <entry colname="col1">orgname</entry>
            <entry colname="col2">orgname</entry>
            <entry colname="col3"/>
          </row>
        </tbody>
      </tgroup>
    </table>
    <section>
      <title>Attributes</title>
      <para>Attributes are a feature of DocBook XML that have no direct counterpart in Word.  Several approaches are possible:</para>
      <itemizedlist>
        <listitem>
          <para>Use Word comments (annotations); the currently implemented approach.  Some dummy text (just a space, using a character style that includes the hidden property) anchors the comment.  Within the comment text, character types are used to indicate attribute names and values (these must be paired).  This approach keeps the attributes separate to the main body and allows multiple attributes to be encoded.</para>
          <para>A disadvantage to this approach (which also applies to the other approaches below) is that a paragraph may be related to more than one element, but the attributes are associated with only one element (by default the parent).  For example, a section may have an attribute as well as the title child element, but only a single paragraph (with paragraph style <literal>section-title</literal>) represents both elements.  Any attribute defined in a comment would be associated with the <sgmltag>section</sgmltag> element.</para>
	  <para>Pages does not have annotations, so the character styles attribute-name and attribute-value are used.</para>
        </listitem>
        <listitem>
          <para>Use Word Bookmarks for attributes. For example, a Word Bookmark named <literal>att_role_foobar</literal> could be inserted into a paragraph. When converted to DocBook XML, this would become a <sgmltag class="attribute">role="foobar"</sgmltag> attribute on the element derived from the paragraph containing the Bookmark.</para>
        </listitem>
        <listitem>
          <para>Use hidden text.  Define character styles that have their text hidden, and place these at the beginning of a paragraph.</para>
        </listitem>
      </itemizedlist>
    </section>
  </section>
</article>
