Eric White's Blog : OpenXmlSdk

Accepting Revisions in Open XML WordprocessingML Documents

EricWhite — Mon, 21 Dec 2009 14:51:00 GMT

[Blog Map]

Update Dec 21, 2009: This is the 9th in a series of posts on implementing a transform of WordprocessingML to XHtml.

1) Transforming Open XML Word-Processing Documents to XHtml

2) Transforming Open XML Word-Processing Documents to XHtml (Post #2)

3) Transforming Open XML Word-Processing Documents to Html (Post #3)

4) Open XML WordprocessingML Style Inheritance

5) Comparison of Html/CSS Tables to WordprocessingML Tables

6) Assembling Paragraph and Run Properties for Cells in an Open XML WordprocessingML Table

7) Implementing 'Inheritance' in XML

8) Working with Numbering in Open XML WordprocessingML

9) Accepting Revisions in Open XML WordprocessingML Documents

Revision tracking markup in Open XML word-processing documents is one of the more complex areas of the standard. If you first accept tracked revisions, it makes subsequent processing of text in word-processing documents much simpler. As an example, in my current project of transforming Open XML word-processing documents to XHtml, before doing the conversion, I accept tracked revisions in an in-memory WordprocessingDocument object. I then transform that in-memory document to XHtml. This means that in my transformation algorithm, I can completely disregard all of the revision tracking elements and attributes, and all of the complexities associated with them. If you want to know in exacting detail how the tracked revision markup works in Open XML, then this post will tell you. It also describes the algorithms in detail for accepting tracked revisions.

Note: This is an MSDN article that I've written that was recently published. You can find it on MSDN at Accepting Revisions in Open XML Word-Processing Documents. We want to make this as easy to find as possible, so publishing here as well as on MSDN.

There are some posts that I put up because they have wide applicability, and there are some posts that I put up because they are important. There are probably a handfull of developers in the world who need to know the exact details of accepting revisions. This post will be important to them.

This post presents the markup semantics behind the code that I've written that accepts tracked revisions for the PowerTools for Open Xml project. You can find this code under the Downloads tab at CodePlex.com/PowerTools.

Table of Contents

Understanding the Difference Between Collapsing and Removing

Removing Elements

Collapsing Elements

Table Cell Deletion (cellDel Element)

Vertically Merged/Split Table Cells (cellMerge Element)

Custom XML Markup Deletion Start and End (customXmlDelRangeStart Element and customXmlDelRangeEnd Element)

Custom XML Markup Move Source Start and End (customXmlMoveFromRangeStart Element and customXmlMoveFromRangeEnd Element)

Deleted Math Control Character (del Element)

Deleted Paragraph (del Element)

Deleted Table Row (del Element)

Move Source Paragraph (moveFrom Element)

Move Source Location Container—Start and End (moveFromRangeStart Element and moveFromRangeEnd Element)

Conclusion

Additional Resources

Overview

Tracking revisions in Open XML documents is one of the most important features of the document format. It is very useful to programmatically accept revisions using the Open XML SDK. In one scenario, you may have a SharePoint document library that contains documents designed and written for distribution outside your company. You want to ensure that there are no tracked revisions in any document in the document library. You could implement code to accept revisions as the document is saved into the document library. Another scenario: many kinds of complex text processing operations are made much simpler if we first accept tracked revisions. For instance, it is easier to write a high-fidelity conversion of Open XML to XHTML if you first accept all revisions, and then perform the appropriate transforms. These are just some the interesting scenarios. There are many more.

This article examines the semantics of transforming an Open XML word- processing document that contains tracked revisions to one that contains no revisions. I implemented these algorithms in a class, RevisionAccepter, which is part of the PowerTools for Open XML project, an open source project on CodePlex.

The use of RevisionAccepter.AcceptRevisions is simple. You call a static method in the RevisionAccepter class by using an open WordprocessingDocument object. Upon return of the method, the document contains no tracked revisions.

using (WordprocessingDocument doc =

WordprocessingDocument.Open("DocumentWithRevisions.docx", true))

{

RevisionAccepter.AcceptRevisions(doc);

}

The RevisionAccepter class uses a recursive approach to XML transformation using LINQ to XML. For details about that code, see the following blog post: Recursive Pure Functional Transformations of XML.

Note: The PowerTools for Open XML are licensed under the Microsoft Public License (Ms-PL) license, which gives you wide latitude in how you use the code, so download the RevisionAccepter class and try it out. To download it, see PowerTools for OpenXml 1.1.1.

The Open XML markup for revision tracking is extensive—there are more than 40 elements that we must process when accepting tracked revisions. Although some are simple to process, other elements are more involved.

There are more than 20 elements that must be removed (together with their descendants) from the XML tree. There are several elements that must be collapsed—the element must be replaced with its descendant elements.

Understanding the Difference Between Collapsing and Removing

It is useful to define what collapsing an element means and how collapsing is related to removing an element. The processing of an inserted paragraph requires collapsing the w:ins element. To show exactly what collapsing means, consider the following markup that shows that a paragraph was inserted while revisions were being tracked. The inserted paragraph is preceded and followed with empty paragraphs.

<w:p/>

<w:ins w:id="16"

w:author="Eric White"

w:date="2009-08-29T06:47:00Z">

<w:p>

<w:r>

<w:t>This is another inserted paragraph.</w:t>

</w:r>

</w:p>

</w:ins>

<w:p/>

Collapsing the w:ins element means that we remove the w:ins element, and promote its child element or elements to the level of the w:ins element. The resulting markup after accepting revisions looks as follows:

<w:p/>

<w:p>

<w:r>

<w:t>This is another inserted paragraph.</w:t>

</w:r>

</w:p>

<w:p/>

In contrast, removing an element eliminates that element and all descendants from the resulting XML tree. The following is markup for a deleted paragraph. To accept this tracked revision, the w:del element and its descendants are removed.

<w:p/>

<w:del w:id="2"

w:author="Eric White"

w:date="2009-09-11T07:53:00Z">

<w:p>

<w:r>

<w:delText>You can create pictures, charts, or diagrams.</w:delText>

</w:r>

</w:p>

</w:del>

<w:p/>

The resulting markup after accepting revisions looks as follows:

<w:p/>

Note that collapsing an element that has no descendant elements effectively is the same as removing that element. In some situations, you must collapse some elements, whereas you must remove other elements with the same tag. For better performance and simpler code, in those situations, I collapse all elements, which removes those elements that have no descendants.

Removing Elements

By far, when accepting revisions, the most common operation is to remove elements. You must remove the following elements (and descendants if any) from the document when accepting revisions:

Elements to Remove

