prawn 0.11.1 → 0.15.0

data/manual/example_helper.rb

@@ -0,0 +1,411 @@
+# encoding: utf-8
+#
+# Helper for organizing examples
+#
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'prawn'
+require 'prawn/security'
+require 'prawn/layout'
+
+require 'enumerator'
+
+require File.expand_path(File.join(File.dirname(__FILE__), 'example_file'))
+require File.expand_path(File.join(File.dirname(__FILE__), 'example_section'))
+require File.expand_path(File.join(File.dirname(__FILE__), 'example_package'))
+require File.expand_path(File.join(File.dirname(__FILE__), 'syntax_highlight'))
+
+Prawn.debug = true
+
+module Prawn
+
+  # The Prawn::Example class holds all the helper methods used to generate the
+  # Prawn by example manual.
+  #
+  # The overall structure is to have single example files grouped by package
+  # folders. Each package has a package builder file (with the same name as the
+  # package folder) that defines the inner structure of subsections and
+  # examples. The manual is then built by loading all the packages and some
+  # standalone pages.
+  #
+  # To see one of the examples check manual/basic_concepts/cursor.rb
+  #
+  # To see one of the package builders check
+  # manual/basic_concepts/basic_concepts.rb
+  #
+  # To see how the manual is built check manual/manual/manual.rb (Yes that's a
+  # whole load of manuals)
+  #
+  class Example < Prawn::Document
+
+    # Values used for the manual design:
+
+    # This is the default value for the margin box
+    #
+    BOX_MARGIN   = 36
+
+    # Additional indentation to keep the line measure with a reasonable size
+    #
+    INNER_MARGIN = 30
+
+    # Vertical Rhythm settings
+    #
+    RHYTHM  = 10
+    LEADING = 2
+
+    # Colors
+    #
+    BLACK      = "000000"
+    LIGHT_GRAY = "F2F2F2"
+    GRAY       = "DDDDDD"
+    DARK_GRAY  = "333333"
+    BROWN      = "A4441C"
+    ORANGE     = "F28157"
+    LIGHT_GOLD = "FBFBBE"
+    DARK_GOLD  = "EBE389"
+    BLUE       = "0000D0"
+
+    # Used to generate the url for the example files
+    #
+    MANUAL_URL = "http://github.com/prawnpdf/prawn/tree/master/manual"
+
+
+    # Loads a package. Used on the manual.
+    #
+    def load_package(package)
+      load_file(package, package)
+    end
+
+    # Loads a page with outline support. Used on the manual.
+    #
+    def load_page(page)
+      load_file("manual", page)
+
+      outline.define do
+        section(page.gsub("_", " ").capitalize, :destination => page_number)
+      end
+    end
+
+    # Opens a file in a given package and evals the source
+    #
+    def load_file(package, file)
+      start_new_page
+      example = ExampleFile.new(package, "#{file}.rb")
+      eval example.generate_block_source
+    end
+
+
+    # Creates a new ExamplePackage object and yields it to a block in order for
+    # it to be populated with examples, sections and some introduction text.
+    # Used on the package files.
+    #
+    def package(package, &block)
+      ep = ExamplePackage.new(package)
+      ep.instance_eval(&block)
+      ep.render(self)
+    end
+
+    # Renders an ExamplePackage cover page.
+    #
+    # Starts a new page and renders the package introduction text.
+    #
+    def render_package_cover(package)
+      header(package.name)
+      instance_eval &(package.intro_block)
+
+      outline.define do
+        section(package.name, :destination => page_number, :closed => true)
+      end
+    end
+
+    # Add the ExampleSection to the document outline within the appropriate
+    # package.
+    #
+    def render_section(section)
+      outline.add_subsection_to(section.package_name) do
+        outline.section(section.name, :closed => true)
+      end
+    end
+
+    # Renders an ExampleFile.
+    #
+    # Starts a new page and renders an introductory text, the example source and
+    # evaluates the example source inline whenever that is appropriate according
+    # to the ExampleFile directives.
+    #
+    def render_example(example)
+      start_new_page
+
+      outline.add_subsection_to(example.parent_name) do
+        outline.page(:destination => page_number, :title => example.name)
+      end
+
+      example_header(example.parent_folder_name, example.filename)
+
+      prose(example.introduction_text)
+
+      code(example.source)
+
+      if example.eval?
+        eval_code(example.source)
+      else
+        source_link(example)
+      end
+
+      reset_settings
+    end
+
+    # Render the example header. Used on the example pages of the manual
+    #
+    def example_header(package, example)
+      header_box do
+        register_fonts
+        font('DejaVu', :size => 18) do
+          formatted_text([ { :text => package, :color => BROWN  },
+                           { :text => "/",     :color => BROWN  },
+                           { :text => example, :color => ORANGE }
+                         ], :valign => :center)
+        end
+      end
+    end
+
+    # Register fonts used on the manual
+    #
+    def register_fonts
+      kai_file = "#{Prawn::DATADIR}/fonts/gkai00mp.ttf"
+      font_families["Kai"] = {
+        :normal => { :file => kai_file, :font => "Kai" }
+      }
+
+      dejavu_file = "#{Prawn::DATADIR}/fonts/DejaVuSans.ttf"
+      font_families["DejaVu"] = {
+        :normal => { :file => dejavu_file, :font => "DejaVu" }
+      }
+    end
+
+    # Render a block of text after processing code tags and URLs to be used with
+    # the inline_format option.
+    #
+    # Used on the introducory text for example pages of the manual and on
+    # package pages intro
+    #
+    def prose(str)
+
+      # Process the <code> tags
+      str.gsub!(/<code>([^<]+?)<\/code>/,
+          "<font name='Courier'><b>\\1<\/b><\/font>")
+
+      # Process the links
+      str.gsub!(/(https?:\/\/\S+)/,
+                  "<color rgb='#{BLUE}'><link href=\"\\1\">\\1</link></color>")
+
+      inner_box do
+        font("Helvetica", :size => 11) do
+          str.split(/\n\n+/).each do |paragraph|
+
+            text(paragraph.gsub(/\s+/," "),
+                 :align         => :justify,
+                 :inline_format => true,
+                 :leading       => LEADING,
+                 :color         => DARK_GRAY)
+
+            move_down(RHYTHM)
+          end
+        end
+      end
+
+      move_down(RHYTHM)
+    end
+
+    # Render a code block. Used on the example pages of the manual
+    #
+    def code(str)
+      pre_text = str.gsub(' ', Prawn::Text::NBSP)
+      pre_text = ::CodeRay.scan(pre_text, :ruby).to_prawn
+
+      font('Courier', :size => 9.5) do
+        colored_box(pre_text, :fill_color => DARK_GRAY)
+      end
+    end
+
+    # Renders a dashed line and evaluates the code inline
+    #
+    def eval_code(source)
+      move_down(RHYTHM)
+
+      dash(3)
+      stroke_color(BROWN)
+      stroke_horizontal_line(-BOX_MARGIN, bounds.width + BOX_MARGIN)
+      stroke_color(BLACK)
+      undash
+
+      move_down(RHYTHM*3)
+      begin
+        eval(source)
+      rescue => e
+        puts "Error evaluating example: #{e.message}"
+        puts
+        puts "---- Source: ----"
+        puts source
+      end
+    end
+
+    # Renders a box with the link for the example file
+    #
+    def source_link(example)
+      url = "#{MANUAL_URL}/#{example.parent_folder_name}/#{example.filename}"
+
+      reason = [{ :text  => "This code snippet was not evaluated inline. " +
+                            "You may see its output by running the " +
+                            "example file located here:\n",
+                  :color => DARK_GRAY },
+
+                { :text   => url,
+                  :color  => BLUE,
+                  :link   => url}
+               ]
+
+      font('Helvetica', :size => 9) do
+        colored_box(reason,
+                    :fill_color   => LIGHT_GOLD,
+                    :stroke_color => DARK_GOLD,
+                    :leading      => LEADING*3)
+      end
+    end
+
+    # Render a page header. Used on the manual lone pages and package
+    # introductory pages
+    #
+    def header(str)
+      header_box do
+        register_fonts
+        font('DejaVu', :size => 24) do
+          text(str, :color  => BROWN, :valign => :center)
+        end
+      end
+    end
+
+    # Render the arguments as a bulleted list. Used on the manual package
+    # introductory pages
+    #
+    def list(*items)
+      move_up(RHYTHM)
+
+      inner_box do
+        font("Helvetica", :size => 11) do
+          items.each do |li|
+            float { text("•", :color => DARK_GRAY) }
+            indent(RHYTHM) do
+              text(li.gsub(/\s+/," "),
+                   :inline_format => true,
+                   :color         => DARK_GRAY,
+                   :leading       => LEADING)
+            end
+
+            move_down(RHYTHM)
+          end
+        end
+      end
+    end
+
+    # Renders the page-wide headers
+    #
+    def header_box(&block)
+      bounding_box([-bounds.absolute_left, cursor + BOX_MARGIN],
+                   :width  => bounds.absolute_left + bounds.absolute_right,
+                   :height => BOX_MARGIN*2 + RHYTHM*2) do
+
+        fill_color LIGHT_GRAY
+        fill_rectangle([bounds.left, bounds.top],
+                        bounds.right,
+                        bounds.top - bounds.bottom)
+        fill_color BLACK
+
+        indent(BOX_MARGIN + INNER_MARGIN, &block)
+      end
+
+      stroke_color GRAY
+      stroke_horizontal_line(-BOX_MARGIN, bounds.width + BOX_MARGIN, :at => cursor)
+      stroke_color BLACK
+
+      move_down(RHYTHM*3)
+    end
+
+    # Renders a Bounding Box for the inner margin
+    #
+    def inner_box(&block)
+      bounding_box([INNER_MARGIN, cursor],
+                   :width => bounds.width - INNER_MARGIN*2,
+                   &block)
+    end
+
+    # Renders a Bounding Box with some background color and the formatted text
+    # inside it
+    #
+    def colored_box(box_text, options={})
+      options = { :fill_color   => DARK_GRAY,
+                  :stroke_color => nil,
+                  :text_color   => LIGHT_GRAY,
+                  :leading      => LEADING
+                }.merge(options)
+
+      register_fonts
+      text_options = { :leading        => options[:leading],
+                       :fallback_fonts => ["DejaVu", "Kai"]
+                     }
+
+      box_height = height_of_formatted(box_text, text_options)
+
+      bounding_box([INNER_MARGIN + RHYTHM, cursor],
+                   :width => bounds.width - (INNER_MARGIN+RHYTHM)*2) do
+
+        fill_color   options[:fill_color]
+        stroke_color options[:stroke_color] || options[:fill_color]
+        fill_and_stroke_rounded_rectangle(
+            [bounds.left - RHYTHM, cursor],
+            bounds.left + bounds.right + RHYTHM*2,
+            box_height + RHYTHM*2,
+            5
+        )
+        fill_color   BLACK
+        stroke_color BLACK
+
+        pad(RHYTHM) do
+          formatted_text(box_text, text_options)
+        end
+      end
+
+      move_down(RHYTHM*2)
+    end
+
+    # Draws X and Y axis rulers beginning at the margin box origin. Used on
+    # examples.
+    #
+    def stroke_axis(options={})
+      super({:height => (cursor - 20).to_i}.merge(options))
+    end
+
+    # Reset some of the Prawn settings including graphics and text to their
+    # defaults.
+    #
+    # Used after rendering examples so that each new example starts with a clean
+    # slate.
+    #
+    def reset_settings
+
+      # Text settings
+      font("Helvetica", :size => 12)
+      default_leading 0
+      self.text_direction = :ltr
+
+      # Graphics settings
+      self.line_width = 1
+      self.cap_style  = :butt
+      self.join_style = :miter
+      undash
+      fill_color   BLACK
+      stroke_color BLACK
+    end
+
+  end
+end

