prawn 0.11.1 → 0.15.0

data/manual/text/inline.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+# 
+# Inline formatting gives you the option to format specific portions of a text.
+# It uses HTML-esque syntax inside the text string. Supported tags are:
+# <code>b</code> (bold), <code>i</code> (italic), <code>u</code> (underline),
+# <code>strikethrough</code>, <code>sub</code> (subscript), <code>sup</code>
+# (superscript)
+#
+# The following tags accept specific attributes: <code>font</code> accepts
+# <code>size</code>, <code>name</code>, and <code>character_spacing</code>;
+# <code>color</code> accepts <code>rgb</code> and <code>cmyk</code>;
+# <code>link</code> accepts <code>href</code> for external links and
+# <code>anchor</code> for internal links.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  %w[b i u strikethrough sub sup].each do |tag|
+    text "Just your regular text <#{tag}>except this portion</#{tag}> " +
+         "is using the #{tag} tag",
+         :inline_format => true
+    move_down 10
+  end
+  
+  text "This <font size='18'>line</font> uses " +
+       "<font name='Courier'>all the font tag</font> attributes in " +
+       "<font character_spacing='2'>a single line</font>. ",
+       :inline_format => true
+  move_down 10
+  
+  text "Coloring in <color rgb='FF00FF'>both RGB</color> " +
+       "<color c='100' m='0' y='0' k='0'>and CMYK</color>",
+       :inline_format => true
+  move_down 10
+  
+  text "This an external link to the " +
+       "<u><link href='https://github.com/prawnpdf/prawn/wiki'>Prawn wiki" +
+       "</link></u> and this is a link to the " +
+       "<u><link anchor='Text Reference'>Text Reference</link></u> anchor",
+       :inline_format => true
+end

data/manual/text/kerning_and_character_spacing.rb

@@ -0,0 +1,39 @@
+# encoding: utf-8
+# 
+# Kerning is the process of adjusting the spacing between characters in a
+# proportional font. It is usually done with specific letter pairs. We can
+# switch it on and off if it is available with the current font. Just pass a
+# boolean value to the <code>:kerning</code> option of the text methods.
+#
+# Character Spacing is the space between characters. It can be increased or
+# decreased and will have effect on the whole text. Just pass a number to the
+# <code>:character_spacing</code> option from the text methods.
+#
+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(30) do
+    text_box "With kerning:",    :kerning => true,  :at => [0, y - 40]
+    text_box "Without kerning:", :kerning => false, :at => [0, y - 80]
+    
+    text_box "Tomato", :kerning => true,  :at => [250, y - 40]
+    text_box "Tomato", :kerning => false, :at => [250, y - 80]
+    
+    text_box "WAR", :kerning => true,  :at => [400, y - 40]
+    text_box "WAR", :kerning => false, :at => [400, y - 80]
+    
+    text_box "F.", :kerning => true,  :at => [500, y - 40]
+    text_box "F.", :kerning => false, :at => [500, y - 80]
+  end
+  
+  move_down 80
+  
+  string = "What have you done to the space between the characters?"
+  [-2, -1, 0, 0.5, 1, 2].each do |spacing|
+    move_down 20
+    text "#{string} (character_spacing: #{spacing})",
+         :character_spacing => spacing
+  end
+end

data/manual/text/leading.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+# 
+# Leading is the additional space between lines of text.
+#
+# The leading can be set using the <code>default_leading</code> method which
+# applies to the rest of the document or until it is changed, or inline in the
+# text methods with the <code>:leading</code> option.
+#
+# The default leading is <code>0</code>.
+#
+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 = "Hey, what did you do with the space between my lines? " * 10
+  text string, :leading => 0
+  
+  move_down 20
+  default_leading 5
+  text string
+  
+  move_down 20
+  text string, :leading => 10
+end