Element Name	Description	Ecma376	ISO/IEC 29500
cellIns	Table cell insertion	2.13.5.2	17.13.5.2
customXmlInsRangeStart	Custom XML markup insertion start	2.13.5.7	17.13.5.7
customXmlInsRangeEnd	Custom XML markup insertion end	2.13.5.6	17.13.5.6
customXmlMoveToRangeStart	Custom XML markup move destination location start	2.13.5.11	17.13.5.11
customXmlMoveToRangeEnd	Custom XML markup move destination location end	2.13.5.10	17.13.5.10
del	Deleted run content	2.13.5.12	17.13.5.12
delText	Deleted text	2.3.3.7	17.3.3.7
delInstrText	Deleted field code	2.16.13	17.16.13
ins	Inserted math control character	2.13.5.17	17.13.5.17
ins	Inserted numbering properties	2.13.5.19	17.13.5.19
ins	Inserted paragraph	2.13.5.18	17.13.5.18
ins	Inserted table row	2.13.5.16	17.13.5.16
moveTo	Move destination paragraph	2.13.5.25	17.13.5.25
moveFrom	Move source run content	2.13.5.21	17.13.5.21
moveToRangeStart	Move destination location container - start	2.13.5.28	17.13.5.28
moveToRangeEnd	Move destination location container - end	2.13.5.27	17.13.5.27
numberingChange	Previous numbering field properties	2.13.5.29	17.13.5.29
numberingChange	Previous paragraph numbering properties	2.13.5.30	17.13.5.30
pPrChange	Revision information for paragraph properties	2.13.5.31	17.13.5.31
rPrChange	Revision information for run properties	2.13.5.32	17.13.5.32
rPrChange	Revision information for run properties on the paragraph mark	2.13.5.33	17.13.5.33
sectPrChange	Revision information for section properties	2.13.5.34	17.13.5.34
tblGridChange	Revision information for table grid column definitions	2.13.5.35	17.13.5.35
tblPrChange	Revision information for table properties	2.13.5.36	17.13.5.36
tblPrExChange	Revision information for table-level property exceptions	2.13.5.37	17.13.5.37
tcPrChange	Revision information for table cell properties	2.13.5.38	17.13.5.38
trPrChange	Revision information for table row properties	2.13.5.39	17.13.5.39

Collapsing Elements

You should collapse the following elements from the document when accepting revisions:

Elements to Collapse

Element Name	Description	Ecma376	ISO/IEC 29500
ins	Inserted math control character	2.13.5.17	17.13.5.17
ins	Inserted run content	2.13.5.20	17.13.5.20
ins	Inserted table row	2.13.5.16	17.13.5.16
moveTo	Move destination run content	2.13.5.26	17.13.5.26

Beyond processing elements that we can remove or collapse, there are several elements where processing involves more complex algorithms. In the following sections, I present the algorithm to process the markup. The Open XML specification does not specify these algorithms. The specification only defines the format, not any behavior associated with the format. However, you can infer some aspects of these algorithms from the specification. In the following subsections, I also present examples of the markup with the tracked revision and how the markup appears when the tracked revision is accepted.

Table Cell Deletion (cellDel Element)

This element specifies that a table cell was removed from the document.

Open XML Specification Location

Ecma-376 2.13.5.1

ISO/IEC 29500 17.13.5.1

Algorithm

To accept this revision, you remove these elements. The complication in accepting this revision is that you must group consecutive deleted cells, and increase the w:val attribute of the w:gridSpan element of the cell immediately before the group of deleted cells by the sum of the values of the w:val attributes of w:gridSpan elements of each of the deleted cells. Note that if a cell does not contain a w:gridSpan element, its grid span value is set to 1.

Example

The following example contains no w:gridSpan elements, so that the w:gridSpan values for each cell is set to 1.

<w:tr>

<w:tc>

<w:tcPr>

<w:tcW w:w="9576"

w:type="dxa"/>

</w:tcPr>

<w:p>

<w:r>

<w:t>1</w:t>

</w:r>

</w:p>

</w:tc>

<w:tc>

<w:tcPr>

<w:tcW w:w="3192"

w:type="dxa"/>

<w:cellDel w:id="3"

w:author="Eric White"

w:date="2009-09 -11T15:30:00Z"/>

</w:tcPr>

<w:p/>

</w:tc>

<w:tc>

<w:tcPr>

<w:tcW w:w="3192"

w:type="dxa"/>

<w:cellDel w:id="6"

w:author="Eric White"

w:date="2009-09 -11T15:30:00Z"/>

</w:tcPr>

<w:p/>

</w:tc>

</w:tr>

The following example shows the resulting XML after revisions are accepted. Notice that the w:val attribute of the w:gridSpan element is set to 3, calculated as the sum of the value of the first cell (default value of 1) plus the values of the deleted cells (each with a default value of 1).

<w:tr>

<w:tc>

<w:tcPr>

<w:gridSpan w:val="3" />

<w:tcW w:w="9576"

w:type="dxa" />

</w:tcPr>

<w:p>

<w:r>

<w:t>1</w:t>

</w:r>

</w:p>

</w:tc>

</w:tr>

Producing This Markup by Using Word 2007

Microsoft Office Word 2007 does not track revisions when merging, inserting, or deleting cells. Instead, it informs you that those revisions are not tracked. However, you can create a document that contains this markup using the following procedure:

Create a document that contains a table.
Copy that document to a new file, open the new document, and merge cells in the table.
Save the new document.
Compare the two documents by using Word 2007. Click the Review tab of the Ribbon, and then click Compare in the Compare section of the Ribbon. Click Compare two versions of a document (legal blackline). Save the resulting document without accepting changes in the document. The saved document contains the w:cellDel elements.

Note that, while Word 2007 does not produce this element without following the previous procedure, it definitely is possible in the future that an Open XML word-processing application could produce this element (and the w:cellIns element and the w:cellMerge element). It is important for this implementation to correctly process it.

Vertically Merged/Split Table Cells (cellMerge Element)

This element specifies that the vertical merge state of its parent cell was modified while revisions were tracked.

Open XML Specification Location

Ecma-376 2.13.5.3

ISO/IEC 29500 17.13.5.3

Algorithm

To accept this revision, you transform the w:cellMerge element that has an attribute of w:vMerge="rest" to the w:vMerge element that has an attribute w:val="restart". You transform the w:cellMerge element that has an attribute of w:vMerge="cont" to the w:vMerge element that has an attribute w:val="continue". To make this clear, this is what w:cellMerge with an attribute of w:vMerge="rest" looks like the following:

<w:cellMerge w:id="3"

w:author="Eric White"

w:date="2009-08- 29T07:07:00Z"

w:vMerge="rest" />

That element is transformed to this:

<w:vMerge w:val="restart" />

Example

The following example shows two spreadsheet rows that contain the w:cellMerge element. The example also contains w:ins elements, which are processed separately.

<w:tr>

<w:tc>

<w:tcPr>

<w:tcW w:w="4788"

w:type="dxa" />

</w:tcPr>

<w:p>

<w:r>

<w:t>1</w:t>

</w:r>

</w:p>

</w:tc>

<w:tc>

<w:tcPr>

<w:tcW w:w="4788"

w:type="dxa" />

<w:cellMerge w:id="3"

w:author="Eric White"

w:date="2009-08-29T07:07:00Z"

w:vMerge="rest" />

</w:tcPr>

<w:p>

<w:pPr>

<w:rPr>

<w:ins w:id="6"

w:author="Eric White"

w:date="2009-08 -29T07:07:00Z" />

</w:rPr>

</w:pPr>

<w:r>

<w:t>2</w:t>

</w:r>

</w:p>

<w:p>

<w:ins w:id="7"

w:author="Eric White"

w:date="2009-08- 29T07:07:00Z">

<w:r>

<w:t>4</w:t>

</w:r>

</w:ins>

</w:p>

</w:tc>

</w:tr>

<w:tr>

<w:tc>

<w:tcPr>

<w:tcW w:w="4788"

w:type="dxa" />

</w:tcPr>

<w:p>

<w:r>

<w:t>3</w:t>

</w:r>

</w:p>

</w:tc>

<w:tc>

<w:tcPr>

<w:tcW w:w="4788"

w:type="dxa" />

<w:cellMerge w:id="9"

w:author="Eric White"

w:date="2009-08-29T07:07:00Z"

w:vMerge="cont" />

</w:tcPr>

<w:p>

<w:del w:id="12"

w:author="Eric White"

w:date="2009-08- 29T07:07:00Z">

<w:r>

<w:delText>4</w:delText>

</w:r>

</w:del>

</w:p>

</w:tc>

</w:tr>

The following example shows the resulting XML that contains the w:vMerge element when this revision is accepted.

<w:tr>

<w:tc>

