prawn-manual_builder 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c85c4457c9cc7079dbd6d92ea0778aab34009074
+  data.tar.gz: fc8dc917c37b3d59791b9d5112e1f55a23e449f7
+SHA512:
+  metadata.gz: 582e12aaa4931c67442fec5b0946e4ea7ce384d84ea64e2477d1fbe10a8fc39637a8303cf1db6dfa8032ac950e180363c693804a2c5d1c5048e91bda90d24bdb
+  data.tar.gz: 7cd0ce8266d4544308cd40bf3f10cd35d2f8ff889bf9b4e1d315ce96aa6116c276b57dc5c4f9c54f6137c9bbbef96d4849e56f2b9c780a2c2ec12b9a900f1c6d

data/README.md

@@ -0,0 +1,6 @@
+# Prawn::ManualBuilder
+
+This is an experiment to extract manual building functionality from Prawn into
+its own standalone gem, so that it can be used by all Prawn extensions.
+
+**This is a work-in-progress and is not remotely ready for use yet!**

data/lib/prawn/manual_builder.rb

@@ -0,0 +1,34 @@
+require "enumerator"
+require "prawn"
+
+module Prawn
+  module ManualBuilder
+    def self.manual_dir=(dir)
+      @manual_dir = dir
+    end
+
+    def self.manual_dir
+      @manual_dir || Dir.pwd
+    end
+
+    def self.document_class
+      @document_class || Prawn::Document
+    rescue NameError
+      raise "Prawn::ManualBuilder.document_class was not set. "+
+            "Either assign a custom document class, or make sure to install "+
+            "and require the Prawn gem."
+
+    end
+
+    DATADIR = File.dirname(__FILE__) + "/../../data"
+  end
+end
+
+require_relative "manual_builder/example"
+require_relative "manual_builder/example_file"
+require_relative "manual_builder/example_section"
+require_relative "manual_builder/example_package"
+require_relative "manual_builder/syntax_highlight"
+require_relative "manual_builder/example"
+
+

data/lib/prawn/manual_builder/example.rb

@@ -0,0 +1,391 @@
+module Prawn
+  module ManualBuilder
+    # The Prawn::ManualBuilder::Example class holds all the helper methods 
+    # used to generate manuals.
+    #
+    # 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::ManualBuilder.document_class
+
+      # 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::ManualBuilder::DATADIR}/fonts/gkai00mp.ttf"
+        font_families["Kai"] = {
+          :normal => { :file => kai_file, :font => "Kai" }
+        }
+
+        dejavu_file = "#{Prawn::ManualBuilder::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
+end

data/lib/prawn/manual_builder/example_file.rb

