RTF Exporter Specification

Christian Roth

C.R.

Revision History
Revision 1Fri, 16 Sep 2016 12:55:00 CEST

1. Overview
2. Source XML format
1. Grammar: The upCast DTD
2. Including a CSS stylesheet
3. The part element
4. Sections and headings
5. Special Unicode characters
3. Stylesheet contents
1. @charset declaration
2. Selectors
3. Paragraph and Character styles
4. @media rules
4. Styling details
1. Specifying page sizes
2. Footnote and Endnotes
2.1. Numbering and positioning
2.2. Footnote markup samples
3. Lists
3.1. List marker contents
3.2. Automatic numbering
3.3. List metrics
3.4. List properties
3.5. Examples
3.6. Using paragraph styles for list layout
4. Headings
4.1. Outline level
4.2. Automatic heading numbering
4.3. The little Heading-How-To
5. Generated text (Word Fields)
6. Table of Contents
7. Tabulators
8. Tables
8.1. Table width
8.2. Column widths
8.3. Table layout
8.4. Table positioning
8.5. Cell properties
9. Page Headers and Footers
10. References
11. Hyperlinks
12. Images
12.1. Positioning
12.2. Size and scaling
13. Hyphenation control
5. CSS Property Reference
1. ilx-additive
2. ilx-alt-text
3. ilx-annotation-marker
4. background-color
5. ilx-baseline-shift
6. border-bottom-color
7. border-bottom-style
8. border-bottom-width
9. border-left-color
10. border-left-style
11. border-left-width
12. border-right-color
13. border-right-style
14. border-right-width
15. border-top-color
16. border-top-style
17. border-top-width
18. bottom
19. color
20. ilx-column-count
21. ilx-column-gap
22. ilx-column-rule
23. ilx-column-width
24. ilx-content-rotation
25. ilx-default-tab-size
26. direction
27. display
28. display-align
29. ilx-editing-rights
30. ilx-endnote-numbering-policy
31. ilx-endnote-numbering-start
32. ilx-endnote-position
33. ilx-endnote-style-type
34. ilx-facing-pages
35. float
36. ilx-following-style
37. font-family
38. ilx-font-family-default
39. ilx-font-family-generic
40. font-size
41. font-style
42. font-variant
43. font-weight
44. ilx-footer-offset
45. ilx-footnote-numbering-policy
46. ilx-footnote-numbering-start
47. ilx-footnote-position
48. ilx-footnote-style-type
49. ilx-gutter
50. ilx-header-offset
51. height
52. ilx-horizontal-alignment
53. ilx-image-source
54. ilx-inline-class
55. left
56. letter-spacing
57. line-height
58. ilx-line-numbering-distance
59. ilx-line-numbering-interval
60. ilx-line-numbering-mode
61. ilx-line-numbering-start
62. ilx-line-numbering-state
63. line-stacking-strategy
64. ilx-list-group
65. ilx-list-level
66. ilx-list-numbering-absolute
67. ilx-list-numbering-restart
68. list-style-position
69. ilx-list-style-reference
70. list-style-type
71. margin-bottom
72. margin-left
73. margin-right
74. margin-top
75. ilx-marker-align
76. ilx-marker-color
77. ilx-marker-follow
78. ilx-marker-font-family
79. ilx-marker-font-size
80. ilx-marker-format
81. ilx-marker-offset
82. max-height
83. max-width
84. min-height
85. min-width
86. ilx-mirror-margins
87. ilx-note-marker
88. orphans
89. ilx-outline-level
90. padding-bottom
91. padding-left
92. padding-right
93. padding-top
94. page
95. page-break-after
96. page-break-before
97. page-break-inside
98. ilx-page-numbering-mode
99. ilx-page-numbering-start
100. ilx-page-numbering-style
101. ilx-page-padding-calculation-ref
102. ilx-paper-orientation
103. ilx-paragraph-class
104. position
105. ilx-position-reference-horizontal
106. ilx-position-reference-vertical
107. ilx-reference-presentation-type
108. right
109. ilx-style-display
110. ilx-style-update
111. ilx-tab-stops
112. table-layout
113. text-align
114. text-decoration
115. text-indent
116. text-line-through-style
117. text-transform
118. text-underline-color
119. text-underline-mode
120. text-underline-style
121. ilx-text-visibility
122. top
123. vertical-align
124. ilx-vertical-alignment
125. widows
126. width
127. ilx-word-base-style
128. word-break-inside
129. ilx-word-list-type
130. ilx-word-style-id
131. ilx-wrap-distance-horizontal
132. ilx-wrap-distance-vertical
133. ilx-xml-lang
134. z-index

Chapter 1. Overview

The RTF Exporter is an upCast module that converts XML documents to Word or, more precisely, RTF documents. For specifying the layout, the application relies on a subset of Cascading Style Sheets, level 2 and 3 (CSS2, CSS3) properties, amended by some proprietary properties where needed. Input XML documents must either be valid according to the upCast DTD, or they can be any arbitrary XML language for which a transformation into the upCast DTD can (and needs to) be created.

Main features of the RTF Exporter's XML to RTF conversion are:

  • creates fully editable Word documents conforming to the RTF 1.7 specification (Word 2000 and later; Word 97 may work)

  • uses native structuring RTF constructs wherever possible

  • supports paragraph and character styles

  • offers powerful table translation, incl. nested tables, row/column spans, cell and table formatting properties

  • processes footnotes, hyperlinks and references (XLink), fields, annotations, index entries, bookmarks, page headers and footers

  • supports any combination of nested lists, tables and layout elements

  • support for standard and custom document properties

  • Unicode and two-byte encoding support

  • on-the-fly creation of style table, list table and intelligent font handling using extensible default properties for standard fonts

  • supports inline style information via the style attribute on elements

Chapter 2. Source XML format

1. Grammar: The upCast DTD

The RTF Exporter accepts only documents for input that conform to the upCast DTD as introduced and used in upCast Version 5.

Important

Do not confuse the upCast DTD with the upCast Internal Schema as created by the RTF Importer module! These two formats are different, and in this release, you cannot (yet, unfortunately…) use the upCast Internal Schema as an input format for the RTF Exporter.

Basically, this DTD consists of all essential structural and also layout features that can be expressed in RTF. This means that when you cannot transform your custom DTD by some means to the upCast DTD, you won't be able to render your document contents in Word, anyway. In this sense, the upCast DTD and being able to express your documents therein can be regarded as a check of your XML documents for Word compatibility/expressibility.

What does this actually mean for you? There are two facts which are important:

  • When you cannot find a way to convert your specific DTD to the upCast DTD, you won't be able to publish your document with Word. This is because – as said above – the upCast DTD reflects the implicit DTD that's behind the RTF specification and therefore the Word document model.

  • When you can find a way to convert your DTD back and forth to the upCast DTD without loss of information, roundtrip editing of your XML document using Word is possible. For the conversion back from Word to XML, you may want to have a look at the Word to XML (upCast DTD) template supplied with upCast, which generates XML files including CSS that follow the upCast DTD.

You can download a copy of the upCast DTD from http://www.infinity-loop.de/DTD/upcast/5.0/upcast.dtd, which contains inline documentation that should help you enough to create any necessary transformation processing sheets.

To have downCast automatically validate your document during import, you may want to include a DOCTYPE declaration at the top of your XML document:

<!DOCTYPE document 
    PUBLIC "-//infinity-loop//DTD upCast 5.0//EN" 
    "http://www.infinity-loop.de/DTD/upcast/5.0/upcast.dtd">

2. Including a CSS stylesheet

For downCast to be able to generate a RTF document, you must supply a stylesheet that follows CSS syntax. To do this, you should include a stylesheet Processing Instruction in your document before the root element:

<?xml-stylesheet type="text/css" href="myStyleSheet.css"?>

downCast will then read the stylesheet myStyleSheet.css and use it for processing the XML source file.

3. The part element

Note

The part element is the counterpart of Word's sections.

The part element, as well as the partbreak element, are the anchor point for setting page size, footnote and endnote counting and positioning, and line numbering properties. All of these can potentially change throughout the document at part boundaries.

A part is always child of document. When you are using the part element, the contained substructures must be well-formed. Though this is often the case structurewise, there are situations where you need to change e.g. page orientation within, say, a subsection to place a wide table on a landscape page, but then continue in portrait paper format. For these instances, you must use the partbreak element, which (like e.g. pagebreak) is an empty element and therefore can be placed almost anywhere in the body content of the document.

4. Sections and headings

Within a part, you (may) have a nested structure of sections that structure your document in chapters, sections, subsections etc. The nesting level is restricted by RTF to nine levels.

Each section may be immediately followed by a heading element containing the heading for that section. A heading is just a par element with special semantics.

Within a section, you place the actual contents, where the last block level element in the downward hierarchy is a par element indicating a paragraph of text. Within a par element, only inline level elements (or elements that are rendered out-of-flow, like footnotes, annotations or textboxes) are allowed.

5. Special Unicode characters

The RTF Exporter translates certain Unicode characters into their special RTF equivalents (instead of writing them as plain Unicode to the RTF file). Here's the list of characters (and their RTF equivalents) that are handled this way:

Unicode codepoint

RTF output

Comments

U+000A (LINE FEED(LF))
U+2028 (LINE SEPARATOR)

\line

forced, manual linebreak within a paragraph

U+2011 (NON-BREAKING HYPHEN)

\_

non-breaking hyphen

U+00AD (SOFT HYPHEN)

\-

