Runs

The next level of the document hierarchy is the run, which defines a region of text with a common set of properties, represented by the @r element. An <r >element allows the producer to combine breaks, styles, or formatting properties, applying the same information to all the parts of the run.

Just as a paragraph can have properties, so too can a run. All of the elements inside an <r >element have their properties controlled by a corresponding optional <rPr >run properties element, which must be the first child of the <r >element. In turn, the <rPr >element is a container for a set of property elements that are applied to the rest of the children of the <r> element. The elements inside the <rPr >container element allow the consumer to control whether the text in the following <t >elements is bold, underlined, or visible, for example. Some examples of run properties are bold, border, character style, color, font, font size, italic, kerning, disable spelling/grammar check, shading, small caps, strikethrough, text direction, and underline.

Consider the following run within a WordprocessingML document:

<w:r>
  <w:rPr>
    <w:b/>
    <w:i/>
  </w:rPr>
  <w:t>quick</w:t>
</w:r>

The run specifies two formatting properties in its run contents: bold and italic. These properties are therefore applied to all content within this run.

A producer can break a run into an arbitrary number of smaller runs, provided each smaller run uses the same set of properties, without changing the content of the document.

Consider the content "only one word is emphasized" in a WordprocessingML document. An efficient producer could choose to output this content using two runs, as follows:

<w:r>
  <w:t xml:space="preserve">only one word is </w:t>
</w:r>
<w:r>
  <w:rPr>
    <w:i/>
  <w:rPr>
  <w:t>emphasized</w:t>
</w:r>

However, a less efficient producer might use four runs, as follows:

<w:r>
  <w:t>only one</w:t>
</w:r>
<w:r>
  <w:t xml:space="preserve"> word is </w:t>
</w:r>
<w:r>
  <w:rPr>
    <w:i/>
  <w:rPr>
  <w:t>empha</w:t>
</w:r>
<w:r>
  <w:rPr>
    <w:i/>
  <w:rPr>
  <w:t>sized</w:t>
</w:r>

Although the latter example uses four runs rather than two, the net run information applied to each region of text is identical, and both are equally valid.

Of course, a run might need to be broken. For example, the properties of only some the text in that run are changed, requiring the changed part to be put into its own run. Another example involves the insertion of some sort of marker into the middle of an existing run. That requires the run be broken into two with the marker inserted between them.

The following run contains two sentences:

<w:r>
  <w:t>Hello, world. How are you, today?</w:t>
</w:r>

If the first two words are bolded in these sentences, the run will need to be broken into two runs in order to store the formatting, as follows:

<w:r>
  <w:rPr>
    <w:b/>
  </w:rPr>
  <w:t xml:space="preserve">Hello, world. </w:t>
</w:r>
<w:r>
  <w:t>How are you, today?</w:t>
</w:r>

Apart from text, a run can also contain numerous kinds of textual content (§2.4.3) A run can also contain a set of revision IDs used for document "merge and compare".