Bob Stayton Sagehill Enterprises Steve Ball Explain 1.7 2008-02-22 SRB Added edition. 1.6 2007-10-19 SRB Added keyword. 1.5 2007-01-05 SRB Reduce emphasis on WordML, add support for OpenOffice. 1.4 2005-11-11 SRB Added bibliography. 1.3 2005-10-31 SRB Added mediaobjectco, imageobjectco, programlistingco, areaspec, area, calloutlist. 1.2 2005-10-13 SRB Version prior to using revhistory. 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.

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. DocBook content creators could write in their familiar wordprocessing application, rather than learning a new XML editing application. DocBook XML documents could be styled for output using the typesetting features of the word processor. 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. 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.

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: Enable authoring of basic DocBook documents in the word processor. Enable importing of basic DocBook XML documents into the word processor. To meet these goals, the project will produce a toolkit that can be immediately put to use. The kit will include: Templates for Microsoft Word, Apple Pages and OpenOffice with formatting styles attached to the style names. XSLT stylesheets that convert a word processing document that is authored with the corresponding template into a DocBook XML file. XSLT stylesheets that convert a DocBook document into a word processing document that can be opened in a word processor.

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. 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. 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.

The following goals are not in the scope of this project: Support of versions of Word that do not feature reading/writing WordML (XML). That is, all versions prior to Word 11 (Office 2003). Supporting user-defined style names. However, this system should not prevent, or make difficult, adding such support via a customisation layer. 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).

