prawn 0.11.1 → 0.15.0

data/manual/images/vertical.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+#
+# To set the vertical position of an image use the <code>:vposition</code>
+# option.
+#
+# It may be <code>:top</code>, <code>:center</code>, <code>:bottom</code> or a
+# number representing the y-offset from the top boundary.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  bounding_box([0, cursor], :width => 500, :height => 450) do
+    stroke_bounds
+    
+    [:top, :center, :bottom].each do |vposition|
+      text "Image vertically aligned to the #{vposition}.", :valign => vposition
+      image "#{Prawn::DATADIR}/images/stef.jpg", :position  => 250,
+                                                 :vposition => vposition
+    end
+    
+    text_box "The next image has a 100 point offset from the top boundary",
+             :at => [bounds.width - 110, bounds.top - 10], :width => 100
+    image "#{Prawn::DATADIR}/images/stef.jpg", :position  => :right,
+                                               :vposition => 100
+  end
+end

data/manual/images/width_and_height.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+#
+# The image size can be set with the <code>:width</code> and
+# <code>:height</code> options.
+#
+# If only one of those is provided, the image will be scaled proportionally.
+# When both are provided, the image will be stretched to fit the dimensions
+# without maintaining the aspect ratio.
+#
+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  "Scale by setting only the width"
+  image "#{Prawn::DATADIR}/images/pigs.jpg", :width => 150
+  move_down 20
+  
+  text  "Scale by setting only the height"
+  image "#{Prawn::DATADIR}/images/pigs.jpg", :height => 100
+  move_down 20
+  
+  text  "Stretch to fit the width and height provided"
+  image "#{Prawn::DATADIR}/images/pigs.jpg", :width => 500, :height => 100
+end

data/manual/layout/boxes.rb

@@ -0,0 +1,27 @@
+# encoding: utf-8
+#
+# After defined the grid is there but nothing happens. To start taking effect
+# we need to use the grid boxes.
+#
+# <code>grid</code> has three different return values based on the arguments
+# received. With no arguments it will return the grid itself. With integers it
+# will return the grid box at those indices. With two arrays it will return a
+# multi-box spanning the region of the two grid boxes at the arrays indices.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  # The grid only need to be defined once, but since all the examples should be
+  # able to run alone we are repeating it on every example
+  define_grid(:columns => 5, :rows => 8, :gutter => 10)
+  
+  grid(4,0).show
+  grid(5,1).show
+  
+  grid([6,2], [7,3]).show
+  
+  grid([4,4], [7,4]).show
+  grid([7,0], [7,1]).show
+end

data/manual/layout/content.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+#
+# Now that we know how to access the boxes we might as well add some content
+# to them.
+#
+# This can be done by taping into the bounding box for a given grid box or
+# multi-box with the <code>bounding_box</code> method.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  # The grid only need to be defined once, but since all the examples should be
+  # able to run alone we are repeating it on every example
+  define_grid(:columns => 5, :rows => 8, :gutter => 10)
+  
+  grid([5,0], [7,1]).bounding_box do
+    text "Adding some content to this multi_box.\n" + " _ " * 200
+  end
+  
+  grid(6,3).bounding_box do
+    text "Just a little snippet here.\n" + " _ " * 10
+  end
+end