optional hyphen

U+0009 (CHARACTER TABULATION)

\tab

tabulator character

U+200C (ZERO WIDTH NON-JOINER)

\zwnj

zero-width non-joiner

U+200D (ZERO WIDTH JOINER)

\zwj

zero-width joiner

U+200E (LEFT-TO-RIGHT MARK)

\ltrmark

ltr mark

U+200F (RIGHT-TO-LEFT MARK)

\rtlmark

rtl mark

Chapter 3. Stylesheet contents

This section describes details on what a downCast stylesheet should contain and how it is processed by the application. The following items are the minimal set of elements a stylesheet must contain:

  • a @charset declaration, describing the character set used for the contents of the stylesheet; this should be UTF-8

  • an @page rule, defining the document page layout (including margins, gutter, and whether the document uses two-side printing)

  • a complete style definition for the paragraph style with a class value of Normal

  • a complete style definition for the inline style with a class value of Default Paragraph Font

Important

Due to specifics and compatibility reasons with existing CSS aware applications, you cannot use the space character (0x20) in CSS class names, though RTF does allow and actually use these for several of its standard style names. Therefore, you need to replace them by a non-breaking space character (0xa0 hex, "\a0 " in CSS escape sequence notation). Non-breaking spaces are converted to normal space characters automatically when rendering the RTF by downCast.

Some of these components will be detailed on in the following.

1. @charset declaration

downCast supports the @charset at-rule for specifying the encoding of a stylesheet. For compatibility reasons, we recommend specifying UTF-8 as the encoding, but making sure you only use plain ASCII characters in the contents and use the CSS escaping mechanism ('\' [0-9A-Fa-f]{1,6} ' ') for all characters with a Unicode code point higher than 127.

Specify the @charset rule as the very first item in a CSS file:

@charset "UTF-8";
/* remaining stylesheet contents... */

2. Selectors

downCast does only support a very limited set of CSS selectors, specifically:

  • Universal Selector

  • Type selector

  • Attribute selector (with exception of '|=' )

  • Class selector

  • ID selector

No pseudo classes or pseudo elements are supported.

3. Paragraph and Character styles

RTF has the concept of Paragraph Styles and Character Styles. These are supported by downCast in the following way:

  • From a CSS rule with a selector only based on the class attribute and a value for the display property of inline, downCast will create a character style in the resulting RTF document with the value of the class attribute as the style name.

  • From a CSS rule with a selector only based on the class attribute and a value for the display property of block, downCast will create a paragraph style in the resulting RTF document with the value of the class attribute as the style name.

Important

Any non-breaking space characters in the value will be replaced by normal spaces.

This character translation is necessary to allow for style names that contain spaces. If you wrote

<par class="first paragraph">...</par>

, the contents of the class attribute would be interpreted as a list of values { first, paragraph } according to the XML specification. To have the two parts treated as a single token, you need to use a different character than the normal space, and the RTF exporter uses the non-breaking space (&nbsp;) for this. Any non-breaking space in a style name will be converted to a normal space at the time of writing the resulting RTF file.

To get the equivalent of assigning a character or paragraph style to an element in an application like Word, you need to set the class attribute of the respective element in the XML document to the corresponding selector value of the desired style rule in the CSS.

downCast automatically generates correct style table entries and code to link the RTF document contents to that style definition.

Note

RTF does not support nested, named character styles, only one specific character style can be active at any position in the document (together with exactly one paragraph style). A construct like

<inline class="emph">use <inline class="tag">part</inline> elements</inline>

will be treated in RTF as if it was written like

<inline class="emph">use </inline><inline class="tag">part</inline><inline class="emph"> elements</inline>

4. @media rules

downCast supports the use of @media rules, that is sets of specific rules that the stylesheet author only intends to be used for certain kinds of output media like display in a browser on screen compared to printed output on paper.

downCast respects all rules without any specific media kind specified as well as @media print. This allows you to author a single stylesheet for optimized output depending on the output medium by specifying rule variations in different @media blocks.

Also supported is the media dependant @import of external stylesheets.

Chapter 4. Styling details

This chapter gives you details on how to best style certain elements like lists, tables or images. Some styling requirements for creating an easily editable Word document are to some extent special and differ a little from how you would apply styling for rendering in a web browser. This is why we encourage you to read the following sections carefully before creating style rules for those particular elements.

1. Specifying page sizes

Paper and page sizes are specified using the CSS2 @page rules. The size property specifies the actual paper sheet size, and with the margin-… properties, you define the margins inward from the paper size. You can use the pseudo-classes :first, :left and :right to specify different margin setups for the first page, all left pages and all right pages respectively of the contents of a part.

Important

For two-sided layouts using :left and :right pseudo-classes, there are significant limitations in translating freely defined page sizes and margins to actual RTF supported parameter settings. RTF defines two-sided layouts using the following two mechanisms (either of them or both combined):

mirrored margins

When this is set, the margins of the left side are specified as mirroring left and right margins of the right side specification

gutter

This is additional margin added at the inner sides of both left and right pages

Although the RTF exporter allows you to freely define page dimensions for :left and :right, internally it has to fit the given dimensions into the RTF model described above. It does this by searching for the combination of available RTF parameter settings that result in the best approximation of the given dimensions.

The conclusions for you are:

  1. Make sure the size property is specified identically for :left, :right and :first pages. RTF does not support different paper sizes for these pseudo-classes.

  2. When you think in the RTF dimensions model and e.g. specify mirrored margin-left and margin-right properties for :left and :right pseudo-classes, you are much more likely to get those dimensions also exactly in the final RTF since the RTF exporter will detect that the given values can be expressed in the RTF model without error.

Example 4.1. 

@page mainmatter { 
  size: 210.0mm 297.0mm; /* = A4 */
  margin-top: 25.0mm;
  margin-bottom: 20.0mm;
  margin-left: 25.0mm;
  margin-right: 25.0mm;
}

specifies a named page layout with a paper size of A4 and with margins as specified at the respective sides. To refer to this page layout on a part in the XML document instance, you would use a style attribute as follows:

<part style="page: mainmatter;">
  ...
</part>

2. Footnote and Endnotes

2.1.  Numbering and positioning

Word allows specifying numbering schemes for footnotes, endnotes and annotations per part. The RTF exporter supports this capability by a set of custom properties.

For footnotes:

For endnotes:

These properties should be defined directly on the respective part, either via a Class selector, ID selector or a local style override in the style attribute.

2.2. Footnote markup samples

You can create footnotes with automatic numbering in two ways, depending on whether you want to control styling and following text (e.g. a space) of the marker in a more refined way:

<par>Autonumber FN<inline class="footnote reference"><gentext type="upcast-NOTENUMBER">1</gentext><footnote style="\-ilx-note-marker: suppress;"><par><inline class="footnote reference"><gentext type="upcast-NOTENUMBER">1</gentext></inline> Autonumber FN</par></footnote></inline></par>

or want the RTF Exporter handle all this:

<par>Autonumber FN2<footnote><par>Autonumber FN2</par></footnote></par>

To create a footnote with a custom marker string, use:

<par>custom marker FN<inline class="footnote reference">A<footnote style="\-ilx-note-marker: suppress;"><par><inline class="footnote reference">ABC</inline> custom marker FN</par></footnote>BC</inline></par>

Important

You must make sure that the footnote element is placed exactly after the first character of the custom marker text (if that consists of more than one character as in the example above, "ABC"). Otherwise, Word will not correctly recognize and handle that marker text in further editing operations.

3. Lists

Lists in Word (beside tables) are an element whose styling properties differ quite a bit from usual CSS styling. This comes from the fact that in CSS, calculating counter values used in the list markers is done in a procedural manner, although the specification of it is still declarative. Unfortunately, the layout properties and layout model of RTF lists and CSS list styling differs quite a bit. This is why we needed to introduce several custom properties to create real, editable lists in RTF. "Real" here means that they stay editable and will continue to auto-number themselves as expected when e.g. inserting an item into a list directly in Word.

3.1. List marker contents

The RTF exporter does not support the procedural counter() and counters() functions from CSS2. Styling of list markers is done in a purely declarative way using so-called template strings for specifying the list marker format. The corresponding property is -ilx-marker-format. For its value, it takes a template string that may contain placeholders for the current list level number.

Example 4.2. 

To format a list marker as 1. a), 1. b) and so on, you would define the marker format for the lists as follows:

<list style="list-style-type: decimal; \-ilx-marker-format: &quot;%0.&quot;">
  ...
  <list style="list-style-type: lower-alpha; \-ilx-marker-format: &quot;%0. %1)&quot;">
    ...
  </list>
</list>

In the marker format template strings, a character combination of %digit is replaced by the current numbering of the list at level digit.

The special sequence %c can be used as a convenience to indicate the numbering of the current list level.

So, the first list will be numbered 1., 2. etc, and the nested list will first take the current numbering of the outermost list, followed by a period and a space, and then by the numbering of the first nested list (which is itself), followed by a closing bracket. The percent sign % is the escape character for the following digit (0 .. 8) or character (c). If you want to have the percent sign be a part of the marker string itself, you need to quote it by doubling it: %% .


The marker's position relative to the left border of the list item, is specified using the -ilx-marker-offset property.

There are several styling properties for the list marker text, -ilx-marker-font-family to set the font for the marker, -ilx-marker-font-size to set its size, -ilx-marker-color to set its text color.

