prawn 2.4.0 → 2.5.0

data/manual/graphics/stroke_join.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-# The join style defines how the intersection between two lines is drawn. There
-# are three types: <code>:miter</code> (the default), <code>:round</code> and
-# <code>:bevel</code>
-#
-# Just like <code>cap_style</code>, the difference between styles is better
-# seen with thicker lines.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_axis
-
-  self.line_width = 25
-
-  %i[miter round bevel].each_with_index do |style, i|
-    self.join_style = style
-
-    y = 200 - i * 100
-    stroke do
-      move_to(100, y)
-      line_to(200, y + 100)
-      line_to(300, y)
-    end
-    stroke_rectangle [400, y + 75], 50, 50
-  end
-end

data/manual/graphics/translate.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-# This transformation is used to translate the user space. Just provide the
-# x and y coordinates for the new origin.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_axis
-
-  1.upto(3) do |i|
-    x = i * 50
-    y = i * 100
-    translate(x, y) do
-      # Draw a point on the new origin
-      fill_circle [0, 0], 2
-      draw_text "New origin after translation to [#{x}, #{y}]",
-        at: [5, -2],
-        size: 8
-
-      stroke_rectangle [100, 75], 100, 50
-      text_box 'Top left corner at [100,75]',
-        at: [110, 65],
-        width: 80,
-        size: 8
-    end
-  end
-end

data/manual/graphics/transparency.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-# Although the name of the method is <code>transparency</code>, what we are
-# actually setting is the opacity for fill and stroke. So <code>0</code> means
-# completely transparent and <code>1.0</code> means completely opaque
-#
-# You may call it providing one or two values. The first value sets fill opacity
-# and the second value sets stroke opacity. If the second value is omitted fill
-# and stroke will have the same opacity.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_axis
-
-  self.line_width = 5
-  fill_color 'ff0000'
-  fill_rectangle [0, 100], 500, 100
-
-  fill_color '000000'
-  stroke_color 'ffffff'
-
-  base_x = 100
-  [[0.5, 1], 0.5, [1, 0.5]].each do |args|
-    transparent(*args) do
-      fill_circle [base_x, 100], 50
-      stroke_rectangle [base_x - 20, 100], 40, 80
-    end
-
-    base_x += 150
-  end
-end

data/manual/how_to_read_this_manual.rb

@@ -1,39 +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
-  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(Prawn::ManualBuilder::Example::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. Generally 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 throughout the manual is part of standard Prawn. It is defined in this file:
-
-  https://github.com/prawnpdf/prawn/blob/master/lib/prawn/graphics.rb
-  END_TEXT
-end

data/manual/images/absolute_position.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-# One of the options that the <code>image</code> method accepts is
-# <code>:at</code>. If you've read some of the graphics examples you are
-# probably already familiar with it. Just provide it the upper-left corner where
-# you want the image placed.
-#
-# While sometimes useful this option won't be practical. Notice that the cursor
-# won't be moved after the image is rendered and there is nothing forbidding the
-# text to overlap with the image.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  y_position = cursor
-  text "The image won't go below this line of text."
-
-  image "#{Prawn::DATADIR}/images/fractal.jpg", at: [200, y_position]
-
-  text 'And this line of text will go just below the previous one.'
-end

data/manual/images/fit.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-# <code>:fit</code> option is useful when you want the image to have the
-# maximum size within a container preserving the aspect ratio without
-# overlapping.
-#
-# Just provide the container width and height pair.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  size = 300
-
-  text 'Using the fit option'
-  bounding_box([0, cursor], width: size, height: size) do
-    image "#{Prawn::DATADIR}/images/pigs.jpg", fit: [size, size]
-    stroke_bounds
-  end
-end

data/manual/images/horizontal.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-# The image may be positioned relatively to the current bounding box. The
-# horizontal position may be set with the <code>:position</code> option.
-#
-# It may be <code>:left</code>, <code>:center</code>, <code>:right</code> or a
-# number representing an x-offset from the left boundary.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  bounding_box([50, cursor], width: 400, height: 450) do
-    stroke_bounds
-
-    %i[left center right].each do |position|
-      text "Image aligned to the #{position}."
-      image "#{Prawn::DATADIR}/images/stef.jpg", position: position
-    end
-
-    text 'The next image has a 50 point offset from the left boundary'
-    image "#{Prawn::DATADIR}/images/stef.jpg", position: 50
-  end
-end

data/manual/images/images.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-# Examples for embedding images.
-
-require_relative '../example_helper'
-
-Prawn::ManualBuilder::Example.generate('images.pdf', page_size: 'FOLIO') do
-  package 'images' do |p|
-    p.section 'Basics' do |s|
-      s.example 'plain_image'
-      s.example 'absolute_position'
-    end
-
-    p.section 'Relative Positioning' do |s|
-      s.example 'horizontal'
-      s.example 'vertical'
-    end
-
-    p.section 'Size' do |s|
-      s.example 'width_and_height'
-      s.example 'scale'
-      s.example 'fit'
-    end
-
-    p.intro do
-      prose <<-TEXT
-        Embedding images on PDF documents is fairly easy. Prawn supports both
-        JPG and PNG images.
-
-        The examples show:
-      TEXT
-
-      list(
-        'How to add an image to a page',
-        'How place the image on a specific position',
-        'How to configure the image dimensions by setting the width and '\
-          'height or by scaling it'
-      )
-    end
-  end
-end

data/manual/images/plain_image.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-# To embed images onto your PDF file use the <code>image</code> method.
-# It accepts the file path of the image to be loaded and some optional
-# arguments.
-#
-# If only the image path is provided the image will be rendered starting on
-# the cursor position. No manipulation is done with the image even if it doesn't
-# fit entirely on the page like the following snippet.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  text 'The image will go right below this line of text.'
-  image "#{Prawn::DATADIR}/images/pigs.jpg"
-end

data/manual/images/scale.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-# To scale an image use the <code>:scale</code> option.
-#
-# It scales the image proportionally given the provided value.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  text 'Normal size'
-  image "#{Prawn::DATADIR}/images/stef.jpg"
-  move_down 20
-
-  text 'Scaled to 50%'
-  image "#{Prawn::DATADIR}/images/stef.jpg", scale: 0.5
-  move_down 20
-
-  text 'Scaled to 200%'
-  image "#{Prawn::DATADIR}/images/stef.jpg", scale: 2
-end

data/manual/images/vertical.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-# 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_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  bounding_box([0, cursor], width: 500, height: 450) do
-    stroke_bounds
-
-    %i[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

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-# 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_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::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

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-# 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_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::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

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-# 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_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::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

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-# Examples for using grid layouts.
-
-require_relative '../example_helper'
-
-Prawn::ManualBuilder::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 <<-TEXT
-        Prawn has support for two-dimensional grid based layouts out of the box.
-
-        The examples show:
-      TEXT
-
-      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

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-# 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_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::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/outline/add_subsection_to.rb

@@ -1,60 +0,0 @@
-# frozen_string_literal: true
-
-# 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_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::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

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-# 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_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::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

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-# Examples for defining the document outline.
-
-require_relative '../example_helper'
-
-Prawn::ManualBuilder::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 <<-TEXT
-        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:
-      TEXT
-
-      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

@@ -1,66 +0,0 @@
-# frozen_string_literal: true
-
-# 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_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::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