prawn 1.0.0.rc1 → 1.0.0.rc2

data/manual/text/single_usage.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+#
+# The PDF format has some built-in font support. If you want to use other fonts
+# in Prawn you need to embed the font file.
+#
+# Doing this for a single font is extremely simple. Remember the Styling font
+# example? Another use of the <code>font</code> method is to provide a font file
+# path and the font will be embedded in the document and set as the current
+# font.
+#
+# This is reasonable if a font is used only once, but, if a font used several
+# times, providing the path each time it is used becomes cumbersome. The example
+# on the next page shows a better way to deal with fonts which are used several
+# times in a document.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  # Using a TTF font file
+  font("#{Prawn::DATADIR}/fonts/Chalkboard.ttf") do
+    text "Written with the Chalkboard TTF font."
+  end
+  move_down 20
+  
+  text "Written with the default font."
+  move_down 20
+  
+  # Using an DFONT font file
+  font("#{Prawn::DATADIR}/fonts/Action Man.dfont") do
+    text "Written with the Action Man DFONT font"
+  end
+  move_down 20
+
+  text "Written with the default font once more."
+end

data/manual/text/text.rb

@@ -0,0 +1,75 @@
+# encoding: utf-8
+#
+# Examples for text rendering.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::Example.generate("text.pdf", :page_size => "FOLIO") do
+  
+  package "text" do |p|
+    
+    p.section "Basics" do |s|
+      s.example "free_flowing_text"
+      s.example "positioned_text"
+      s.example "text_box_overflow"
+      s.example "text_box_excess"
+      s.example "group"
+      s.example "column_box"
+    end
+    
+    p.section "Styling" do |s|
+      s.example "font"
+      s.example "font_size"
+      s.example "font_style"
+      s.example "color"
+      s.example "alignment"
+      s.example "leading"
+      s.example "kerning_and_character_spacing"
+      s.example "paragraph_indentation"
+      s.example "rotation"
+    end
+    
+    p.section "Advanced Styling" do |s|
+      s.example "inline"
+      s.example "formatted_text"
+      s.example "formatted_callbacks"
+      s.example "rendering_and_color"
+      s.example "text_box_extensions"
+    end
+    
+    p.section "External Fonts" do |s|
+      s.example "single_usage"
+      s.example "registering_families"
+    end
+    
+    p.section "M17n" do |s|
+      s.example "utf8"
+      s.example "line_wrapping"
+      s.example "right_to_left_text"
+      s.example "fallback_fonts"
+      s.example "win_ansi_charset"
+    end
+    
+    p.intro do
+      prose("This is probably the feature people will use the most. There is no shortage of options when it comes to text. You'll be hard pressed to find a use case that is not covered by one of the text methods and configurable options.
+
+      The examples show:")
+
+      list( "Text that flows from page to page automatically starting new pages when necessary",
+            "How to use text boxes and place them on specific positions",
+            "What to do when a text box is too small to fit its content",
+            "How to proceed when you want to prevent paragraphs from splitting between pages",
+            "Flowing text in columns",
+            "How to change the text style configuring font, size, alignment and many other settings",
+            "How to style specific portions of a text with inline styling and formatted text",
+            "How to define formatted callbacks to reuse common styling definitions",
+            "How to use the different rendering modes available for the text methods",
+            "How to create your custom text box extensions",
+            "How to use external fonts on your pdfs",
+            "What happens when rendering text in different languages"
+          )
+    end
+    
+  end
+end

data/manual/text/text_box_excess.rb

@@ -0,0 +1,32 @@
+# encoding: utf-8
+#
+# Whenever the <code>text_box</code> method truncates text, this truncated bit
+# is not lost, it is the method return value and we can take advantage of that.
+#
+# We just need to take some precautions.
+#
+# This example renders as much of the text as will fit in a larger font inside
+# one text_box and then proceeds to render the remaining text in the default
+# size in a second text_box.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  string = "This is the beginning of the text. It will be cut somewhere and " +
+           "the rest of the text will procede to be rendered this time by " +
+           "calling another method." + " . " * 50
+
+  y_position = cursor - 20
+  excess_text = text_box string,
+                         :width    => 300,
+                         :height   => 50,
+                         :overflow => :truncate,
+                         :at       => [100, y_position],
+                         :size     => 18
+  
+  text_box excess_text,
+           :width    => 300,
+           :at       => [100, y_position - 100]
+end

data/manual/text/text_box_extensions.rb

@@ -0,0 +1,45 @@
+# encoding: utf-8
+#
+# We've already seen one way of using text boxes with the <code>text_box</code>
+# method. Turns out this method is just a convenience for using the
+# <code>Prawn::Text::Box</code> class as it creates a new object and call
+# <code>render</code> on it.
+#
+# Knowing that any extensions we add to <code>Prawn::Text::Box</code> will take
+# effect when we use the <code>text_box</code> method. To add an extension all
+# we need to do is append the <code>Prawn::Text::Box.extensions</code> array
+# with a module.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  module TriangleBox
+    def available_width
+      height + 25
+    end
+  end
+
+  y_position = cursor - 10
+  width      = 100
+  height     = 100
+  
+  Prawn::Text::Box.extensions << TriangleBox
+  stroke_rectangle([0, y_position], width, height)
+  text_box("A" * 100,
+           :at => [0, y_position],
+           :width => width,
+           :height => height)
+  
+  Prawn::Text::Formatted::Box.extensions << TriangleBox
+  stroke_rectangle([200, y_position], width, height)
+  formatted_text_box([:text => "A" * 100, :color => "009900"],
+                     :at => [200, y_position],
+                     :width => width,
+                     :height => height)
+
+  # Here we clear the extensions array
+  Prawn::Text::Box.extensions.clear
+  Prawn::Text::Formatted::Box.extensions.clear
+end

data/manual/text/text_box_overflow.rb

@@ -0,0 +1,44 @@
+# encoding: utf-8
+#
+# The <code>text_box</code> method accepts both <code>:width</code> and
+# <code>:height</code> options. So what happens if the text doesn't fit the box?
+#
+# The default behavior is to truncate the text but this can be changed with
+# the <code>:overflow</code> option. Available modes are <code>:expand</code>
+# (the box will increase to fit the text) and <code>:shrink_to_fit</code>
+# (the text font size will be shrunk to fit).
+#
+# If <code>:shrink_to_fit</code> mode is used with the
+# <code>:min_font_size</code> option set. The font size will not be reduced to
+# less than the value provided even if it means truncating some text.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  string = "This is the sample text used for the text boxes. See how it " +
+           "behave with the various overflow options used."
+
+  text string
+  
+  y_position = cursor - 20
+  [:truncate, :expand, :shrink_to_fit].each_with_index do |mode, i|
+    text_box string, :at => [i * 150, y_position],
+             :width => 100, :height => 50,
+             :overflow => mode
+  end
+  
+  string = "If the box is too small for the text, :shrink_to_fit " +
+           "can render the text in a really small font size."
+  
+  move_down 120
+  text string
+  y_position = cursor - 20
+  [nil, 8, 10, 12].each_with_index do |value, index|
+    text_box string, :at => [index * 150, y_position],
+             :width => 50, :height => 50,
+             :overflow => :shrink_to_fit,
+             :min_font_size => value
+  end
+end

data/manual/text/utf8.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+# 
+# Multilingualization isn't much of a problem on Prawn as its default encoding
+# is UTF-8. The only thing you need to worry about is if the font support the
+# glyphs of your language.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  text "Take this example, a simple Euro sign:"
+  text "€", :size => 32
+  move_down 20
+  
+  text "Seems ok. Now let's try something more complex:"
+  text "ὕαλον ϕαγεῖν δύναμαι· τοῦτο οὔ με βλάπτει."
+  move_down 20
+  
+  text "Looks like the current font (#{font.inspect}) doesn't support those."
+  text "Let's try them with another font."
+  move_down 20
+  
+  font("#{Prawn::DATADIR}/fonts/DejaVuSans.ttf") do
+    text "ὕαλον ϕαγεῖν δύναμαι· τοῦτο οὔ με βλάπτει."
+    text "There you go."
+  end
+end

data/manual/text/win_ansi_charset.rb

@@ -0,0 +1,59 @@
+# encoding: utf-8
+#
+# Prints a list of all of the glyphs that can be rendered by Adobe's built
+# in fonts, along with their character widths and WinAnsi codes.  Be sure
+# to pass these glyphs as UTF-8, and Prawn will transcode them for you.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  FONT_SIZE = 9.5
+
+  x = 0
+  y = bounds.top
+
+  fields = [[20, :right], [8, :left], [12, :center], [30, :right], [8, :left],
+            [0, :left]]
+
+  font "Helvetica", :size => FONT_SIZE
+
+  move_down 30
+  text "(See next page for WinAnsi table)", :align => :center
+  start_new_page
+
+  Prawn::Encoding::WinAnsi::CHARACTERS.each_with_index do |name, index|
+    next if name == ".notdef"
+    y -= FONT_SIZE
+
+    if y < FONT_SIZE
+      y = bounds.top - FONT_SIZE
+      x += 170
+    end
+
+    code = "%d." % index
+    char = index.chr
+
+    width = 1000 * width_of(char, :size => FONT_SIZE) / FONT_SIZE
+    size  = "%d" % width
+
+    data = [code, nil, char, size, nil, name]
+    dx   = x
+    fields.zip(data).each do |(total_width, align), field|
+      if field
+        width = width_of(field, :size => FONT_SIZE)
+
+        case align
+        when :left   then offset = 0
+        when :right  then offset = total_width - width
+        when :center then offset = (total_width - width)/2
+        end
+
+        text_box(field, :at => [dx + offset, y], :skip_encoding => true)
+      end
+
+      dx += total_width
+    end
+  end
+end

data/prawn.gemspec

@@ -1,12 +1,11 @@
-PRAWN_VERSION = "1.0.0.rc1"
-
 Gem::Specification.new do |spec|
   spec.name = "prawn"
-  spec.version = PRAWN_VERSION
+  spec.version = File.read(File.expand_path('VERSION', File.dirname(__FILE__))).strip
   spec.platform = Gem::Platform::RUBY
   spec.summary = "A fast and nimble PDF generator for Ruby"
-  spec.files =  Dir.glob("{examples,lib,spec,data}/**/**/*") +
-    ["Rakefile", "prawn.gemspec", "COPYING", "LICENSE", "GPLv2", "GPLv3"]
+  spec.files =  Dir.glob("{examples,lib,spec,data,manual}/**/**/*") +
+    ["Rakefile", "prawn.gemspec", "COPYING", "LICENSE", "GPLv2", "GPLv3",
+     "Gemfile"]
   spec.require_path = "lib"
   spec.required_ruby_version = '>= 1.8.7'
   spec.required_rubygems_version = ">= 1.3.6"
@@ -18,9 +17,13 @@ Gem::Specification.new do |spec|
   spec.authors = ["Gregory Brown","Brad Ediger","Daniel Nelson","Jonathan Greenberg","James Healy"]
   spec.email = ["gregory.t.brown@gmail.com","brad@bradediger.com","dnelson@bluejade.com","greenberg@entryway.net","jimmy@deefa.com"]
   spec.rubyforge_project = "prawn"
-  spec.add_dependency('pdf-reader', '>=0.9.0')
+  spec.add_dependency('pdf-reader', '>=0.9.0', '<2.0')
   spec.add_dependency('ttfunk', '~>1.0.3')
+  spec.add_dependency('ruby-rc4')
+  spec.add_dependency('afm')
   spec.add_development_dependency('pdf-inspector', '~> 1.0.1')
+  spec.add_development_dependency('coderay', '~> 1.0.7')
+  spec.add_development_dependency('rdoc')
   spec.homepage = "http://prawn.majesticseacreature.com"
   spec.description = <<END_DESC
   Prawn is a fast, tiny, and nimble PDF generator for Ruby
@@ -34,7 +37,7 @@ END_DESC
 
   Please read the changelog for details:
 
-  https://github.com/sandal/prawn/wiki/CHANGELOG
+  https://github.com/prawnpdf/prawn/wiki/CHANGELOG
 
 
   ********************************************

data/spec/bounding_box_spec.rb

@@ -84,14 +84,14 @@ describe "A bounding box" do
   it "should require width to be set" do
     lambda do
       Prawn::Document::BoundingBox.new(nil, nil, [100,100])
-    end.should.raise(ArgumentError)
+    end.should raise_error(ArgumentError)
   end
 
-  it "should raise an ArgumentError if a block is not passed" do
+  it "should raise_error an ArgumentError if a block is not passed" do
     pdf = Prawn::Document.new
     lambda do
       pdf.bounding_box([0, 0], :width => 200)
-    end.should.raise(ArgumentError)
+    end.should raise_error(ArgumentError)
   end
 
 end
@@ -100,6 +100,15 @@ describe "drawing bounding boxes" do
 
   before(:each) { create_pdf }
 
+  it "should not stomp on the arguments to bounding_box" do
+    pdf = Prawn::Document.new
+    x = [100, 500]
+    pdf.bounding_box x, :width => 100 do
+      pdf.text "bork-bork-bork"
+    end
+    x.should == [100, 500]
+  end
+
   it "should restore the margin box when bounding box exits" do
     margin_box = @pdf.bounds
 
@@ -135,7 +144,7 @@ describe "drawing bounding boxes" do
       @pdf.text "The rain in Spain falls mainly on the plains."
     end
 
-    @pdf.y.should.be.close 458.384, 0.001
+    @pdf.y.should be_within(0.001).of(458.384)
   end
 
   it "should keep track of the max height the box was stretched to" do
@@ -153,7 +162,7 @@ describe "drawing bounding boxes" do
         :height => 30 do
       @pdf.text "hello"
     end
-    @pdf.y.should.be.close(orig_y - 30, 0.001)
+    @pdf.y.should be_within(0.001).of(orig_y - 30)
   end
 
   it "should not advance y-position if passed :hold_position => true" do
@@ -163,7 +172,7 @@ describe "drawing bounding boxes" do
       @pdf.text "hello"
     end
     # y only advances by height of one line ("hello")
-    @pdf.y.should.be.close(orig_y - @pdf.height_of("hello"), 0.001)
+    @pdf.y.should be_within(0.001).of(orig_y - @pdf.height_of("hello"))
   end
 
   it "should not advance y-position of a stretchy bbox if it would stretch " +
@@ -179,9 +188,8 @@ describe "drawing bounding boxes" do
     # the bottom of the page, which we don't want. This should be equivalent to
     # a bbox with :hold_position => true, where we only advance by the amount
     # that was actually drawn.
-    @pdf.y.should.be.close(
-      @pdf.margin_box.absolute_top - @pdf.height_of("hello"),
-      0.001
+    @pdf.y.should be_within(0.001).of(
+      @pdf.margin_box.absolute_top - @pdf.height_of("hello")
     )
   end
 
@@ -261,7 +269,7 @@ describe "Indentation" do
                       :height => 200, :columns => 2, :spacer => 20) do
         width = @pdf.bounds.width
         @pdf.indent(20) do
-          @pdf.bounds.width.should.be.close(width - 20, 0.01)
+          @pdf.bounds.width.should be_within(0.01).of(width - 20)
         end
       end
     end
@@ -271,11 +279,93 @@ describe "Indentation" do
                       :height => 200, :columns => 2, :spacer => 20) do
         width = @pdf.bounds.width
         @pdf.indent(20, 30) do