data/manual/example_package.rb

@@ -0,0 +1,53 @@
+# encoding: utf-8
+
+module Prawn
+  
+  # The Prawn::ExamplePackage class is a utility class to handle the packaging
+  # of individual examples within a hierarchy when building the manual
+  #
+  class ExamplePackage
+    attr_reader :intro_block, :folder_name
+    
+    def initialize(folder_name)
+      @folder_name = folder_name
+      @hierarchy = []
+    end
+    
+    # Stores a new ExampleSection in the hierarchy and yields it to a block
+    #
+    def section(name)
+      s = ExampleSection.new(self, name)
+      yield s
+      @hierarchy << s
+    end
+    
+    # Stores a new ExampleFile in the hierarchy
+    #
+    def example(filename, options={})
+      @hierarchy << ExampleFile.new(self, "#{filename}.rb", options)
+    end
+    
+    # Stores a block with code to be evaluated when rendering the package cover
+    #
+    def intro(&block)
+      @intro_block = block
+    end
+    
+    # Returns a human friendly version of the package name
+    #
+    def name
+      @name ||= @folder_name.gsub("_", " ").capitalize
+    end
+    
+    # Renders a cover page for the package to a pdf and iterates the examples
+    # hierarchy delegating the examples and sections to be rendered as well
+    #
+    def render(pdf)
+      pdf.render_package_cover(self)
+      
+      @hierarchy.each do |node|
+        node.render(pdf)
+      end
+    end
+  end
+end

