NAME RTF::Document - Perl extension for generating Rich Text (RTF) Files DESCRIPTION RTF::Document is a module for generating Rich Text Format (RTF) documents that can be used by most text converters and word processors. The interface is not yet documented, although the example below will demonstrate how to use this module. For a listing of properties, consult the %PROPERTIES hash in the source code. REQUIRED MODULES Carp POSIX Units::Type 0.32 Units::Type is part of the Units package. EXAMPLE use RTF::Document; # Document properties $rtf = new RTF::Document( { doc_page_width => '8.5in', doc_page_height => '11in' } ); # Font definitions $fAvantGarde = $rtf->add_font ("AvantGarde", { family=>swiss, default=>1 } ); $fCourier = $rtf->add_font ("Courier", { family=>monospace, alternates=>["Courier New", "American Typewriter"] } ); # Color definitions $cRed = $rtf->add_color ( { red=>255 } ); $cGreen = $rtf->add_color ( { green=>255 } ); $cPurpl = $rtf->add_color ( { red=>255, blue=>255 } ); $cBlack = $rtf->add_color ( { gray=>0 } ); $cWhite = $rtf->add_color ( { gray=>100 } ); $cDkBlue = $rtf->add_color ( { blue=>255, gray=>50 } ); # style definitions $sNormal = $rtf->add_style( "Normal", { font=>$fAvantGarde, font_size=>'12pt', color_foreground=>$cBlack }, { type=>paragraph, default=>1 } ); $sGreen = $rtf->add_style( "Green", { color_foreground=>$cGreen }, { type=>character, additive=>1 } ); # Mix any combo of properties and text... $rtf->text( "Default text\n\n", { bold=>1, underline=>dash }, "Bold/Underlined Text\n\n", { font_size=>'20pt', font=>$fCourier, color_foreground=>$cRed }, "Bigger, Red and Monospaced.\n\n", { style_default=>paragraph, style_default=>character }, "This is ", [ { style=>$sGreen }, "green" ], " styled.\n\n" ); open FILE, ">MyFile.rtf"; binmode FILE; print FILE $rtf->rtf(); close FILE; KNOWN ISSUES This module should be considered in the "alpha" stage. Use at your own risk. There are no default document or style properties produced by this module, with the exception of the character set. If you want to make sure that a specific font, color, or style is available, you must specify it. (You may be able to rely on default properties documented in the RTF specification, but you do so at the risk that an RTF viewer will assume different defaults.) This module does not insert newlines anywhere in the text, even though some RTF writers break lines before they exceed 225 characters. This may or may not be an issue with some reader software. Unknown text or document properties will return a warning. Attempting to define a "global" document property (for example, defining the paper size) within the text will also produce a warning but the code will be emitted in place anyway. This "feature" may change in a future version. Unknown font or style properties will generally be ignored without warning. Inappropriate properties for a specific font or style are also ignored. Potentially invalid names for fonts and styles are ignored. (Don't use tabs, newlines, backslashes, brackets, or other control characters in these.) Fonts, Colors and Styles are referenced in text and style properties using the returned values when they are added, and *not* by names associated with them. This is intentional, since it makes the interface more object-oriented. Once a Font, Color or Style is added, it cannot be changed. No checking for redundant entries is done. Generally, it is not possible to reference a not-yet-created Style with the next or basedon attributes. However, you can use the constances "last", "self" or "next" to reference the last style added, the current style being added, or the next style that will be added, respectively. Properties are *write-only* (global properties should be considered *write-once* as well). Unimplemented Features A rather large number of features and control words are not handled in this version. Among the major features: * Annotations and Comments * Bookmarks * Bullets and Line Numbering * Character Sets and Internationalization Non-"ANSI" character sets (i.e., Macintosh) and Unicode character sets are not supported (at least not intentionally). There is no support for Asian character sets in this version of the module. Unicode character escapes are not implemented. Language codes (defining a default language, or a language for a group of characters) are not implemented. Bi-directional and text-flow controls are not implemented. * Embedded Images and OLE Objects * File Tables * Footnotes and Endnotes * Forms * Headers and Footers * Hyphenation Control * Lists and List Tables * Page Numbering Minimal definition, untested. * Printer Bin Controls * Revision Tables * Special Characters and Document Variables Most special characters not not implemented, with the exception of tabs. Double newline characters are converted to a new paragraph control, and single newlines are converted to a new line control. * Tabs * Tables and Frames SEE ALSO Microsoft Technical Support and Application Note, "Rich Text Format (RTF) Specification and Sample Reader Program", Version 1.5. *Units::Type*. AUTHOR Robert Rothenberg LICENSE Copyright (c) 1999 Robert Rothenberg. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.