document(3)

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.

For a listing of properties, consult the %DOCINFO and
%PROPERTIES hashes in the source code.

REQUIRED MODULES

Carp
POSIX
Convert::Units::Type 0.33

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, pitch=>fixed,
alternates=>["Courier New", "American Typewriter"]; } );
# Color definitions
$cRed = $rtf->add_color ( { red=>255 } ); $cGreen = $rtf->add_color ( { green=>128 } ); $cCustm = $rtf->add_color ( { red=>0x66, blue=>0x33,
green=>0x33 } );
$cBlack = $rtf->add_color ( { name=>'black' } ); $cWhite = $rtf->add_color ( { gray=>'100%' } );
$cNavy = $rtf->add_color ( { blue=>'100%', 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->add_text( $rtf->root(),: "Default text0,; { bold=>1, underline=>continuous },
"Bold/Underlined Text0,; { font_size=>'20pt', font=>$fCourier,
color_foreground=>$cRed },; "Bigger, Red and Monospaced.0,; { style_default=>paragraph },
{ style_default=>character },; "This is ",
[ { style=>$sGreen }, "green" ],
" styled.0
);
open FILE, ">MyFile.rtf"; binmode FILE; print FILE $rtf->rtf(); close FILE;

DOCUMENT STRUCTURE

For purposes of using this module, a Rich Text (RTF) Docu
ment can be subdivided into groups. Groups can be consid
ered containers for text and controls (controlling docu ment and text properties).

For all intents and purposes, a group limits the scope of
controls. So if we set the "bold" character property
within a group, the text will be bold only within that
group (until it is turned off within that group).

When generating a RTF document using this module, we are
only concerned with the root group (also called the "Docu
ment Area"). (The "Header" groups are taken care of auto
matically by this module.)

The Document Area is subdivided into sections. Each sec tion is subdivided into paragraphs.

METHODS

Some of the methods are documented below. (Methods not
documented here may be changed in future versions.)

new: $rtf = new RTF::Document( DocumentProperties );
Creates a new RTF document object.
root: $gRoot = $rtf->root();
Returns the "root" group in the RTF document.
new_group: $gMyGroup = $rtf->new_group();
Creates a new group (not inside of the RTF document).
add_group: $gChildOfRoot = $rtf->add_group();
$gChildOfChild = $rtf->add_group( $gChild );
Adds a child group to the specfied group. If no group is specified, the "root" group is assumed.: $rtf->add_group( $rtf->root(), $gMyGroup );
Adds a group to the specified parent group (in this case, the root group).
add_raw: $rtf->add_raw( "Some Text" );
Adds raw controls and text to the group. This method is intended for internal use only.
add_text: $rtf->add_text( $group, "Some text ", { bold=>1 },; "more text" );
Adds text and controls to a group. Text is escaped.
add_font
add_color
add_style

PROPERTIES

Document Properties

Section Properties

Paragraph Properties

Character Properties

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 used, you must specify it. Otherwise you rely on
the assumptions of whatever RTF reader someone is using.

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 font or style properties will generally be ignored
without warning.

This module supports some newer RTF controls (used in Word
95/Word 97) that may are not understood by older RTF read
ers.

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-cre
ated 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.

Specifying properties in a particular order within a group does not guarantee that they will be emitted in that order. If order matters, specify them separetly. For instance,: $rtf->add_text($rtf->root, { style_default=>character,; bold=>1 } );
should be (if you want to ensure character styles are reset before setting bold text):: $rtf->add_text($rtf->root, { style_default=>character; }, { bold=>1 } );
Also note that duplicate properties within the same group won't work. i.e., If you want to set "style_default" for both paragraphs and characters, you must do so in separate groups.
This isn't so much as a bug as the way Perl handles hashes.
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 Paragraph Numbering: Some support has been added. The backwards-compatabil
ity controls for numbered paragraphs used by older
readers has not been added because it is not properly
handled by newer readers.
Character Sets and Internationalization: Non-"ANSI" character sets (i.e., Macintosh) and Uni
code character sets are not supported (at least not
intentionally). There is no support for Asian charac
ter sets in this version of the module.; Unicode character escapes are not implemented.; Language codes (defining a default language, or a lan
guage for a group of characters) are not implemented.; Bi-directional and text-flow controls are not imple
mented.
Embedded Images and OLE Objects File Tables Footnotes and Endnotes Forms Headers and Footers Hyphenation Control: Some minimal controls have been added.
Lists and List Tables: Not implemented: List Tables are really a kind of
style sheet for lists. Priority will be given to sup
port generic bullets and paragraph numbering.
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 con
verted to a new paragraph control, and single newlines
are converted to a new line control.
Tabs Tables and Frames

AUTHOR

Robert Rothenberg <wlkngowl@unix.asb.com>

docs.sk

comprehensive documentation repository

Most Viewed