Document(3pm)

💖 Document 💖

okay so bestie, this is RTF::Document — a Perl extension for generating Rich Text (RTF) Files. yes, that RTF. the one your word processor speaks. let's go ✨

---

🌸 NAME 🌸

RTF::Document — a Perl extension for generating Rich Text (RTF) Files. periodt. 💅

---

🦋 DESCRIPTION 🦋

So like, RTF::Document is a module for generating Rich Text Format (RTF) documents that can be used by most text converters and word processors. it's giving "I make files that everyone can open" energy, no cap.

If you want the full listing of properties, go consult the %DOCINFO and %PROPERTIES hashes in the source code. they're right there, iykyk. 👑

---

🎀 REQUIRED MODULES 🎀

These are the besties this module literally cannot function without:

Carp
POSIX
Convert::Units::Type 0.33

---

🌈 EXAMPLE 🌈

okay here's the whole vibe in action, copied exactly, don't touch a character:

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;

slay. that's a whole document right there. 💜

---

💅 DOCUMENT STRUCTURE 💅

For purposes of using this module, a Rich Text (RTF) Document can be subdivided into groups. Think of groups as containers for text and controls (the things that control document and text properties). little cozy boxes. 🎁

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). it doesn't leak out, she's contained. 💅

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 — you don't gotta worry about them, bestie. 🫶)

The Document Area is subdivided into sections. Each section is subdivided into paragraphs. it's giving nesting dolls, fr fr. 🪆

---

✨ METHODS ✨

Some of the methods are documented below. (Methods not documented here may be changed in future versions — so like, don't get too attached to the undocumented ones, okay? 😭)

🦋 new

$rtf = new RTF::Document( \%DocumentProperties );

Creates a new RTF document object. brand new, fresh out the box. ✨

🦋 root

$gRoot = $rtf->root();

Returns the "root" group in the RTF document. the main character of groups, honestly. 👑

🦋 new_group

$gMyGroup = $rtf->new_group();

Creates a new group (not inside of the RTF document). she exists but she's not attached yet — free agent energy. 🦋

🦋 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. defaults to the main character, obviously.

$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. so like, stay out of her business unless you know what you're doing. 🙈

🦋 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

(no description given here, they're just vibing as headers. go look at the source, bestie. 💖)

---

👑 PROPERTIES 👑

Document Properties

Section Properties

Paragraph Properties

Character Properties

(the details live in the source code — check %DOCINFO and %PROPERTIES like the DESCRIPTION said! 🔥)

---

💀 KNOWN ISSUES 💀

okay bestie, deep breaths, here's the honest part.

This module should be considered in the "alpha" stage. Use at your own risk. like, fr fr, be careful. 😭

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. and assumptions are not a vibe. 🚩

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. no heads up, no nothing. 💀

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. so like, get it right the first time, bestie. 💅

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. cute little shortcuts, iykyk. ✨

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. that's just how hashes are, bestie, no cap. 🍓

🌸 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. glow up achieved. ✨

---

and that's the whole page, bestie!! this one's from perl v5.34.0, dated 2022-06-17, and it lives in the Document(3pm) section of the manual. mwah, go generate some RTF documents, you got this 💅💖🦋