RTF::Cookbook(3pm) User Contributed Perl Documentation RTF::Cookbook(3pm)
NAME
The_RTF_Cookbook -- RTF overview and quick reference
SYNOPSIS
# Time-stamp: "2003-09-23 21:27:56 ADT"
# This document is in Perl POD format, but you can read it
# with just an ASCII text viewer, if you want.
DESCRIPTION
RTF is a nearly ubiquitous text formatting language devised by Microsoft. Microsoft's Rich Text Format Specification is widely available,
but it's usable mainly just as a reference for the language's entire command set.
This short document, however, is meant as a quick reference and overview. It is meant for people interested in writing programs that
generate a minimal subset of RTF.
NOTE : I've mostly superceded this document with my book RTF Pocket Guide, which is much longer and more comprehensive -- see
<http://www.oreilly.com/catalog/rtfpg/>
INTRODUCTION
RTF code consists of plaintext, commands, escapes, and groups:
Plaintext contains seven bit (US ASCII) characters except for , {, and }. Returns and linefeeds can be present but are ignored, and are
harmless (as long as they are not in the middle of an RTF command). Space (ASCII 0x20) characters are significant -- five spaces means
five spaces. (The only exception is a space that ends an RTF command; such a space is ignored.) Example of plaintext: "I like pie".
An RTF command consists of a backslash, then some characters a-z, and then an optional positive or negative integer argument. The command
is then terminated either by a space, return, or linefeed (all of which are ignored), or by some character (like brace or backslash, etc.)
that couldn't possibly be a continuation of this command. A simple rule of thumb for emitting RTF is that every command should be
immediately followed either by a space, return, or linefeed, (as in "foo bar"), or by another command (as in "fooar"). Examples of RTF
commands: "page" (command "page" with no parameter), "f3" (command "f" with parameter 3), "li-320" (command "li" with parameter -320).
An RTF escape consists of a backslash followed by something other than a letter. There are few of these in the language, and the basic
ones to know now are the two-byte long escape sequences: {, }, \ (to convey a literal openbrace, closebrace, or backslash), and the only
four-byte-long escape sequence, 'xx, where xx is two hexadecimal digits. This is used for expressing any byte value in a document. For
example, x'BB expresses character value BB (decimal 187), which for Latin-1/ANSI is close-angle-quote (which looks like a little ">>").
An RTF group consists of an openbrace "{", any amount of RTF code (possibly including other groups), and then a closebrace "}". Roughly
speaking, you can treat an RTF group as the conceptual equivalent of an SGML element. Effectively, a group limits the scope of commands in
that group. So if you're in a group and you turn on italics, then that can apply only as far as the end of the group -- regardless of
whether you do this at the start of the group, as in {i I like pie}, or the middle, as in {I like i pie}. Note that you must emit just
as many openbraces as closebraces -- otherwise your document is syntactally invalid, and RTF readers will not tolerate that.
This is an example of a paragraph using plaintext, escapes, commands, and groups:
{pardfs32 NOTESpar}
{pardfs26 Recently I skimmed {i Structure and Interpretation of
Computer Programs}, by Sussman and Abelson, and I think there should
have been more pictures.
line I like pictures. Is that so na'efve?
par}
('ef makes an i-dieresis, in the Latin-1/ANSI character set.)
Note that "foo[newline]bar" isn't the same as "foo bar", it's the same as "foobar", because the newline is ignored. So if you mean "foo
bar", and want to work in a newline, you should consider "foo[newline] bar", or "foo [newline]bar", or even things like "fo[newline]o bar".
Note that newlines aren't needed in your output file at all, and there's no reason to get your RTF code to be wrapped at 72 columns or
anywhere else; but it's very useful to be able to open a RTF file in a plaintext editor and see something other than a giant sea of
unbroken text. So at the very least, I emit a newline before every paragraph.
(Note that if you are ambitiously trying to wrap your RTF code by inserting newlines, consider that just about the only really harmful
places to insert a newline are in the middle of a command or an escape -- because "pa[newline]ge" doesn't mean the same as "page", it
means the same as "pa ge" (i.e., a pa command, and then two text characters "ge"); and "'f[newline]8" is not good RTF. So I suggest
making wrapping algorithms insert a newline only after a space character -- a guaranteed safe spot.)
Twips
Measurements in RTF are generally in twips. A twip is a twentieth of a point, i.e., a 1440th of an inch. That leads to some large numbers
sometimes (like li2160, to set the left indent to an inch and a half), but this table should be useful for conversions:
inches twips points centimeters
------ ------- ------ -----------
20 tw 1 pt
40 tw 2 pt
~57 tw .1cm
60 tw 3 pt
80 tw 4 pt
1/16" 90 tw 4.5 pts
100 tw 5 pts
~113 tw .2cm
1/9" 160 tw 8 pts
~170 tw .3cm
1/8" 180 tw 9 pts
1/7" ~206 tw ~10.3 pts
~227 tw .4cm
1/6" 240 tw 12 pts
3/16" 270 tw 13.5 pts
~283 tw .5cm
1/5" 288 tw 14.4 pts
~340 tw .6cm
1/4" 360 tw 18 pts
~397 tw .7cm
~454 tw .8cm
1/3" 480 tw 24 pts
~510 tw .9cm
~567 tw 1cm
1/2" 720 tw 36 pts
~850 tw 1.5cm
3/4 1080 tw 54 pts
~1134 tw 2cm
1" 1440 tw 72 pts
~1701 tw 3cm
1.5" 2160 tw 108 pts
~2268 tw 4cm
~2835 tw 5cm
2" 2880 tw 144 pts
~3402 tw 6cm
2.5" 3600 tw 180 pts
3" 4320 tw 216 pts
~5669 tw 10cm
4" 5760 tw 288 pts
5" 7200 tw 360 pts
(Conversions between centimeters and anything else are approximate, so figures with a preceding "~" have been rounded.)
RTF Document Structure
An RTF document consists of:
o a prolog, which starts with a "{", and then has essential information for the document
o then some optional document-formatting commands
o then any amount of commands, groups, plaintext, and escapes
o then a closing "}" (which closes the group opened by the start of the prolog).
RTF Prolog
A minimal RTF prolog looks like this:
{
tf1ansideff0{fonttbl{f0 Times New Roman;}}
This declares this file as being in RTF version 1 (the only version there is at time of writing), that the charset in use in ANSI
(Latin-1), the default font is the 0th entry in the font table (to follow). And then this declares a font table consisting only of one
entry, number 0, for Times New Roman.
A font table with three fonts might look like:
{
tf1ansideff0{fonttbl
{f0 Georgia;}
{f1 Braille Kiama;}
{f2 Courier New;}
}
Note that each font-name has to be followed by a semicolon. Recall that the newlines here ignored, and so are useful here only for
readability. But unlike most computer languages, you can't indent this (or any other part of an RTF document) with space characters or
tabs -- those would not be ignored!
A generally optional but sometimes necessary part of the prolog is a color table. This is a color table:
{colortbl;
ed255green0lue0;
ed0green0lue255;}
That declares three colors: a 0th entry, with null (default) color (expressed by the zero-length string between "colortbl" and ";"), then
a 1st entry, which is 100% red, and then a 2nd entry, which is 100% blue. (Note that each entry, whether null or
edNgreenNlueN, must
be followed by a semicolon.) A color table is necessary only if you need to change text foreground or background colors -- in that case,
you need to refer to entries in the color table. For more information, see the RTF spec. If you aren't changing text color in the
document, you needn't bother with a color table. (Some graphics options might involve the color table, but graphics is not discussed in
this document.)
RTF Document Formatting Commands
Then following the prolog, there are document-formatting codes -- i.e., codes that apply to the document as a whole. This section is often
left empty, but a commonly useful string is:
deflang1033widowctrl
That declares that the default language in the document is US English (for purposes of spellchecking and possibly hyphenation), and also
turns on widow-and-orphan control.
A useful bit of code that's worth emitting right after the document-formatting commands, is this:
{headerpardqrplainf0chpgnpar}
That turns on page numbering. Strictly speaking, it is not a document-formatting command, but a section-formatting command. However, as
"section" is not a concept addressed in this document, you can just think of that code as just something to be emitted before you start
your document content, and after any real document-formatting commands.
RTF Document Content
Document content is basically text (plaintext, commands, and escapes) in paragraphs (in the broad sense of "paragraph", including things
like headers). Although it's not necessary to put braces ("{...}") around each paragraph, it is often useful to do so, to keep character
formatting codes from bleeding into the next paragraph. Taking that approach, a basic paragraph looks like this:
{pard
...stuff...
par}
Here, pard signals that this paragraph shouldn't inherit paragraph-formatting attributes from the previous paragraph. (You're free to try
experimenting with leaving out the pard in order to inherit attributes, but I advise against it, as I find it leads to abstruse RTF and
hard-to-find bugs.) And par signals the end of this paragraph.
Paragraph-formatting attributes include justification (like qj for full justification), liN,
iN, and fiN for (respectively) paragraph
indenting on the left, paragraph indenting on the right, and left indenting for just the first line.
For example:
{pard
li1440
i1440fi480qj
A resource can be anything that has identity. Familiar
examples include an electronic document, an image, a service
(e.g., "today's weather report for Los Angeles"), and a
collection of other resources. Not all resources are network
"retrievable"; e.g., human beings, corporations, and bound
books in a library can also be considered resources.
par}
This sets left and right margins of 1 inch, and an additional first-line indenting of a third of an inch (480 twips), and full
justification. Formatted, it'll look like this:
A resource can be anything that has identity. Familiar
examples include an electronic document, an image, a service
(e.g., "today's weather report for Los Angeles"), and a
collection of other resources. Not all resources are network
"retrievable"; e.g., human beings, corporations, and bound
You can have a negative figure for first-line indenting, to give the effect of a "hanging paragraph":
{pard
li500fi-300
i200ql
{f2fs30 resource:} [jargon] {i n.} anything that has identity.
Familiar examples include an electronic document, an image, a
service (e.g., "today's weather report for Los Angeles"), and a
collection of other resources.
par
}
This says that the paragraph's left margin is 500 twips; the first line indent is -300 twips -- meaning 300 twips back from the paragraph's
left end (i.e., 200 twips from the page's left margin!); the right indent is 200 twips; and the paragraph is to be left-justified (i.e.,
with a ragged right edge).
Formatted, it'll look like this:
resource: [jargon] n. anything that has anything that has
identity. Familiar examples include an electronic
document, an image, a service (e.g., "today's weather
report for Los Angeles"), and a collection of other
resources.
If you want a newline in the middle of a paragraph (like a "<br>" in HTML), use the line command:
{parpardsb300sa300
my $x = "<<<><<<>><>><<>><>>>";line
print "[$x] initially'5cn";line
print "[$x]'5cn"line
while $x =~ s/<>//;line
print "[$x] finally'5cn";line
par}
That paragraph expresses a block of Perl code, with 300 twips of vertical space before it all, and 300 twips of vertical space after it
all.
Even headings are typically expressed as paragraphs:
{pard
qc
f3fs40 Section 1: The Larch
par}
This uses the qc code, for paragraph-centering, which is useful generally only in headings. The character-formatting codes used here are:
for bold, f3 to change to whatever is entry 3 in the font table, and fs40 to change the current point size to 20-point. The integer
parameter for the fsN command is in half-points, so that's why 40 means 20-point type. fsN is is one of the few commands in RTF (and the
only one that I mention here) that expresses size/distance in units other than twips.
Character formatting codes are given further below, and they are relatively straightforward.
RTF Conclusion
To conclude your document, you should emit a "}", and then close the file. That closebrace closes the group that the first character of
the file opened. Presumably that's all the groups you have to close.
FORMATTING CODES
The following are references for: 1) Character Formatting, 2) Paragraph and Block-Level Formatting, 3) Document Formatting, and 4)
Characters, Escapes, and Character Commands
Character Formatting
plain -- turn off all formatting
ul -- underline
-- bold
i -- italic
sub -- subscript
super -- superscript
fN -- change to font #N (where that's the number of a font declared
in the fonttable in the prolog)
fsN -- set current font size to N half-points
e.g., fs30 = 15 point
scaps -- smallcaps
strike -- strikethru
v -- hidden text (For comments?)
langN -- language N
US English: 1033 MX Spanish: 2058 French: 1036
Turkish: 1055 No language: 1024
oproof -- disable spellchecking here (not known to older RTF readers)
{superchftn}{footnotepardplainchftn. Foo!}
-- set an autonumbered footnote of "Foo!" hanging off of the current
point in the text
{field{*fldinst{HYPERLINK "http://www.suck.com/"}}{fldrslt{ul
stuff
}}}
-- make "stuff" a link to http://www.suck.com/
cfN -- select foreground color #N (from color table)
cbN -- select background color #N (from color table)
Paragraph and Block-Level Formatting
page -- pagebreak
line -- newline (not a real paragraph break)
ab -- tab (better than using a literal tab character)
par -- End this paragraph, and start a new one, inheriting paragraph
properties from the previous one.
(Note that par means END-paragraph, but if you treat it as it
if means start-paragraph, you won't break too many things.)
parpard -- End previous paragraph, and start a new one that doesn't
inherit paragraph properties from the previous one.
(The par ends the previous paragraph, the pard resets
the new paragraph's formatting attributes.)
ql -- left (i.e., no) justification
qr -- right-justify (i.e., align right)
qj -- full-justify (i.e., smooth margins on both sides)
qc -- center
liN -- left-indent this whole paragraph by N twips (default: 0)
iN -- right-indent this whole paragraph by N twips (default: 0)
fiN -- first-line left-indent this paragraph by N twips (default: 0)
(Note that this indenting is relative to the margin set by liN!)
(Note also that the above can have negative values.
E.g., fi-120 backdents (to the left!) the first line by
120 twips from the paragraph's left margin.)
sbN -- N twips of extra (vertical) space before this paragraph (default: 0)
saN -- N twips of extra (vertical) space after this paragraph (default: 0)
pagebb -- pagebreak before this paragraph
keep -- don't split up this paragraph (i.e., across pages)
keepn -- don't split up this paragraph from the next one
widctlpar -- widow-and-orphans control for this paragraph
(antonym:
owidctlpar)
{headerpardqrplainf0chpgnpar}
-- turn on page numbering. Lasts until next sectsectd.
colsN -- N newspaper-columns per page. Lasts until next sectsectd.
linebetcol -- show lines between columns.
sectsectd -- new section. (Resets header and columnation.)
Document Formatting
If you emit these, do it right after the prolog:
ftnbjftnrestart -- initialize footnote numbering
deflangN -- set the document's default language to N.
(See languageN, above)
widowctrl -- turn on widows-and-orphans control for the document
hyphcaps -- allow hyphenation of capitalized words (hyphcaps0 turns off)
hyphauto -- automatic hyphenation (hyphauto0 turns off)
pgnstartN -- for page numbering, set first page to N
marglN -- set left page-margin to N twips (default: 1800)
margrN -- set right page-margin to N twips (default: 1800)
margtN -- set top page-margin to N twips (default: 1440)
margbN -- set top page-margin to N twips (default: 1440)
landscape -- document is in landscape format
(i.e., it's sideways on the page)
Characters, Escapes, and Character Commands
[return] -- ignored (unless preceded by an escaping backslash)
[linefeed] -- ignored (unless preceded by an escaping backslash)
[space] -- a space (yes, space and tabs ARE significant whitespace)
[tab] -- a tab to the next tab stop. Use the command ab instead, or
consider expanding tabs to spaces.
(Setting tab stops is not covered in this document.)
'XX -- character with hex code XX (e.g., 'BB is character 187)
\ -- a backslash (same as '5c)
{ -- an open-brace (same as '7b)
} -- a close-brace (same as '7d)
~ -- non-breaking space
- -- optional hyphen (!)
\_ -- non-breaking hyphen
Remember that all of the following, unlike the above, are commands; and so you can't say, for example, "ulleta" to get a bullet and then
an "a". Instead, you'd need to have: "ullet a". Or "ullet", a newline, and "a".
ullet -- bullet character (same as Latin-1 character 149)
endash -- n-width dash
emdash -- m-width dash
enspace -- n-width non-breaking space
emspace -- m-width non-breaking space
lquote -- single openquote(6)
quote -- single closequote(9)
ldblquote -- double openquote(66)
dblquote -- double closequote(66)
SAMPLE COMPLETE RTF DOCUMENT
{
tf1ansideff0
{fonttbl
{f0 Times New Roman;}
}
deflang1033widowctrl
{headerpardqrplainf0{
oproofi La dame} p.chpgnpar}
lang1036fs36
{pardqcf1fs60i La damepar}
{pardsb300li900
Toc toc Il a ferm'e9 la porteline
Les lys du jardin sont fl'e9trisline
Quel est donc ce mort qu'on emporte
par}
{pardsb300li900
Tu viens de toquer 'e0 sa porteline
Et trotte trotteline
Trotte la petite souris
par}
{pardsb900li900scapsfs44
endash Guillaume Apollinaire, {i Alcools}par}
pagelang1033fs32
{pardulfs40 Vocabularypar}
{pardli300fi-150{
oproof toc }{i(n.m.)} endash tap; knockpar}
{pardli300fi-150{
oproof lys }{i(n.m.)} endash lilypar}
{pardli300fi-150{
oproof fl'e9trir }
{i(v.itr.)} endash to wilt; for a flower or beauty to fade;
for a plant to witherpar}
{pardli300fi-150{
oproof mort }
{i(adj., here used as a masc. noun)} endash deadpar}
{pardli300fi-150{
oproof emporter }
{i(v.tr.)} endash to take a person or thing [somewhere];
to take~[out/away/etc.] or carry~[away] a thingpar}
{pardli300fi-150{
oproof toquer }
{i(v.itr.)} endash to tap; to knockpar}
{pardli300fi-150{
oproof trotter }
{i(v.itr.)} endash to trot; to scurrypar}
{pardli300fi-150{
oproof souris }{i(n.f.)} endash mousepar}
{pardsb200ulfs40 Free Translationpar}
{pard
Click click He closed the door / Garden lilies faded / Which body is today
// You just tapped on the door / And tip toe / Taps the little mouse
line \_Translation Sean M. Burke, 2001
par}
}
NOTES
* This document does not discuss the RTF commands specific to the MSWin .HLP compiler.
* There may be slight differences in how the same RTF is interpreted by different word processors. For example, wordpad understands only a
subset of RTF. Also, the last version of WordPerfect that I dealt with (8.0) would occasionally apply margin-changing codes to more
paragraphs than the RTF actually said to. The most "reliable" rendering of RTF is generally what you get from MSWord, since RTF is after
all (as far as I can tell), a direct recapitulation of the MSWord's internal representation of documents.
* In this document, I don't cover embedding graphics in RTF, because it's a big old mess.
* A hint: if you're writing a program that generates RTF, and it runs happily, but the generated document crashes your word processor, then
make sure you've got as many {'s as }'s. If you represent literal openbrace and closebrace as '7b and '7d, then all "{"s in your RTF
code will be group-openers, all "}"s in RTF code will be group-closers, and there should be equal numbers of them. (They should also nest
properly, but most errors are detectable thru unequal numbers of braces.)
This bit of Perl code can be used to check a given file for matching {'s and }'s:
# Assuming all that literal {'s are encoded as '7b
# that all literal }'s are encoded as '7d
$/ = '}';
use strict;
my $stack = '';
my $open_count = my $close_count = 0;
while(<>) {
tr/{}//cd;
$open_count += tr/{//;
$close_count += tr/}//;
while( s/{}//g ) {1};
$stack .= $_;
}
while( $stack =~ s/{}//g ) {1}
print "$open_count x {
$close_count x }
",
length($stack) ? "Unbalanced.
" : "Balanced.
";
Altho note that this fails to trap the case where you close the document's top-level group and then open another (which you shouldn't do).
* I don't cover making tables here, because they're rather hard to do; because they're not really isomorphic with HTML tables or TeX tables
(just to name two models of tables that people know, and that are rather more sane than RTF); and also because messing up the code for
tables (as you are prone to do while experimenting with a writer-program) sometimes crashes MSWord! However, if you need to make tables,
you can mull over this code while referring to the murky explanation of tables in the RTF Spec:
{pard Hmmm par}
{pard
rowd rgaph300 rleft400cellx1500cellx3000cellx4500
pardintbl Wun. Doo wah ditty ditty dum ditty do cell
pardintbl Too. Doo wah ditty ditty dum ditty do cell
pardintbl Chree. Doo wah ditty ditty dum ditty do cell
ow
rowd rgaph300 rleft400cellx1500cellx3000cellx4500
pardintbl Foh. Doo wah ditty ditty dum ditty do cell
pardintbl Fahv. Doo wah ditty ditty dum ditty do cell
pardintbl Saxe. Doo wah ditty ditty dum ditty do cell
ow
rowd rgaph300 rleft400cellx1500cellx3500
pardintbl Saven. Doo wah ditty ditty dum ditty do cell
pardintbl Ight. Doo wah ditty ditty dum ditty do cell
ow
}
{pard I LIKE PIE}
COPYRIGHT AND DISCLAIMER
Copyright 2001,2,3 Sean M. Burke.
This document is not in the public domain, but you can redistribute this document and/or modify it under the same terms as Perl itself, as
explained in the Perl Artistic License.
This document is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of accuracy,
merchantability, or fitness for a particular purpose.
The author of this document is not affiliated with the Microsoft corporation.
Product and company names mentioned in this document may be the trademarks or service marks of their respective owners. Trademarks and
service marks are not identified, although this must not be construed as the author's expression of validity or invalidity of each
trademark or service mark.
AUTHOR
Sean M. Burke, sburke@cpan.org
perl v5.10.1 2003-09-24 RTF::Cookbook(3pm)