<w:tcPr>

<w:tcW w:w="4788"

w:type="dxa" />

</w:tcPr>

<w:p>

<w:r>

<w:t>1</w:t>

</w:r>

</w:p>

</w:tc>

<w:tc>

<w:tcPr>

<w:tcW w:w="4788"

w:type="dxa" />

<w:vMerge w:val="restart" />

</w:tcPr>

<w:p>

<w:pPr>

<w:rPr />

</w:pPr>

<w:r>

<w:t>2</w:t>

</w:r>

</w:p>

<w:p>

<w:r>

<w:t>4</w:t>

</w:r>

</w:p>

</w:tc>

</w:tr>

<w:tr>

<w:tc>

<w:tcPr>

<w:tcW w:w="4788"

w:type="dxa" />

</w:tcPr>

<w:p>

<w:r>

<w:t>3</w:t>

</w:r>

</w:p>

</w:tc>

<w:tc>

<w:tcPr>

<w:tcW w:w="4788"

w:type="dxa" />

<w:vMerge w:val="continue" />

</w:tcPr>

<w:p />

</w:tc>

</w:tr>

Producing This Markup by Using Word 2007

You can create a document that contains this markup using the following procedure:

Create a document that contains a table.
Copy that document to a new file, open the new document, and vertically merge cells in the table. Save the new document.
Compare the two documents by using Word 2007 using the procedure that is described in the Table Cell Deletion (cellDel Element) section.

Custom XML Markup Deletion Start and End (customXmlDelRangeStart Element and customXmlDelRangeEnd Element)

These elements specify a region in the document where custom XML markup was deleted from the document.

Open XML Specification Location

Ecma-376 2.13.5.4, 2.13.5.5

ISO/IEC 29500 17.13.5.4, 17.13.5.5

Algorithm

To accept this revision, you must find all custom XML elements where both the start and end tag of the custom XML elements fall inside a matched pair of the w:customXmlDelRangeStart element and the w:customXmlDelRangeEnd element. A matched pair of elements requires that both the w:customXmlDelRangeStart element and the w:customXmlDelRangeEnd element have matching w:id attributes. After a w:customXml element is identified as deleted, you must collapse the w:customXml element, promoting its content to the level of the w:customXml element. The w:customXmlDelRangeStart element and the w:customXmlDelRangeEnd element are removed also.

One of the interesting things about this transform is that you must verify that the end tag of a custom XML element falls inside a range. When using an XML DOM tree, such as LINQ to XML or the classes in the System.Xml.XmlDocument namespace, you must implement a somewhat complex algorithm that would not have a direct correlation to the text of the Open XML specification. Instead, in the code to accept tracked revisions, I implemented a method that returns a collection of descendant start and end tags for a LINQ to XML element. The code that looks for the pattern where the end tag of a custom XML element is then implemented so that the logic of the method has a direct parallel to the text of the specification.

Example

The following example shows revision tracking markup for a deleted custom XML element and its contents. The w:customXml element that has the w:element="Abstract" element is considered deleted because both its start and end tags are in ranges. As I mentioned previously, it is important that the w:id attributes match also.

<w:customXml w:uri="http://www.adventureworks.com"

w:element="Root">

<w:p>

<w:customXmlDelRangeStart w:id="0"

w:author="Eric White"

w:date="2009-09-11T20:59:00Z" />

<w:customXml w:uri="http://www.adventureworks.com"

w:element="Abstract">

<w:customXmlDelRangeEnd w:id="0" />

<w:del w:id="1"

w:author="Eric White"

w:date="2009-09- 11T20:59:00Z">

<w:r>

<w:delText>Hello</w:delText>

</w:r>

</w:del>

<w:customXmlDelRangeStart w:id="2"

w:author="Eric White"

w:date="2009-09-11T20:59:00Z" />

</w:customXml>

<w:customXmlDelRangeEnd w:id="2" />

<w:r>

<w:t>Goodbye</w:t>

</w:r>

</w:p>

</w:customXml>

The following example shows the resulting XML when this revision is accepted.

<w:customXml w:uri="http://www.adventureworks.com"

w:element="Root">

<w:p>

<w:r>

<w:t>Goodbye</w:t>

</w:r>

</w:p>

</w:customXml>

Custom XML Markup Move Source Start and End (customXmlMoveFromRangeStart Element and customXmlMoveFromRangeEnd Element)

These elements specify a region in the document where custom XML markup was moved to another location.

Open XML Specification Location

Ecma-376 2.13.5.8, 2.13.5.9

ISO/IEC 29500 17.13.5.8, 17.13.5.9

Algorithm

To accept this revision, you must find all custom XML elements where both the start and end tag of the custom XML elements fall inside a matched pair of the w:customXmlMoveRangeStart element and the w:customXmlMoveRangeEnd element. The handling of these elements is identical to the handling of the w:customXmlDelRangeStart element and the w:customXmlDelRangeEnd element. In my implementation, I process all four elements in the same method.

Example

The following example shows revision tracking markup for a moved custom XML element and its contents. The w:customXml element that has w:element="Root" element is considered moved from this location because both its start and end tags are in ranges.

<w:body>

<w:customXmlMoveFromRangeStart w:id="0"

w:author="Eric White"

w:date="2009-09-11T21:35:00Z" />

<w:moveFromRangeStart w:id="1"

w:author="Eric White"

w:date="2009-09-11T21:35:00Z"

w:name="move240468267"

w:displacedByCustomXml="next" />

<w:customXml w:uri="http://www.adventureworks.com"

w:element="Root">

<w:customXmlMoveFromRangeEnd w:id="0" />

<w:p>

<w:moveFrom w:id="2"

w:author="Eric White"

w:date="2009-09-11T21:35:00Z">

<w:r>

<w:t>On the Insert tab, the galleries include items that are designed to coordinate with the overall look of your document.</w:t>

</w:r>

</w:moveFrom>

</w:p>

<w:customXmlMoveFromRangeStart w:id="3"

w:author="Eric White"

w:date="2009-09-11T21:35:00Z" />

</w:customXml>

<w:customXmlMoveFromRangeEnd w:id="3" />

<w:moveFromRangeEnd w:id="1" />

<w:p>

<w:r>

<w:t>You can use these galleries to insert tables, headers, footers, lists, cover pages, and other document building blocks.</w:t>

</w:r>

</w:p>

. . .

The following example shows the resulting XML when this revision is accepted.

<w:body>

<w:p>

<w:r>

<w:t>You can use these galleries to insert tables, headers, footers, lists, cover pages, and other document building blocks.</w:t>

</w:r>

</w:p>

. . .

Producing This Markup by Using Word 2007

To create a document that has this markup, associate a schema with the document, insert custom XML, turn on revision tracking, and move the custom XML. Note that if you move custom XML inside a paragraph, Word 2007 may not generate move revision tracking markup, but may delete and insert the XML.

Deleted Math Control Character (del Element)

This element specifies that a math control character was deleted.

Open XML Specification Location

Ecma-376 2.13.5.15

ISO/IEC 29500 17.13.5.15

Algorithm

To accept this revision, you match the pattern m:f/m:fPr/m:ctrlPr/w:del, and remove the m:f element.

Example

The following example shows a deleted math control character.

<w:p>

<m:oMathPara>

<m:oMath>

<m:r>

<w:rPr>

<w:rFonts w:ascii="Cambria Math"

w:hAnsi="Cambria Math" />

</w:rPr>

<m:t>1+</m:t>

</m:r>

<m:f>

<m:fPr>

<m:ctrlPr>

<w:del w:id="0"

w:author="Eric White"

w:date="2009-09-09T15:45:00Z">

<w:rPr>

<w:rFonts w:ascii="Cambria Math"