data/manual/layout/layout.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+#
+# Examples for using grid layouts.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::Example.generate("layout.pdf", :page_size => "FOLIO") do
+  
+  package "layout" do |p|
+    
+    p.example "simple_grid"
+    p.example "boxes"
+    p.example "content"
+    
+    p.intro do
+      prose("Prawn has support for two-dimensional grid based layouts out of the box.
+
+      The examples show:")
+
+      list( "How to define the document grid",
+            "How to configure the grid rows and columns gutters",
+            "How to create boxes according to the grid"
+          )
+    end
+    
+  end
+end

data/manual/layout/simple_grid.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+#
+# The document grid on Prawn is just a table-like structure with a defined
+# number of rows and columns. There are some helpers to create boxes of content
+# based on the grid coordinates.
+#
+# <code>define_grid</code> accepts the following options which are pretty much
+# self-explanatory: <code>:rows</code>, <code>:columns</code>,
+# <code>:gutter</code>, <code>:row_gutter</code>, <code>:column_gutter</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
+  # The grid only need to be defined once, but since all the examples should be
+  # able to run alone we are repeating it on every example
+  define_grid(:columns => 5, :rows => 8, :gutter => 10)
+  text "We defined the grid, roll over to the next page to see its outline"
+  
+  start_new_page
+  grid.show_all
+end

data/manual/manual/cover.rb

@@ -0,0 +1,36 @@
+# encoding: utf-8
+#
+# Prawn manual how to read this manual page. 
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  move_down 200
+
+  image "#{Prawn::DATADIR}/images/prawn.png",
+        :scale => 0.9,
+        :at => [10, cursor]
+        
+  formatted_text_box([ {:text => "Prawn\n",
+                        :styles => [:bold],
+                        :size => 100}
+                     ], :at => [170, cursor - 50])
+
+  formatted_text_box([ {:text => "by example",
+                        :font => 'Courier',
+                        :size => 60}
+                     ], :at => [170, cursor - 160])
+
+  #long git commit hash
+  #commit = `git show --pretty=%H`
+  #short git commit hash
+  commit = `git show --pretty=%h`
+  formatted_text_box([  {:text => "Last Update: #{Time.now.strftime("%Y-%m-%d")}\n"+
+                                  "Prawn Version: #{Prawn::VERSION}\n"+
+                                  "git commit: #{commit}",
+                         :size => 12}
+                    ],   :at => [390, cursor - 620])
+  
+end

data/manual/manual/foreword.rb

@@ -0,0 +1,85 @@
+# encoding: utf-8
+#
+# Prawn manual foreword page.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  header("Foreword, by Gregory Brown")
+  prose %{
+    Back in 2008, the state of PDF generation in
+    Ruby was grim. The best general purpose tool that existed was
+    Austin Ziegler's PDF::Writer, which was an ambitious but
+    painfully unsustainable project. Despite years of hard work
+    from Austin, the code was slow, buggy, and hard to
+    understand. All of those things made it very difficult
+    to extend with the many features that its users needed,
+    and so it gradually turned into abandonware.
+
+    Because I had a lot of work that depended on PDF generation
+    I eventually volunteered to become the new maintainer of
+    PDF::Writer. In the first couple months after I got commit bit, I
+    managed to get out a couple minor releases that fixed
+    known issues that had been left unresolved for years,
+    and that made some people happy. However, the cliff
+    ahead of me was far too steep to climb: without a
+    major redesign, PDF::Writer would never support proper
+    internationalization, would not easily be ported to
+    Ruby 1.9, and would remain painfully slow for many
+    ordinary tasks.
+
+    Against my better judgement, but out of desperation, I
+    was convinced that the only way forward was to attempt the
+    big rewrite. It is good that I didn't realize
+    how impossible that task would be, because otherwise,
+    I would have never started working
+    on Prawn. But with the support of dozens of Ruby community
+    members who had graciously crowd-funded this project
+    so that I could take a few months off of work to
+    kick start it (long before Kickstarter existed!), Prawn
+    was born.
+
+    The PDF specification is over 1300 pages long, and despite
+    being the original author and lead maintainer of this
+    project from 2008-2011, I still know relatively little
+    about the intricacies of the format. I relied heavily
+    on the insights of our core team and casual contributors
+    to educate me on various issues, and to help develop
+    nearly every feature of this project. From day one,
+    Prawn was a stone soup in which virtually all of the
+    tasty bits were provided by the community at large --
+    my most significant contribution was to simply
+    keep stirring the pot. Now, the pot mostly stirs itself,
+    with the occasional nudge from one of the core
+    team members (usually Brad or James, but everyone
+    has pitched in at one time or the other.)
+
+    Although Prawn bears no resemblance to PDF::Writer, this library
+    is most certainly its spiritual successor. That means that between
+    Austin's efforts and that of the Prawn team, we've been
+    trying to solve the PDF problem comfortably in Ruby for
+    nearly a decade now. This manual will help you decide for
+    yourself whether we've managed to finally overcome that
+    challenge or not.
+
+    I sincerely hope that a few years down the line, someone else
+    comes along and makes something brand new and exciting that
+    blows Prawn out of the water and onto the barbeque. But until
+    that happens, what you'll find here is a very powerful
+    PDF generation library that has a great team supporting it,
+    and I suspect it will stay that way for the forseeable future.
+
+    Happy Hacking!
+
+    -greg
+
+    PS: I cannot be possibly be more grateful for the time, money,
+    code, and knowledge that the Ruby community has invested in
+    this project. Whether you're a core team member or someone
+    who filed a single thoughtful bug report, your efforts are
+    what kept me motivated throughout the years that I spent working
+    on this project.
+  }
+end

data/manual/manual/how_to_read_this_manual.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+#
+# Prawn manual how to read this manual page. 
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  header("How to read this manual")
+  
+  prose <<-END_TEXT
+  This manual is a collection of examples categorized by theme and organized from the least to the most complex. While it covers most of the common use cases it is not a comprehensive guide.
+  
+  The best way to read it depends on your previous knowledge of Prawn and what you need to accomplish.
+  
+  If you are beginning with Prawn the first chapter will teach you the most basic concepts and how to create pdf documents. For an overview of the other features each chapter beyond the first either has a Basics section (which offer enough insight on the feature without showing all the advanced stuff you might never use) or is simple enough with only a few examples.
+  
+  Once you understand the basics you might want to come back to this manual looking for examples that accomplish tasks you need.
+  
+  Advanced users are encouraged to go beyond this manual and read the source code directly if any doubt is not directly covered on this manual.
+  END_TEXT
+  
+  move_down(BOX_MARGIN)
+  header("Reading the examples")
+  
+  prose <<-END_TEXT
+  The title of each example is the relative path from the Prawn source manual/ folder.
+  
+  The first body of text is the introductory text for the example. Generaly it is a short description of the features illustrated by the example.
+  
+  Next comes the example source code block in fixed width font.
+  
+  Most of the example snippets illustrate features that alter the page in place. The effect of these snippets is shown right below a dashed line. If it doesn't make sense to evaluate the snippet inline, a box with the link for the example file is shown instead.
+
+  Note that the <code>stroke_axis</code> method, used occasionally in the manual, is not part of standard Prawn and is used for demonstrative purposes. It is defined in this file:
+  
+  https://github.com/prawnpdf/prawn/blob/master/manual/example_helper.rb
+  END_TEXT
+
+end

data/manual/manual/manual.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+#
+# Generates the Prawn by example manual.
+#
+
+Encoding.default_external = Encoding::UTF_8
+
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::Example.generate("manual.pdf",
+                        :optimize_objects => true,
+                        :skip_page_creation => true,
+                        :page_size => "FOLIO") do
+
+  load_page "cover"
+  load_page "foreword"
+  load_page "how_to_read_this_manual"
+
+  # Core chapters
+  load_package "basic_concepts"
+  load_package "graphics"
+  load_package "text"
+  load_package "bounding_box"
+
+  # Remaining chapters
+  load_package "layout"
+  load_package "images"
+  load_package "table"
+  load_package "document_and_page_options"
+  load_package "outline"
+  load_package "repeatable_content"
+  load_package "security"
+end

data/manual/outline/add_subsection_to.rb

@@ -0,0 +1,61 @@
+# encoding: utf-8
+#
+# We have already seen how to define an outline tree sequentially.
+#
+# If you'd like to add nodes to the middle of an outline tree the
+# <code>add_subsection_to</code> may help you.
+#
+# It allows you to insert sections to the outline tree at any point. Just
+# provide the <code>title</code> of the parent section, the
+# <code>position</code> you want the new subsection to be inserted
+# <code>:first</code> or <code>:last</code> (defaults to <code>:last</code>)
+# and a block to declare the subsection.
+#
+# The <code>add_subsection_to</code> block doesn't necessarily create new
+# sections, it may also create new pages.
+#
+# If the parent title provided is the title of a page. The page will be
+# converted into a section to receive the subsection created.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  # First we create 10 pages and some default outline
+  (1..10).each do |index|
+    text "Page #{index}"
+    start_new_page
+  end
+  
+  outline.define do
+    section("Section 1", :destination => 1) do 
+      page :title => "Page 2", :destination => 2
+      page :title => "Page 3", :destination => 3
+    end
+  end
+  
+  # Now we will start adding nodes to the previous outline
+  outline.add_subsection_to("Section 1", :first) do
+    outline.section("Added later - first position") do
+      outline.page :title => "Page 4", :destination => 4
+      outline.page :title => "Page 5", :destination => 5
+    end
+  end
+  
+  outline.add_subsection_to("Section 1") do
+    outline.page :title => "Added later - last position",
+                 :destination => 6
+  end
+  
+  outline.add_subsection_to("Added later - first position") do
+    outline.page :title => "Another page added later",
+                 :destination => 7
+  end
+  
+  # The title provided is for a page which will be converted into a section
+  outline.add_subsection_to("Page 3") do
+    outline.page :title => "Last page added",
+                 :destination => 8
+  end
+end

data/manual/outline/insert_section_after.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+#
+# Another way to insert nodes into an existing outline is the
+# <code>insert_section_after</code> method.
+#
+# It accepts the title of the node that the new section will go after and a
+# block declaring the new section.
+#
+# As is the case with <code>add_subsection_to</code> the section added
+# doesn't need to be a section, it may be just a page.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  # First we create 10 pages and some default outline
+  (1..10).each do |index|
+    text "Page #{index}"
+    start_new_page
+  end
+  
+  outline.define do
+    section("Section 1", :destination => 1) do 
+      page :title => "Page 2", :destination => 2
+      page :title => "Page 3", :destination => 3
+    end
+  end
+  
+  # Now we will start adding nodes to the previous outline
+  outline.insert_section_after("Page 2") do
+    outline.section("Section after Page 2") do
+      outline.page :title => "Page 4", :destination => 4
+    end
+  end
+
+  outline.insert_section_after("Section 1") do
+    outline.section("Section after Section 1") do
+      outline.page :title => "Page 5", :destination => 5
+    end
+  end
+  
+  # Adding just a page
+  outline.insert_section_after("Page 3") do
+    outline.page :title => "Page after Page 3", :destination => 6
+  end
+end

data/manual/outline/outline.rb

@@ -0,0 +1,32 @@
+# encoding: utf-8
+#
+# Examples for defining the document outline.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::Example.generate("outline.pdf", :page_size => "FOLIO") do
+  
+  package "outline" do |p|
+    
+    p.section "Basics" do |s|
+      s.example "sections_and_pages", :eval_source => false
+    end
+    
+    p.section "Adding nodes later" do |s|
+      s.example "add_subsection_to",    :eval_source => false
+      s.example "insert_section_after", :eval_source => false
+    end
+    
+    p.intro do
+      prose("The outline of a PDF document is the table of contents tab you see to the right or left of your PDF viewer.
+
+      The examples include:")
+
+      list( "How to define sections and pages",
+            "How to insert sections and/or pages to a previously defined outline structure"
+          )
+    end
+    
+  end
+end

data/manual/outline/sections_and_pages.rb

@@ -0,0 +1,67 @@
+# encoding: utf-8
+#
+# The document outline tree is the set of links used to navigate through the
+# various document sections and pages.
+#
+# To define the document outline we first use the <code>outline</code>
+# method to lazily instantiate an outline object. Then we use the
+# <code>define</code> method with a block to start the outline tree.
+#
+# The basic methods for creating outline nodes are <code>section</code> and
+# <code>page</code>. The only difference between the two is that
+# <code>page</code> doesn't accept a block and will only create leaf nodes
+# while <code>section</code> accepts a block to create nested nodes.
+#
+# <code>section</code> accepts the title of the section and two options:
+# <code>:destination</code> - a page number to link and <code>:closed</code> -
+# a boolean value that defines if the nested outline nodes are shown when the
+# document is open (defaults to true).
+#
+# <code>page</code> is very similar to section. It requires a
+# <code>:title</code> option to be set and accepts a <code>:destination</code>.
+#
+# <code>section</code> and <code>page</code> may also be used without the
+# <code>define</code> method but they will need to instantiate the
+# <code>outline</code> object every time.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  # First we create 10 pages just to have something to link to
+  (1..10).each do |index|
+    text "Page #{index}"
+    start_new_page
+  end
+  
+  outline.define do
+    section("Section 1", :destination => 1) do 
+      page :title => "Page 2", :destination => 2
+      page :title => "Page 3", :destination => 3
+    end
+    
+    section("Section 2", :destination => 4) do
+      page :title => "Page 5", :destination => 5
+      
+      section("Subsection 2.1", :destination => 6, :closed => true) do
+        page :title => "Page 7", :destination => 7
+      end
+    end
+  end
+  
+  # Outside of the define block
+  outline.section("Section 3", :destination => 8) do
+    outline.page :title => "Page 9", :destination => 9
+  end
+  
+  outline.page :title => "Page 10", :destination => 10
+  
+  # Section and Pages without links. While a section without a link may be
+  # useful to group some pages, a page without a link is useless
+  outline.update do  # update is an alias to define
+    section("Section without link") do 
+      page :title => "Page without link"
+    end
+  end
+end

data/manual/repeatable_content/page_numbering.rb

@@ -0,0 +1,54 @@
+# encoding: utf-8
+#
+# The <code>number_pages</code> method is a simple way to number the pages of
+# your document. It should be called towards the end of the document since
+# pages created after the call won't be numbered.
+#
+# It accepts a string and a hash of options:
+#
+# <code>start_count_at</code> is the value from which to start numbering pages
+#
+# <code>total_pages</code> If provided, will replace <code>total</code> with
+# the value given.  Useful for overriding the total number of pages when using
+# the start_count_at option.
+#
+# <code>page_filter</code>, which is one of: <code>:all</code>,
+# <code>:odd</code>, <code>:even</code>, an array, a range, or a Proc that
+# receives the page number as an argument and should return true if the page
+# number should be printed on that page.
+#
+# <code>color</code> which accepts the same values as <code>fill_color</code>
+#
+# As well as any option accepted by <code>text_box</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
+  text "This is the first page!"
+  
+  10.times do
+    start_new_page
+    text "Here comes yet another page."
+  end
+
+  string = "page <page> of <total>"
+  # Green page numbers 1 to 7
+  options = { :at => [bounds.right - 150, 0],
+              :width => 150,
+              :align => :right,
+              :page_filter => (1..7),
+              :start_count_at => 1,
+              :color => "007700" }
+  number_pages string, options
+
+  # Gray page numbers from 8 on up
+  options[:page_filter]    = lambda{ |pg| pg > 7}
+  options[:start_count_at] = 8
+  options[:color]          = "333333"
+  number_pages string, options
+  
+  start_new_page
+  text "See. This page isn't numbered and doesn't count towards the total."
+end

data/manual/repeatable_content/repeatable_content.rb

@@ -0,0 +1,31 @@
+# encoding: utf-8
+#
+# Examples for stamps and repeaters.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+Prawn::Example.generate("repeatable_content.pdf", :page_size => "FOLIO") do
+  
+  package "repeatable_content" do |p|
+    
+    p.example "repeater",       :eval_source => false
+    p.example "stamp"
+    p.example "page_numbering", :eval_source => false
+    
+    p.intro do
+      prose("Prawn offers two ways to handle repeatable content blocks. Repeater is useful for content that gets repeated at well defined intervals while Stamp is more appropriate if you need better control of when to repeat it.
+
+      There is also one very specific helper for numbering pages.
+
+      The examples show:")
+
+      list( "How to repeat content on several pages with a single invocation",
+            "How to create a new Stamp",
+            'How to "stamp" the content block on the page',
+            "How to number the document pages with one simple call"
+          )
+    end
+    
+  end
+end