The reader of an RTF stream is concerned with the following:

* Separating control information from plain text.

* Acting on control information.

* Collecting and properly inserting text into the document, as directed by the current group state.

Acting on control information is designed to be a relatively simple process. Some control information simply contributes special characters to the plain text stream. Other information serves to change the program state, which includes properties of the document as a whole, or to change any of a collection of group states, which apply to parts of the document.

As previously mentioned, a group state can specify the following:

* The destination, or part of the document that the plain text is constructing.

* Character-formatting properties, such as bold or italic.

* Paragraph-formatting properties, such as justified or centered.

* Section-formatting properties, such as the number of columns.

* Table-formatting properties, which define the number of cells and dimensions of a table row.

In practice, an RTF reader will evaluate each character it reads in sequence as follows:

* If the character is an opening brace ({), the reader stores its current state on the stack. If the character is a closing brace (}), the reader retrieves the current state from the stack.

* If the character is a backslash (\), the reader collects the control word or control symbol and its parameter, if any, and looks up the control word or control symbol in a table that maps control words to actions. It then carries out the action prescribed in the table. (The possible actions are discussed below.) The read pointer is left before or after a control-word delimiter, as appropriate.

* If the character is anything other than an opening brace ({), closing brace (}), or backslash (\), the reader assumes that the character is plain text and writes the character to the current destination using the current formatting properties.

If the RTF reader cannot find a particular control word or control symbol in the look-up table described above, the control word or control symbol should be ignored. If a control word or control symbol is preceded by an opening brace ({), it is part of a group. The current state should be saved on the stack, but no state change should occur. When a closing brace (}) is encountered, the current state should be retrieved from the stack, thereby resetting the current state. If the \* control symbol precedes a control word, then it defines a destination group and was itself preceded by an opening brace ({). The RTF reader should discard all text up to and including the closing brace (}) that closes this group. All RTF readers must recognize all destinations defined in the March 1987 RTF Specification. The reader may skip past the group, but it is not allowed to simply discard the control word. Destinations defined since March 1987 are marked with the \* control symbol.

Note All RTF readers must implement the \* control symbol so that they can read RTF files written by newer RTF writers.

For control words or control symbols that the RTF reader can find in the look-up table, the possible actions are as follows.

FORMAL SYNTAX

This Application Note describes RTF using the following syntax, based on Backus-Naur Form.

CONTENTS OF AN RTF FILE

An RTF file has the following syntax:

This syntax is the standard RTF syntax; any RTF reader must be able to correctly interpret RTF written to this syntax. It is worth mentioning again that RTF readers do not have to use all control words, but they must be able to harmlessly ignore unknown (or unused) control words, and they must correctly skip over destinations marked with the \* control symbol. There may, however, be RTF writers that generate RTF that does not conform to this syntax, and as such, RTF readers should be robust enough to handle some minor variations. Nonetheless, if an RTF writer generates RTF conforming to this specification, then any correct RTF reader should be able to interpret it.

Header

The header has the following syntax:

<header>

Each of the various header tables should appear, if they exist, in the above order. Document properties can occur before and between the header tables. A property must be defined before being referenced. Specifically:

* The style sheet must occur before any style usage.

* The font table must precede any reference to a font.

* The \deff keyword must precede any text without an explicit reference to a font, because it specifies the font to use in such cases.

RTF Version

An entire RTF file is considered a group and must be enclosed in braces. The \rtfN control word must follow the opening brace. The numeric parameter N identifies the major version of the RTF Specification used. The RTF standard described in this Application Note, although titled as version 1.5, continues to correspond syntactically to RTF Specification version 1. Therefore, the numeric parameter N for the \rtf control word should still be emitted as 1.

Character Set

After specifying the RTF version, you must declare the character set used in this document. The control word for the character set must precede any plain text or any table control words. The RTF Specification currently supports the following character sets.

Unicode RTF

{\upr{keyword ansi_text}{\*\ud{keyword Unicode_text}}}

Document Text

Document text should be emitted as ANSI characters. If there are Unicode characters that do not have corresponding ANSI characters, they should be output using the \ucN and \uN keywords.