data/manual/text/line_wrapping.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+# 
+# Line wrapping happens on white space or hyphens. Soft hyphens can be used to
+# indicate where words can be hyphenated. Non-breaking spaces can be used to
+# display space without allowing for a break.
+#
+# For writing styles that do not make use of spaces, the zero width space serves
+# to mark word boundaries. Zero width spaces are available only with TTF fonts.
+#
+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 "Hard hyphens:\n" +
+       "Slip-sliding away, slip sliding awaaaay. You know the " +
+       "nearer your destination the more you're slip-sliding away."
+  move_down 20
+
+  shy = Prawn::Text::SHY
+  text "Soft hyphens:\n" +
+       "Slip slid#{shy}ing away, slip slid#{shy}ing away. You know the " +
+       "nearer your destinat#{shy}ion the more you're slip slid#{shy}ing away."
+  move_down 20
+  
+  nbsp = Prawn::Text::NBSP
+  text "Non-breaking spaces:\n" +
+       "Slip#{nbsp}sliding away, slip#{nbsp}sliding awaaaay. You know the " +
+       "nearer your destination the more you're slip#{nbsp}sliding away."
+  move_down 20
+
+  font("#{Prawn::DATADIR}/fonts/gkai00mp.ttf", :size => 16) do
+    long_text = "No word boundaries:\n更可怕的是，同质化竞争对手可以按照URL中后面这个ID来遍历您的DB中的内容，写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事，这样的话，你就非常被动了。更可怕的是，同质化竞争对手可以按照URL中后面这个ID来遍历您的DB中的内容，写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事，这样的话，你就非常被动了。"
+    text long_text
+    move_down 20
+    
+    zwsp = Prawn::Text::ZWSP
+    long_text = "Invisible word boundaries:\n更#{zwsp}可怕的#{zwsp}是，#{zwsp}同质化#{zwsp}竞争#{zwsp}对#{zwsp}手#{zwsp}可以#{zwsp}按照#{zwsp}URL#{zwsp}中#{zwsp}后面#{zwsp}这个#{zwsp}ID#{zwsp}来#{zwsp}遍历#{zwsp}您的#{zwsp}DB#{zwsp}中的#{zwsp}内容，#{zwsp}写个#{zwsp}小爬虫#{zwsp}把#{zwsp}你的#{zwsp}页面#{zwsp}上的#{zwsp}关#{zwsp}键#{zwsp}信#{zwsp}息顺#{zwsp}次#{zwsp}爬#{zwsp}下来#{zwsp}也#{zwsp}不是#{zwsp}什么#{zwsp}难事，#{zwsp}这样的话，#{zwsp}你#{zwsp}就#{zwsp}非常#{zwsp}被动了。#{zwsp}更#{zwsp}可怕的#{zwsp}是，#{zwsp}同质化#{zwsp}竞争#{zwsp}对#{zwsp}手#{zwsp}可以#{zwsp}按照#{zwsp}URL#{zwsp}中#{zwsp}后面#{zwsp}这个#{zwsp}ID#{zwsp}来#{zwsp}遍历#{zwsp}您的#{zwsp}DB#{zwsp}中的#{zwsp}内容，#{zwsp}写个#{zwsp}小爬虫#{zwsp}把#{zwsp}你的#{zwsp}页面#{zwsp}上的#{zwsp}关#{zwsp}键#{zwsp}信#{zwsp}息顺#{zwsp}次#{zwsp}爬#{zwsp}下来#{zwsp}也#{zwsp}不是#{zwsp}什么#{zwsp}难事，#{zwsp}这样的话，#{zwsp}你#{zwsp}就#{zwsp}非常#{zwsp}被动了。"
+    text long_text
+  end
+end

data/manual/text/paragraph_indentation.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+# 
+# Prawn strips all whitespace from the beginning and the end of strings so there
+# are two ways to indent paragraphs:
+#
+# One is to use non-breaking spaces which Prawn won't strip. One shortcut to
+# using them is the <code>Prawn::Text::NBSP</code>.
+#
+# The other is to use the <code>:indent_paragraphs</code> option with the text
+# methods. Just pass a number with the space to indent the first line in each
+# paragraph.
+#
+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 non-breaking spaces
+  text " " * 10 + "This paragraph won't be indented. " * 10 +
+       "\n#{Prawn::Text::NBSP * 10}" + "This one will with NBSP. " * 10
+  
+  move_down 20
+  text "This paragraph will be indented. " * 10 +
+       "\n" + "This one will too. " * 10,
+       :indent_paragraphs => 60
+end

data/manual/text/positioned_text.rb

@@ -0,0 +1,38 @@
+# encoding: utf-8
+#
+# Sometimes we want the text on a specific position on the page. The
+# <code>text</code> method just won't help us.
+#
+# There are two other methods for this task: <code>draw_text</code> and
+# <code>text_box</code>.
+#
+# <code>draw_text</code> is very simple. It will render text starting at the
+# position provided to the <code>:at</code> option. It won't flow to a new line
+# even if it hits the document boundaries so it is best suited for short text.
+#
+# <code>text_box</code> gives us much more control over the output. Just provide
+# <code>:width</code> and <code>:height</code> options and the text will flow
+# accordingly. Even if you don't provide a <code>:width</code> option the text
+# will flow to a new line if it reaches the right border.
+#
+# Given that said, <code>text_box</code> is the better option available.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  draw_text "This draw_text line is absolute positioned. However don't " +
+            "expect it to flow even if it hits the document border",
+            :at => [200, 300]
+  
+  text_box "This is a text box, you can control where it will flow by " +
+           "specifying the :height and :width options",
+           :at => [100, 250],
+           :height => 100,
+           :width => 100
+  
+  text_box "Another text box with no :width option passed, so it will " +
+           "flow to a new line whenever it reaches the right margin. ",
+           :at => [200, 100]
+end

data/manual/text/registering_families.rb