Finally, you must specify using the -ilx-marker-follow property which character should be appended to the marker string: a space character, a tab character or nothing. When you outdent the marker, the RTF Exporter automatically places a left-aligned tab at position 0 in that paragraph, so that you should specify tab whenever you outdent the list marker (which will be most often the case). When the marker is placed inside, however, then space will probably the best value to use.

3.2. Automatic numbering

RTF's list concept is based on the notion of list ids. Each list can have up to 9 nested levels of counting, and is assigned a unique list id. For each unique list id, Word keeps a set of 9 running counters (for each level in that list id) that are valid throughout the document. Each occurrence of a list item, which is a combination of { list id, level }, increments the respective Word-internal counter variable by one after creating the marker string (unless the list-style-type for that item is 'none').

The RTF exporter tries to satisfy this RTF list model by translating XML structures automatically into the required RTF model. By default, each new top-level list element creates a new list id. However, sometimes you may want to have a single running list throughout the document (like for heading numbering) with arbitrary content in-between, and you do not want to have to put all of this into one big list structure. This is why we offer to explicitly set the list id using a custom-property as well: -ilx-list-group.

Another point to remember is that Word seems to have an undocumented limit of number of list ids it can handle properly. This means when there are more than about 250 top-level lists within a single document, Word's automatic numbering feature seems to get confused and generates arbitrarily wrong list marker strings. It therefore may be necessary to reduce the number of individual list ids used in a document. For example, all types of non-numbered lists (bulleted, dashed etc.) could be assigned just one single list id, since the user cannot determine a visual difference between the marker display of the third and say, eighth bullet. We essentially use one continuously numbered, single list throughout the document for lists whose marker displays do not change or increment.

3.3. List metrics

Of interest is the placement of the marker and whether the list items should be indented (compared to surrounding content) or not.

Note

Inline list rendering is not supported.

Here's an overview of how positioning properties work:

List positioning properties

The property -ilx-marker-offset takes precedence over list-style-position, when specified.

Tip

When you want to have a list numbering outside the list items, but the numbering flush with the left edge of surrounding content, make sure that

  1. margin-left = –(-ilx-marker-offset)

  2. margin-left is big enough to have space for the longest marker text to expect

  3. -ilx-marker-align is left

  4. -ilx-marker-follow is tab

3.4. List properties

Let's now have a look at what properties you should set on lists for optimal RTF generation.

The basic XML structure of a list is as follows:

<list>
  <item>...</item>
  <item>
    ...
    <list>
      <item>...</item>
    </list>
  </item>
  ...
</list>

In this structure, on the list element you can specify in its style attribute the following properties.

Recommended properties are:

  • Use the list-style-type property to determine how the counter of this list level should be formatted within the final marker string.

  • Set any positioning and indenting properties, most probably margin-left, -ilx-marker-offset and -ilx-marker-align.

  • Set the marker formatting template string in -ilx-marker-format when either you need to include higher-level list numbering components or wish to add additional characters like brackets or points (e.g. to create markers like (a), 1–a or 1.) ) that are not part of the basic numbering templates. You may also specify -ilx-marker-font-family and -ilx-marker-font-size to further specify the marker display.

Optionally, you can specify further properties where needed:

  • Set an initial counter value for that list using the -ilx-list-numbering-absolute property if you do not want to start counting from 1, or if you are using it with an ilx-list-group value already used in an earlier list in the document and need to reset the counter to 1.

  • Set an -ilx-list-group value if you either want this list to continue numbering from where an earlier one with the same ilx-list-group value left off, or to conserve list ids when using itemized (non-numbered) lists – see explanation above.

  • Finally, you can specify whether counting on nested lists should restart at 1 when a new parent list item starts, or numbering should continue sequentially throughout the list. For this, use the -ilx-list-numbering-restart property.

3.5. Examples

Finally, let's have a look at some real-world examples:

Example 4.3. Simple ordered list

XML Code:

<list id="list_1">
    <item><par>Item 1</par></item>
    <item><par>Item 2</par></item>
</list>

To number items with "n)" and have the markers to the left of the block, you could use the following CSS:

#list_1 {
    list-style-type: lower-roman;
    \-ilx-marker-format: "%c)";
    list-style-position: outside;
}

The resulting formatting would look like this:


Example 4.4. Nested lists

XML Code:

<list class="list_2">
  <item><par>Item 1</par></item>
  <item>
    <par>Item 2</par>
    <list class="list_3">
      <item><par>subitem i</par></item>
      <item><par>subitem ii</par></item>
    </list>
  </item>
  <item><par>Item 3</par></item>
  <item>
    <par>Item 4</par>
    <list class="list_3">
      <item><par>subitem i</par></item>
      <item><par>subitem ii</par></item>
    </list>
  </item>
</list>

With the following CSS code

.list_2 {
  margin-left: 1.0cm;
  list-style-type: decimal;
  list-style-position: outside;
}

.list_3 {
  margin-left: 1.0cm;
  list-style-type: lower-alpha;
  list-style-position: outside;
}

the result looks like:

However, if we change the CSS to the following:

.list_2 {
  margin-left: 1.0cm;
  list-style-type: decimal;
  list-style-position: outside;
  \-ilx-list-numbering-absolute: 5;
}
.list_3 {
  margin-left: 1.0cm;
  list-style-type: lower-alpha;
  list-style-position: outside;
  \-ilx-list-numbering-restart: never;
}

the result will look like

Note how the setting of -ilx-list-numbering-restart to never continues numbering of list items at the second list level, even across higher-level list items. Also note how the list numbering of the top-level list now starts at "5", due to the setting of the -ilx-list-numbering-absolute property.


Example 4.5. Using a custom bullet character

If you want to use a special character for the marker of unnumbered lists, you can do this using the marker format string. XML code:

<list class="simpleArrow">
  <item><par>some item</par></item>
  <item><par>another item</par></item>
</list>

CSS code:

.simpleArrow {
  list-style-type: disc;
  margin-left: 1.0in;
  \-ilx-marker-offset: -0.5in;
  \-ilx-marker-align: center;
  \-ilx-marker-format: "\25B6 "; /* BLACK RIGHT POINTING TRIANGLE */
  \-ilx-list-group: 12345;
}

Formatted result:

You can of course use any Unicode character or even character sequence.

Note how we also set an explicit list id, therefore working against Word's unspecified limit on the number of different list definitions it can handle within a single document. You should apply that class definition on each list in your document that should be formatted likewise.


3.6. Using paragraph styles for list layout

In Word, you can use a style's definition for setting list item indents, and link that style to a numbering style definition including level information. Though this is not the way the RTF Exporter works in its default mode, there is a way to simulate that behaviour.

Key to this is the custom property -ilx-list-style-reference. This property must be set on the list element of the respective level, specifying the paragraph style that defines indents and marker definition for that list. The RTF Exporter then looks into this style and automatically retrieves all relevant list styling properties from that style. Additionally, it (internally) marks that list as being in a special mode where left indents are alyways calculated from the left column margin, not from the left margin of the containing box. This is an essential detail! It means that all paragraph styles you use in that list (resp. its items) are rendered as if they knew nothing about being in a list and no additional indents had been applied. Essentially, this is how Word would render them, as well. This also means that you must consider any indents you want to see in your list items yourself when creating the style properties used in such a list, you can no longer rely on the CSS box model implementation of the RTF Exporter do the calculations for you.

However, the RTF Exporter is smart enough to look into a list item's first paragraph style and extract its left indent value and use that for horizontally positioning of any table elements in list items. This is the only exception and supporting function in this context.

Example 4.6. 

<list style="\-ilx-list-style-reference: 'List Bullet 1'">
  <item>
    <par class="List&#xa0;Bullet&#xa0;1">A bulleted list item using a paragraph style.</par>
    </item>
<list>

will create a bulleted list item, where the definition for the paragraph style "List Bullet 1" contains all the necessary indent and list formatting properties as described earlier in this section. It then can also be used in editing the generated document directly in Word, yielding consistent indenting and formatting of lists.


4. Headings

To have a heading used in Word for outline display, you must set some specific properties. Word does not know the concept of a structuring section element, but infers the document structure from the sequence and outline level attributes of headings.

4.1. Outline level

So, a heading must indicate the outline level it represents, i.e. the level of logical content nesting. This is done using the property -ilx-outline-level with the level index as value, ranging from 1 to 9. A value of 0 (the default) indicates that that paragraph or heading does not constitute the beginning of a new level, but that it is a plain paragraph.

Specifying an outline level is most important when defining named styles using the Class selector. This ensures that when editing a generated document and the authro applies one of the heading styles, the paragraph is assigned the appropriate level information automatically.

Within the XML document structure, it is not required to set the -ilx-outline-level property, because the RTF exporter always re-calculates that value during conversion from the surround depth of section element nesting.

4.2. Automatic heading numbering

Numbering a heading in RTF is achieved by standard list properties. Similarly, the RTF exporter uses the list properties described in 4.3 for specifying the numbering style to generate:

List group assignment

Among the listed properties, the ilx-list-group property is the most important one as it groups nested headings into the same list group in RTF. This property is necessary since headings are treated as lists in Word, although they are not organized in a list element in the XML. Make sure that heading elements that are part of the same section nesting structure (which usually are all of them in a document) all get the identical, arbitrary -ilx-list-group integer value.

4.3. The little Heading-How-To

