rtf 0.1.0

data/doc/README

@@ -0,0 +1,177 @@
+== Ruby Rich Text Format (RTF) Library 0.1.0
+The RTF library provides a pure Ruby set of functionality that can be used to
+programmatically create RTF documents. The main aim in developing this library
+is to ease the complexity involved in assembling RTF documents although some
+consideration has also been given to generating documents that are easier to
+manually interpret too.
+
+This library does not include functionality for parsing RTF documents. Nor does
+the library claim to provide extensive coverage of the RTF specification. The
+library was developed mostly with reference to the RTF Pocket Guide by Sean M.
+Burke and some reference to the RTF specification itself. The introduction to
+the RTF Pocket Guide states that the book covers version 1.7 of the RTF
+specification so I guess, as this was the primary source, that this is the
+version that the library covers too. Finally, no consideration was given to
+making the functionality within the library thread safe.
+
+In creating this library I set out to make it reasonably easy to create RTF
+documents in code. Having said that I'm certain that it is possible to generate
+invalid RTF documents with this library.
+
+=== Known Issues
+I've tried to assemble a reasonably extensive (although I won't claim
+exhaustive) unit test for the library. Despite that, this is an early release of
+the code and I'm sure there will be issues with it given the complexity inherent
+in RTF. The following are issues that I'm already aware of with the library...
+
+* The implementation of headers and footers is incomplete. Stick to using
+  universal headers and footers for the time being.
+
+* The library makes no attempt to split large chunks of text into separate
+  lines. This can make editing the resulting document in a text editor a little
+  awkward.
+
+* RTF is, when it comes down to it, a Microsoft standard. As a result I have
+  taken Word and Wordpad to be definitive when it comes to displaying the RTF
+  documents generated by the library. I have tried things like Abiword and
+  Open Office with varying degrees of success. I'm certainly not saying that
+  this is due to deficencies in these particular applications as it could
+  equally be a lack of my understanding of the RTF standard or problems with my
+  implementation. Still, I think I should mention the point that I don't get
+  consistent appearance across all of the RTF viewers I've tried.
+
+=== To Do
+This section details that areas where I feel the library is currently lacking
+or incomplete. I hope to address the things detailed here in later releases of
+the code.
+
+* Check into RTF image handling with a view to adding support for the insertion
+  of images into a Document.
+
+* Provide a complete implementation for the headers and footers.
+
+=== Some Examples
+Okay, so how is the library used. Well lets look at some examples to see if we
+can cast a little light on the matter. The examples provided here assume that
+you are already familiar with the Ruby language. So, for a start, consider...
+
+   require 'rubygems'
+   require 'rtf'
+
+   include RTF
+
+The first thing to look at here at the are the first two lines. The RTF library
+is provided as a Ruby gem and these two lines load the libraries functionality
+into the script. The third line of code includes the RTF module into the current
+name space. This is a convenience mechanism that saves on specifically having
+to refer to the module when accessing the RTF library. Next we want to create
+an RTF document and that is done like this...
+
+   document = Document.new(Font.new(Font::ROMAN, 'Times New Roman'))
+
+This line of code creates a new Document object, specifying that the default
+font for the document will the the Times New Roman font. So we have a document,
+what can we do with it. Well, lets add a short paragraph of text...
+
+   document.paragraph << "This is a short paragraph of text."
+
+That's fine, but what if we wanted to extend that paragraph or we simply wanted
+to add more text than we've added here? Well, the paragraph method accepts a
+block to which it passes the actual paragraph object, so we could do something
+like the following...
+
+   document.paragraph do |p|
+      p << "This is the first sentence in the paragraph. "
+      p << "This is the second sentence in the paragraph. "
+      p << "And this is the third sentence in the paragraph."
+   end
+
+This is a common approach used by the RTF library, allowing a block to define
+the scope of a document element. Lets see a more complicated example of this
+in which we apply a number of document effects. Lets say that we want to insert
+some code into the document. We want the code to appear in the document slightly
+indented on the left hand side, in a non-proportionately space font and we want
+it in bold text. Heres the code that shows how to do that...
+
+   01 styles = {}
+   02 styles['PS_CODE'] = ParagraphStyle.new
+   03 styles['CS_CODE'] = CharacterStyle.new
+   04
+   05 styles['PS_CODE'].left_indent = 200
+   06 styles['CS_CODE'].font        = Font.new(Font::MODERN, 'Courier')
+   07 styles['CS_CODE'].bold        = true
+   08
+   09 document.paragraph(styles['PS_CODE']) do |n1|
+   10    n1.apply(styles['CS_CODE']) do |n2|
+   11       n2 << "count = 0"
+   12       n2.line_break
+   13       n2 << "File.open('file.txt', 'r') do |file|"
+   14       n2.line_break
+   15       n2 << "   file.each_line {|line| count += 1}"
+   16       n2.line_break
+   17       n2 << "end"
+   18       n2.line_break
+   19       n2 << "puts \"File contains \#{count} lines.\""
+   20    end
+   21 end
+
+This is a much larger piece of code and covers a number of topics that need to
+be addressed. I have included line numbers with code so that individual elements
+can be referenced. Lines 1 to 3 are the first new elements. Here we create a
+Hash and assign it to a variable called styles. On the next two lines we create
+two style objects, one that can be applied to paragraphs and one that applies
+to characters.
+
+On lines 5 to 7 we update settings on the style objects we've created. We set
+the left indentation value of the paragraph style to 200. The 200 in this case
+refers to a measurement of twips. A twip is a type setting measurement that
+equates to one twentieth of a point (about a fifty seventh of a millimetre or
+one seventy second of an inch). This is the measurement scale used by RTF
+documents so it is also employed in the library.
+
+On lines 6 and 7 we update the character style to use a courier font and to
+apply bold styling to the text. On line 9 we start a new paragraph in our
+document. This differs from our previous use of this method in that we specify
+a style that will be applied to the paragraph created, the paragraph style we
+had prepared earlier.
+
+The block accompanying the paragraph method takes the single parameter that we
+have seen previously. At this point its probably a good idea to point out that
+the elements that make up an RTF document created with the library are all
+stored as nodes in a tree. We've named the one passed to the paragraph method as
+n1 to reflect this.
+
+Within the block we've called a method on the paragraph node called apply. This
+method applies a character style and we're using the one we prepared earlier.
+Like the call to the paragraph method, the apply method is passed a block. All
+text added to the blocks node (n2 in this case) will have the styling we've
+defined (bold courier font) applied to it.
+
+Note, that within the apply block we could still use the n1 node. Any text we
+added to this would appear in the paragraph but wouldn't be styled and, it
+should be noted, will appear before any text added to n2 (as the n2 node only
+becomes part of the document when the apply block completes).
+
+Within the apply method block we add some lines of text to the n2 node. Note
+that, as this is all encompassed within the parapgraph block, all the text is
+part of a single paragraph. To get each of the lines of code to appear on a
+line of their own we have used the line_break method which inserts a carriage
+return into the document. Note you should use this method to insert line breaks
+rather than trying to add a string containing "\n". RTF is a text based standard
+and won't treat "\n" as you're expecting. You should note also that we've had to
+escape the '#' in one of the code lines to stop Ruby considering it as an
+interpolated value.
+
+Okay, so we've seen have the basics of creating a document and adding elements
+to that document. How do we get what we've created to a file. Well thats
+actually quite straight forward. As was mentioned previously, RTF is a text
+based standard so you simply generate the RTF and write it to a file. Heres an
+example...
+
+   File.open('my_document.rtf') {|file| file.write(document.to_rtf)}
+
+There you have it. You've been given a quick overview of the basics of using
+the library. For more information consult the HTML based API documentation that
+is installed with the library gem (if you're reading this you may already be
+looking at this documentation). Another source of information is the examples
+directory, so check that out too.