-          @pdf.bounds.width.should.be.close(width - 50, 0.01)
+          @pdf.bounds.width.should be_within(0.01).of(width - 50)
+        end
+      end
+    end
+
+    it "should maintain the same left indentation across column breaks" do
+      @pdf.column_box([0, @pdf.cursor], :width => @pdf.bounds.width, :columns => 3, :spacer => 15) do
+        3.times do |column|
+          x = @pdf.bounds.left_side
+          @pdf.indent(20) do
+            @pdf.bounds.left_side.should == x+20
+          end
+          @pdf.bounds.move_past_bottom
+        end
+      end
+    end
+
+    it "should not change the right margin if only left indentation is requested" do
+      @pdf.column_box([0, @pdf.cursor], :width => @pdf.bounds.width, :columns => 3, :spacer => 15) do
+        3.times do |column|
+          x = @pdf.bounds.right_side
+          @pdf.indent(20) do
+            @pdf.bounds.right_side.should == x
+          end
+          @pdf.bounds.move_past_bottom
+        end
+      end
+    end
+
+    it "should maintain the same right indentation across columns" do
+      @pdf.column_box([0, @pdf.cursor], :width => @pdf.bounds.width, :columns => 3, :spacer => 15) do
+        3.times do |column|
+          x = @pdf.bounds.right_side
+          @pdf.indent(20, 10) do
+            @pdf.bounds.right_side.should == x-10
+          end
+          @pdf.bounds.move_past_bottom
+        end
+      end
+    end
+
+    it "should keep the right indentation after nesting indents" do
+      @pdf.column_box([0, @pdf.cursor], :width => @pdf.bounds.width, :columns => 3, :spacer => 15) do
+        3.times do |column|
+          # I am giving a right indent of 10...
+          @pdf.indent(20, 10) do
+            x = @pdf.bounds.right_side
+            # ...and no right indent here...
+            @pdf.indent(20) do
+              # right indent is inherited from the parent!
+              @pdf.bounds.right_side.should == x
+            end
+          end
+          @pdf.bounds.move_past_bottom
+        end
+      end
+    end
+
+    it "should revert the right indentation if negative indent is given in nested indent" do
+      @pdf.column_box([0, @pdf.cursor], :width => @pdf.bounds.width, :columns => 3, :spacer => 15) do
+        3.times do |column|
+          x = @pdf.bounds.right_side
+          @pdf.indent(20, 10) do
+            # requesting a negative right-indent of equivalent size...
+            @pdf.indent(20, -10) do
+              # ...resets the right margin to that of the column!
+              @pdf.bounds.right_side.should == x
+            end
+          end
+          @pdf.bounds.move_past_bottom
         end
       end
     end
 