Follows a How-To for styling heading elements to take full advantage of Word's built-in heading handling:

  1. Make sure that the class name is "heading x", where x is a number from 1 through 9, corresponding to the level of the section element it is the first child of. Althrough you can use a different, arbitrary style name for headings, using the above default Word naming scheme ensures that Word immediately knows that these are heading styles and many functions and automations based on headings have the correct style(-names) already preset in the Word UI. Additionally, these names are automatically localized in the application's UI for the user's respectively the operating system's default language setting.

    Important

    Use a non-breaking space between "heading" and the number in the style's name, effectively giving a literal text of "heading\00a0 x" to be used in the stylesheet's Class selector text. This is necessary to make the class a single NMTOKEN.

    See 3.3 for further details.

  2. Add the property -ilx-outline-level to the style definition with an integer value corresponding to the level of that heading, numbered 1 through 9 (i.e. that number should correspond to the number used in the heading's class name).

  3. To all heading styles, add a property -ilx-list-group, which must have the same, arbitrary integer value (e.g. 1). This groups the levelled heading styles logically together (based on matching the provided integer value) so that e.g. numbering for a deeper level heading is automatically reset after a parent level has been seen.

  4. Add appropriate list-style-type and list marker formatting properties to control the styling of the numbering of the section heading.

5. Generated text (Word Fields)

RTF fields are portions of a document whose contents is automatically generated by the application processing the RTF code. Field code and instruction syntax are not part of the RTF specification, but are proprietary to the respective application.

The RTF exporter supports several selected Word field instructions directly (HYPERLINK for hyperlinks, REF, NOTEREF for references, TOC for the Table of Contents), but you can also insert arbitrary field types with appropriate instructions into the resulting RTF file. This is done by using the gentext element, short for: generated text.

Fields in RTF have two components, the field type and the field instruction. You specify both of these using the attributes type and data on a gentext element, respectively.

Example 4.7. Inserting the total number of pages

The following definition makes Word insert the total number of pages of the document at that position into the document body:

<gentext type="NUMPAGES" data="\* MERGEFORMAT" />

6. Table of Contents

To specify the place in a document where a Table of Contents should be automatically generated by Word, use the toc element. Its data attribute lets you specify options, like the formatting that Word should use, in the same way as you specify it for field instructions. Please confer the Word documentation or online help for available and supported options for the TOC field.

Example 4.8. Inserting a generated table of contents

This is a sample toc element you might place in your document to have a table of contents automatically generated at that place:

<toc data="\o &quot;1-3&quot; \h \z" />

7. Tabulators

Tabulators are evil.

Tabulators pose a wealth of problems in a system like the RTF exporter due to their relative positioning nature, so we can not encourage their use. There are situations, however, where you will probably need to use them. This is why we do support them using the -ilx-tab-stops property.

You can specify an -ilx-tab-stops property on par and heading elements, whose value takes the following form:

val ::= ( alignment ' ' leader ' ' pos (' '|',') )+
alignment ::= 'left' | 'center' | 'right' | 'decimal' | 'bar'
leader ::= 'blank' | 'dotted' | 'middle-dotted' | 'lined' | 'dashed' | 'thick' | 'double-dashed'
pos ::= number unit
number ::= decimalNumber
unit ::= 'cm' | 'in' | 'mm' | 'tw'

This results in a list of tab positions where you can tab to using the tabulator character (U+0009, &#9;).

Example 4.9. 

To place a left-aligned tab 1cm from the left edge the paragraph contents and a centering tab 5cm from the left edge of the pararaph, you would specify that as follows:

<par style="\-ilx-tab-stops: left blank 1cm, center blank 5cm;">...</par>

8. Tables

The RTF exporter can process both, HTML tables and OASIS Exchange Table Model tables, which are a subset of CALS. This is in accordance with the upCast DTD which allows both table models. You need not configure downCast a priori to which table model you want to use, since downCast detects the table model based on the XHTML namespace to place the HTML table elements in. You can use both, CALS and HTML table model tables, within the same document (or even nested).

RTF only supports a subset of the styling possibilities CSS offers. Therefore, the RTF exporter can only try to mimic the specified CSS properties in RTF code in a best-effort manner. Please inform us of specifications where the currently implemented algorithm fails and/or you are not able to create the styling you need with the means provided.

8.1. Table width

The table width is specified using the width property on the html:table resp. table element. Both absolute values and percentages are supported.

Example 4.10. Specifying the full table width

<html:table style="width: 6cm">

specifies a width of 6cm for the table.

<html:table style="width: 50%">

specifies that the table should use half of the available containing box width.


8.2. Column widths

The RTF exporter supports most of the table model-specific column width specifications.

You can use either html:col or colspec elements to specify widths, where fractional widths (e.g. "2*" or "4*") are supported, as are absolute values (incl. all units supported by CSS, even for html:col) and, with limitations, percentages.

Additionally, you can specify the width property on individual table cells, which take precedence over the specifications in html:col or colspec.

For final column width calculation, the RTF exporter looks for the cell with the biggest width within each table column. This is the width that then is used for that column. If no absolute width is specified, it uses either the specified fractional width or, if that is also not specified, uses the fractional value of "1*" for that column.

When the sum of the specified table column widths exceeds the available width for the complete table, the table will extend beyond the right edge of its content box.

Example 4.11. Complex table column width specification

A table column width specification making use of all of the mentioned size specification types could look like this:

<html:table frame="box" border="1" style="width: 8in">
  <html:colgroup>
    <html:col width="96" />
    <html:col width="4*"/>
    <html:col width="2*"/>
    <html:col width="25%" />
    <html:col />
  </html:colgroup>
  <html:tbody>
    <html:tr>
      <html:td><par>A</par></html:td>
      <html:td><par>B</par></html:td>
      <html:td><par>C</par></html:td>
      <html:td><par>D</par></html:td>
      <html:td style="width: 1in"><par>E</par></html:td>
    </html:tr>
    <html:tr>
      <html:td><par>F</par></html:td>
      <html:td><par>G</par></html:td>
      <html:td><par>H</par></html:td>
      <html:td><par>J</par></html:td>
      <html:td style="width: 2in"><par>K</par></html:td>
    </html:tr>
  </html:tbody>
</html:table>

The resulting column widths then are as follows:

Column

1

2

3

4

5

final size

1in

2in

1in

2in

2in

calculation

=96px

8in - (1in + 2in + 2in) = 3in, which is the remaining width to be distributed between these two columns.

3in / 6 = 0.5in per fraction, multiplied by the specified multi-length number

= 25% of 8in (=table width)

(specified on last cell in second row)

and the final table would look like this:


8.3. Table layout

You can have tables laid out automatically by Word (which allows e.g. columns to proportionally grow with respect to their contents), or have their widths fixed, regardless of the user editing the cell contents.

The layout mode to use is determined by the value of the property table-layout, auto or fixed.

Important

The table layout mode can only be set on the outermost table in case of tables nesting. All nested tables in RTF automatically inherit the setting of this property from the outermost table, regardless of how the property is actually set on nested instances.

The border mode of tables currently is always collapse and therefore the properties border-collapse and border-spacing are not supported.

8.4. Table positioning

To right-align a table, set its margin-left to auto and margin-right to 0.

To center a table, set both, its margin-left and margin-right, to auto.

To indent a table from the left content edge, use a positive margin-left value and set its margin-right to auto.

8.5. Cell properties

To align a cell's content vertically, use the valign attribute on the html:td, html:th or entry elements.

To rotate the content of a cell, use the -ilx-content-rotation property on the respective html:td, html:th or entry element.

On cells, you can also set the various margin-related properties, padding, and background-color.

9. Page Headers and Footers

Page headers and footers must be marked up using the pageheader and pagefooter elements, respectively, which must be child elements of part. Their contents can be considered a subdocument to the main document, put into container elements. The contents can be arbitrarily complex, so you may use lists and tables, paragraphs and images in a header and a footer. The contents is styled using the style rules present in the stylesheet as if it was a part of the main document.

You can specify different types of headers and footers for left (evenpages), right (oddpages) and first (firstpage) pages, or just use one definition for all (all) pages. This is specified in the type attribute on pageheader and pagefooter elements.

Example 4.12. Different page header and footer types

<part style="page: twoSided">
  <pageheader type="evenpages">...left header contents...</pageheader>
  <pageheader type="oddpages">...right header contents...</pageheader>
  <pagefooter type="all">...footer contents for all pages...</pagefooter>
  ...document contents...
</part>

generates different headers for left and right pages, but uses the same footer definition for all pages in that part.


You can specify header and footer offsets from the paper's top and bottom edge, respectively, using the following properties on part or partbreak elements:

The header and footer boxes overlay the page's top and bottom margins, if their content is smaller in height. If the content height exceeds the available page margin, Word will automatically increase the page margins as necessary so that header and footer content does not overlap the document body content.

10. References

References are referrals of the reader to a different section of a document. Word allows several kinds of reference notices to the reader and targets. You may for example specify to have it only read "above" if the reader is referred to an earlier point in the document, or you may have it name the specific section you would like to refer the reader to, like "2.3".

This can be specified on a reference element using the property -ilx-reference-presentation-type. For a description of the available options, see the property description.

Example 4.13. 

A reference element might look like this in an XML document:

<reference xlink:show="other" xlink:actuate="onLoad" xlink:href="refTarget1" style="\-ilx-reference-presentation-type: number;" />

The target of the reference, refTarget1, must of course be marked up by an appropriate target element.


11. Hyperlinks

Hyperlinks, that is links to external URLs, are created using the link element, which takes its linking attributes and values from the XLink specification.

Note

The only supported value for the xlink:type is simple.

The only supported value for the xlink:show is replace.

The only supported value for the xlink:actuate is onRequest.

The listed values are also the default values when the attributes are not explicitly specified on the link element.

Example 4.14. 

A link to our web site could look like this:

<link xlink:href="http://www.upcast.de/">upCast product website</link>

12. Images

You can include images in the document using the image element.

Images can either be embedded with their image data into the final document, or they can be referenced only via a relative or absolute path. This is specified using the -ilx-image-source property.

12.1. Positioning

When not specified otherwise, images are rendered as inline elements. However, when the float property is specified, you can have images be taken out of the document flow and have it float to the right, left or center (an RTF exporter extension).

When floating an image, you can also specify border properties and margin values. Note, however, that support for these properties is limited to what RTF allows for parameters.

12.2. Size and scaling

The RTF exporter supports scaling of images. This is implicitly applied preserving the image's aspect ratio when either width or height are specified, or possibly distorting when both are specified.

You can also specify min-width, min-height, max-width or max-height to constrain image scaling.

Some Word versions only support specifying a relative scaling of images (in integer percentage values), others support specifying the image dimensions as absolute size. When both are present, percentage values take precedence over absolute sizes, which makes it impossible to support all Word versions with a single RTF writing method.

The RTF Exporter therefore implements the image attribute (not a property!) size-writing-mode that lets you choose how final image size should be written to RTF. It can take one of the following values:

percentage

(=default when not specified) image scaling is written to RTF by way of integer percenatge values calculated from the relation between original image size and specified target image size. Since only integer values are supported, rounding errors will occur (increasing with difference between original and target image size).

absolute

image size is written as absolute values in twips (tw)

13. Hyphenation control

You can specify globally for the document whether you want automatic hyphenation to be turned on or off. This is controlled by the word-break-inside property.

Additionally, you can selectively suppress hyphenation on each individual par or heading element using the same word-break-inside property with a value of normal.

Chapter 5. CSS Property Reference

1. ilx-additive

-ilx-additive: true | false

Default: true

Inherited: false

RTF equivalent: \additive

Description:

When set to true on a named inline, i.e. character style, the properties defined here are added to the ones in effect at the place of application. When this is false, any additional properties compared to the plain style are cleared, then only the defined properties are applied.

2. ilx-alt-text

-ilx-alt-text: "text"

Default:

Inherited: false

RTF equivalent: \wzDescription

Description:

This property is read-only.

This property holds alternative text for graphical objects like images. It is only present in the internal document tree created by the RTF Importer and is serialized as an uci:description attribute on uci:image elements (if present).

Only supported on image elements.

3. ilx-annotation-marker

-ilx-annotation-marker: auto | suppress

Default: auto

Inherited: false

Description:

Specifies annotation marker generation handling.

auto the RTF Exporter generates an instruction in the output to have the RTF renderer insert an automatically, sequentially numbered annotation marker

suppress no automatic counter generation code is written and the document is responsible for providing the marker value. This must be used when you do not want to rely on automatic annotation numbering but want to specify custom annotation marker text for that annotation

Only supported on annotation elements.

4. background-color

background-color: color

Default: transparent

Inherited: false

Description:

Sets the background color.

Supported for elements par, inline, textbox, html:td and entry.

5. ilx-baseline-shift

-ilx-baseline-shift: length

Default: 0in

Inherited: false

Description:

This property is read-only.

This property holds the baseline-offset of an image when it is set inline with other text. This is a positive, absolute value indicating the offset of the baseline from the bottom of the image (its default position) towards the top.

Only supported on the image element.

6. border-bottom-color

border-bottom-color: color

Default: &color

Inherited: false

Description:

The color of the bottom border.

Only supported on par, table, html:td, html:th, entry and inline elements and @page rules.

7. border-bottom-style

border-bottom-style: none | hidden | solid | dashed | dotted | double | groove | ridge | inset | outset

Default: none

Inherited: false

Description:

The line style of the bottom border.

Only supported on par, table, html:td, html:th, entry and inline elements and @page rules.

8. border-bottom-width

border-bottom-width: length

Default: 0

Inherited: false

Description:

The width of the bottom border.

Only supported on par, table, html:td, html:th, entry and inline elements and @page rules.

9. border-left-color

border-left-color: color

Default: &color

Inherited: false

Description:

The color of the left border.

Only supported on par, table, html:td, html:th, entry and inline elements and @page rules.

10. border-left-style

border-left-style: none | hidden | solid | dashed | dotted | double | groove | ridge | inset | outset

Default: none

Inherited: false

Description:

The line style of the left border.

Only supported on par, table, html:td, html:th, entry and inline elements and @page rules.

11. border-left-width

border-left-width: length

Default: 0

Inherited: false

Description:

The width of the left border.

Only supported on par, table, html:td, html:th, entry and inline elements and @page rules.

12. border-right-color

border-right-color: color

Default: &color

Inherited: false

Description:

The color of the right border.

Only supported on par, table, html:td, html:th, entry and inline elements and @page rules.

13. border-right-style

border-right-style: none | hidden | solid | dashed | dotted | double | groove | ridge | inset | outset

Default: none

Inherited: false

Description:

The line style of the right border.

Only supported on par, table, html:td, html:th, entry and inline elements and @page rules.

14. border-right-width

border-right-width: length

Default: 0

Inherited: false

Description:

The width of the right border.

Only supported on par, table, html:td, html:th, entry and inline elements and @page rules.

15. border-top-color

border-top-color: color

Default: &color

Inherited: false

Description:

The color of the top border.

Only supported on par, table, html:td, html:th, entry and inline elements and @page rules.

16. border-top-style

border-top-style: none | hidden | solid | dashed | dotted | double | groove | ridge | inset | outset

Default: none

Inherited: false

Description:

The line style of the top border.

Only supported on par, table, html:td, html:th, entry and inline elements and @page rules.

17. border-top-width

border-top-width: length

Default: 0

Inherited: false

Description:

The width of the top border.

Only supported on par, table, html:td, html:th, entry and inline elements and @page rules.

18. bottom

bottom: length

Default: 0

Inherited: false

Description:

Specifies displacement of the element when its position property is absolute or fixed.

Only supported on textbox elements.

19. color

color: color

Default: black

Inherited: true

Description:

Sets the text color. Transparency (rgba(…)) is not supported by RTF.

20. ilx-column-count

-ilx-column-count: number

Default: 1

Inherited: false

Description:

Specifies the number of content columns in the document or part.

Only supported on part and partbreak elements.

21. ilx-column-gap

-ilx-column-gap: length

Default:

Inherited: false

Description:

Sets the free space between columns.

Only supported on part and partbreak elements.

22. ilx-column-rule

-ilx-column-rule: none | solid

Default: none

Inherited: false

Description:

Specifies whether a vertical line should be drawn between columns (solid) or not (none).

Only supported on part and partbreak elements.

23. ilx-column-width

-ilx-column-width: length

Default:

Inherited: false

Description:

Specifies the column width to use for all of the content columns in this document or part.

Only supported on part and partbreak elements.

24. ilx-content-rotation

-ilx-content-rotation: angle

Default: 0deg

Inherited: false

Description:

Specifies the rotation of table cell contents. The property takes an angle as value which is to be applied in counter-clockwise direction. The only supported values by RTF are 0deg, 90deg and 270deg.

Only supported on html:td, html:th and cell elements.

25. ilx-default-tab-size

-ilx-default-tab-size: length

Default:

Inherited: false

RTF equivalent: \deftab

Description:

Specifies the default tab size (distance) to use in this document.

Only supported on the document element.

26. direction

direction: ltr | rtl

Default: ltr

Inherited: false

Description:

Sets writing direction. Used for interpreting offsets (top, right, left, bottom) correctly.

Only supported on textbox element.

27. display

display: inline | block | inline-block | ilx-internal-inline | ilx-internal-block

Default: inline

Inherited: false

Description:

Sets a certain display semantics for the element it is used on.

inline

renders the element inline. When used with a Class selector, makes the definition a named RTF Character Style.

block

renders the element as a block. When used with a Class selector, makes the definition a named RTF Paragraph Style.

inline-block

renders the element as a block flowing inline. Only allowed on textbox elements.

ilx-internal-inline

renders the element inline. Even when used with a Class selector, the definition is not made a named RTF Character Style.

ilx-internal-block

renders the element as a block. Even when used with a Class selector, the definition is not made a named RTF Paragraph Style.

28. display-align

display-align: top | middle | bottom | justify

Default: top

Inherited: false

Details: http://www.w3.org/TR/SVGTiny12/text.html#DisplayAlignProperty

RTF equivalent: \vertal?

Description:

Positions the page content on each page of that part (virtual page content bounding box) relative to the available containing block height on the page.

Only supported on part and partbreak elements.

29. ilx-editing-rights

-ilx-editing-rights: full | none

Default: full

Inherited: false

Description:

Sets editing rights for the document.

full

the complete document can be edited

none

only (the contents of) form elements can be edited

Only supported on document element.

30. ilx-endnote-numbering-policy

-ilx-endnote-numbering-policy: continuous | restartsection

Default: continuous

Inherited: false

Description:

Specifies the numbering method to use for endnote numbering.

continous

number endnotes continously throughout the document

restartsection

restart endnote numbering at the beginning of each part or partbreak

Only supported on document, part and partbreak elements.

31. ilx-endnote-numbering-start

-ilx-endnote-numbering-start: number

Default: 1

Inherited: false

Description:

Sets the start number for endnote numbering.

Only supported on document, part and partbreak elements.

32. ilx-endnote-position

-ilx-endnote-position: textbottom | sectionbottom | pagebottom | documentbottom

Default: sectionbottom

Inherited: false

Description:

Specifies where footnotes should be placed.

textbottom

places footnotes directly below the last text on each page

pagebottom

places footnotes on the bottom of the page

Only supported on document, part and partbreak elements.

sectionbottom

places footnotes at the end of the current section (= part)

documentbottom

places footnotes at the end of the document

Only supported on document element.

33. ilx-endnote-style-type

-ilx-endnote-style-type: decimal | disc | circle | lower-roman | upper-roman | lower-alpha | upper-alpha | chicago | footnotes

Default: decimal

Inherited: false

Description:

Specifies the kind of marker or numbering used for numbering endnotes.

Only supported on document, part and partbreak elements.

34. ilx-facing-pages

-ilx-facing-pages: true | false

Default: false

Inherited: false

RTF equivalent: \facingp

Description:

Turns on or off the support for left and right pages. When false, only right (=odd) pages are generated.

Only supported on document element.

35. float

float: left | center | right | none | inside | outside

Default: none

Inherited: false

Description:

Specifies that an element should be taken out of the rendering flow and placed floating to the left or right border or in the center of the current column.

Supported on image, par and textbox elements.

Note

Due to limitations of the RTF format, this property cannot be supported in full as described in the CSS specifications. It is therefore implemented on a best-effort basis.

36. ilx-following-style

-ilx-following-style: "stylename"

Default:

Inherited: false

RTF equivalent: \snext

Description:

Used in style rules with a Class selector for paragraph styles only, lets you specify the name of the style that should be automatically chosen when an author hits the return key when in the specified style.

The style name must be the Word style name, not the mangled class name, i.e. normal spaces are used and not be replaced with non breaking space characters (\a0).

Only supported in style rules for paragraph styles (Class selector).

37. font-family

font-family: "name"

Default: "Times"

Inherited: true

Details: http://www.w3.org/TR/CSS21/fonts.html#propdef-font-family

Description:

Sets the font name to use. When the font is not available on the system the RTF document is opened, the displaying application is free to use a different, similar font. Only the first font in a list of fonts is used and set.

38. ilx-font-family-default

-ilx-font-family-default: "name"

Default: "Times"

Inherited: false

RTF equivalent: \deff

Description:

Sets the RTF file's default font.

Only supported on document element.

39. ilx-font-family-generic

-ilx-font-family-generic: serif | sans-serif | monospace

Default: serif

Inherited: false

Description:

This cutom property sets the generic fallback font type to use if the first specified font in font-family does not exist on the final RTF rendering system.

40. font-size

font-size: length

Default: 12pt

Inherited: true

Description:

Sets the font size.

41. font-style

font-style: normal | italic | oblique

Default: normal

Inherited: false

RTF equivalent: \i

Description:

Sets the font style.

Note that both, italic and oblique, are translated to same RTF symbol.

42. font-variant

font-variant: normal | small-caps

Default: normal

Inherited: false

Description:

Selects a specific font variation.

43. font-weight

font-weight: normal | bold | bolder | lighter

Default: normal

Inherited: false

Description:

Selects the weight of the font.

RTF does not support varying font weights, a font can either be bold or normal. The RTF Exporter translates any graded or relative values to either one of these two states.

44. ilx-footer-offset

-ilx-footer-offset: length

Default: 0.5in

Inherited: false

Description:

Specifies the vertical distance of the page footer from the bottom paper margin.

Only supported on document, part and partbreak elements.

45. ilx-footnote-numbering-policy

-ilx-footnote-numbering-policy: continuous | restartsection | restartpage

Default: restartsection

Inherited: false

Description:

Specifies the numbering method to use for footnote numbering.

continous

number footnotes continously throughout the document

restartsection

restart footnote numbering at the beginning of each part or partbreak

restartpage

restart footnote numbering at the beginning of each laid out page

Only supported on document, part and partbreak elements.

46. ilx-footnote-numbering-start

-ilx-footnote-numbering-start: number

Default: 1

Inherited: false

Description:

Sets the start number for footnote numbering.

Only supported on document, part and partbreak elements.

47. ilx-footnote-position

-ilx-footnote-position: textbottom | sectionbottom | pagebottom | documentbottom

Default: pagebottom

Inherited: false

Description:

Specifies where footnotes should be placed.

textbottom

places footnotes directly below the last text on each page

pagebottom

places footnotes on the bottom of the page

Only supported on document, part and partbreak elements.

sectionbottom

places footnotes at the end of the current section (= part)

documentbottom

places footnotes at the end of the document

Only supported on document element.

48. ilx-footnote-style-type

-ilx-footnote-style-type: decimal | disc | circle | lower-roman | upper-roman | lower-alpha | upper-alpha | chicago | footnotes

Default: decimal

Inherited: false

Description:

Specifies the kind of marker or numbering used for numbering footnotes.

Only supported on document, part and partbreak elements.

49. ilx-gutter

-ilx-gutter: absolute-length

Default: 0

Inherited: false

Description:

This value defines the additional right margin (for left=even pages) resp. the additional left margin (for right=odd pages) when using @page rules that are different for left and right pages and -ilx-facing-pages is true.

Only supported in @page rules.

50. ilx-header-offset

-ilx-header-offset: length

Default: 0.5in

Inherited: false

Description:

Specifies the vertical distance of the page header from the top paper margin.

Only supported on document, part and partbreak elements.

51. height

height: length

Default: 0

Inherited: false

Description:

The height of the element.

Only supported on par, image, table, html:td, html:th, entry and formcheckbox elements.

52. ilx-horizontal-alignment

-ilx-horizontal-alignment: left | center | right | inside | outside | none

Default: none

Inherited: false

Description:

Specifies how the paragraph is aligned with respect to its horizontal reference point.

See -ilx-position-reference-horizontal.

Only supported on par elements.

53. ilx-image-source

-ilx-image-source: embed | reference

Default: embed

Inherited: false

Description:

Specifies how a referenced image should be included in an RTF document.

embed

the image data is embedded into the document, increasing its size (possibly considerably). The advantage is that you can apply scaling factors, positioning, borders and other properties.

reference

the image is referenced by file path and read only at rendering time by the RTF renderer. The advantage is that the image data can be updated externally without having to re-generate the RTF document and the document's size is kept small. However, no scaling or other properties can be applied, i.e. the image size specified in the file must be already the same as it is to be displayed. Additionally, you must take care that relative references (if used) do not break when copying or moving the RTF file.

54. ilx-inline-class

-ilx-inline-class: "name"

Default:

Inherited: false

Description:

This property is read-only.

Holds the original Word name of the character style.

55. left

left: length

Default: 0

Inherited: false

Description:

Specifies displacement of the element when its position property is absolute or fixed.

Only supported on textbox elements.

56. letter-spacing

letter-spacing: normal | length

Default: normal

Inherited: false

Description:

This property specifies spacing behavior between text characters.

57. line-height

line-height: normal | length | percentage

Default: normal

Inherited: false

Description:

Specifies the minimal line height.

When specifying the height in a relative unit (i.e., em, % or ex), the resulting value is interpreted as a minimum line height, with the rendering engine being free to increase that value based on the specific line contents.

If you specify an absolute value, it is interpreted as being an exact line height, with taller content in that line possibly being clipped.

58. ilx-line-numbering-distance

-ilx-line-numbering-distance: auto | length

Default: auto

Inherited: false

Description:

Sets the distance between the left side of the content column and the display of line numbering information.

Only supported on part and partbreak elements.

59. ilx-line-numbering-interval

-ilx-line-numbering-interval: number

Default: 1

Inherited: false

Description:

Specifies to show line numbering at every nth line.

Only supported on part and partbreak elements.

60. ilx-line-numbering-mode

-ilx-line-numbering-mode: off | continue | restart | page

Default: off

Inherited: false

Description:

Specifies when to reset line nuber counting and whether to enable or disable it.

off

turns line numbering off

continue

continues line numbering from the last part

restart

restarts line numbering from this part on

page

restarts line numbering on each laid out page

Only supported on part and partbreak elements.

61. ilx-line-numbering-start

-ilx-line-numbering-start: number

Default: 1

Inherited: false

Description:

Sets the start number for line numbering after a numbering reset.

Only supported on part and partbreak elements.

62. ilx-line-numbering-state

-ilx-line-numbering-state: suppress | show

Default: suppress

Inherited: false

Description:

Allows to suppress line numbering display selectively for individual paragraphs.

Only supported on par elements.

63. line-stacking-strategy

line-stacking-strategy: inline-line-height | block-line-height

Default: inline-line-height

Inherited: false

Description:

Controls the algorithm for line height calculation in paragraphs of text.

inline-line-height

the tallest element (font, image, etc.) within each line of text establishes the actual line height for that line, with the value set by the line-height property treated as minimum value. Effectively, this sets the meaning of the line-height value to "minimum line height".

block-line-height

all lines within the paragraph have the same line height, possibly cutting off elements in a line that are taller than the value specified with the line-height property. Effectively, this sets the meaning of the line-height value to "exact line height".

64. ilx-list-group

-ilx-list-group: number

Default: 0

Inherited: false

Description:

This specifies the list group. For details on list formatting properties, see Lists.

Only supported on list elements.

65. ilx-list-level

-ilx-list-level: number

Default: 0

Inherited: false

Description:

Sets the nesting level information for lists. For details on list formatting properties, see Lists.

Only supported on list elements.

66. ilx-list-numbering-absolute

-ilx-list-numbering-absolute: number

Default: 1

Inherited: false

Description:

Set the absolute starting number for a list. For details on list formatting properties, see Lists.

Only supported on list and item lements.

67. ilx-list-numbering-restart

-ilx-list-numbering-restart: never | on-parent-increment

Default: on-parent-increment

Inherited: false

Description:

Determines how in nested lists, item counting should be performed.

never

counting continues at the next number from the last list item at the same level, irrespective of whether higher level items are present between those.

on-parent-increment

the item counter is reset whenever an item of a higher level is seen

68. list-style-position

list-style-position: outside | inside

Default: outside

Inherited: true

Description:

The positioning of the list marker. When outside, it is positioned hanging, i.e. to the left of the list item block. When inside, it is placed on the first line within the list item's block.

A value of outside translates internally to setting -ilx-marker-offset to its default value and -ilx-marker-follow to tab.

A value of inside translates internally to setting -ilx-marker-offset to 0tw and -ilx-marker-follow to space.

69. ilx-list-style-reference

-ilx-list-style-reference: "paragraph_stylename"

Default:

Inherited: false

Description:

Specifies that for this list, any left indents of paragraph styles will be calculated with a reference of the left column border (instead of the left edge of the containing block), and that list formatting properties are to be taken from the specified, named style.

For details on list formatting properties and building lists using paragraph styles in particular, see Lists.

Only supported on the list element.

70. list-style-type

list-style-type: disc | circle | square | decimal | decimal-leading-zero | lower-roman | upper-roman | lower-alpha | lower-latin | upper-alpha | upper-latin | hebrew | cjk-ideographic | hiragana | katakana | hiragana-iroha | katakana-iroha | none | hyphen

Default: disc

Inherited: true

Description:

The kind of marker or numbering to be used for numbering list items.

71. margin-bottom

margin-bottom: length

Default: 0

Inherited: false

Description:

The bottom margin of the element.

Note

The value auto is not supported.

72. margin-left

margin-left: length

Default: 0

Inherited: false

Description:

The left margin of the element.

Note

The value auto is only supported on the table element for left-, right-aligning or centering a table with respect to its containing column.

73. margin-right

margin-right: length

Default: 0

Inherited: false

Description:

The right margin of the element.

Note

The value auto is only supported on the table element for left-, right-aligning or centering a table with respect to its containing column.

74. margin-top

margin-top: length

Default: 0

Inherited: false

Description:

The top margin of the element.

Note

The value auto is not supported.

75. ilx-marker-align

-ilx-marker-align: left | center | right

Default: right

Inherited: false

Description:

Specifies how the marker should be aligned with respect to the -ilx-marker-offset position. For details on list formatting properties, see Lists.

Only supported on list elements.

76. ilx-marker-color

-ilx-marker-color: color

Default:

Inherited: false

Description:

Sets the color for the list marker text. For details on list formatting properties, see Lists.

Only supported on list elements.

See also: color

77. ilx-marker-follow

-ilx-marker-follow: tab | space | nothing

Default: tab

Inherited: false

Description:

Specifies which single character should be inserted automatically after the marker string in the RTF text. When specifying none, no additional character is inserted. For details on list formatting properties, see Lists.

Only supported on list elements.

78. ilx-marker-font-family

-ilx-marker-font-family: "name"

Default: "Arial"

Inherited: false

Description:

Sets the font to use for the list marker text. For details on list formatting properties, see Lists.

Only supported on list elements.

See also: font-family

79. ilx-marker-font-size

-ilx-marker-font-size: absolute-length

Default: 12pt

Inherited: false

Description:

Sets the font size for the list marker text. For details on list formatting properties, see Lists.

Only supported on list elements.

See also: font-size

80. ilx-marker-format

-ilx-marker-format: format-string

Default: "\2022 "

Inherited: false

Description:

Specifies how the list marker text content should be calculated. The string can consist of verbatim content or placeholders for the current numbering of the respective level (%n, where n is the 0-based level to use the number from). For details on list formatting properties, see Lists.

Example 5.1. 

To format a list marker as 1. a), 1. b) and so on, you would use the following property definition:

\-ilx-marker-format: "%0. %1)";

Only supported on list elements.

81. ilx-marker-offset

-ilx-marker-offset: length

Default: -360tw

Inherited: false

Description:

Specifies the offset from the left side of the content box to place the marker. Both negative (=outdent) and positive (indent) values are supported. For details on list formatting properties, see Lists.

Only supported on list elements.

82. max-height

max-height: length

Default:

Inherited: false

Description:

Sets the maximum height of an element.

Supported on image elements only.

83. max-width

max-width: length

Default:

Inherited: false

Description:

Sets the maximum width of an element.

Supported on image elements only.

84. min-height

min-height: length

Default:

Inherited: false

Description:

Sets the minimum height of an element.

Supported on image, html:td, html:th, entry, html:tr and row elements only.

85. min-width

min-width: length

Default:

Inherited: false

Description:

Sets the minimum width of an element.

Supported on image elements only.

86. ilx-mirror-margins

-ilx-mirror-margins: true | false

Default: false

Inherited: false

RTF equivalent: \margmirror

Description:

This property is synthesized internally from the actual :left and :right page rule specifications. The RTF exporter decides whether to implement the given page property specification using the gutter mechanism or the mirror margins mechanism. You should not use that property in style specifications.

87. ilx-note-marker

-ilx-note-marker: auto | suppress