data/doc/makedoc.bat

@@ -0,0 +1,2 @@
+@echo off
+rdoc -N -o ..\doc rtf.rb README -m README

data/examples/example01.rb

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'rtf'
+
+include RTF
+
+# Create required styles.
+styles = {}
+styles['HEADER'] = CharacterStyle.new
+styles['HEADER'].bold      = true
+styles['HEADER'].font_size = 28
+styles['NORMAL'] = ParagraphStyle.new
+styles['NORMAL'].justification = ParagraphStyle::FULL_JUSTIFY
+styles['INDENTED'] = ParagraphStyle.new
+styles['INDENTED'].left_indent = 400
+
+document = Document.new(Font.new(Font::ROMAN, 'Arial'))
+document.paragraph do |p|
+   p.apply(styles['HEADER']) do |s|
+      s << '1.0 Introduction'
+   end
+end
+document.paragraph(styles['NORMAL']) do |p|
+   p << 'Here is a short example program in the Ruby programming '
+   p << 'language that demonstrates writing a single line of text '
+   p << 'to a file created in the current working directory...'
+end
+
+c = 1
+document.paragraph(styles['INDENTED']) do |n1|
+   n1.line_break
+   n1.font(Font.new(Font::MODERN, 'Courier New')) do |n2|
+      n2 << "#{sprintf('%02d', c)}   File.open('output.txt', 'w') do |file|"
+      c += 1
+      n2.line_break
+      n2 << "#{sprintf('%02d', c)}      file.write('Some text.')"
+      c += 1
+      n2.line_break
+      n2 << "#{sprintf('%02d', c)}   end"
+   end
+end
+
+document.line_break
+document.paragraph(styles['NORMAL']) do |p|
+   p << "And there you have it. A simple example indeed."
+end
+
+File.open('example01.rtf', 'w') do |file|
+   file.write(document.to_rtf)
+end