@@ -0,0 +1,48 @@
+# encoding: utf-8
+#
+# Registering font families will help you when you want to use a font over and
+# over or if you would like to take advantage of the <code>:style</code> option
+# of the text methods and the <code>b</code> and <code>i</code> tags when using
+# inline formatting.
+#
+# To register a font family update the <code>font_families</code>
+# hash with the font path for each style you want to use.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  # Registering a single TTF font
+  font_families.update("Chalkboard" => {
+    :normal => "#{Prawn::DATADIR}/fonts/Chalkboard.ttf"
+  })
+  
+  font("Chalkboard") do
+    text "Using the Chalkboard font providing only its name to the font method"
+  end
+  move_down 20
+  
+  # Registering a DFONT package
+  font_path = "#{Prawn::DATADIR}/fonts/Action Man.dfont"
+  font_families.update("Action Man" => {
+    :normal      => { :file => font_path, :font => "ActionMan" },
+    :italic      => { :file => font_path, :font => "ActionMan-Italic" },
+    :bold        => { :file => font_path, :font => "ActionMan-Bold" },
+    :bold_italic => { :file => font_path, :font => "ActionMan-BoldItalic" }
+  })
+  
+  font "Action Man"
+  text "Also using the Action Man by providing only its name"
+  move_down 20
+  
+  text "Taking <b>advantage</b> of the <i>inline formatting</i>",
+       :inline_format => true
+  move_down 20
+  
+  [:bold, :bold_italic, :italic, :normal].each do |style|
+    text "Using the #{style} style option.",
+         :style => style
+    move_down 10
+  end
+end

data/manual/text/rendering_and_color.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+#
+# You have already seen how to set the text color using both inline formatting
+# and the format text methods. There is another way by using the graphics
+# methods <code>fill_color</code> and <code>stroke_color</code>.
+#
+# When reading the graphics reference you learned about fill and stroke. If you
+# haven't read it before, read it now before continuing.
+#
+# Text can be rendered by
+# being filled (the default mode) or just stroked or both filled and stroked.
+# This can be set using the <code>text_rendering_mode</code> method or the
+# <code>:mode</code> option on the text methods.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  fill_color   "00ff00"
+  stroke_color "0000ff"
+  
+  font_size(40) do
+    # normal rendering mode: fill
+    text "This text is filled with green."
+    move_down 20
+
+    # inline rendering mode: stroke
+    text "This text is stroked with blue", :mode => :stroke
+    move_down 20
+
+    # block rendering mode: fill and stroke
+    text_rendering_mode(:fill_stroke) do
+      text "This text is filled with green and stroked with blue"
+    end
+  end
+end

data/manual/text/right_to_left_text.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+# 
+# Prawn can be used with right-to-left text. The direction can be set
+# document-wide, on particular text, or on a text-box. Setting the direction to
+# <code>:rtl</code> automatically changes the default alignment to
+# <code>:right</code>
+#
+# You can even override direction on an individual fragment. The one caveat is
+# that two fragments going against the main direction cannot be placed next to
+# each other without appearing in the wrong order.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  # set the direction document-wide
+  self.text_direction = :rtl
+
+  font("#{Prawn::DATADIR}/fonts/gkai00mp.ttf", :size => 16) do
+    long_text = "写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事写个小"
+    text long_text
+    move_down 20
+
+    text "You can override the document direction.", :direction => :ltr
+    move_down 20
+
+    formatted_text [{ :text => "更可怕的是，同质化竞争对手可以按照" },
+                    { :text => "URL", :direction => :ltr },
+                    { :text => "中后面这个" },
+                    { :text => "ID",  :direction => :ltr },
+                    { :text => "来遍历您的" },
+                    { :text => "DB",  :direction => :ltr },
+                    { :text => "中的内容，写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事，这样的话，你就非常被动了。" }]
+    move_down 20
+
+    formatted_text [{ :text => "更可怕的是，同质化竞争对手可以按照" },
+                    { :text => "this",  :direction => :ltr },
+                    { :text => "won't", :direction => :ltr, :size => 24 },
+                    { :text => "work",  :direction => :ltr },
+                    { :text => "中的内容，写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事" }]
+  end
+end

data/manual/text/rotation.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+#
+# Rotating text is best avoided on free flowing text, so this example
+# will only use the <code>text_box</code> method as we can have much more
+# control over its output.
+#
+# To rotate text all we need to do is use the <code>:rotate</code> option
+# passing an angle in degrees and an optional <code>:rotate_around</code> to
+# indicate the origin of the rotation (the default is <code>:upper_left</code>).
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  width  = 100
+  height = 60
+  angle  = 30
+  x      = 200
+  y      = cursor - 30
+
+  stroke_rectangle [0, y], width, height
+  text_box("This text was not rotated",
+           :at => [0, y], :width => width, :height => height)
+  
+  stroke_rectangle [0, y - 100], width, height
+  text_box("This text was rotated around the center",
+           :at => [0, y - 100], :width => width, :height => height,
+           :rotate => angle, :rotate_around => :center)
+  
+  [:lower_left, :upper_left,
+   :lower_right, :upper_right].each_with_index do |corner, index|
+    
+    y = y - 100 if index == 2
+    stroke_rectangle [x + (index % 2) * 200, y], width, height
+    text_box("This text was rotated around the #{corner} corner.",
+             :at     => [x + (index % 2) * 200, y],
+             :width  => width,
+             :height => height,
+             :rotate => angle,
+             :rotate_around => corner)
+  end
+end

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", :eval_source => false
+      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