Update Manual

This uses new Manual Builder. It fixes text extraction and adds a new
coat of paint here and there.

Rakefile

@@ -8,8 +8,10 @@ task default: %i[spec rubocop]
 desc "Generate the 'Prawn by Example' manual"
 task :manual do
   puts 'Building manual...'
-  require File.expand_path(File.join(__dir__, %w[manual contents]))
-  prawn_manual_document.render_file('manual.pdf')
+  require_relative 'manual/manual'
+  manual_path = File.expand_path('manual/manual.rb', __dir__)
+  manual = eval(File.read(manual_path), TOPLEVEL_BINDING, manual_path)
+  manual.generate('manual.pdf')
   puts 'The Prawn manual is available at manual.pdf. Happy Prawning!'
 end
 

manual/basic_concepts.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'prawn/manual_builder'
+
+Prawn::ManualBuilder::Peritext.new do
+  text do
+    header_with_bg('Basic Concepts')
+
+    prose <<~TEXT
+      This chapter covers the minimum amount of functionality you'll need to
+      start using Prawn.
+
+      If you are new to Prawn this is the first chapter to read. Once you are
+      comfortable with the concepts shown here you might want to check the
+      Basics section of the Graphics, Bounding Box and Text sections.
+
+      The examples show:
+    TEXT
+
+    list(
+      'How to create new pdf documents in every possible way',
+      'Where the origin for the document coordinates is. What are Bounding '\
+        'Boxes and how they interact with the origin',
+      'How the cursor behaves',
+      'How to start new pages',
+      'What the base unit for measurement and coordinates is and how to use '\
+        'other convenient measures',
+      "How to build custom view objects that use Prawn's DSL"
+    )
+  end
+end

manual/basic_concepts/adding_pages.rb

@@ -1,26 +1,33 @@
 # frozen_string_literal: true
 
-# A PDF document is a collection of pages. When we create a new document be it
-# with <code>Document.new</code> or on a <code>Document.generate</code> block
-# one initial page is created for us.
-#
-# Some methods might create new pages automatically like <code>text</code> which
-# will create a new page whenever the text string cannot fit on the current
-# page.
-#
-# But what if you want to go to the next page by yourself? That is easy.
-#
-# Just use the <code>start_new_page</code> method and a shiny new page will be
-# created for you just like in the following snippet.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  text "We are still on the initial page for this example. Now I'll ask " \
-    'Prawn to gently start a new page. Please follow me to the next page.'
-
-  start_new_page
-
-  text "See. We've left the previous page behind."
+require 'prawn/manual_builder'
+
+Prawn::ManualBuilder::Chapter.new do
+  title 'Adding Pages'
+
+  text do
+    prose <<~TEXT
+      A PDF document is a collection of pages. When we create a new document be
+      it with <code>Document.new</code> or on a <code>Document.generate</code>
+      block one initial page is created for us.
+
+      Some methods might create new pages automatically like <code>text</code>
+      which will create a new page whenever the text string cannot fit on the
+      current page.
+
+      But what if you want to go to the next page by yourself? That is easy.
+
+      Just use the <code>start_new_page</code> method and a shiny new page will
+      be created for you just like in the following snippet.
+    TEXT
+  end
+
+  example do
+    text "We are still on the initial page for this example. Now I'll ask " \
+      'Prawn to gently start a new page. Please follow me to the next page.'
+
+    start_new_page
+
+    text "See. We've left the previous page behind."
+  end
 end

manual/basic_concepts/creation.rb

@@ -1,38 +1,49 @@
 # frozen_string_literal: true
 
-# There are three ways to create a PDF Document in Prawn: creating a new
-# <code>Prawn::Document</code> instance, or using the
-# <code>Prawn::Document.generate</code> method with and without block arguments.
-#
-# The following snippet showcase each way by creating a simple document with
-# some text drawn.
-#
-# When we instantiate the <code>Prawn::Document</code> object the actual pdf
-# document will only be created after we call <code>render_file</code>.
-#
-# The generate method will render the actual pdf object after exiting the block.
-# When we use it without a block argument the provided block is evaluated in the
-# context of a newly created <code>Prawn::Document</code> instance. When we use
-# it with a block argument a <code>Prawn::Document</code> instance is created
-# and passed to the block.
-#
-# The generate method without block arguments requires
-# less typing and defines and renders the pdf document in one shot.
-# Almost all of the examples are coded this way.
-
-require_relative '../example_helper'
-
-# Assignment
-pdf = Prawn::Document.new
-pdf.text 'Hello World'
-pdf.render_file 'assignment.pdf'
-
-# Implicit Block
-Prawn::Document.generate('implicit.pdf') do
-  text 'Hello World'
-end
+require 'prawn/manual_builder'
+
+Prawn::ManualBuilder::Chapter.new do
+  title 'Creating a PDF Document'
+
+  text do
+    prose <<~TEXT
+      There are three ways to create a PDF Document in Prawn: creating a new
+      <code>Prawn::Document</code> instance, or using the
+      <code>Prawn::Document.generate</code> method with and without block
+      arguments.
+
+      The following snippet showcase each way by creating a simple document with
+      some text drawn.
+
+      When we instantiate the <code>Prawn::Document</code> object the actual pdf
+      document will only be created after we call <code>render_file</code>.
+
+      The generate method will render the actual pdf object after exiting the
+      block. When we use it without a block argument the provided block is
+      evaluated in the context of a newly created <code>Prawn::Document</code>
+      instance. When we use it with a block argument a
+      <code>Prawn::Document</code> instance is created and passed to the block.
+
+      The generate method without block arguments requires less typing and
+      defines and renders the pdf document in one shot. Almost all of the
+      examples are coded this way.
+    TEXT
+  end
+
+  example eval: false, standalone: true do
+    # Assignment
+    pdf = Prawn::Document.new
+    pdf.text 'Hello World'
+    pdf.render_file 'assignment.pdf'
+
+    # Implicit Block
+    Prawn::Document.generate('implicit.pdf') do
+      text 'Hello World'
+    end
 