data/examples/example02.rb

@@ -0,0 +1,45 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'rtf'
+
+include RTF
+
+colours = [Colour.new(0, 0, 0),
+           Colour.new(255, 255, 255)]
+           
+# Create the used styles.
+styles                           = {}
+styles['EMPHASISED']             = CharacterStyle.new
+styles['EMPHASISED'].bold        = true
+styles['EMPHASISED'].underline   = true
+styles['NORMAL']                 = ParagraphStyle.new
+styles['NORMAL'].space_after     = 300
+
+document = Document.new(Font.new(Font::ROMAN, 'Arial'))
+
+document.paragraph(styles['NORMAL']) do |p|
+   p << 'This document is a simple programmatically generated file that is '
+   p << 'used to demonstrate table generation. A table containing 3 rows '
+   p << 'and three columns should be displayed below this text.'
+end
+
+table    = document.table(3, 3, 2000, 4000, 2000)
+table.border_width = 5
+table[0][0] << 'Cell 0,0'
+table[0][1].top_border_width = 10
+table[0][1] << 'This is a little preamble text for '
+table[0][1].apply(styles['EMPHASISED']) << 'Cell 0,1'
+table[0][1].line_break
+table[0][1] << ' to help in examining how formatting is working.'
+table[0][2] << 'Cell 0,2'
+table[1][0] << 'Cell 1,0'
+table[1][1] << 'Cell 1,1'
+table[1][2] << 'Cell 1,2'
+table[2][0] << 'Cell 2,0'
+table[2][1] << 'Cell 2,1'
+table[2][2] << 'Cell 2,2'
+
+File.open('example02.rtf', 'w') do |file|
+   file.write(document.to_rtf)
+end

data/examples/example03.rb

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'rtf'
+
+include RTF
+
+fonts = [Font.new(Font::ROMAN, 'Times New Roman'),
+         Font.new(Font::MODERN, 'Courier')]
+
+styles = {}
+styles['PS_HEADING']              = ParagraphStyle.new
+styles['PS_NORMAL']               = ParagraphStyle.new
+styles['PS_NORMAL'].justification = ParagraphStyle::FULL_JUSTIFY
+styles['PS_INDENTED']             = ParagraphStyle.new
+styles['PS_INDENTED'].left_indent = 300
+styles['PS_TITLE']                = ParagraphStyle.new
+styles['PS_TITLE'].space_before   = 100
+styles['PS_TITLE'].space_after    = 200
+styles['CS_HEADING']              = CharacterStyle.new
+styles['CS_HEADING'].bold         = true
+styles['CS_HEADING'].font_size    = 36
+styles['CS_CODE']                 = CharacterStyle.new
+styles['CS_CODE'].font            = fonts[1]
+styles['CS_CODE'].font_size       = 16
+
+document = Document.new(fonts[0])
+
+document.paragraph(styles['PS_HEADING']) do |p1|
+   p1.apply(styles['CS_HEADING']) << 'Example Program'
+end
+
+document.paragraph(styles['PS_NORMAL']) do |p1|
+   p1 << 'This document is automatically generated using the RTF Ruby '
+   p1 << 'library by Peter Wood. This serves as an example of what can '
+   p1 << 'be achieved in document creation via the library. The source '
+   p1 << 'code that was used to generate it is listed below...'
+end
+
+document.paragraph(styles['PS_INDENTED']) do |p1|
+   n = 1
+   p1.apply(styles['CS_CODE']) do |p2|
+      File.open('example03.rb') do |file|
+         file.each_line do |line|
+            p2.line_break
+            p2 << "#{n > 9 ? '' : ' '}#{n}   #{line.chomp}"
+            n += 1
+         end
+      end
+   end
+end
+
+document.paragraph(styles['PS_TITLE']) do |p1|
+   p1.italic do |p2|
+      p2.bold << 'Listing 1:'
+      p2 << ' Generator program code listing.'
+   end
+end
+
+document.paragraph(styles['PS_NORMAL']) do |p1|
+   p1 << "This example shows the creation of a new document and the "
+   p1 << "of textual content to it. The example also provides examples "
+   p1 << "of using block scope to delimit style scope (lines 35-40)."
+end
+
+File.open('example03.rtf', 'w') {|file| file.write(document.to_rtf)}

data/examples/example03.rtf