data/manual/example_section.rb

@@ -0,0 +1,46 @@
+# encoding: utf-8
+
+module Prawn
+  
+  # The Prawn::ExampleSection class is a utility class to handle sections
+  # of related examples within an ExamplePackage
+  #
+  class ExampleSection
+    attr_reader :name
+    
+    def initialize(package, name)
+      @package  = package
+      @name     = name
+      @examples = []
+    end
+    
+    # Stores a new ExampleFile in the examples list
+    #
+    def example(filename, options={})
+      @examples << ExampleFile.new(self, "#{filename}.rb", options)
+    end
+
+    # Returns this example's package original folder name
+    #
+    def folder_name
+      @package.folder_name
+    end
+    
+    # Returns the human friendly version of this section's package name
+    #
+    def package_name
+      @package.name
+    end
+    
+    # Renders the section to a pdf and iterates the examples list delegating the
+    # examples to be rendered as well
+    #
+    def render(pdf)
+      pdf.render_section(self)
+      
+      @examples.each do |example|
+        example.render(pdf)
+      end
+    end
+  end
+end

data/manual/graphics/circle_and_ellipse.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+#
+# To define a <code>circle</code> all you need is the center point and the
+# radius.
+#
+# To define an <code>ellipse</code> you provide the center point and two radii
+# (or axes) values. If the second radius value is ommitted, both radii will be
+# equal and you will end up drawing a circle.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+  
+  stroke_circle [100, 300], 100
+    
+  fill_ellipse [200, 100], 100, 50
+    
+  fill_ellipse [400, 100], 50
+end