For example, the text Lab[Gamma]Value (Unicode characters 0x004c, 0x0061, 0x0062, 0x0393, 0x0056, 0x0061, 0x006c, 0x0075, 0x0065) should be represented as follows (assuming a previous \ucl):

Lab\u915Gvalue

Destination Text

Destination text is defined as any text represented in an RTF destination. A good example is the bookmark name in the \bkmkstart destination.

Any destination containing Unicode characters should be emitted as two destinations within a \upr destination to ensure that old readers can read it properly and that no Unicode character encoding is lost when read with a new reader.

For example, a bookmark name Lab[Gamma]Value (Unicode characters 0x004c, 0x0061, 0x0062, 0x0393, 0x0056, 0x0061, 0x006c, 0x0075, 0x0065) should be represented as follows:

{\upr{\*\bkmkstart LabGValue}{\*\ud{\*\bkmkstart Lab\u915 Value}}}

The first sub-destination contains only ANSI characters and is the representation that old readers will see. The second sub-destination is a \*\ud destination which contains a second copy of the \bkmkstart destination. This copy can contain Unicode characters and is the representation that Unicode-aware readers must pay attention to, ignoring the ANSI-only version.

Font Table

The \fonttbl control word introduces the font table group. Unique \fN control words define each font available in the document, and are used to reference that font throughout the document. This group has the syntax listed in the following table.

Note for <fontemb> that either <fontfname> or <data> must be present, although both may be present.

All fonts available to the RTF writer can be included in the font table, even if the document doesn't use all the fonts.

RTF also supports font families, so that applications can attempt to intelligently choose fonts if the exact font is not present on the reading system. RTF uses the following control words to describe the various font families.

If an RTF file uses a default font, the default font number is specified with the \deffN control word, which must precede the font-table group. The RTF writer supplies the default font number used in the creation of the document as the numeric argument N. The RTF reader then translates this number through the font table into the most similar font available on the reader's system.

The following control words specify the character set, alternative font name, pitch of a font in the font table, and non-tagged font name.

If \fprq is specified, the N argument can be one of the following values.

Font Embedding

RTF supports embedded fonts with the \fontemb group located inside a font definition. An embedded font can be specified by a file name, or the actual font data may be located inside the group. If a file name is specified, it is contained in the \fontfile group. The \cpg control word can be used to specify the character set for the file name.

RTF supports TrueType® and other embedded fonts. The type of the embedded font is described by the following control words.

Code Page Support

A font may have a different character set from the character set of the document. For example, the Symbol font has the same characters in the same positions both on the Macintosh and in Windows. RTF describes this with the \cpg control word, which names the character set used by the font. In addition, file names (used in field instructions and in embedded fonts) may not necessarily be the same as the character set of the document; the \cpg control word can change the character set for these file names as well. However, all RTF documents must still declare a character set (that is, \ansi, \mac, \pc, or \pca) to maintain backward compatibility with earlier RTF readers.

The table below describes valid values for \cpg.

File Table

The \filetbl control word introduces the file table destination. The only time a file table is created in RTF is when the document contains subdocuments. This group defines the files referenced in the document and has the following syntax:

Note that the file name can be any valid alphanumeric string for the named file system, indicating the complete path and file name.

Color Table

The \colortbl control word introduces the color table group, which defines screen colors, character colors, and other color information. This group has the following syntax:

The following are valid control words for this group.

