Provided by: librtf-document-perl_0.64-12_all bug

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 text\n\n",

              { bold=>1, underline=>continuous },
              "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;

DOCUMENT STRUCTURE

       For purposes of using this module, a Rich Text (RTF) Document can be subdivided into
       groups. Groups can be considered containers for text and controls (controlling document
       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 "Document Area"). (The "Header" groups are taken care of
       automatically by this module.)

       The Document Area is subdivided into sections. Each section 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( $group, '\par', "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 readers.

       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.

       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-compatability 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 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
           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 support 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 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.

       Convert::Units::Type.

AUTHOR

       Robert Rothenberg <wlkngowl@unix.asb.com>

LICENSE

       Copyright (c) 1999-2000 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.

FIXES

       Some bugs have been fixed by nmag only <nmag@softhome.net>, now the code is clean and
       under strict directives.