w:hAnsi="Cambria Math" />

<w:i />

</w:rPr>

</w:del>

</m:ctrlPr>

</m:fPr>

<m:num>

<w:del w:id="1"

w:author="Eric White"

w:date="2009-09 -09T15:45:00Z">

<m:r>

<w:rPr>

<w:rFonts w:ascii="Cambria Math"

w:hAnsi="Cambria Math" />

</w:rPr>

<m:t>2</m:t>

</m:r>

</w:del>

</m:num>

<m:den>

<w:del w:id="2"

w:author="Eric White"

w:date="2009-09 -09T15:45:00Z">

<m:r>

<w:rPr>

<w:rFonts w:ascii="Cambria Math"

w:hAnsi="Cambria Math" />

</w:rPr>

<m:t>3</m:t>

</m:r>

</w:del>

</m:den>

</m:f>

</m:oMath>

</m:oMathPara>

</w:p>

The following example shows the resulting XML when this revision is accepted.

<w:p>

<m:oMathPara>

<m:oMath>

<m:r>

<w:rPr>

<w:rFonts w:ascii="Cambria Math"

w:hAnsi="Cambria Math" />

</w:rPr>

<m:t>1+</m:t>

</m:r>

</m:oMath>

</m:oMathPara>

</w:p>

Producing This Markup by Using Word 2007

To create a document by using this markup, insert a math formula, such as a fraction, turn on revision tracking, and delete the fraction.

Deleted Paragraph (del Element)

This element specifies that the paragraph mark for the paragraph that contains this element is deleted. In practical terms, it means that the contents of the paragraph that contains this element, and the contents of the following paragraph are combined to form a new paragraph.

Open XML Specification Location

Ecma376 2.13.5.13

ISO/IEC 29500 17.13.5.13

Algorithm

The algorithm for this is somewhat complex. More than one consecutive paragraph may contain this element. Therefore, you must group paragraphs that contain this, combine the contents of the grouped paragraphs with the paragraph following the last in the group, and form a new paragraph. The paragraph properties for the new paragraph come from the paragraph following the last in the group.

The algorithm is more complex in that any of the paragraphs with a deleted paragraph mark, or the paragraph following the last in the series may be contained in custom XML elements or in content controls. When combining the set of paragraphs, we must manipulate the custom XML elements and the content controls that are contained within the series. The rule when manipulating a content control while accepting deleted paragraph marks is that the content control should always enclose the same (non-deleted) runs as before accepting revisions. One additional addendum to this rule: if the content control was at the block level before accepting revisions, and if the content control surrounds runs that exactly match the contents of paragraphs, the content control should stay at the block level. In other words, it should not be demoted to the run level unnecessarily. The rule when manipulating custom XML elements when accepting deleted paragraph marks is that if a custom XML element was at the block level before accepting revisions, it must stay at block level after accepting revisions, even if it means moving text that was outside the custom XML element into a paragraph within the custom XML element. And of course, custom XML elements at the run level remain at the run level. The example code that is part of the PowerTools for Open XML project exhibits this behavior.

Example

The following example shows a deleted paragraph mark.

<w:p>

<w:r>

<w:t>On the Insert tab.</w:t>

</w:r>

</w:p>

<w:p>

<w:pPr>

<w:rPr>

<w:del w:id="0"

w:author="Eric White"

w:date="2009-08- 21T15:38:00Z" />

</w:rPr>

</w:pPr>

<w:r>

<w:t>You can use these.</w:t>

</w:r>

</w:p>

<w:sdt>

<w:sdtPr>

<w:id w:val="283218227" />

<w:placeholder>

<w:docPart w:val="DefaultPlaceholder_22675703" />

</w:placeholder>

</w:sdtPr>

<w:sdtContent>

<w:p>

<w:pPr>

<w:rPr>

<w:del w:id="1"

w:author="Eric White"

w:date="2009-08 -21T15:38:00Z" />

</w:rPr>

</w:pPr>

<w:r>

<w:t>Create pictures, charts, or diagrams.</w:t>

</w:r>

</w:p>

</w:sdtContent>

</w:sdt>

<w:p>

<w:r>

<w:t>You can easily change the formatting.</w:t>

</w:r>

</w:p>

The following example shows the resulting XML when this revision is accepted. Because one of the paragraphs that contains the deleted paragraph mark was in a content control, the content control was demoted to enclose a run.

<w:p>

<w:r>

<w:t>On the Insert tab.</w:t>

</w:r>

</w:p>

<w:p>

<w:r>

<w:t>You can use these.</w:t>

</w:r>

<w:sdt>

<w:sdtPr>

<w:id w:val="283218227" />

<w:placeholder>

<w:docPart w:val="DefaultPlaceholder_22675703" />

</w:placeholder>

</w:sdtPr>

<w:sdtContent>

<w:r>

<w:t>Create pictures, charts, or diagrams.</w:t>

</w:r>

</w:sdtContent>

</w:sdt>

<w:r>

<w:t>You can easily change the formatting.</w:t>

</w:r>

</w:p>

Producing This Markup by Using Word 2007

Place the cursor at the end of a paragraph, and press Delete.

Deleted Table Row (del Element)

This element specifies that a row in a table was deleted.

Open XML Specification Location

Ecma-376 2.13.5.14

ISO/IEC 29500 17.13.5.14

Algorithm

To accept this revision, you match the pattern w:tr/w:trPr/w:del, and remove the w:tr element.

Example

The following example shows a deleted table row.

<w:tr>

<w:tc>

<w:tcPr>

<w:tcW w:w="9576"

w:type="dxa"/>

</w:tcPr>

<w:p/>

</w:tc>

</w:tr>

<w:tr>

<w:trPr>

<w:del w:id="0"

w:author="Eric White"

w:date="2009-09-29T22:10:00Z"/>

</w:trPr>

<w:tc>

<w:tcPr>

<w:tcW w:w="9576"

w:type="dxa"/>

</w:tcPr>

<w:p>

<w:pPr>

<w:rPr>

<w:del w:id="1"

w:author="Eric White"

w:date="2009-09 -29T22:10:00Z"/>

</w:rPr>

</w:pPr>

<w:del w:id="2"

w:author="Eric White"

w:date="2009-09- 29T22:10:00Z">

<w:r>

<w:delText>123</w:delText>

</w:r>

</w:del>

</w:p>

</w:tc>

</w:tr>

<w:tr>

<w:tc>

<w:tcPr>

<w:tcW w:w="9576"

w:type="dxa"/>

</w:tcPr>

<w:p/>

</w:tc>

</w:tr>

The following example shows the resulting XML when this revision is accepted. The second of the three rows is no longer present.

<w:tr>

<w:tc>

<w:tcPr>

<w:tcW w:w="9576"

w:type="dxa"/>

</w:tcPr>

<w:p/>

</w:tc>

</w:tr>

<w:tr>

<w:tc>

<w:tcPr>

<w:tcW w:w="9576"

w:type="dxa"/>

</w:tcPr>

<w:p/>

</w:tc>

</w:tr>

Move Source Paragraph (moveFrom Element)

This element specifies that the paragraph mark for the paragraph that contains this element is moved. In practical terms, it means that the contents of the paragraph that contains this element, and the contents of the following paragraph are combined to form a new paragraph. If more than one consecutive paragraph contains this element, then the paragraphs are grouped together, and the code produces a new paragraph that contains the content of all grouped paragraphs, plus the content of the paragraph following the last in the group. The paragraph properties come from the paragraph following the group.

Open XML Specification Location

Ecma-376 2.13.5.22

ISO/IEC 29500 17.13.5.22

Algorithm

The algorithm for this is identical to the processing of a paragraph that has a deleted paragraph mark.