@@ -0,0 +1,164 @@
+{\rtf1\ansi\deff0\deflang\plain\fs24
+{\fonttbl
+{\f0\froman Times New Roman;}
+{\f1\fmodern Courier;}
+}
+{\info
+{\createim\yr2005\mo11\dy8\hr15\min16}
+}
+{\pard\ql
+{\b\fs36
+Example Program
+}
+\par}
+{\pard\qj
+This document is automatically generated using the RTF Ruby library by Peter Wood. This serves as an example of what can be achieved in document creation via the library. The source code that was used to generate it is listed below...
+\par}
+{\pard\ql\li300
+{\f1\fs16
+{\line}
+ 1   #!/usr/bin/env ruby
+{\line}
+ 2   
+{\line}
+ 3   require 'rubygems'
+{\line}
+ 4   require 'rtf'
+{\line}
+ 5   
+{\line}
+ 6   include RTF
+{\line}
+ 7   
+{\line}
+ 8   fonts = [Font.new(Font::ROMAN, 'Times New Roman'),
+{\line}
+ 9            Font.new(Font::MODERN, 'Courier')]
+{\line}
+10   
+{\line}
+11   styles = \{\}
+{\line}
+12   styles['PS_HEADING']              = ParagraphStyle.new
+{\line}
+13   styles['PS_NORMAL']               = ParagraphStyle.new
+{\line}
+14   styles['PS_NORMAL'].justification = ParagraphStyle::FULL_JUSTIFY
+{\line}
+15   styles['PS_INDENTED']             = ParagraphStyle.new
+{\line}
+16   styles['PS_INDENTED'].left_indent = 300
+{\line}
+17   styles['PS_TITLE']                = ParagraphStyle.new
+{\line}
+18   styles['PS_TITLE'].space_before   = 100
+{\line}
+19   styles['PS_TITLE'].space_after    = 200
+{\line}
+20   styles['CS_HEADING']              = CharacterStyle.new
+{\line}
+21   styles['CS_HEADING'].bold         = true
+{\line}
+22   styles['CS_HEADING'].font_size    = 36
+{\line}
+23   styles['CS_CODE']                 = CharacterStyle.new
+{\line}
+24   styles['CS_CODE'].font            = fonts[1]
+{\line}
+25   styles['CS_CODE'].font_size       = 16
+{\line}
+26   
+{\line}
+27   document = Document.new(fonts[0])
+{\line}
+28   
+{\line}
+29   document.paragraph(styles['PS_HEADING']) do |p1|
+{\line}
+30      p1.apply(styles['CS_HEADING']) << 'Example Program'
+{\line}
+31   end
+{\line}
+32   
+{\line}
+33   document.paragraph(styles['PS_NORMAL']) do |p1|
+{\line}
+34      p1 << 'This document is automatically generated using the RTF Ruby '
+{\line}
+35      p1 << 'library by Peter Wood. This serves as an example of what can '
+{\line}
+36      p1 << 'be achieved in document creation via the library. The source '
+{\line}
+37      p1 << 'code that was used to generate it is listed below...'
+{\line}
+38   end
+{\line}
+39   
+{\line}
+40   document.paragraph(styles['PS_INDENTED']) do |p1|
+{\line}
+41      n = 1
+{\line}
+42      p1.apply(styles['CS_CODE']) do |p2|
+{\line}
+43         File.open('example03.rb') do |file|
+{\line}
+44            file.each_line do |line|
+{\line}
+45               p2.line_break
+{\line}
+46               p2 << "#\{n > 9 ? '' : ' '\}#\{n\}   #\{line.chomp\}"
+{\line}
+47               n += 1
+{\line}
+48            end
+{\line}
+49         end
+{\line}
+50      end
+{\line}
+51   end
+{\line}
+52   
+{\line}
+53   document.paragraph(styles['PS_TITLE']) do |p1|
+{\line}
+54      p1.italic do |p2|
+{\line}
+55         p2.bold << 'Listing 1:'
+{\line}
+56         p2 << ' Generator program code listing.'
+{\line}
+57      end
+{\line}
+58   end
+{\line}
+59   
+{\line}
+60   document.paragraph(styles['PS_NORMAL']) do |p1|
+{\line}
+61      p1 << "This example shows the creation of a new document and the "
+{\line}
+62      p1 << "of textual content to it. The example also provides examples "
+{\line}
+63      p1 << "of using block scope to delimit style scope (lines 35-40)."
+{\line}
+64   end
+{\line}
+65   
+{\line}
+66   File.open('example03.rtf', 'w') \{|file| file.write(document.to_rtf)\}
+}
+\par}
+{\pard\ql\sb100\sa200
+{\i
+{\b
+Listing 1:
+}
+ Generator program code listing.
+}
+\par}
+{\pard\qj
+This example shows the creation of a new document and the of textual content to it. The example also provides examples of using block scope to delimit style scope (lines 35-40).
+\par}
+}