Default: auto

Inherited: false

Description:

Specifies footnote/endnote marker generation handling.

auto the RTF Exporter generates an instruction in the output to have the RTF renderer insert an automatically, sequentially numbered footnote or endnote marker

suppress no automatic counter generation code is written and the document is responsible for providing the marker value. This must be used when you do not want to rely on automatic note numbering but want to specify custom footnote or endnote marker text for that note

See Footnotes and Endnotes for details on how to create footnotes and endnotes in a document.

Only supported on footnote and endnote elements.

88. orphans

orphans: 0 | 2

Default: 2

Inherited: false

Description:

Orphan control for calculating page breaks.

Only values 0 (=off) and 2 (=on) are supported. The orphans and widows property cannot be set independently, but share their value.

89. ilx-outline-level

-ilx-outline-level: number

Default: 0

Inherited: false

Description:

Specifies the outline level (in Word outline view) this paragraph should be part of. The default value, 0, identifies body text.

Only supported on par and heading elements.

90. padding-bottom

padding-bottom: length

Default: 0

Inherited: false

Description:

The bottom padding of an element.

Only supported on part, par, html:tr, row, html:td, html:th, entry and textbox elements.

91. padding-left

padding-left: length

Default: 0

Inherited: false

Description:

The left padding of an element.