Move Source Location Container—Start and End (moveFromRangeStart Element and moveFromRangeEnd Element)

These elements specify a region in the document where content was moved from this location to another.

Open XML Specification Location

Ecma-376 2.13.5.23, 2.13.5.24

ISO/IEC 29500 17.13.5.23, 17.13.5.24

Algorithm

Processing of this revision is somewhat similar to the w:customXmlDelRangeStart and w:customXmlDelRangeEnd elements. You must find all elements where both the start and end tag of the elements fall inside a matched pair of w:moveFromRangeStart and w:moveFromRangeEnd elements. A matched pair of elements requires that both the w:moveFromRangeStart and w:moveFromRangeEnd elements have matching w:id attributes. However, different from the w:customXmlDelRangeStart and w:customXmlDelRangeEnd elements, these ranges apply to all contained content, and instead of collapsing, as the w:customXmlDelRangeStart and w:customXmlDelRangeEnd elements require, contained content is removed.

There is one more complication when you process these elements. If the end tag of a paragraph (w:p) is inside a range, but the start tag of the paragraph is not, the paragraph mark is considered deleted. This aspect of processing these elements is handled in the same manner to processing of the w:del (Deleted Paragraph Mark) element.

Example

The following example shows revision tracking markup for content that was moved away from a specific location.

<w:p>

<w:r>

<w:t>Hello.</w:t>

</w:r>

</w:p>

<w:p>

<w:moveFromRangeStart w:id="2"

w:author="Eric White"

w:date="2009-09-13T16:42:00Z"

w:name="move240623472" />

<w:moveFrom w:id="3"

w:author="Eric White"

w:date="2009-09- 13T16:42:00Z">

<w:r>

<w:t>Goodbye.</w:t>

</w:r>

</w:moveFrom>

</w:p>

<w:moveFromRangeEnd w:id="2" />

<w:p />

The following example shows the resulting XML when this revision is accepted.

<w:p>

<w:r>

<w:t>Hello.</w:t>

</w:r>

</w:p>

<w:p />

Conclusion

Accepting tracked revisions is important to several Open XML scenarios. By accepting tracked revisions, we simplify the Open XML markup, and make additional processing of the markup easier. If we want to extract the content of a document for any purpose, accepting revisions first makes the job significantly easier. Another scenario is that we may want to write server-side code to ensure that a file share or a SharePoint document library does not contain any documents that have tracked changes.

Additional Resources

For more information about how to use Open XML to work with documents, see the following resources:

Developer Center: Open XML Formats Resource Center

Download: PowerTools for Open XML on CodePlex

Download: Open XML SDK 2.0 for Microsoft Office

Working with Numbering in Open XML WordprocessingML

EricWhite — Tue, 15 Dec 2009 22:44:00 GMT

[Blog Map]

Update Dec 21, 2009: This is the 8th in a series of posts on implementing a transform of WordprocessingML to XHtml.

1) Transforming Open XML Word-Processing Documents to XHtml

2) Transforming Open XML Word-Processing Documents to XHtml (Post #2)

3) Transforming Open XML Word-Processing Documents to Html (Post #3)

4) Open XML WordprocessingML Style Inheritance

5) Comparison of Html/CSS Tables to WordprocessingML Tables

6) Assembling Paragraph and Run Properties for Cells in an Open XML WordprocessingML Table

7) Implementing 'Inheritance' in XML

8) Working with Numbering in Open XML WordprocessingML

9) Accepting Revisions in Open XML WordprocessingML Documents

When implementing a conversion of Open XML word processing documents to HTML, one of the interesting issues is accurately converting numbered and bulleted lists. You must pay special attention to them, because they impact the text that the document contains, but that text isn't directly in the markup. If you are accurately extracting the text of the document, you must process some elements and attributes to assemble the correct text.

Numbered items and bulleted lists are not trivial, and justifiably so. There are a large number of features of numbered and bulleted lists, each used by a different set of users. These features are represented by elements in the markup. However, you don't need to pay attention to all elements. Some aspects of the markup are there just to affect the user interface, and you don't need to pay attention to those elements when determining the textual representation of a numbered or bulleted item. This post presents just the essentials that you need to know to work with numbered and bulleted items.

Note: This blog post is an MSDN article that I've written. It will be published on MSDN sometime in the near future. Thanks to Tristan Davis, Zeyad Rajabi, and Brian Hyams for tech reviewing this post.

The easiest way to talk about numbering markup is to relate the markup to the user interface of Word. You are concerned only with the document modifications that we can make with these three buttons:

There is a fair amount of indirection for WordprocessingML numbering markup. There are three patterns for this indirection in the markup:

Direct numbering for simple numbered or bulleted lists
Style based numbering, i.e. Heading1 is at the first level of indentation, Heading2 is at the second level of indentation, etc.
Named numbering styles

I'll examine each of these patterns in depth.

Markup for a Simple Numbered List

First, I'll show the markup that is generated if you create a simple numbered list:

So that I can discuss the markup accurately, I need to make an important distinction between two aspects of numbered or bulleted lists. For each numbered or bulleted item, there are two components – the list item, and the paragraph text:

We need to make this distinction because the list item is what we need to assemble for each paragraph. In addition, there is separate formatting markup for the list item. The same distinction applies to a numbered list:

The following diagram shows the indirection for a simple numbered or bulleted list:

I'll examine the markup for the following simple numbered list:

The markup in the main document part looks like this:

<w:p>

<w:pPr>

<w:pStyle w:val="ListParagraph"/>

<w:numPr>

<w:ilvl w:val="0"/>

<w:numId w:val="1"/>

</w:numPr>

</w:pPr>

<w:r>

<w:t>Paragraph one.</w:t>

</w:r>

</w:p>

The w:numPr element contains the numbering elements that we're concerned with. The w:ilvl element is a zero based number that indicates the indentation level. The numbered items are at the least indented level, so the value of w:ilvl is zero. The w:numId element is an index into the w:num elements, which is located in the numbering part.

Note: The w:numId can contain a value of 0, which is a special value that indicates that numbering has been removed at this level of the style hierarchy. While processing this markup, if the w:val='0', the paragraph doesn't have a list item.

The numbering part markup looks like this:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>

<w:numbering xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">

<w:abstractNum w:abstractNumId="0">

<w:nsid w:val="5FE17486"/>

<w:multiLevelType w:val="hybridMultilevel"/>

<w:tmpl w:val="1084E0BA"/>

<w:lvl w:ilvl="0"

w:tplc="0409000F">

<w:start w:val="1"/>

<w:numFmt w:val="decimal"/>

<w:lvlText w:val="%1."/>

<w:lvlJc w:val="left"/>

<w:pPr>

<w:ind w:left="720"

w:hanging="360"/>

</w:pPr>

</w:lvl>

<w:lvl w:ilvl="1"

w:tplc="04090019"

w:tentative="1">

<w:start w:val="1"/>

<w:numFmt w:val="lowerLetter"/>

<w:lvlText w:val="%2."/>

<w:lvlJc w:val="left"/>

<w:pPr>

<w:ind w:left="1440"

w:hanging="360"/>

</w:pPr>

</w:lvl>

</w:abstractNum>

<w:num w:numId="1">

<w:abstractNumId w:val="0"/>

</w:num>

</w:numbering>