-# Explicit Block
-Prawn::Document.generate('explicit.pdf') do |pdf|
-  pdf.text 'Hello World'
+    # Explicit Block
+    Prawn::Document.generate('explicit.pdf') do |pdf|
+      pdf.text 'Hello World'
+    end
+  end
 end

manual/basic_concepts/cursor.rb

@@ -1,32 +1,38 @@
 # frozen_string_literal: true
 
-# We normally write our documents from top to bottom and it is no different with
-# Prawn. Even if the origin is on the bottom left corner we still fill the page
-# from the top to the bottom. In other words the cursor for inserting content
-# starts on the top of the page.
-#
-# Most of the functions that insert content on the page will start at the
-# current cursor position and proceed to the bottom of the page.
-#
-# The following snippet shows how the cursor behaves when we add some text to
-# the page and demonstrates some of the helpers to manage the cursor position.
-# The <code>cursor</code> method returns the current cursor position.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_axis
-
-  text "the cursor is here: #{cursor}"
-  text "now it is here: #{cursor}"
-
-  move_down 200
-  text "on the first move the cursor went down to: #{cursor}"
-
-  move_up 100
-  text "on the second move the cursor went up to: #{cursor}"
-
-  move_cursor_to 50
-  text "on the last move the cursor went directly to: #{cursor}"
+require 'prawn/manual_builder'
+
+Prawn::ManualBuilder::Chapter.new do
+  title 'Cursor'
+
+  text do
+    prose <<~TEXT
+      We normally write our documents from top to bottom and it is no different
+      with Prawn. Even if the origin is on the bottom left corner we still fill
+      the page from the top to the bottom. In other words the cursor for
+      inserting content starts on the top of the page.
+
+      Most of the functions that insert content on the page will start at the
+      current cursor position and proceed to the bottom of the page.
+
+      The following snippet shows how the cursor behaves when we add some text
+      to the page and demonstrates some of the helpers to manage the cursor
+      position. The <code>cursor</code> method returns the current cursor
+      position.
+    TEXT
+  end
+
+  example axes: true do
+    text "the cursor is here: #{cursor}"
+    text "now it is here: #{cursor}"
+
+    move_down 100
+    text "on the first move the cursor went down to: #{cursor}"
+
+    move_up 50
+    text "on the second move the cursor went up to: #{cursor}"
+
+    move_cursor_to 50
+    text "on the last move the cursor went directly to: #{cursor}"
+  end
 end

manual/basic_concepts/measurement.rb

@@ -1,24 +1,30 @@
 # frozen_string_literal: true
 
-# The base unit in Prawn is the PDF Point. One PDF Point is equal to 1/72 of
-# an inch.
-#
-# There is no need to waste time converting this measure. Prawn provides
-# helpers for converting from other measurements
-# to PDF Points.
-#
-# Just <code>require "prawn/measurement_extensions"</code> and it will mix some
-# helpers onto <code>Numeric</code> for converting common measurement units to
-# PDF Points.
+require 'prawn/manual_builder'
 
-require_relative '../example_helper'
+Prawn::ManualBuilder::Chapter.new do
+  title 'Measurement Extensions'
 
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  require 'prawn/measurement_extensions'
+  text do
+    prose <<~TEXT
+      The base unit in Prawn is the PDF Point. One PDF Point is equal to 1/72
+      of an inch.
 
-  %i[mm cm dm m in yd ft].each do |measurement|
-    text "1 #{measurement} in PDF Points: #{1.public_send(measurement)} pt"
-    move_down 5.mm
+      There is no need to waste time converting this measure. Prawn provides
+      helpers for converting from other measurements to PDF Points.
+
+      Just <code>require "prawn/measurement_extensions"</code> and it will mix
+      some helpers onto <code>Numeric</code> for converting common measurement
+      units to PDF Points.
+    TEXT
+  end
+
+  example do
+    require 'prawn/measurement_extensions'
+
+    %i[mm cm dm m in yd ft].each do |measurement|
+      text "1 #{measurement} in PDF Points: #{1.public_send(measurement)} pt"
+      move_down 5.mm
+    end
   end
 end