data/manual/graphics/color.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+#
+# We can change the stroke and fill colors providing an HTML rgb 6 digit color
+# code string ("AB1234") or 4 values for CMYK.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+  
+  # Fill with Yellow using RGB
+  fill_color "FFFFCC"
+  fill_polygon [50, 150], [150, 200], [250, 150],
+               [250, 50], [150, 0], [50, 50]
+  
+  # Stroke with Purple using CMYK
+  stroke_color 50, 100, 0, 0
+  stroke_rectangle [300, 300], 200, 100
+  
+  # Both together
+  fill_and_stroke_circle [400, 100], 50
+end

data/manual/graphics/common_lines.rb

@@ -0,0 +1,30 @@
+# encoding: utf-8
+#
+# Prawn provides helpers for drawing some commonly used lines:
+#
+# <code>vertical_line</code> and <code>horizontal_line</code> do just what their
+# names imply. Specify the start and end point at a fixed coordinate to define
+# the line.
+#
+# <code>horizontal_rule</code> draws a horizontal line on the current bounding
+# box from border to border, using the current y position.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+
+  stroke_color "ff0000"
+  
+  stroke do
+    # just lower the current y position
+    move_down 50  
+    horizontal_rule
+    
+    vertical_line   100, 300, :at => 50
+  
+    horizontal_line 200, 500, :at => 150
+  end
+end

data/manual/graphics/fill_and_stroke.rb

