prawn 2.3.0 → 2.5.0

data/manual/basic_concepts/origin.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-# This is the most important concept you need to learn about Prawn:
-#
-# PDF documents have the origin <code>[0,0]</code> at the bottom-left corner of
-# the page.
-#
-# A bounding box is a structure which provides boundaries for inserting content.
-# A bounding box also has the property of relocating the origin to its relative
-# bottom-left corner. However, be aware that the location specified when
-# creating a bounding box is its top-left corner, not bottom-left (hence the
-# <code>[100, 300]</code> coordinates below).
-#
-# Even if you never create a bounding box explictly, each document already comes
-# with one called the margin box. This initial bounding box is the one
-# responsible for the document margins.
-#
-# So practically speaking the origin of a page on a default generated document
-# isn't the absolute bottom left corner but the bottom left corner of the margin
-# box.
-#
-# The following snippet strokes a circle on the margin box origin. Then strokes
-# the boundaries of a bounding box and a circle on its origin.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_axis
-
-  stroke_circle [0, 0], 10
-
-  bounding_box([100, 300], width: 300, height: 200) do
-    stroke_bounds
-    stroke_circle [0, 0], 10
-  end
-end

data/manual/basic_concepts/other_cursor_helpers.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-# Another group of helpers for changing the cursor position are the pad methods.
-# They accept a numeric value and a block. <code>pad</code> will use the numeric
-# value to move the cursor down both before and after the block content.
-# <code>pad_top</code> will only move the cursor before the block while
-# <code>pad_bottom</code> will only move after.
-#
-# <code>float</code> is a method for not changing the cursor. Pass it a block
-# and the cursor will remain on the same place when the block returns.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_horizontal_rule
-  pad(20) { text 'Text padded both before and after.' }
-
-  stroke_horizontal_rule
-  pad_top(20) { text 'Text padded on the top.' }
-
-  stroke_horizontal_rule
-  pad_bottom(20) { text 'Text padded on the bottom.' }
-
-  stroke_horizontal_rule
-  move_down 30
-
-  text 'Text written before the float block.'
-
-  float do
-    move_down 30
-    bounding_box([0, cursor], width: 200) do
-      text 'Text written inside the float block.'
-      stroke_bounds
-    end
-  end
-
-  text 'Text written after the float block.'
-end

data/manual/basic_concepts/view.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-# The recommended way to extend Prawn's functionality is to include the
-# <code>Prawn::View</code> mixin in your own class, which will make all
-# <code>Prawn::Document</code> methods available to your custom objects.
-#
-# This approach is preferred over inheriting from
-# <code>Prawn::Document</code>, as your state will be kept completely separate
-# from <code>Prawn::Document</code>'s, thus avoiding accidental method
-# collisions.
-#
-# Note that <code>Prawn::View</code> lazily instantiates a
-# <code>Prawn::Document</code> with default initialization settings, such as
-# page size, layout, margins, etc.
-#
-# By defining your own <code>document</code> method, as shown in the example,
-# you will be able to override those settings and initialize a
-# <code>Prawn::Document</code> to your heart's content. This method will be
-# called repeatedly by <code>Prawn::View</code>, so be sure to memoize the
-# object by assigning it to an instance variable via the <code>||=</code>
-# operator.
-
-require_relative '../example_helper'
-
-class Greeter
-  include Prawn::View
-
-  def initialize(name)
-    @name = name
-  end
-
-  def say_hello
-    text "Hello, #{@name}!"
-  end
-
-  def say_goodbye
-    font('Courier') do
-      text "Goodbye, #{@name}!"
-    end
-  end
-end
-
-greeter = Greeter.new('Gregory')
-
-greeter.say_hello
-greeter.say_goodbye
-
-greeter.save_as('greetings.pdf')

data/manual/bounding_box/bounding_box.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-# Examples for bounding boxes.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename, page_size: 'FOLIO') do
-  package 'bounding_box' do |p|
-    p.section 'Basics' do |s|
-      s.example 'creation'
-      s.example 'bounds'
-    end
-
-    p.section 'Advanced' do |s|
-      s.example 'stretchy'
-      s.example 'nesting'
-      s.example 'indentation'
-      s.example 'canvas'
-      s.example 'russian_boxes'
-    end
-
-    p.intro do
-      prose <<-TEXT
-        Bounding boxes are the basic containers for structuring the content
-        flow. Even being low level building blocks sometimes their simplicity is
-        very welcome.
-
-        The examples show:
-      TEXT
-
-      list(
-        'How to create bounding boxes with specific dimensions',
-        'How to inspect the current bounding box for its coordinates',
-        'Stretchy bounding boxes',
-        'Nested bounding boxes',
-        'Indent blocks'
-      )
-    end
-  end
-end