Although WordML, OpenDocument and DocBook are all XML, there several challenges when trying to convert between them. 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. 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. 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. 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 orderedlist2 is considered to be contained within a preceding paragraph with style listitem. In the word processor, paragraph indent levels will be used to visually indicate nesting of blocks. 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. 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 para is followed by a paragraph styled as itemizedlist, the conversion to DocBook will output a para element and then start an itemizedlist element, with the second paragraph as its first listitem. All itemizedlist paragraphs that follow without interruption are put in the same itemizedlist element. Some combinations of elements cannot be supported (at least not with the techniques as described in this document). An example is informalexample 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. Here are the design principles used in this project for selecting paragraph/character style names: 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 Normal paragraph style maps to a DocBook para element, and a Word table (w:tbl) maps to a DocBook tableIn 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.. 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. 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 personblurb paragraph may only occur after an author, editor or othercontrib paragraph. If a paragraph occurs without the appropriate preceding paragraph, then an error is signalled. 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, chapter-title indicates that the paragraph is a title whose DocBook parent is a chapter. 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: orderedlist, listitem, and para. The paragraph style name in Word is shortened from orderedlist-listitem-para to just orderedlist. In the case of lists (see below), the list level is appended so this example becomes orderedlist1 Style names with a number suffix indicate a nesting level, as described above. Style names with continue indicate that the paragraph is part of the preceding element. For example, a para paragraph is used for a single paragraph para 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 para-continue style. 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 surname character style in an author paragraph becomes a surname child element of the author element. Empty paragraph and character styles are ignored. 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 book-title, then the DocBook document will have book as its root element. All the rest of the document content will be contained in that root element. Sequential structures are coalesced into a single parent element. For example, a sequence of itemizedlist paragraphs becomes a single itemizedlist element with several listitem children. DocBook element Style(s) Comments Components and sections book/bookinfo/title book-title book/bookinfo/subtitle book-subtitle book/bookinfo/titleabbrev book-titleabbrev chapter/chapterinfo/title chapter-title Assigned Word outline level 1. chapter/chapterinfo/subtitle chapter-subtitle chapter/chapterinfo/titleabbrev chapter-titleabbrev appendix/appendixinfo/title appendix-title Assigned Word outline level 1. preface/prefaceinfo/title preface-title Assigned Word outline level 1. article/articleinfo/title article-title Assigned Word outline level 1. article/articleinfo/subtitle article-subtitle article/articleinfo/titleabbrev article-titleabbrev bibliography/bibliographyinfo/title bibliography-title Assigned Word outline level 1. bibliography/bibliodiv bibliodiv-title biblioentry biblioentry-title Metadata elements after the biblioentry-title paragraph become part of the biblioentry. glossary/glossaryinfo/title glossary-title Assigned Word outline level 1. index/indexinfo/title index-title Assigned Word outline level 1. sect1/sect1info/title sect1-title Assigned Word outline level 2. sect1/sect1info/subtitle sect1-subtitle sect1/sect1info/titleabbrev sect1-titleabbrev sect2/sect2info/title sect2-title Assigned Word outline level 3. sect2/sect2info/subtitle sect2-subtitle sect2/sect2info/titleabbrev sect2-titleabbrev sect3/sect3info/title sect3-title Assigned Word outline level 4. sect3/sect3info/subtitle sect3-subtitle sect3/sect3info/titleabbrev sect3-titleabbrev sect4/sect4info/title sect4-title Assigned Word outline level 5. sect4/sect4info/subtitle sect4-subtitle sect4/sect4info/titleabbrev sect4-titleabbrev sect5/sect5info/title sect5-title Assigned Word outline level 6. sect5/sect5info/subtitle sect5-subtitle sect5/sect5info/titleabbrev sect5-titleabbrev section sectN-title Unnumbered sections are mapped to their numbered equivalent. A parameter (named?) may be set to map numbered sections (sect1, etc) back to unnumbered sections. Metadata elements edition edition Block-level elements para para, Normal Any Word paragraph with style Normal will also be converted to a para element. abstract abstract,abstract-title abstract/para. note/para note Consecutive paragraphs with style "note" after the first note are to be treated as part of the same note element. That is, consecutive notes are coalesced. note/title note-title caution/para caution Consecutive cautions are coalesced. warning/para warning Consecutive warnings are coalesced. important/para important Consecutive importants are coalesced. tip/para tip Consecutive tips are coalesced. itemizedlist/listitem/para itemizedlist1 itemizedlist1 itemizedlist2 itemizedlist3 itemizedlist4 A number suffix indicates a nesting level within other lists. orderedlist/listitem/para orderedlist1 orderedlist1 orderedlist2 orderedlist3 orderedlist4 variablelist/varlistentry/term variablelist1-term variablelist2-term variablelist3-term variablelist4-term variablelist5-term A variablelist in Word should be a sequence of alternating paragraphs styled as variablelist-term and variablelist. variablelist/varlistentry/listitem/para variablelist1 variablelist1 variablelist2 variablelist3 variablelist4 listitem/para[position() != 1] para-continue This paragraph is included in the immediately preceding listitem. example with title and programlisting children example-title followed by programlisting example with title and literallayout children example-title followed by literallayout example with title and mediaobject children example-title followed by image styled with example style figure with title and programlisting children figure-title followed by programlisting figure with title and literallayout children figure-title followed by literallayout figure with title and mediaobject children figure-title followed by image styled with figure style informalfigure image tagged as figure style with no figure-title above or below informalfigure/mediaobject/imageobject/imagedata/@fileref informalfigure-imagedata 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. mediaobject|imageobject imageobject-imagedata, caption The content of the imageobject-imagedata paragraph is taken as the URI for the image. May be followed by a caption style paragraph. mediaobjectco/imageobjectco/*[self::imagedata/@fileref|areaspec|calloutlist] mediaobjectco-title, imageobjectco-imagedata, areaspec, area, callout 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. programlistingco/*[self::programlisting|areaspec|calloutlist] programlistingco, areaspec, area, callout 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. table Word table table/title table-title informaltable Word table with no table-title above or below literallayout literallayout Inside a literallayout paragraph in Word, lines should be separated by line break (Shift-Enter) rather than paragraph break (Enter). programlisting programlisting Inside a programlisting paragraph in Word, lines should be separated by line break (Shift-Enter) rather than paragraph break (Enter). Tabs are not supported. blockquote/para blockquote blockquote/title blockquote-title Should immediately precede a blockquote paragraph in Word. blockquote/attribution blockquote-attribution Should immediately follow a blockquote paragraph in Word. highlights/para highlights Consecutive highlights paragraphs are coalesced into a single highlights parent. highlights/itemizedlist/listitem/para highlights-itemizedlist Nested lists are not currently supported. highlights/orderedlist/listitem/para highlights-orderedlist Nested lists are not currently supported. highlights/caution highlights-caution highlights/important highlights-important highlights/note highlights-note highlights/tip highlights-tip highlights/warning highlights-warning Inline elements emphasis emphasis emphasis with @role="bold" emphasis-bold footnote Word footnote link link In Word, hyperlink properties identify the DocBook linkend. xref xref 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. olink olink In Word, hyperlink properties identify the DocBook targetdoc and targetptr. ulink ulink In Word, hyperlink properties identify the url. glossterm glossterm In Word, hyperlink properties identify the DocBook linkend. firstterm firstterm In Word, hyperlink properties identify the DocBook linkend. computeroutput computeroutput literal literal replaceable replaceable userinput userinput command command filename filename option option parameter parameter systemitem systemitem releaseinfo releaseinfo author author bibliomisc bibliomisc surname surname Character style. Must occur in an appropriate parent paragraph, such as author. firstname firstname Character style. Must occur in an appropriate parent paragraph, such as author. orgname orgname keyword keywordset/kyword Paragraph style. Consecutive keyword elements are merged into a single keywordset parent element. Words (phrases) within a paragraph separated by commas become individual keyword elements.

Attributes are a feature of DocBook XML that have no direct counterpart in Word. Several approaches are possible: 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. 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 section-title) represents both elements. Any attribute defined in a comment would be associated with the section element. Pages does not have annotations, so the character styles attribute-name and attribute-value are used. Use Word Bookmarks for attributes. For example, a Word Bookmark named att_role_foobar could be inserted into a paragraph. When converted to DocBook XML, this would become a role="foobar" attribute on the element derived from the paragraph containing the Bookmark. Use hidden text. Define character styles that have their text hidden, and place these at the beginning of a paragraph.