Each definition must be delimited by a semicolon, even if the definition is omitted. If a color definition is omitted, the RTF reader uses its default color. The example below defines the default color table used by Word. The first color is omitted, as shown by the semicolon following the \colortbl control word. The missing definition indicates that color 0 is the `'auto'' color.

{\colortbl;\red0\green0\blue0;\red0\green0\blue255;\red0\green255\blue255;\red0\green255\blue0;\red255\green0\blue255;\red255\green0\blue0;\red255\green255\blue0;\red255\green255\blue255;\red0\green0\blue128;\red0\green128\blue128;\red0\green128\blue0;\red128\green0\blue128;\red128\green0\blue0;\red128\green128\blue0;\red128\green128\blue128;\red192\green192\blue192;}

The foreground and background colors use indexes into the color table to define a color. For more information on color setup, see your Windows documentation.

The following example defines a block of text in color (where supported). Note that the cf/cb index is the index of an entry in the color table, which represents a red/green/blue color combination.

{\f1\cb1\cf2 This is colored text. The background is color

1 and the foreground is color 2.}

If the file is translated for software that does not display color, the reader ignores the color table group.

Style Sheet

The \stylesheet control word introduces the style sheet group, which contains definitions and descriptions of the various styles used in the document. All styles in the document's style sheet can be included, even if not all the styles are used. In RTF, a style is a form of shorthand used to specify a set of character, paragraph, or section formatting.

The style-sheet group has the following syntax:

For <style>, both <styledef> and <stylename> are optional; the default is paragraph style 0. Note for <stylename> that Microsoft Word for the Macintosh interprets commas in #PCDATA as separating style synonyms. Also, for <key>, the data must be exactly one character.

(on the Format menu, click Styles).

The following is an example of an RTF style sheet

{\stylesheet{\fs20 \sbasedon222\snext0{\*\keycode \shift\ctrl n} 

Normal;}{\s1\qr \fs20 \sbasedon0\snext1 FLUSHRIGHT;}{\s2\fi-720\li720\fs20\ri2880\sbasedon0\snext2 IND;}}

and RTF paragraphs to which the styles are applied:

\widowctrl\ftnbj\ftnrestart \sectd \linex0\endnhere \pard\plain 

\fs20 This is Normal style.

\par \pard\plain \s1\qr\fs20

This is right justified. I call this style FLUSHRIGHT.

\par \pard\plain \s2\fi-720\li720\fs20\ri2880

This is an indented paragraph. I call this style IND. It produces 

a hanging indent.

\par}

Some of the control words in this example are discussed in later sections. In the example, note that the properties of the style were emitted following the application of the style. This was done for two reasons: (1) to allow RTF readers that don't support styles to still retain all formatting; and, (2) to allow the additive model for styles, where additional property changes are "added" on top of the defined style. Some RTF readers may not "apply" a style upon only encountering the style number without the accompanying formatting information because of this.

List Table

Word 97 stores bullets and numbering information very differently from earlier versions of Word. In Word 6.0, for example, number formatting data is stored individually with each paragraph. In Word 97, however, all of the formatting information is stored in a pair of document-wide list tables which act as a style sheet, and each individual paragraph stores only an index to one of the tables, like a style index.

There are two list tables in Word: the List table (destination \listtable), and the List Override table (destination \listoverridetable).

The first table Word stores is the List table. A List table is a list of lists (destination \list). Each list contains a number of list properties that pertain to the entire list, and a list of levels (destination \listlevel), each of which contains properties that pertain only to that level.

Top-level List Properties

List Levels

Each list consists of either one or nine list levels depending upon whether the \listsimple flag is set. Each list level contains a number of properties that specify the formatting for that level, such as the start-at value, the text string surrounding the number, its justification and indents, and so on.

{\levelnumbers \'01\'03\'05}

In addition to all of these properties, each list level can contain any character properties (all of which affect all text for that level) and any combination of three paragraph properties: left indents, first line left indents, and tabs--each of which must be of a special type: jclisttab. These paragraph properties will be automatically applied to any paragraph in the list.

List Override Table

The List Override table is a list of list overrides (destination \listoverride). Each list override contains the listid of one of the lists in the List table, as well as a list of any properties it chooses to override. Each paragraph will contain a list override index (keyword ls) which is a 1-based index into this table. Most list overrides don't override any properties--instead, they provide a level of indirection to a list. There are generally two types of list overrides: (1) formatting overrides, which allow a paragraph to be part of a list and are numbered along with the other members of the list, but have different formatting properties; and, (2) start-at overrides, which allow a paragraph to share the formatting properties of a list, but have a different start-at values. The first element in the document with each list override index takes the start-at value that the list override specifies as its value, while each subsequent element is assigned the number succeeding the previous element of the list.

List overrides have a few top-level keywords, including a \listoverridecount, which contains a count of the number of levels whose format is overridden. This \listoverridecount should always be either 1 or 9, depending upon whether the list to be overridden is simple or multilevel. All of the actual override information is stored within a list of list override levels (destination \lfolevel).

List Override Level

Each list override level contains flags to specify whether the formatting or start-at values are being overridden for each level. If the format flag (listoverrideformat) is given, the lfolevel should also contain a list level (listlevel). If the start-at flag (listoverridestart) is given, a start-at value must be provided. If the start-at is overridden but the format is not, then a levelstartat should be provided in the lfolevel itself. If both start-at and format are overridden, put the levelstartat inside the listlevel contained in the lfolevel.

Track Changes (Revision Marks)

This table allows tracking of multiple authors and reviewers of a document, and is used in conjunction with the character properties for tracking changes (using revision marks).

CurrentAuthor\'00\'<length of previous author's name>PreviousAuthor\'00

PreviousRevisionTime

All time references for revision marks use the following bit field structure, DTTM.

Document Area

Once the RTF header is defined, the RTF reader has enough information to correctly read the actual document text. The document area has the following syntax.

Information Group

The \info control word introduces the information group, which contains information about the document. This can include the title, author, keywords, comments, and other information specific to the file. This information is for use by a document-management utility, if available.

This group has the following syntax.

Some applications, such as Word, ask the user to type this information when saving the document in its native format. If the document is then saved as an RTF file or translated into RTF, the RTF writer specifies this information using the following control words. These control words are destinations and both the control words and the text should be enclosed in braces ({ }).

The \userprops control word introduces the user-defined document properties. Unique \propname control words define each user-defined property in the document. The group has the following syntax.

For \proptype, the N argument can have the following values.

The RTF writer may automatically enter other control words, including the following.

Any control word described in the previous table that does not have a numeric parameter specifies a date; all dates are specified with the \yr \mo \dy \hr \min \sec controls. An example of an information group follows:

{\info{\title The Panda's Thumb}{\author Stephen J Gould}{\keywords 
science natural history }}

Document Formatting Properties

After the information group (if there are any), there may be some document formatting control words (described as <docfmt> in the document area syntax description). These control words specify the attributes of the document, such as margins and footnote placement. These attributes must precede the first plain-text character in the document.

The control words that specify document formatting are listed in the following table (measurements are in twips; a twip is one-twentieth of a point). For omitted control words, RTF uses the default values.

Note that the three document-protection control words (\formprot, \revprot, and \annotprot) are mutually exclusive; only one of the three can apply to any given document. Also, there is currently no method for storing passwords in RTF, so any document that associates a password with a protection level will lose the password protection in RTF.

For more information about bidirectional controls, see "Bidirectional Language Support" in this Application Note.

The color, width, border style, and border spacing keywords for page borders are the same as the keywords defined for paragraph borders.

Section Text

Each section in the RTF file has the following syntax:

Section Formatting Properties

At the beginning of each section, there may be some section-formatting control words (described as <secfmt> in the section text syntax description). These control words specify section-formatting properties, which apply to the text following the control word, with the exception of the section-break control words (those beginning with \sbk). Section-break control words describe the break preceding the text. These control words can appear anywhere in the section, not just at the start.

Note that if the \sectd control word is not present, the current section inherits all section properties defined in the previous section.

The section-formatting control words are listed in the following table.

The color, width, border style, and border spacing keywords for page borders are the same as the keywords defined for paragraph borders.

Headers and Footers

Headers and footers are RTF destinations. Each section in the document can have its own set of headers and footers. If no headers or footers are defined for a given section, the headers and footers from the previous section (if any) are used. Headers and footers have the following syntax:

Note that each separate <hdrftr> group must have a distinct <hdrctl> introducing it.

The \headerl, \headerr, \footerl, and \footerr control words are used in conjunction with the \facingp control word, and the \headerf and \footerf control words are used in conjunction with the \titlepg control word. Many RTF readers will not function correctly if the appropriate document properties are not set. In particular, if \facingp is not set, then only \header and \footer should be used; if \facingp is set, then only \headerl, \headerr, \footerl, and \footerr should be used. Combining both \facingp and \titlepg is allowed. You should not use \header to set the headers for both pages when \facingp is set. You can use \headerf if \titlepg is not set, but no header will appear. For more information, see "Document Formatting Properties" on page 20 and "Section Formatting Properties" on page 26 of this Application Note.

If the previous section had a first page header or footer and had \titlepg set, and the current section does not, then the previous section's first page header or footer is disabled. However, it is not destroyed; if subsequent sections have \titlepg set, then the first page header or footer is restored.

Paragraph Text

There are two kinds of paragraphs: plain and table. A table is a collection of paragraphs, and a table row is a continuous sequence of paragraphs partitioned into cells. The \intbl paragraph-formatting control word identifies the paragraph as part of a table. For more information, see "Table Definitions" on page 40 of this Application Note. This control is inherited between paragraphs that do not have paragraph properties reset with \pard.

Paragraph Formatting Properties

These control words (described as <parfmt> in the paragraph-text syntax description) specify generic paragraph formatting properties. These control words can appear anywhere in the body of the paragraph, not just at the beginning.

Note that if the \pard control word is not present, the current paragraph inherits all paragraph properties defined in the previous paragraph.

The paragraph-formatting control words are listed in the following table.

Tabs

Any paragraph may have its own set of tabs. Tabs must follow this syntax:

Bullets and Numbering

Word 6.0/95 RTF

To provide compatibility with existing RTF readers, all applications that can automatically format paragraphs with bullets or numbers will also emit the generated text as plain text in the \pntext group. This will allow existing RTF readers to capture the plain text and safely ignore the autonumber instructions. This group precedes all bulleted or numbered paragraphs, and will contain all the text and formatting that would be auto-generated. It should precede the '{'\*\pn ... '}' destination, and it is the responsibility of RTF readers that understand the '{'\*\pn ... '}' destination to ignore the \pntext group.

Settings below marked with an asterisk can be turned off by appending 0 to the control word.

Note that there is a limit of 32 characters total for the sum of text before and text after for simple numbering. Multilevel numbering has a limit of 64 characters total for the sum of all levels.

Word 97 RTF

Each paragraph that is part of a list must contain some keyword to indicate which list it's in, and which level of the list it belongs to. Word 97 also provides the flat text representation of each number (in the \listtext destination); so, RTF readers that don't understand Word 97 numbering will get the paragraph number, along with appropriate character properties, inserted into their document at the beginning of the paragraph. Any RTF reader that does understand Word 97 numbering should ignore the entire \listtext destination.

REVISION MARKS FOR PARAGRAPH NUMBERS

Paragraph numbers and ListNum fields track revision information with special properties applied to the paragraph mark and ListNum field, respectively. The special properties hold the "old" value of the number--the value it held when revision-mark tracking began. At display time, Word checks the number's current value and compares it with this "old" value to tell if it has changed. If the numbers are different, the old value shows up as deleted and the new value as inserted; if the numbers are the same, Word displays the new value normally, with no revision information. If there was no old value, the new value shows up as inserted. The following table lists the RTF specifications for these special properties.

Example:

Let's take an example of the number "3-4b." which represents the third level of the list. The following table lists the values of each array.

Here is the RTF for this number:

\pnrstart0

\pnrxst0\pnrxst5\pnrxst0\pnrxst1\pnrxst0\pnrxst45\pnrxst0\pnrxst2\pnrxst0\pnrxst3\pnrxst0\pnrxst46

\pnrstop12

\pnrstart1

\pnrrgb1\pnrrgb3\pnrrgb4

\pnrrgb0\pnrrgb0\pnrrgb0

\pnrrgb0\pnrrgb0\pnrrgb0

\pnrstop9

\pnrstart2

\pnrnfc0\pnrnfc0\pnrnfc0\pnrnfc0\pnrnfc0\pnrnfc4

\pnrnfc0\pnrnfc0\pnrnfc0\pnrnfc0\pnrnfc0\pnrnfc0

\pnrnfc0\pnrnfc0\pnrnfc0\pnrnfc0\pnrnfc0\pnrnfc0

\pnrstop18

\pnrstart3

\pnrpnbr0\pnrpnbr0\pnrpnbr0\pnrpnbr3

\pnrpnbr0\pnrpnbr0\pnrpnbr0\pnrpnbr4

\pnrpnbr0\pnrpnbr0\pnrpnbr0\pnrpnbr2

\pnrpnbr0\pnrpnbr0\pnrpnbr0\pnrpnbr0

\pnrpnbr0\pnrpnbr0\pnrpnbr0\pnrpnbr0

\pnrpnbr0\pnrpnbr0\pnrpnbr0\pnrpnbr0

\pnrpnbr0\pnrpnbr0\pnrpnbr0\pnrpnbr0

\pnrpnbr0\pnrpnbr0\pnrpnbr0\pnrpnbr0

\pnrpnbr0\pnrpnbr0\pnrpnbr0\pnrpnbr0

\pnrstop36

Example:

Let's take the sample example from above. The deleted value is "3-4b." The RTF would then be

\dfrstart0\dfrxst0\dfrxst5\dfrxst0\dfrxst51\dfrxst0\dfrxst45\dfrxst0\dfrxst52

\dfrxst0\dfrxst66\dfrxst0\dfrxst46\dfrstop10

where 5 is the length byte, 51 is Unicode for "3", 45 is Unicode for "-", 52 is Unicode for "4", and so on.

Paragraph Borders

Paragraph borders have the following syntax:

Paragraph Shading

Paragraph shading has the following syntax:

Positioned Objects and Frames

The following paragraph-formatting control words specify the location of a paragraph on the page. Consecutive paragraphs with the same frame formatting are considered part of the same frame. For two framed paragraphs to appear at the same position on a page, they must be separated by a paragraph with different or no frame information.

Note that if any paragraph in a table row has any of these control words specified, then all paragraphs in the table row must have the same control words specified, either by inheriting the properties from the previous paragraph or by re-specifying the controls.

Paragraph positioning has the following syntax:

The following is an example of absolute-positioned text in a document:

\par \pard \pvpg\phpg\posxc\posyt\absw5040\dxfrtest173 First APO para
\par \pard \phmrg\posxo\posyc\dxfrtext1152 Second APO para

Table Definitions

There is no RTF table group; instead, tables are specified as paragraph properties. A table is represented as a sequence of table rows. A table row is a continuous sequence of paragraphs partitioned into cells. The table row begins with the \trowd control word and ends with the \row control word. Every paragraph that is contained in a table row must have the \intbl control word specified or inherited from the previous paragraph. A cell may have more than one paragraph in it; the cell is terminated by a cell mark (the \cell control word), and the row is terminated by a row mark (the \row control word). Table rows can also be positioned. In this case, every paragraph in a table row must have the same positioning controls (see the <apoctl> controls on page 29 of this Application Note). Table properties may be inherited from the previous row; therefore, a series of table rows may be introduced by a single <tbldef>.

An RTF table row has the following syntax, as shown in the general paragraph-text syntax shown on page 23 of this Application Note.

A table definition has the following syntax:

Note for <tbldef> that the number of \cellxs must match the number of \cells in the \row.

The following control words further define options for each row of the table.

The following is an example of table text:

\par \trowd \trqc\trgaph108\trrh280\trleft36
\clbrdrt\brdrth \clbrdrl\brdrth \clbrdrb\brdrdb
\clbrdrr\brdrdb \cellx3636\clbrdrt\brdrth
\clbrdrl\brdrdb \clbrdrb\brdrdb \clbrdrr\brdrdb
\cellx7236\clbrdrt\brdrth \clbrdrl\brdrdb
\clbrdrb\brdrdb \clbrdrr\brdrdb \cellx10836\pard \intbl
\cell \pard \intbl \cell \pard \intbl \cell \pard \intbl \row
\trowd \trqc\trgaph108\trrh280\trleft36 \clbrdrt\brdrdb
\clbrdrl\brdrth \clbrdrb \brdrsh\brdrs \clbrdrr\brdrdb
\cellx3636\clbrdrt\brdrdb \clbrdr \brdrdb
\clbrdrb\brdrsh\brdrs \clbrdrr\brdrdb
\cellx7236\clbrdrt\brdrdb \clbrdr \brdrdb
\clbrdrb\brdrsh\brdrs \clbrdrr\brdrdb \cellx10836\pard
\intbl \cell \pard \intbl \cell \pard \intbl \cell \pard
\intbl \row \pard