data/manual/bounding_box/bounds.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-# The <code>bounds</code> method returns the current bounding box. This is
-# useful because the <code>Prawn::BoundingBox</code> exposes some nice boundary
-# helpers.
-#
-# <code>top</code>, <code>bottom</code>, <code>left</code> and
-# <code>right</code> methods return the bounding box boundaries relative to its
-# translated origin. <code>top_left</code>, <code>top_right</code>,
-# <code>bottom_left</code> and <code>bottom_right</code> return those boundaries
-# pairs inside arrays.
-#
-# All these methods have an "absolute" version like <code>absolute_right</code>.
-# The absolute version returns the same boundary relative to the page absolute
-# coordinates.
-#
-# The following snippet shows the boundaries for the margin box side by side
-# with the boundaries for a custom bounding box.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  def print_coordinates
-    text "top: #{bounds.top}"
-    text "bottom: #{bounds.bottom}"
-    text "left: #{bounds.left}"
-    text "right: #{bounds.right}"
-
-    move_down 10
-
-    text "absolute top: #{bounds.absolute_top.to_f.round(2)}"
-    text "absolute bottom: #{bounds.absolute_bottom.to_f.round(2)}"
-    text "absolute left: #{bounds.absolute_left.to_f.round(2)}"
-    text "absolute right: #{bounds.absolute_right.to_f.round(2)}"
-  end
-
-  text 'Margin box bounds:'
-  move_down 5
-  print_coordinates
-
-  bounding_box([250, cursor + 140], width: 200, height: 150) do
-    text 'This bounding box bounds:'
-    move_down 5
-    print_coordinates
-    transparent(0.5) { stroke_bounds }
-  end
-end

data/manual/bounding_box/canvas.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-# The origin example already mentions that a new document already comes with
-# a margin box whose bottom left corner is used as the origin for calculating
-# coordinates.
-#
-# What has not been told is that there is one helper for "bypassing" the margin
-# box: <code>canvas</code>. This method is a shortcut for creating a bounding
-# box mapped to the absolute coordinates and evaluating the code inside it.
-#
-# The following snippet draws a circle on each of the four absolute corners.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  canvas do
-    fill_circle [bounds.left, bounds.top],     30
-    fill_circle [bounds.right, bounds.top],    30
-    fill_circle [bounds.right, bounds.bottom], 30
-    fill_circle [0, 0],                        30
-  end
-end

data/manual/bounding_box/creation.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-# If you've read the basic concepts examples you probably know that the origin
-# of a page is on the bottom left corner and that the content flows from top to
-# bottom.
-#
-# You also know that a Bounding Box is a structure for helping the content flow.
-#
-# A bounding box can be created with the <code>bounding_box</code> method. Just
-# provide the top left corner, a required <code>:width</code> option and an
-# optional <code>:height</code>.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  bounding_box([200, cursor - 100], width: 200, height: 100) do
-    text 'Just your regular bounding box'
-
-    transparent(0.5) { stroke_bounds }
-  end
-end

data/manual/bounding_box/indentation.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-# Sometimes you just need to indent a portion of the contents of a bounding box,
-# and using a nested bounding box is pure overkill. The <code>indent</code>
-# method is what you might need.
-#
-# Just provide a number for it to indent all content generated inside the
-# block.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  text 'No indentation on the margin box.'
-  indent(20) do
-    text 'Some indentation inside an indent block.'
-  end
-  move_down 20
-
-  bounding_box([50, cursor], width: 400, height: cursor) do
-    transparent(0.5) { stroke_bounds }
-
-    move_down 10
-    text 'No indentation inside this bounding box.'
-    indent(40) do
-      text 'Inside an indent block. And so is this horizontal line:'
-
-      stroke_horizontal_rule
-    end
-    move_down 10
-    text 'No indentation'
-
-    move_down 20
-    indent(60) do
-      text 'Another indent block.'
-
-      bounding_box([0, cursor], width: 200) do
-        text 'Note that this bounding box coordinates are relative to the ' \
-          'indent block'
-
-        transparent(0.5) { stroke_bounds }
-      end
-    end
-  end
-end

data/manual/bounding_box/nesting.rb