Only supported on part, par, html:tr, row, html:td, html:th, entry and textbox elements.

92. padding-right

padding-right: length

Default: 0

Inherited: false

Description:

The right padding of an element.

Only supported on part, par, html:tr, row, html:td, html:th, entry and textbox elements.

93. padding-top

padding-top: length

Default: 0

Inherited: false

Description:

The top padding of an element.

Only supported on part, par, html:tr, row, html:td, html:th, entry and textbox elements.

94. page

page: id

Default: ilx-defaultPageStyle

Inherited: false

Description:

Selects the @page rule specification with the given id. It is effective from this location on for all following content.

Only supported on part and partbreak elements.

95. page-break-after

page-break-after: auto | avoid

Default: auto

Inherited: false

Description:

Allows or suppresses page breaks after an element.

Supported on par element only.

96. page-break-before

page-break-before: auto | always | left | right

Default: auto

Inherited: false

Description:

Controls the page break algorithm for breaks before this element.

Only when set on the part element, all four values are supported. On all other block-level elements, only auto and always are supported.

97. page-break-inside

page-break-inside: auto | avoid

Default: auto

Inherited: false

Description:

Allows or suppresses page breaks inside an element.

Supported on par, html:tr and row elements only.

98. ilx-page-numbering-mode

-ilx-page-numbering-mode: continue | restart

Default:

Inherited: false

Description:

Specifies whether page numbering should continue in this part or should restart from the start value (see -ilx-page-numbering-start).

Only supported on part and partbreak elements.

99. ilx-page-numbering-start

-ilx-page-numbering-start: number

Default: 1

Inherited: false

Description:

Sets the start number for page numbering.

Only supported on document, part and partbreak elements.

100. ilx-page-numbering-style

-ilx-page-numbering-style: decimal | upper-roman | lower-roman | upper-alpha | lower-alpha

Default: decimal

Inherited: false

Description:

Specifies the kind of numbering used for page numbers.

Only supported on document, part and partbreak elements.

101. ilx-page-padding-calculation-ref

-ilx-page-padding-calculation-ref: frompage | fromtext

Default: fromtext

Inherited: false

RTF equivalent: \pgbrdropt

Description:

Determines whether padding values for the page's content are calculated outward from the content area of the page (fromtext), or inward from the page area (frompage).

Only supported on document and part elements.

102. ilx-paper-orientation

-ilx-paper-orientation: auto | landscape | portrait

Default: auto

Inherited: false

Description:

Sets paper orientation.

Normally, this property is calculated automatically from the @page rule settings.

Only supported on part and partbreak elements.

103. ilx-paragraph-class

-ilx-paragraph-class: "name"

Default:

Inherited: false

Description:

This property is read-only.

Holds the original Word name of the paragraph style.