The index in the w:numPr element in the main document part refers to the w:num element highlighted in yellow above. In this case, that element contains a single element, w:abstractNumId, which refers to the w:abstractNum element above it. The w:abstractNum element contains the information necessary to format the list item. Note that the w:abstractNum element does not contain formatting information for the paragraph (except for indentation information, with pertains to both the list item and the paragraph). Formatting for the paragraph itself is stored in the main document and styles part, as usual. There are three elements (w:nsid, w:multiLevelType, and w:tmpl) that only impact the user interface in the word processing application, and you can disregard them. From now on in this post, I will eliminate those elements from markup listings. The w:lvl elements and the w:lvl child elements define the formatting for each indentation level of the list items. There are additional w:lvl elements (removed from the listing) that define the formatting for list items for each level at level two and above. The w:tplc and w:tentative attributes of the w:lvl element are there for the user interface only. I'll remove them from further listings.

Note: the indirection from w:num to w:abstractNum allows for markup that overrides formatting of list items. I'll show this markup later.

The elements that you are really interested in are children of the w:lvl element – the w:start, w:numFmt, w:lvlText, and w:lvlJc elements, and the complex element w:pPr.

The w:start element specifies the starting number for the indentation level. Do you start counting at 0, 1, or some other number? Negative start numbers are not allowed (and are not very useful).

In this example, the w:numFmt element indicates that the document uses a decimal in the list item for indentation level 0, and that the document uses a lower case letter for indentation level 1. There are a fair number of options for this element:

Bullets
Decimal (1, 2, 3)
Decimal Zero (01, 02, 03)
Upper Roman (I, II, III)
Lower Roman (i, ii, iii)
Upper Letter (A, B, C)
Lower Letter (a, b, c)
Ordinal (1st, 2nd, 3rd)
Cardinal Text (One, Two Three)
Ordinal Text (First, Second, Third)

Note: There are other options for other languages that I've not included. Various Asian languages have numbering systems that are not included in this list. In the near future, I'll be posting code to assemble the list item text, and in that code, I am supporting only the above list. I've designed that code so that it is easily extended to include other numbering systems.

You use the w:lvlText element as a template to construct the list item. For level 0, this example uses "%1.", which indicates that whatever w:numFmt text was determined for the least indented item above replaces the %1 in the format string. For level 1, this example uses "%2.", which indicates that whatever text was determined for the first indentation replaces the %2. Note that for the w:lvl elements, you specify indentation level with a zero based index, whereas in the w:lvlText template, you specify replacement tokens using a one based index. This makes sense – the w:lvl elements are used only by developers, and zero based indexes are easier, whereas the template is used and specified by users, so a one based index makes sense. These two elements are pretty powerful, and allow you to put together hierarchical list formats to satisfy just about any need. I will show more examples of these two elements further on.

Note: For bulleted lists, even if the w:lvltext element contains replacement tokens (%1, %2, etc.), the replacement tokens are not replaced with the level number. This does not impact our code, because the w:lvlText element will not contain replacement tokens.

The w:lvlJc element controls whether the list items are right or left justified, as well as some other options. The following shows the difference between left and right justification for numbered items that use text. It is easy to see in this example, but is more difficult to notice when using bulleted lists or numbered lists that use digits.

Finally, there are paragraph properties that apply to the list item, most importantly here specifying the indentation and hanging indentation.

The w:lvl element can also contain run properties that apply to the list item. If you change the font of the list item to Courier, it would look like this:

Here is an example of the w:lvl element that contains run properties that define the font for the list item:

<w:lvl w:ilvl="0">

<w:start w:val="1"/>

<w:numFmt w:val="ordinalText"/>

<w:lvlText w:val="%1)"/>

<w:lvlJc w:val="left"/>

<w:pPr>

<w:ind w:left="720"

w:hanging="360"/>

</w:pPr>

<w:rPr>

<w:rFonts w:ascii="Courier New"

w:hAnsi="Courier New"

w:hint="default"/>

</w:rPr>

</w:lvl>

As usual, the paragraph in the main document part also contains a reference to a style:

<w:p>

<w:pPr>

<w:pStyle w:val="ListParagraph"/>

<w:numPr>

<w:ilvl w:val="0"/>

<w:numId w:val="1"/>

</w:numPr>

</w:pPr>

<w:r>

<w:t>One</w:t>

</w:r>

</w:p>

We can find that style in the styles part, which specifies the formatting for the paragraph text:

<w:style w:type="paragraph"

w:styleId="ListParagraph">

<w:name w:val="List Paragraph"/>

<w:basedOn w:val="Normal"/>

<w:pPr>

<w:ind w:left="720"/>

<w:contextualSpacing/>

</w:pPr>

</w:style>

This is the normal pattern for markup for styled paragraphs.

Markup for a Simple Bulleted List

Next, I'll show the markup that is generated if you create a simple bulleted list:

The markup indirection pattern for a simple bulleted list is the same as the pattern for a simple numbering list.

For the simple bulleted list, the main document part (document.xml) contains paragraphs that are identical to the simple numbered list:

<w:p>

<w:pPr>

<w:pStyle w:val="ListParagraph"/>

<w:numPr>

<w:ilvl w:val="0"/>

<w:numId w:val="1"/>

</w:numPr>

</w:pPr>

<w:r>

<w:t>One</w:t>

</w:r>

</w:p>

Here's what the numbering part looks like:

<w:abstractNum w:abstractNumId="0">

<w:lvl w:ilvl="0">

<w:start w:val="1"/>

<w:numFmt w:val="bullet"/>

<w:lvlText w:val=""/>

<w:lvlJc w:val="left"/>

<w:pPr>

<w:ind w:left="720"

w:hanging="360"/>

</w:pPr>

<w:rPr>

<w:rFonts w:ascii="Symbol"

w:hAnsi="Symbol"

w:hint="default"/>

</w:rPr>

</w:lvl>

<w:num w:numId="1">

<w:abstractNumId w:val="0"/>

</w:num>

</w:numbering>

The w:val attribute of the w:lvlText element here is saved as the character 0xB7, which is the bullet symbol for this level (from the Symbol font). The Visual Studio XML editor shows this character as a box in the courier font. The main point about this example is that you can write a generalized method to assemble text for the list item, and this method will work for both numbered and bulleted lists.

The w:start element doesn't have an effect on the list item because the w:lvlText template element doesn't contain a replacement token (%1, %2, etc.) But even if it did, we would not replace the token.

Markup for a Multi-Level List

You can see that this framework nicely allows for multi-level lists. You can change the source document to look like this:

The paragraphs in the main document part looks like this. The w:ilvl element for the second paragraph is set to "1".

<w:p>

<w:pPr>

<w:pStyle w:val="ListParagraph"/>

<w:numPr>

<w:ilvl w:val="0"/>

<w:numId w:val="1"/>

</w:numPr>

</w:pPr>

<w:r>

<w:t>One</w:t>

</w:r>

</w:p>

<w:p>

<w:pPr>

<w:pStyle w:val="ListParagraph"/>

<w:numPr>

<w:ilvl w:val="1"/>

<w:numId w:val="1"/>

</w:numPr>

</w:pPr>

<w:r>

<w:t>Two</w:t>

</w:r>

</w:p>

The numbering and style parts are not modified in this example.

Markup for Numbering that is Linked to Styles

There is a feature of numbering that makes it very convenient for users but makes the markup a little more involved. You can link a style to a numbering type and level, and then all paragraphs of that style are then represented with a list item. The canonical example is linking Heading1 style to the first level of indentation, Heading2 style to the second level, and so on. A document using this approach looks like this:

The markup indirection pattern for numbering that is linked to styles looks like this:

In this case, the main document part doesn't contain any markup related to numbering:

<w:p>

<w:pPr>

<w:pStyle w:val="Heading1"/>

</w:pPr>

<w:r>

<w:t>Overview of Numbering</w:t>

</w:r>

</w:p>

<w:p>

<w:pPr>

<w:pStyle w:val="Heading2"/>

</w:pPr>

<w:r>

<w:t>Markup of a Simple Numbered List</w:t>