@@ -1,52 +0,0 @@
-# frozen_string_literal: true
-
-# Normally when we provide the top left corner of a bounding box we
-# express the coordinates relative to the margin box. This is not the
-# case when we have nested bounding boxes. Once nested the inner bounding box
-# coordinates are relative to the outter bounding box.
-#
-# This example shows some nested bounding boxes with fixed and stretchy heights.
-# Note how the <code>cursor</code> method returns coordinates relative to
-# the current bounding box.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  def box_content(string)
-    text string
-    transparent(0.5) { stroke_bounds }
-  end
-
-  gap = 20
-  bounding_box([50, cursor], width: 400, height: 200) do
-    box_content('Fixed height')
-
-    bounding_box([gap, cursor - gap], width: 300) do
-      text 'Stretchy height'
-
-      bounding_box([gap, bounds.top - gap], width: 100) do
-        text 'Stretchy height'
-        transparent(0.5) do
-          dash(1)
-          stroke_bounds
-          undash
-        end
-      end
-
-      bounding_box([gap * 7, bounds.top - gap], width: 100, height: 50) do
-        box_content('Fixed height')
-      end
-
-      transparent(0.5) do
-        dash(1)
-        stroke_bounds
-        undash
-      end
-    end
-
-    bounding_box([gap, cursor - gap], width: 300, height: 50) do
-      box_content('Fixed height')
-    end
-  end
-end

data/manual/bounding_box/russian_boxes.rb

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-# This example is mostly just for fun, and shows how nested bounding boxes
-# can simplify calculations. See the "Bounding Box" section of the manual
-# for more basic uses.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  def combine(horizontal_span, vertical_span)
-    output = []
-    horizontal_span.each do |x|
-      vertical_span.each do |y|
-        output += [[x, y]]
-      end
-    end
-    output
-  end
-
-  def recurse_bounding_box(max_depth = 4, depth = 1)
-    width = (bounds.width - 15) / 2
-    height = (bounds.height - 15) / 2
-    left_top_corners = combine(
-      [5, bounds.right - width - 5],
-      [bounds.top - 5, height + 5]
-    )
-    left_top_corners.each do |lt|
-      bounding_box(lt, width: width, height: height) do
-        stroke_bounds
-        recurse_bounding_box(max_depth, depth + 1) if depth < max_depth
-      end
-    end
-  end
-
-  # Set up a bbox from the dashed line to the bottom of the page
-  bounding_box([0, cursor], width: bounds.width, height: cursor) do
-    recurse_bounding_box
-  end
-end

data/manual/bounding_box/stretchy.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-# Bounding Boxes accept an optional <code>:height</code> parameter. Unless it
-# is provided the bounding box will be stretchy. It will expand the height to
-# fit all content generated inside it.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  y_position = cursor
-  bounding_box([0, y_position], width: 200, height: 100) do
-    text 'This bounding box has a height of 100. If this text gets too large ' \
-      'it will flow to the next page.'
-
-    transparent(0.5) { stroke_bounds }
-  end
-
-  bounding_box([300, y_position], width: 200) do
-    text 'This bounding box has variable height. No matter how much text is ' \
-      'written here, the height will expand to fit.'
-
-    text ' _' * 100
-
-    text ' *' * 100
-
-    transparent(0.5) { stroke_bounds }
-  end
-end

data/manual/contents.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-# Generates the Prawn by example manual.
-
-require_relative 'example_helper'
-
-def prawn_manual_document
-  old_default_external_encoding = Encoding.default_external
-  Encoding.default_external = Encoding::UTF_8
-
-  Prawn::ManualBuilder::Example.new(
-    skip_page_creation: true,
-    page_size: 'FOLIO'
-  ) do
-    load_page '', 'cover'
-    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_page '', 'table'
-    load_package 'images'
-    load_package 'document_and_page_options'
-    load_package 'outline'
-    load_package 'repeatable_content'
-    load_package 'security'
-  end
-ensure
-  Encoding.default_external = old_default_external_encoding
-end

data/manual/cover.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-# Prawn manual how to read this manual page.
-
-require_relative 'example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::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]
-  )
-
-  unless ENV['CI']
-    git_commit =
-      if Dir.exist?("#{Prawn::BASEDIR}/.git")
-        commit = `git show --pretty=%h`
-        "git commit: #{commit.lines.first}"
-      else
-        ''
-      end
-
-    formatted_text_box(
-      [{
-        text: "Last Update: #{Time.now.strftime('%Y-%m-%d')}\n" \
-          "Prawn Version: #{Prawn::VERSION}\n#{git_commit}",
-        size: 12
-      }],
-      at: [390, cursor - 620]
-    )
-  end
-end