+    it "should reduce the available column width by the sum of all nested indents" do
+      @pdf.column_box([0, @pdf.cursor], :width => @pdf.bounds.width, :columns => 3, :spacer => 15) do
+        3.times do |column|
+          w = @pdf.bounds.width
+          @pdf.indent(20, 10) do
+            @pdf.indent(20, 10) do
+              @pdf.bounds.width.should == w - 60
+            end
+          end
+          @pdf.bounds.move_past_bottom
+        end
+      end
+    end
   end
 end
 
@@ -292,12 +382,12 @@ end
 
 describe "Deep-copying" do
   it "should create a new object that does not copy @document" do
-    Prawn::Document.new do
-      orig = bounds
+    Prawn::Document.new do |pdf|
+      orig = pdf.bounds
       copy = orig.deep_copy
 
-      copy.should.not == bounds
-      copy.document.should.be.nil
+      copy.should_not == pdf.bounds
+      copy.document.should be_nil
     end
   end
 
@@ -312,7 +402,7 @@ describe "Deep-copying" do
         copy.parent.height.should == outside.height
 
         # but should not be the same object
-        copy.parent.should.not == outside
+        copy.parent.should_not == outside
       end
     end
   end
@@ -392,7 +482,7 @@ describe "BoundingBox#move_past_bottom" do
     @pdf.text "Foo"
 
     @pdf.bounds.move_past_bottom
-    @pdf.y.should.be.close(top_y, 0.001) # we should be at the top
+    @pdf.y.should be_within(0.001).of(top_y)
     @pdf.text "Bar"
 
     pages = PDF::Inspector::Page.analyze(@pdf.render).pages