</w:r>

</w:p>

The markup in the style part for the Heading1 style contains a reference to the w:num element in the numbering part:

<w:style w:type="paragraph"

w:styleId="Heading1">

<w:name w:val="heading 1"/>

<w:basedOn w:val="Normal"/>

<w:pPr>

<w:numPr>

<w:numId w:val="1"/>

</w:numPr>

<w:spacing w:before="480"

w:after="0"/>

<w:outlineLvl w:val="0"/>

</w:pPr>

<w:rPr>

<w:rFonts w:asciiTheme="majorHAnsi"

w:eastAsiaTheme="majorEastAsia"

w:hAnsiTheme="majorHAnsi"

w:cstheme="majorBidi"/>

<w:b/>

<w:bCs/>

<w:color w:val="365F91"

w:themeColor="accent1"

w:themeShade="BF"/>

<w:sz w:val="28"/>

<w:szCs w:val="28"/>

</w:rPr>

</w:style>

The numbering part looks like this:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>

<w:numbering xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">

<w:abstractNum w:abstractNumId="0">

<w:lvl w:ilvl="0">

<w:start w:val="1"/>

<w:numFmt w:val="decimal"/>

<w:pStyle w:val="Heading1"/>

<w:lvlText w:val="%1"/>

<w:lvlJc w:val="left"/>

<w:pPr>

<w:ind w:left="432"

w:hanging="432"/>

</w:pPr>

</w:lvl>

<w:lvl w:ilvl="1">

<w:start w:val="1"/>

<w:numFmt w:val="decimal"/>

<w:pStyle w:val="Heading2"/>

<w:lvlText w:val="%1.%2"/>

<w:lvlJc w:val="left"/>

<w:pPr>

<w:ind w:left="576"

w:hanging="576"/>

</w:pPr>

</w:lvl>

</w:abstractNum>

<w:num w:numId="1">

<w:abstractNumId w:val="0"/>

</w:num>

</w:numbering>

The w:pStyle element links back to the style in the style part. You determine the indentation level by finding the w:pStyle element that matches the style of the paragraph and looking at the parent w:lvl complex element. As usual, you assemble the text of the list item from the other child elements of the w:lvl element.

Overriding a Number Format in a Multi-Level List with a New Number Format

You can override the numbering format for any level in a multi-level list with a new number format, and this impacts the markup. To create this markup, first create a multi-level list:

Then select a paragraph, and define a new number format:

In the Define new Number Format dialog box, change some aspect. In this example, I changed Heading2 so that the list item is the cardinal number followed by a parenthesis: "One)".

The markup for the main document part now looks like this:

<w:p>

<w:pPr>

<w:pStyle w:val="Heading1"/>

</w:pPr>

<w:r>

<w:t>Paragraph One</w:t>

</w:r>

</w:p>

<w:p>

<w:pPr>

<w:pStyle w:val="Heading2"/>

<w:numPr>

<w:ilvl w:val="1"/>

<w:numId w:val="2"/>

</w:numPr>

</w:pPr>

<w:r>

<w:t>Paragraph Two</w:t>

</w:r>

</w:p>

<w:p>

<w:pPr>

<w:pStyle w:val="Heading3"/>

</w:pPr>

<w:r>

<w:t>Paragraph Three</w:t>

</w:r>

</w:p>

The markup in the numbering part now has two w:num elements, each pointing to their own abstract numbering format:

<w:num w:numId="1">

<w:abstractNumId w:val="1"/>

</w:num>

<w:num w:numId="2">

<w:abstractNumId w:val="0"/>

</w:num>

The abstract numbering markup can be then processed as usual. The main point here is when you format numbering using styles, the markup follows the indirection detailed in this section, but if a paragraph of that style contains a w:numPr element, this overrides the link from the abstract numbering format to the style.

Overriding a Number Format in a Multi-Level List, creating a new Multi-Level List Format

The user can override the numbering format for any level in a multi-level list, creating a new multi-level list format, and this impacts the markup. To create this markup, first create a multi-level list:

Then select a paragraph, and define a new multi-level list:

In the Define new Multilevel list dialog box, change some aspect of the list level. In my example, I changed the format so that list items at the second level of indentation use upper case alpha for the item marker.

The markup for the main document part contains a w:numPr element that overrides the link from the abstract numbering format to the style, in the same way as when creating a new number format:

<w:p>

<w:pPr>

<w:pStyle w:val="Heading1"/>

</w:pPr>

<w:r>

<w:t>Paragraph One</w:t>

</w:r>

</w:p>

<w:p>

<w:pPr>

<w:pStyle w:val="Heading2"/>

<w:numPr>

<w:ilvl w:val="1"/>

<w:numId w:val="3"/>

</w:numPr>

</w:pPr>

<w:r>

<w:t>Paragraph Two</w:t>

</w:r>

</w:p>

<w:p>

<w:pPr>

<w:pStyle w:val="Heading3"/>

</w:pPr>

<w:r>

<w:t>Paragraph Three</w:t>

</w:r>

</w:p>

The w:numPr element in the paragraph properties overrides the link between the abstract numbering format and the Heading2 style. The numbering part now contains a new w:num element that defines w:lvlOverride elements:

<w:num w:numId="1">

<w:abstractNumId w:val="0"/>

</w:num>

<w:num w:numId="2">

<w:abstractNumId w:val="1"/>

</w:num>

<w:num w:numId="3">

<w:abstractNumId w:val="0"/>

<w:lvlOverride w:ilvl="0">

<w:lvl w:ilvl="0">

<w:start w:val="1"/>

<w:numFmt w:val="decimal"/>

<w:pStyle w:val="Heading1"/>

<w:lvlText w:val="%1"/>

<w:lvlJc w:val="left"/>

<w:pPr>

<w:ind w:left="432"

w:hanging="432"/>

</w:pPr>

<w:rPr>

<w:rFonts w:hint="default"/>

</w:rPr>

</w:lvl>

</w:lvlOverride>

<w:lvlOverride w:ilvl="1">

<w:lvl w:ilvl="1">

<w:start w:val="1"/>

<w:numFmt w:val="upperLetter"/>

<w:pStyle w:val="Heading2"/>

<w:lvlText w:val="%1.%2"/>

<w:lvlJc w:val="left"/>

<w:pPr>

<w:ind w:left="576"

w:hanging="576"/>

</w:pPr>

<w:rPr>

<w:rFonts w:hint="default"/>

</w:rPr>

</w:lvl>

</w:lvlOverride>

. . .

Two of the w:num elements now refer to the same abstract numbering format, but the second one now overrides the list item formatting. You can see that the level override for level 1 now specifies that the value for the w:numFmt element is "upperLetter".

The w:startOverride Element

The w:lvlOverride element can contain a child w:startOverride element:

<w:num w:numId="2">

<w:abstractNumId w:val="2"/>

<w:lvlOverride w:ilvl="0">

<w:startOverride w:val="5"/>

</w:lvlOverride>

<w:lvlOverride w:ilvl="1">

<w:startOverride w:val="1"/>

</w:lvlOverride>

. . .

</w:num>

The w:startOverride element causes the starting number of the indent level to be the value specified. This is sometimes used when the user specifically sets this value in the user interface to force counting to start from a specific number. This is one way that markup forms a document that skips an number in a numbered list:

There is another way that markup can specify a starting number. I'll show this markup this shortly.

Defining a new List Style

One option in Word is that you can define a new named list style, and then use that style elsewhere in the document. This is a quick and easy way to implement your own customized numbering format. To do this, select the text to number, and pick "Define New List Style" from the Multi-level List drop down:

This brings up the Define New List Style dialog box.