data/manual/document_and_page_options/background.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-# Pass an image path to the <code>:background</code> option and it will be used
-# as the background for all pages.
-# This option can only be used on document creation.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-
-img = "#{Prawn::DATADIR}/images/letterhead.jpg"
-
-Prawn::Document.generate(filename, background: img, margin: 100) do
-  text 'My report caption', size: 18, align: :right
-
-  move_down font.height * 2
-
-  text 'Here is my text explaning this report. ' * 20,
-    size: 12, align: :left, leading: 2
-
-  move_down font.height
-
-  text "I'm using a soft background. " * 40,
-    size: 12, align: :left, leading: 2
-end

data/manual/document_and_page_options/document_and_page_options.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-# Examples for stamps and repeaters.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename, page_size: 'FOLIO') do
-  package 'document_and_page_options' do |p|
-    p.example 'page_size',    eval_source: false, full_source: true
-    p.example 'page_margins', eval_source: false, full_source: true
-    p.example 'background',   eval_source: false, full_source: true
-    p.example 'metadata',     eval_source: false, full_source: true
-    p.example 'print_scaling', eval_source: false, full_source: true
-
-    p.intro do
-      prose <<-TEXT
-        So far we've already seen how to create new documents and start new
-        pages. This chapter expands on the previous examples by showing other
-        options avialable. Some of the options are only available when creating
-        new documents.
-
-        The examples show:
-      TEXT
-
-      list(
-        'How to configure page size',
-        'How to configure page margins',
-        'How to use a background image',
-        'How to add metadata to the generated PDF'
-      )
-    end
-  end
-end

data/manual/document_and_page_options/metadata.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-# To set the document metadata just pass a hash to the <code>:info</code>
-# option when creating new documents.
-# The keys in the example below are arbitrary, so you may add whatever keys you
-# want.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-
-info = {
-  Title: 'My title',
-  Author: 'John Doe',
-  Subject: 'My Subject',
-  Keywords: 'test metadata ruby pdf dry',
-  Creator: 'ACME Soft App',
-  Producer: 'Prawn',
-  CreationDate: Time.now
-}
-
-Prawn::Document.generate(filename, info: info) do
-  text 'This is a test of setting metadata properties via the info option.'
-  text 'While the keys are arbitrary, the above example sets common attributes.'
-end

data/manual/document_and_page_options/page_margins.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-# The default margin for pages is 0.5 inch but you can change that with the
-# <code>:margin</code> option or if you'd like to have different margins you
-# can use the <code>:left_margin</code>, <code>:right_margin</code>,
-# <code>:top_margin</code>, <code>:bottom_margin</code> options.
-#
-# These options are available both for starting new pages and creating new
-# documents.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::Document.generate(filename, margin: 100) do
-  text '100 pts margins.'
-  stroke_bounds
-
-  start_new_page(left_margin: 300)
-  text '300 pts margin on the left.'
-  stroke_bounds
-
-  start_new_page(top_margin: 300)
-  text '300 pts margin both on the top and on the left. Notice that whenever ' \
-    'you set an option for a new page it will remain the default for the ' \
-    'following pages.'
-  stroke_bounds
-
-  start_new_page(margin: 50)
-  text '50 pts margins. Using the margin option will reset previous specific ' \
-    'calls to left, right, top and bottom margins.'
-  stroke_bounds
-
-  start_new_page(margin: [50, 100, 150, 200])
-  text 'There is also the shorthand CSS like syntax used here.'
-  stroke_bounds
-end

data/manual/document_and_page_options/page_size.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-# Prawn comes with support for most of the common page sizes so you'll only need
-# to provide specific values if your intended format is not supported. To see a
-# list with all supported sizes take a look at PDF::Core::PageGeometry
-#
-# # To define the size use <code>:page_size</code> when creating new documents
-# and <code>:size</code> when starting new pages. The default page size for new
-# documents is LETTER (612.00 x 792.00).
-#
-# You may also define the orientation of the page to be either portrait
-# (default) or landscape. Use <code>:page_layout</code> when creating new
-# documents and <code>:layout</code> when starting new pages.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::Document.generate(
-  filename,
-  page_size: 'EXECUTIVE',
-  page_layout: :landscape
-) do
-  text 'EXECUTIVE landscape page.'
-
-  custom_size = [275, 326]
-
-  ['A4', 'TABLOID', 'B7', custom_size].each do |size|
-    start_new_page(size: size, layout: :portrait)
-    text "#{size} portrait page."
-
-    start_new_page(size: size, layout: :landscape)
-    text "#{size} landscape page."
-  end
-end