104. position

position: static | absolute | fixed

Default: static

Inherited: false

Description:

Specifies whether an element should be placed in the flow or positioned at a fixed location, relative to the top-left page edge.

Only supported on textbox elements.

Note

Due to limitations of the RTF format, this property cannot be supported in full as described in the CSS specifications. It is therefore implemented on a best-effort basis.

105. ilx-position-reference-horizontal

-ilx-position-reference-horizontal: page | margin | column

Default: column

Inherited: false

Description:

Specifies the horizontal reference point for positioned paragraphs.

See -ilx-horizontal-alignment.

Only supported on par elements.

106. ilx-position-reference-vertical

-ilx-position-reference-vertical: page | margin | paragraph

Default: margin

Inherited: false

Description:

Specifies the vertical reference point for positioned paragraphs.

See -ilx-vertical-alignment.

Only supported on par elements.

107. ilx-reference-presentation-type

-ilx-reference-presentation-type: relpagenumber | pagenumber | number | contextnumber | relnumber | relcontextnumber | numbernotext | contextnumbernotext | relnumbernotext | relcontextnumbernotext | docvariable | notenumber | relnotenumber | notenumberwithstyle | relnotenumberwithstyle

Default: pagenumber

Inherited: false

Description:

For reference elements, specifies how the reference should be displayed in the rendered document. Since this value is translated into Word proprietary field options, you should experiment with the values to find the display format suitable for your specific situation. Applications may interpret the options generated differently.

The values will set RTF reference field type and flags as follows:

property value

field type

\f

\p

\r

\t

\w

number

REF

x

numbernotext

REF

x

x

relnumber

REF

x

x

relnumbernotext

REF

x

x

x

pagenumber

PAGEREF

relpagenumber

PAGEREF

x

contextnumber

REF

x

x

relcontextnumber

REF

x

x

x

contextnumbernotext

REF

x

x

x

relcontextnumbernotext

REF

x

x

x

x

docvariable

REF

notenumber

NOTEREF

relnotenumber

NOTEREF

x

notenumberwithstyle

NOTEREF

x

relnotenumberwithstyle

NOTEREF

x

x

108. right

right: length

Default: 0

Inherited: false

Description:

Specifies displacement of the element when its position property is absolute or fixed.

Only supported on textbox elements.

109. ilx-style-display

-ilx-style-display: show | hide | hide-dropdown

Default: show

Inherited: false

Description:

For named paragraph or character styles (defined using a Class selector), this property lets you define whether the style should be made available in various portions of the Word application's UI.

show

the style is made available in menus and popups throughout the application

hide

the style is not shown in the Word UI

hide-dropdown

the style is not available in dropdown menus, but available through dialogs

Only supported on document element.

110. ilx-style-update

-ilx-style-update: link | none

Default: none

Inherited: false

Description:

Sets whether style definitions of named styles should be automatically updated from any linked Word document template (link) or not (none).

Only supported on document element.

111. ilx-tab-stops

-ilx-tab-stops: [[left | center | right | decimal | bar] [blank | dotted | middle-dotted | lined | dashed | thick | double-dashed] absolute-length]*

Default:

Inherited: false

Description:

Important

Tabulators are evil.

This property defines the set of tab stops to be placed in the ruler for this par element or named style.

Tabulators pose a wealth of problems when generating code for RTF rendering applications like Word due to their relative positioning nature to absolute positions, so we can not encourage their use. There are situations, however, where you will probably need to use them. This is why we included them as a feature in the RTF exporter. Use at your own risk.

Supported on par and heading elements.

The value is a list of triplets of tokens. A triplet specifies a single tabulator position, and all three properties of that tabulator position must be specified. The syntax of the value is as follows:

val ::= ( alignment leader pos )+
alignment ::= 'left' | 'center' | 'right' | 'decimal' | 'bar'
leader ::= 'blank' | 'dotted' | 'middle-dotted' | 'lined' | 'dashed' | 'thick' | 'double-dashed'
pos ::= <absolute CSS length unit>

This results in a list of tab positions where you can tab to using the tabulator character (U+0009, &#9;).

112. table-layout

table-layout: auto | fixed

Default: auto

Inherited: false

RTF equivalent: \trautofit

Description:

Specifies table layout algorithm.

Note

In RTF, the setting on the outermost table is inevitably inherited onto nested tables. This means although you can theoretically set the property differently on each table of a nesting hierarchy, only the outermost value will have any effect and it will be the same for all further nested tables.

113. text-align

text-align: left | right | center | justify

Default: left

Inherited: true

Description:

Horizontal text alignment within a paragraph.

114. text-decoration

text-decoration: none | underline | line-through | ilx-outline | ilx-shadow | ilx-emboss | ilx-engrave

Default: none

Inherited: false

Description:

This property describes decorations that are added to the text of an element.

Custom property values (ilx-…) are available for additional decorations of text available in RTF.

115. text-indent

text-indent: length

Default: 0mm

Inherited: true

Description:

First line indent. Can be positive (indented) or negative (hanging).

116. text-line-through-style

text-line-through-style: none | solid | double

Default: solid

Inherited: false

Description:

Style of strikethrough text line.

Specifies the line-through style for stricken text.

Only supported on par, heading and inline elements.

117. text-transform

text-transform: none | uppercase | capitalize

Default: none

Inherited: false

Description:

Selects a case-transformation of text content.

118. text-underline-color

text-underline-color: color

Default: &color

Inherited: false

Description:

Sets the color of the underline.

119. text-underline-mode

text-underline-mode: continuous | skip-white-space

Default: continuous

Inherited: false

Description:

Determines how a run of text should be underlined.

120. text-underline-style

text-underline-style: [none | solid | double | dotted | dashed | dot-dash | dot-dot-dash | wave] || thick

Default: none

Inherited: false

Description:

Sets the style of the underline.

121. ilx-text-visibility

-ilx-text-visibility: full | none

Default: full

Inherited: false

RTF equivalent: \v

Description:

This sets the hidden text RTF property to suppress text from being visibly rendered. The text itself, however, is still output to the document.

122. top

top: length

Default: 0

Inherited: false

Description:

Specifies displacement of the element when its position property is absolute or fixed.

Only supported on textbox elements.

123. vertical-align

vertical-align: baseline | sub | super | length | percentage

Default: top

Inherited: false

Description:

Specifies the vertical alignment of the element.

For cell, values top, middle and bottom are supported.

For inline, values baseline, sub and super are supported, as well as a certain length of displacement.

124. ilx-vertical-alignment

-ilx-vertical-alignment: top | middle | bottom | inside | outside | inline | none

Default: none

Inherited: false

Description:

Specifies how the paragraph is aligned with respect to its vertical reference point.

See -ilx-position-reference-vertical.

Only supported on par elements.

125. widows

widows: 0 | 2

Default: 2

Inherited: false

Description:

Widow control for calculating page breaks.

Only values 0 (=off) and 2 (=on) are supported. The orphans and widows property cannot be set independently, but share their value.

126. width

width: length

Default: 0

Inherited: false

Description:

The width of the element.

Only supported on par, image, table, html:td, html:th, entry, formcheckbox and textbox elements.

127. ilx-word-base-style

-ilx-word-base-style: "stylename"

Default:

Inherited: false

RTF equivalent: \sbasedon

Description:

Used in style rules with a Class selector for paragraph or character styles only, this lets you specify the name of the style that this style should be based on.

Note

Note that this is just a hint for Word when changing style definitions within that application at some later time. You still need to explicitly specify all properties (even if replicated from the style it is based on) in the style definition.

Only supported in style rules for paragraph and character styles (Class selector).

128. word-break-inside

word-break-inside: normal | hyphenate

Default: normal

Inherited: false

Description:

Allows you to control automatic hyphenation.

Note

A value of normal suppresses hyphenation as far as possible.

Supported on elements document and par.

129. ilx-word-list-type

-ilx-word-list-type: hierarchical | simple

Default: simple

Inherited: false

Description:

This property is read-only.

This property indicates whether the corresponding list was constructed as a nine-level outline list (hierarchical) in Word, or as a simple list (simple).

130. ilx-word-style-id

-ilx-word-style-id: number

Default:

Inherited: false

RTF equivalent: \s cs

Description:

This is purely an informational property and holds the internal RTF style id (\s resp. \cs symbol values) this style got assigned in the RTF document.

131. ilx-wrap-distance-horizontal

-ilx-wrap-distance-horizontal: length

Default: 0

Inherited: false

RTF equivalent: \dfrmtxtx

Description:

This custom property mirrors the RTF respective property for specifying left and right margin of positioned paragraphs. This is only useful when you need to define a named paragraph style that creates a positioned paragraph. Normally, you should create a textbox element for this, which has a much more detailed set of properties available.

132. ilx-wrap-distance-vertical

-ilx-wrap-distance-vertical: length

Default: 0

Inherited: false

Description:

This custom property mirrors the RTF respective property for specifying top and bottom margin of positioned paragraphs. This is only useful when you need to define a named paragraph style that creates a positioned paragraph. Normally, you should create a textbox element for this, which has a much more detailed set of properties available.

133. ilx-xml-lang

-ilx-xml-lang: iso-language-code

Default: en

Inherited: false

Description:

Use the xml:lang attribute instead.

This property should only be used for defining named paragraph or inline class styles to include language information.

134. z-index

z-index: auto | number

Default: auto

Inherited: false

Description:

Specifies the rendering layer of the element.

Only supported on positioned elements textbox and image.