After filling out this dialog, the selected paragraphs will have the numbering format that you specify. You can then further apply this same style in other locations in the document. Using this feature impacts the markup.

Here is the indirection when using this pattern:

The document part looks the same as when applying other forms of numbering:

<w:p>

<w:pPr>

<w:pStyle w:val="ListParagraph"/>

<w:numPr>

<w:ilvl w:val="0"/>

<w:numId w:val="2"/>

</w:numPr>

</w:pPr>

<w:r>

<w:t>1</w:t>

</w:r>

</w:p>

We can find the referenced w:num element in the numbering part:

<w:num w:numId="2">

<w:abstractNumId w:val="0"/>

</w:num>

But if we look at the abstract numbering element, it looks quite different. It doesn't contain child w:lvl elements, and uses the w:numStyleLink element to refer to the style that I defined in the dialog box.

<w:abstractNum w:abstractNumId="0">

<w:nsid w:val="03916EF0"/>

<w:multiLevelType w:val="multilevel"/>

<w:tmpl w:val="0409001D"/>

<w:numStyleLink w:val="EricsListStyle"/>

</w:abstractNum>

In the styles part, you can find the newly defined style, which then refers back to a w:num element in the numbering part:

<w:style w:type="numbering"

w:customStyle="1"

w:styleId="EricsListStyle">

<w:name w:val="EricsListStyle"/>

<w:uiPriority w:val="99"/>

<w:rsid w:val="00B1427D"/>

<w:pPr>

<w:numPr>

<w:numId w:val="1"/>

</w:numPr>

</w:pPr>

</w:style>

The w:num element in the numbering part looks like this:

<w:num w:numId="1">

<w:abstractNumId w:val="1"/>

</w:num>

This refers to a w:abstractNum element, which contains the level formats, as usual:

<w:abstractNum w:abstractNumId="1">

<w:nsid w:val="2D235466"/>

<w:multiLevelType w:val="multilevel"/>

<w:tmpl w:val="0409001D"/>

<w:styleLink w:val="EricsListStyle"/>

<w:lvl w:ilvl="0">

<w:start w:val="1"/>

<w:numFmt w:val="decimal"/>

<w:lvlText w:val="%1)"/>

<w:lvlJc w:val="left"/>

<w:pPr>

<w:ind w:left="360"

w:hanging="360"/>

</w:pPr>

</w:lvl>

<w:lvl w:ilvl="1">

<w:start w:val="1"/>

<w:numFmt w:val="lowerLetter"/>

<w:lvlText w:val="%2)"/>

<w:lvlJc w:val="left"/>

<w:pPr>

<w:ind w:left="720"

w:hanging="360"/>

</w:pPr>

</w:lvl>

. . .

This is a fair amount of indirection, but using LINQ to XML, it results in only a few statements to follow this indirection.

Alternatives for the List Item Suffix

The list suffix is the white space content between the list item and the paragraph. There are only two possible values – tab and space. We can alter a list definition to use a space for the list item suffix instead of a tab:

The markup uses the w:suff element to specify this:

<w:abstractNum w:abstractNumId="0">

<w:nsid w:val="21E167DA"/>

<w:multiLevelType w:val="multilevel"/>

<w:tmpl w:val="5BE82C98"/>

<w:lvl w:ilvl="0">

<w:start w:val="1"/>

<w:numFmt w:val="decimal"/>

<w:pStyle w:val="Heading1"/>

<w:suff w:val="space"/>

<w:lvlText w:val="%1"/>

<w:lvlJc w:val="left"/>

<w:pPr>

<w:ind w:left="432"

w:hanging="432"/>

</w:pPr>

<w:rPr>

<w:rFonts w:hint="default"/>

</w:rPr>

</w:lvl>

The w:lvlRestart Element

The w:lvlRestart element allows the markup to control when a particular level restarts counting. In the following example, the level four list item starts recounting when there is an intervening level one item:

The markup (for the above example) for the w:lvl element where the w:ilvl attribute is equal to "3" looks like this:

<w:abstractNum w:abstractNumId="0">

<w:nsid w:val="065A6A4E"/>

<w:multiLevelType w:val="multilevel"/>

<w:tmpl w:val="06A2CF44"/>

<w:lvl w:ilvl="3">

<w:start w:val="1"/>

<w:numFmt w:val="decimal"/>

<w:lvlRestart w:val="1"/>

<w:lvlText w:val="%1.%2.%3.%4."/>

<w:lvlJc w:val="left"/>

<w:pPr>

<w:ind w:left="1728"

w:hanging="648"/>

</w:pPr>

<w:rPr>

<w:rFonts w:hint="default"/>

</w:rPr>

</w:lvl>

The w:isLgl Element

The w:isLgl element changes the textual representation of a list item so that it uses digits for all levels instead of the specified number format for that level, but only when formatting text for a given indentation level. Consider the following document, where items at the third indentation level use legal numbering:

If this list didn't use legal numbering for the third level of indentation, it would look like this:

The markup for w:isLgl looks like this:

<w:abstractNum w:abstractNumId="0">

. . .

<w:lvl w:ilvl="2">

<w:start w:val="1"/>

<w:numFmt w:val="decimal"/>

<w:pStyle w:val="Heading3"/>

<w:isLgl/>

<w:lvlText w:val="%1.%2.%3)"/>

<w:lvlJc w:val="left"/>

<w:pPr>

<w:ind w:left="720"

w:hanging="720"/>

</w:pPr>

<w:rPr>

<w:rFonts w:hint="default"/>

</w:rPr>

</w:lvl>

Algorithm to Assemble List Item Text

The key aspects for assembling list item text is to determine:

The w:lvl formatting for the paragraph
The indentation level of the paragraph
The number for each parent level of indentation for the paragraph. For example, if a paragraph is at the 4th indentation level, you need to determine the level numbers of the 1st, 2nd, 3rd, and 4th levels associated with that paragraph.

Once you have these three items, it is a simple text formatting exercise to assemble the list item text.

A paragraph may contain numbering properties that contain a w:ilvl and w:numId element.

<w:p>

<w:pPr>

<w:pStyle w:val="ListParagraph"/>

<w:numPr>

<w:ilvl w:val="0"/>

<w:numId w:val="1"/>

</w:numPr>

</w:pPr>

<w:r>

<w:t>Paragraph one.</w:t>

</w:r>

</w:p>

In this case, you use the w:ilvl specified for the indentation level. You go to the numbering part, and look up the w:num element. If there is a w:lvlOverride element that contains a w:lvl element, then that w:lvl element applies. If there is no w:lvlOverride element, or if the w:lvlOverride element doesn’t contain a w:lvl element for the indentation level, then find the associated w:abstractNum element, and use the w:lvl formatting specified in the w:abstractNum. If the w:num element contains a w:lvlOverride element, you use the w:lvl specified for the indentation level in the override.

If the paragraph does not contain a w:numPr complex element, then if the style of the paragraph contains a w:numPr element, there is an abstract numbering element that refers to the style. We use the w:lvl that refers to the style. This also gives us the indentation level.

Once we've determined the w:lvl formatting element, and the indentation level, we can determine the list number for each level. You need to count the paragraphs at the same level before the current paragraph, paying attention to the w:lvlRestart element and the w:start element. This is where functional programming will shine – I can build a stateless expression to calculate the item number for each indentation level. This may not be the most efficient way to do this – it may use more CPU processing than another approach, but it will be easy to debug, and probably fast enough for most scenarios. In my informal testing on my slowest machine, it is still basically instantaneous.

Once you have the appropriate w:lvl element and the list of item numbers for each level of indentation, it is a simple text assembly process to put together the list item text.

This may seem like a lot of logic to assemble the list item text, but it is less than 400 lines of code when properly factored and implemented using LINQ to XML.