Microsoft¨ MS-DOS¨, WindowsTM, OS/2¨, ¨ and Apple¨ Macintosh¨ Applications Versions: RTF Version 1.3 Product Support Services Subject: Rich Text Format (RTF) Specification Application Note 1/94 GC0165 INTRODUCTION The Rich Text Format (RTF) Specification is a method of encoding formatted text and graphics for easy transfer between applications. Currently, users depend on special translation software to move word-processing documents between different MS-DOS, Windows, OS/2, and Apple Macintosh applications. The RTF Specification provides a format for text and graphics interchange that can be used with different output devices, operating environments, and operating systems. RTF uses the ANSI, PC-8, Macintosh, or IBM¨ PC character set to control the representation and formatting of a document, both on the screen and in print. With the RTF Specification, documents created under different operating systems and with different software applications can be transferred between those operating systems and applications. Software that takes a formatted file and turns it into an RTF file is called a writer. An RTF writer separates the application's control information from the actual text and writes a new file containing the text and the RTF groups associated with that text. Software that translates an RTF file into a formatted file is called a reader. RTF SYNTAX An RTF file consists of unformatted text, control words, control symbols, and groups. For ease of transport, a standard RTF file can consist of only 7-bit ASCII characters. (Converters that communicate with Microsoft Word for Windows or Microsoft Word for the Macintosh should expect 8-bit characters.) A control word is a specially formatted command that RTF uses to mark printer control codes and information that applications use to manage documents. A control word takes the following form: \LetterSequence Note that a backslash begins each control word. The LetterSequence is made up of lowercase alphabetic characters between "a" and "z" inclusive. RTF is case sensitive, and all RTF control words must be in lowercase. The Delimiter marks the end of an RTF control word, and can be one of the following: * A space. In this case, the space is part of the control word. * A digit or a hyphen (-), which indicates that a numeric parameter follows. The subsequent digital sequence is then delimited by a space or any character other than a letter or a digit. The parameter can be a positive or a negative number. The range of the values for the number is -32767 through 32767. However, Microsoft Word for Windows, Word for OS/2, and Word for the Macintosh restrict the range to -31680 through 31680. If a numeric parameter immediately follows the control word, this parameter becomes part of the control word. The control word is then delimited by a space or a nonalphabetic or nonnumeric character in the same manner as any other control word. * Any character other than a letter or a digit. In this case, the delimiting character terminates the control word but is not actually part of the control word. If a space delimits the control word, the space does not appear in the document. Any characters following the delimiter, including spaces, will appear in the document. For this reason, you should use spaces only where necessary; do not use spaces merely to break up RTF code. A control symbol consists of a backslash followed by a single, nonalphabetic character. For example, \~ represents a nonbreaking space. Control symbols take no delimiters. A group consists of text and control words or control symbols enclosed in braces ({ }). The opening brace ({ ) indicates the start of the group and the closing brace ( }) indicates the end of the group. Each group specifies the text affected by the group and the different attributes of that text. The RTF file can also include groups for fonts, styles, screen color, pictures, footnotes, annotations, headers and footers, summary information, fields, and bookmarks, as well as document-, section-, paragraph-, and character-formatting properties. If the font, file, style, screen-color, revision mark, and summary-information groups and document-formatting properties are included, they must precede the first plain-text character in the document. These groups form the RTF file header. If the group for fonts is included, it should precede the group for styles. If any group is not used, it can be omitted. The groups are discussed in the following sections. The control properties of certain control words (such as bold, italic, keep together, and so forth) have only two states. When such a control word has no parameter or has a nonzero parameter, it is assumed that the control word turns on the property. When such a control word has a parameter of 0 (zero), it is assumed that the control word turns off the property. For example, \b turns on bold, whereas \b0 turns off bold. Certain control words, referred to as destinations, mark the beginning of a collection of related text that could appear at another position, or destination, within the document. Destinations may also be text that is used but should not appear within the document at all. An example of a destination is the \footnote group, where the footnote text follows the control word. Destination control words and their following text must be enclosed in braces. Destinations added after the RTF Specification published in the March 1987 Microsoft Systems Journal may be preceded by the control symbol \*. This control symbol identifies destinations whose related text should be ignored if the RTF reader does not recognize the destination. (RTF writers should follow the convention of using this control symbol when adding new destinations or groups.) Destinations whose related text should be inserted into the document even if the RTF reader does not recognize the destination should not use \*. All destinations that were not included in the March 1987 revision of the RTF Specification are shown with \* as part of the control word. Formatting specified within a group affects only the text within that group. Generally, text within a group inherits the formatting of the text in the preceding group. However, Microsoft implementations of RTF assume that the footnote, annotation, header, and footer groups (described later in this chapter) do not inherit the formatting of the preceding text. Therefore, to ensure that these groups are always formatted correctly, you should set the formatting within these groups to the default with the \sectd, \pard, and \plain control words, and then add any desired formatting. The control words, control symbols, and braces constitute control information. All other characters in the file are plain text. Here is an example of plain text that does not exist within a group: {\rtf\ansi\deff0{\fonttbl{\f0\froman Tms Rmn;}{\f1\fdecor Symbol;}{\f2\fswiss Helv;}}{\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;}{\stylesheet{\fs20 \snext0Normal;}}{\info{\author John Doe} {\creatim\yr1990\mo7\dy30\hr10\min48}{\version1}{\edmins0} {\nofpages1}{\nofwords0}{\nofchars0}{\vern8351}}\widoctrl\ftnbj \sectd\linex0\endnhere \pard\plain \fs20 This is plain text.\par} The phrase "This is plain text" is not part of a group and is treated as document text. As previously mentioned, the backslash ( \) and braces ({ }) have special meaning in RTF. To use these characters as text, precede them with a backslash, as in \\, \{, and \}. CONVENTIONS OF AN RTF READER 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. Action Description Change Destination The RTF reader changes the destination to the destination described in the table entry. Destination changes are legal only immediately after an opening brace ({ ). (Other restrictions may also apply; for example, footnotes cannot be nested.) Many destination changes imply that the current property settings will be reset to their default settings. Examples of control words that change destination are \footnote, \header, \footer, \pict, \info, \fonttbl, \stylesheet, and \colortbl. This Application Note identifies all destination control words where they appear in control-word tables. Change Formatting Property The RTF reader changes the property as described in the table entry. The entry will specify whether a parameter is required. The "Index of RTF Control " section at the end of this Application Note also specifies which control words require parameters. If a parameter is needed and not specified, then a default value will be used. The default value used depends on the control word. If the control word does not specify a default, then all RTF readers should assume a default of 0. Insert Special Character The reader inserts into the document the character code or codes described in the table entry. Insert Special Character and The reader inserts into the document the character code or codes described Perform Action in the table entry and performs whatever other action the entry specifies. For example, when Microsoft Word interprets \par, a paragraph mark is inserted in the document and special code is run to record the paragraph properties belonging to that paragraph mark. FORMAL SYNTAX This Application Note describes RTF using the following syntax, based on Backus-Naur Form. Syntax Meaning #PCDATA Text (without control words). #SDATA Hexadecimal data. #BDATA Binary data. 'c' A literal. A nonterminal. a The (terminal) control word a, without a parameter. a or aN The (terminal) control word a, with a parameter. a? Item a is optional. a+ One or more repetitions of item a. a* Zero or more repetitions of item a. a b Item a followed by item b. a | b Item a or item b. a & b Item a and/or item b, in any order. 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:
\rtf \deff? ? ? ? ? RTF Version An entire RTF file is considered a group and must be enclosed in braces. The control word \rtfN 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.2, 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. Control word Character set \ansi ANSI (the default) \mac Apple Macintosh \pc IBM PC code page 437 \pca IBM PC code page 850, used by IBM Personal System/2¨ (not implemented in version 1 of Microsoft Word for OS/2) 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 following syntax: '{' \fonttbl ( | ('{' '}'))+ '}' ???? ? ';' \f \fnil | \froman | \fswiss | \fmodern | \fscript | \fdecor | \ftech | \fbidi \fcharset \fprq #PCDATA '{\*' \falt #PCDATA '}' '{\*' \fontemb ? ? '}' \ftnil | \fttruetype '{\*' \fontfile ? #PCDATA '}' \c p g Note for that either or 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. Control word Font family Examples \fnil Unknown or default fonts (the default) \froman Roman, proportionally spaced serif fonts Times New Roman¨, Palatino¨ \fswiss Swiss, proportionally spaced sans serif fonts Arial¨ \fmodern Fixed-pitch serif and sans serif fonts Courier New¨, Pica \fscript Script fonts Cursive \fdecor Decorative fonts Old English, ITC Zapf Chancery¨ \ftech Technical, symbol, and mathematical fonts Symbol \fbidi Arabic, Hebrew, or other bidirectional font Miriam 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 and pitch of a font in the font table. Control word Definition \fcharsetN Specifies the character set of a font in the font table. \falt Indicates alternate font name to use if the specified font in the font table is not available. '{\*' \falt '}' \fprqN Specifies the pitch of a font in the font table. If \fcharset is specified, the N argument can be one of the following types. Character set N Value ANSI_CHARSET 0 SYMBOL_CHARSET 2 SHIFTJIS_CHARSET 128 GREEK_CHARSET 161 TURKISH_CHARSET 162 HEBREW_CHARSET 177 ARABICSIMPLIFIED_CHARSET 178 ARABICTRADITIONAL_CHARSET 179 ARABICUSER_CHARSET 180 HEBREWUSER_CHARSET 181 CYRILLIC_CHARSET 204 EASTERNEUROPE_CHARSET 238 PC437_CHARSET 254 OEM_CHARSET 255 If \fprq is specified, the N argument can be one of the following values. Pitch Value Default pitch 0 Fixed pitch 1 Variable pitch 2 Font Embedding RTF supports embedded fonts with the \fontemb group located inside a font definition. An embedded font can be specified by a filename, or the actual font data may be located inside the group. If a filename is specified, it is contained in the \fontfile group. The \cpg control word can be used to specify the character set for the filename. RTF supports TrueType and other embedded fonts. The type of the embedded font is described by the following control words. Control word Embedded font type \ftnil Unknown or default font type (the default) \fttruetype TrueType font 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, filenames (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 filenames as well. However, all RTF documents must still declare a character set (that is, \ansi, \mac, \pc, or \pca) to maintain backwards compatibility with earlier RTF readers. The table below describes valid values for \cpg. Value Description 437 United States IBM 708 Arabic (ASMO 708) 709 Arabic (ASMO 449+, BCON V4) 710 Arabic (transparent Arabic) 711 Arabic (Nafitha Enhanced) 720 Arabic (transparent ASMO) 819 Windows 3.1 (United States and Western Europe) 850 IBM multilingual 852 Eastern European 860 Portuguese 862 Hebrew 863 French Canadian 864 Arabic 865 Norwegian 866 Soviet Union 932 Japanese 1250 Windows 3.1 (Eastern European) 1251 Windows 3.1 (Cyrillic) File Table The \filetbl control word introduces the file table destination. This group defines the files referenced in the document and has the following syntax: '{\*' \filetbl ('{' '}')+ '}' \file ?? + \fid \frelative \fosnum \fvalidmac | \fvaliddos | \fvalidntfs | \fvalidhpfs | \fnetwork #PCDATA Note that the filename can be any valid alphanumeric string for the named file system, indicating the complete path and filename. Control word Definition \filetbl A list of documents referenced by the current document. The file table has a structure analogous to the style or font table. This is a destination control word output as part of the document header. \file Marks the beginning of a file group, which lists relevant information about the referenced file. This is a destination control word. \fidN File ID number. Files are referenced later in the document using this number. \frelativeN The character position within the path (starting at 0 [zero]) where the referenced file's path starts to be relative to the path of the owning document. For example, a document is saved to the path C:\PRIVATE\RESUME\FILE1.DOC and its file table contains the path C:\PRIVATE\RESUME\EDU\FILE2.DOC, then that entry in the file table will be \frelative18, to point at the character "e" in "edu". This allows preservation of relative paths. \fosnumN Currently only filled in for paths from the Macintosh file system. It is an operating-system- specific number for identifying the file, which may be used to speed up access to the file, or find it if the file has been moved to another folder or disk. The Macintosh operating system name for this number is the "file id." Additional meanings of the \fosnumN control word may be defined for other file systems in the future. \fvalidmac Macintosh file system. \fvaliddos MS-DOS file system. \fvalidntfs NTFS file system. \fvalidhpfs HPFS file system. \fnetwork Network file system. This control word may be used in conjunction with any of the previous file source control words. 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: '{' \colortbl + '}' \red ? & \green ? & \blue ? ';' The following are valid control words for this group. Control word Meaning \redN Red index \greenN Green index \blueN Blue index 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. In the example below, three colors are defined. The first color is omitted, as shown by the semicolon following the \colortbl control word. {\colortbl;\red0\green0\blue0;\red0\green0\blue255;} 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: '{' \stylesheet