@@ -0,0 +1,42 @@
+# encoding: utf-8
+#
+# There are two drawing primitives in Prawn: <code>fill</code> and
+# <code>stroke</code>.
+#
+# These are the methods that actually draw stuff on the document. All the other
+# drawing shapes like <code>rectangle</code>, <code>circle</code> or
+# <code>line_to</code> define drawing paths. These paths need to be either
+# stroked or filled to gain form on the document.
+#
+# Calling these methods without a block will act on the drawing path that
+# has been defined prior to the call.
+#
+# Calling with a block will act on the drawing path set within the
+# block.
+#
+# Most of the methods which define drawing paths have methods of the same name
+# starting with stroke_ and fill_ which create the drawing path and then stroke
+# or fill it.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+  
+  # No block
+  line [0, 200], [100, 150]
+  stroke
+  
+  rectangle [0, 100], 100, 100
+  fill
+  
+  # With block
+  stroke { line [200, 200], [300, 150] }
+  fill   { rectangle [200, 100], 100, 100 }
+  
+  # Method hook
+  stroke_line [400, 200], [500, 150]
+  fill_rectangle [400, 100], 100, 100
+end

data/manual/graphics/fill_rules.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+#
+# Prawn's fill operators (<code>fill</code> and <code>fill_and_stroke</code>
+# both accept a <code>:fill_rule</code> option. These rules determine which
+# parts of the page are counted as "inside" vs. "outside" the path. There are
+# two fill rules:
+#
+# * <code>:nonzero_winding_number</code> (default): a point is inside the path
+# if a ray from that point to infinity crosses a nonzero "net number" of path
+# segments, where path segments intersecting in one direction are counted as
+# positive and those in the other direction negative.
+#
+# * <code>:even_odd</code>: A point is inside the path if a ray from that point
+# to infinity crosses an odd number of path segments, regardless of direction.
+#
+# The differences between the fill rules only come into play with complex
+# paths; they are identical for simple shapes.
+#
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  pentagram = [[181, 95], [0, 36], [111, 190], [111, 0], [0, 154]]
+
+  stroke_color 'ff0000'
+  line_width 2
+
+  text_box "Nonzero Winding Number", :at => [50, 215], :width => 170,
+           :align => :center
+  polygon(*pentagram.map { |x, y| [x+50, y] })
+  fill_and_stroke
+
+  text_box "Even-Odd", :at => [330, 215], :width => 170, :align => :center
+  polygon(*pentagram.map { |x, y| [x+330, y] })
+  fill_and_stroke(:fill_rule => :even_odd)
+end

data/manual/graphics/gradients.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+#
+# Note that because of the way PDF renders radial gradients in order to get
+# solid fill your start circle must be fully inside your end circle.
+# Otherwise you will get triangle fill like illustrated in the example below.
+
+require File.expand_path(File.join(File.dirname(__FILE__),
+                                   %w[.. example_helper]))
+
+filename = File.basename(__FILE__).gsub('.rb', '.pdf')
+Prawn::Example.generate(filename) do
+  stroke_axis
+  self.line_width = 10
+
+  fill_gradient [50, 300], [150, 200], 'ff0000', '0000ff'
+  fill_rectangle [50, 300], 100, 100
+
+  stroke_gradient [200, 200], [300, 300], '00ffff', 'ffff00'
+  stroke_rectangle [200, 300], 100, 100
+
+  fill_gradient [350, 300], [450, 200], 'ff0000', '0000ff'
+  stroke_gradient [350, 200], [450, 300], '00ffff', 'ffff00'
+  fill_and_stroke_rectangle [350, 300], 100, 100
+
+  fill_gradient [100, 100], 0, [100, 100], 70.71, 'ff0000', '0000ff'
+  fill_rectangle [50, 150], 100, 100
+
+  stroke_gradient [250, 100], 45, [250, 100], 70.71, '00ffff', 'ffff00'
+  stroke_rectangle [200, 150], 100, 100
+
+  stroke_gradient [400, 100], 45, [400, 100], 70.71, '00ffff', 'ffff00'
+  fill_gradient [400, 100], 0, [400, 100], 70.71, 'ff0000', '0000ff'
+  fill_and_stroke_rectangle [350, 150], 100, 100
+
+  fill_gradient [500, 300], 15, [500, 50], 0, 'ff0000', '0000ff'
+  fill_rectangle [485, 300], 30, 250
+end