@@ -0,0 +1,113 @@
+# encoding: utf-8
+
+module Prawn
+  module ManualBuilder
+    # The Prawn::ManualBuilder ExampleFile class is a utility class to ease 
+    # the manipulation and extraction of source code and comments from the 
+    # actual example files
+    #
+    class ExampleFile
+      attr_reader :package, :filename
+      
+      # Stores the file data, filename and parent, which will be either an
+      # ExampleSection or an ExamplePackage.
+      #
+      # Available boolean options are:
+      # 
+      # <tt>:eval_source</tt>:: Evals the example source code (default: true)
+      # <tt>:full_source</tt>:: Extract the full source code when true. Extract
+      # only the code between the generate block when false (default: false)
+      #
+      def initialize(parent, filename, options={})
+        @parent   = parent.is_a?(String) ? ExamplePackage.new(parent) : parent
+        
+        @filename = filename
+        @data     = read_file(@parent.folder_name, filename)
+        
+        @options  = {:eval_source => true, :full_source => false}.merge(options)
+      end
+      
+      # Return the example source code excluding the initial comments and
+      # require calls
+      #
+      def full_source
+        @data.gsub(/# encoding.*?\n.*require.*?\n\n/m, "\n").strip
+      end
+      
+      # Return the example source contained inside the first generate block or
+      # the full source if no generate block is found
+      #
+      def generate_block_source
+        block = @data.slice(/\w+\.generate.*? do\n(.*)end/m, 1)
+          
+        return full_source unless block
+        
+        block.gsub(/^( ){2}/, "")
+      end
+      
+      # Return either the full_source or the generate_block_source according
+      # to the options
+      #
+      def source
+        @options[:full_source] ? full_source : generate_block_source
+      end
+      
+      # Return true if the example source should be evaluated inline within
+      # the manual according to the options
+      #
+      def eval?
+        @options[:eval_source]
+      end
+      
+      # Retrieve the comments between the encoding declaration and the require
+      # call for example_helper.rb
+      #
+      # Then removes the '#' signs, reflows the line breaks and return the result
+      #
+      def introduction_text
+        intro = @data.lines.grep(/^#/).join
+        intro.gsub!(/\n# (?=\S)/m, ' ')
+        intro.gsub!(/^#/, '')
+        intro.gsub!("\n", "\n\n")
+        intro.rstrip!
+        intro
+      end
+      
+      # Returns a human friendly version of the example file name
+      #
+      def name
+        @name ||= @filename[/(.*)\.rb/, 1].gsub("_", " ").capitalize
+      end
+      
+      # Returns this example's parent original folder name
+      #
+      def parent_folder_name
+        @parent.folder_name
+      end
+      
+      # Returns the human friendly version of this example parent name
+      #
+      def parent_name
+        @parent.name
+      end
+      
+      # Renders this example to a pdf
+      #
+      def render(pdf)
+        pdf.render_example(self)
+      end
+      
+    private
+    
+      # Read the data from a file in a given package
+      #
+      def read_file(folder_name, filename)
+        data = File.read(File.expand_path(File.join(
+          Prawn::ManualBuilder.manual_dir, folder_name, filename)))
+
+        data.encode(::Encoding::UTF_8)
+      end
+      
+    end
+  end
+end

data/lib/prawn/manual_builder/example_package.rb

@@ -0,0 +1,54 @@
+# encoding: utf-8
+
+module Prawn
+  module ManualBuilder  
+    # The Prawn::ManualBuilder::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
+end

data/lib/prawn/manual_builder/example_section.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+module Prawn
+  module ManualBuilder
+    # The Prawn::ManualBuilder::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
+end

data/lib/prawn/manual_builder/syntax_highlight.rb

@@ -0,0 +1,56 @@
+# encoding: utf-8
+
+require "coderay"
+
+module Prawn
+  module ManualBuilder
+    # Registers a to_prawn method on CodeRay. It returns an array of hashes to be
+    # used with formatted_text.
+    #
+    # Usage:
+    #
+    # CodeRay.scan(string, :ruby).to_prawn
+    #
+    class PrawnEncoder < CodeRay::Encoders::Encoder
+      register_for :to_prawn
+
+      COLORS = { :default           => "FFFFFF",
+                 
+                 :comment           => "AEAEAE",
+                 :constant          => "88A5D2",
+                 :instance_variable => "E8ED97",
+                 :integer           => "C8FF0E",
+                 :float             => "C8FF0E",
+                 :inline_delimiter  => "EF804F",  # #{} within a string
+                 :keyword           => "FEE100",
+                 
+                 # BUG: There appear to be some problem with this token. Method
+                 #      definitions are considered as ident tokens
+                 #
+                 :method            => "FF5C00",
+                 :string            => "56D65E",
+                 :symbol            => "C8FF0E" 
+               }
+
+      def setup(options)
+        super
+        @out  = []
+        @open = []
+      end
+
+      def text_token(text, kind)
+        color = COLORS[kind] || COLORS[@open.last] || COLORS[:default]
+        
+        @out << {:text => text, :color => color}
+      end
+
+      def begin_group(kind)
+        @open << kind
+      end
+
+      def end_group(kind)
+        @open.pop
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: prawn-manual_builder
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Felipe Doria
+- Gregory Brown
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-03-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: coderay
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.7
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.7
+description: A tool for writing manuals for Prawn and Prawn accessories
+email:
+- felipe.doria@gmail.com
+- gregory.t.brown@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- data/fonts/DejaVuSans.ttf
+- data/fonts/Dustismo_Roman.ttf
+- data/fonts/gkai00mp.ttf
+- lib/prawn/manual_builder.rb
+- lib/prawn/manual_builder/example.rb
+- lib/prawn/manual_builder/example_file.rb
+- lib/prawn/manual_builder/example_package.rb
+- lib/prawn/manual_builder/example_section.rb
+- lib/prawn/manual_builder/syntax_highlight.rb
+homepage: 
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: A tool for writing manuals for Prawn and Prawn accessories
+test_files: []
+has_rdoc: