Permalink
Browse files

Documentation updates

  • Loading branch information...
1 parent bbd6a6d commit 9eba518c4c682ff5bcf5f8a384b3bda4ce0cd98f @practicingruby committed Aug 3, 2008
View
@@ -37,14 +37,17 @@ task :examples do
t = Time.now
puts "Running Examples"
examples.each { |file| `ruby -Ilib #{file}` }
- puts "Ran in #{Time.now - t} s"
- `mv *.pdf output`
+ puts "Ran in #{Time.now - t} s"
+ `mv *.pdf output`
+=begin
+ # Has some issues
puts "Checking for differences..."
output = Dir["output/*.pdf"]
- ref = Dir["reference_pdfs/*.pdf"]
+ ref = Dir["reference_pdfs/*.pdf"]
output.zip(ref).each do |o,r|
system "diff -q #{o} #{r}"
- end
+ end
+=end
end
spec = Gem::Specification.new do |spec|
View
@@ -26,7 +26,7 @@ class Document
# Creates and renders a PDF document.
#
- # The explicit receiver argument is necessary only when you need to make
+ # The block argument is necessary only when you need to make
# use of a closure.
#
# # Using implicit block form and rendering to a file
@@ -61,15 +61,15 @@ def self.generate(filename,options={},&block)
# <tt>:skip_page_creation</tt>:: Creates a document without starting the first page [false]
#
#
- # # New document, US Letter paper, portrait orientation
- # pdf = Prawn::Document.new
+ # # New document, US Letter paper, portrait orientation
+ # pdf = Prawn::Document.new
#
- # # New document, A4 paper, landscaped
- # pdf = Prawn::Document.new(:page_size => "A4", :page_layout => :landscape)
+ # # New document, A4 paper, landscaped
+ # pdf = Prawn::Document.new(:page_size => "A4", :page_layout => :landscape)
#
- # # New document, draws a line at the start of each new page
- # pdf = Prawn::Document.new(:on_page_start =>
- # lambda { |doc| doc.line [0,100], [300,100] } )
+ # # New document, draws a line at the start of each new page
+ # pdf = Prawn::Document.new(:on_page_start =>
+ # lambda { |doc| doc.line [0,100], [300,100] } )
#
def initialize(options={})
@objects = []
@@ -92,25 +92,16 @@ def initialize(options={})
start_new_page unless options[:skip_page_creation]
end
-
- def generate_margin_box
- old_margin_box = @margin_box
- @margin_box = BoundingBox.new(
- self,
- [ @margins[:left], page_dimensions[-1] - @margins[:top] ] ,
- :width => page_dimensions[-2] - (@margins[:left] + @margins[:right]),
- :height => page_dimensions[-1] - (@margins[:top] + @margins[:bottom])
- )
-
- # update bounding box if not flowing from the previous page
- # TODO: This may have a bug where the old margin is restored
- # when the bounding box exits.
- @bounding_box = @margin_box if old_margin_box == @bounding_box
- end
# Creates and advances to a new page in the document.
- # Runs the <tt>:on_page_start</tt> lambda if one was provided at
- # document creation time (See Document.new).
+ # Runs the <tt>on_page_start</tt> lambda if one was provided at
+ # document creation time (See Document.new).
+ #
+ # Page size, margins, and layout can also be set when generating a
+ # new page. These values will become the new defaults for page creation
+ #
+ # pdf.start_new_page(:size => "LEGAL", :layout => :landscape)
+ # pdf.start_new_page(:left_margin => 50, :right_margin => 50)
#
def start_new_page(options = {})
@page_size = options[:size] if options[:size]
@@ -196,8 +187,7 @@ def move_up(n)
def move_down(n)
self.y -= n
end
-
-
+
# Moves down the document and then executes a block.
#
# pdf.text "some text"
@@ -250,7 +240,22 @@ def mask(*fields) # :nodoc:
fields.each { |f| send("#{f}=", stored[f]) }
end
- private
+ private
+
+ def generate_margin_box
+ old_margin_box = @margin_box
+ @margin_box = BoundingBox.new(
+ self,
+ [ @margins[:left], page_dimensions[-1] - @margins[:top] ] ,
+ :width => page_dimensions[-2] - (@margins[:left] + @margins[:right]),
+ :height => page_dimensions[-1] - (@margins[:top] + @margins[:bottom])
+ )
+
+ # update bounding box if not flowing from the previous page
+ # TODO: This may have a bug where the old margin is restored
+ # when the bounding box exits.
+ @bounding_box = @margin_box if old_margin_box == @bounding_box
+ end
def ref(data)
@objects.push(Prawn::Reference.new(@objects.size + 1, data)).last
@@ -77,7 +77,8 @@ class Table
# <tt>:border_style</tt>:: If set to :grid, fills in all borders. Otherwise, borders are drawn on columns only, not rows
# <tt>:position</tt>:: One of <tt>:left</tt>, <tt>:center</tt> or <tt>n</tt>, where <tt>n</tt> is an x-offset from the left edge of the current bounding box
# <tt>:widths:</tt> A hash of indices and widths in PDF points. E.g. <tt>{ 0 => 50, 1 => 100 }</tt>
- # <tt>:row_colors</tt>:: An array of row background colors which are used cyclicly.
+ # <tt>:row_colors</tt>:: An array of row background colors which are used cyclicly.
+ # <tt>:align</tt>:: Alignment of text in columns [:left]
#
# Row colors are specified as html encoded values, e.g.
# ["ffffff","aaaaaa","ccaaff"]. You can also specify
@@ -27,13 +27,17 @@ module Text
# is being used ). Text will flow onto the next page when it reaches
# the bottom of the margin_box. Text wrap in Prawn does not re-flow
# linebreaks, so if you want fully automated text wrapping, be sure to
- # remove newlines before attempting to draw your string.
+ # remove newlines before attempting to draw your string.
#
# pdf.text "Hello World", :at => [100,100]
# pdf.text "Goodbye World", :at => [50,50], :size => 16
# pdf.text "Will be wrapped when it hits the edge of your bounding box"
#
- # All strings passed to this function should be encoded as UTF-8.
+ # If your font contains kerning pairs data that Prawn can parse, the
+ # text will be kerned by default. You can disable this feature by passing
+ # <tt>:kerning => false</tt>.
+ #
+ # Note that strings passed to this function should be encoded as UTF-8.
# If you get unexpected characters appearing in your rendered
# document, check this.
#
@@ -75,8 +79,12 @@ def text(text,options={})
}
end
end
-
- def font_metrics #:nodoc:
+
+ # Access to low-level font metrics data. This is only necessary for those
+ # who require direct access to font attributes, and can be safely ignored
+ # otherwise.
+ #
+ def font_metrics
@font_metrics ||= Prawn::Font::Metrics["Helvetica"]
end
@@ -121,7 +129,10 @@ def font(name)
# end
#
# text "At size 16"
- # end
+ # end
+ #
+ # When called without an argument, this method returns the current font
+ # size.
#
def font_size(size=nil)
return current_font_size unless size
@@ -40,7 +40,8 @@ class Cell
# <tt>:horizontal_padding</tt>:: The horizontal padding in PDF points
# <tt>:vertical_padding</tt>:: The vertical padding in PDF points
# <tt>:padding</tt>:: Overrides both horizontal and vertical padding
- # <tt>:border_style</tt>:: One of <tt>:all</tt>, <tt>:no_top</tt>, <tt>:no_bottom</tt>, <tt>:sides</tt>
+ # <tt>:border_style</tt>:: One of <tt>:all</tt>, <tt>:no_top</tt>, <tt>:no_bottom</tt>, <tt>:sides</tt>
+ # <tt>:align</tt>:: One of <tt>:left</tt>, <tt>:right</tt>, <tt>:center</tt>
#
def initialize(options={})
@point = options[:point]
@@ -64,7 +65,9 @@ def initialize(options={})
:document, :horizontal_padding, :vertical_padding,
:align
attr_writer :height, :width #:nodoc:
-
+
+ # Returns the cell's text as a string.
+ #
def to_s
@text
end
View
@@ -22,6 +22,18 @@ module Images
# <tt>:height</tt>:: the height of the image [actual height of the image]
# <tt>:width</tt>:: the width of the image [actual width of the image]
# <tt>:scale</tt>:: scale the dimensions of the image proportionally
+ #
+ # Prawn::Document.generate("image2.pdf", :page_layout => :landscape) do
+ # pigs = "#{Prawn::BASEDIR}/data/images/pigs.jpg"
+ # image pigs, :at => [50,450], :width => 450
+ #
+ # dice = "#{Prawn::BASEDIR}/data/images/dice.png"
+ # image dice, :at => [50, 450], :scale => 0.75
+ # end
+ #
+ # If only one of :width / :height are 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.
#
def image(filename, options={})
raise ArgumentError, "#{filename} not found" unless File.file?(filename)
@@ -12,7 +12,7 @@ module Prawn
module Images
# A convenience class that wraps the logic for extracting the parts
# of a PNG image that we need to embed them in a PDF
- class JPG #nodoc
+ class JPG #:nodoc:
attr_reader :width, :height, :bits, :channels
JPEG_SOF_BLOCKS = %W(\xc0 \xc1 \xc2 \xc3 \xc5 \xc6 \xc7 \xc9 \xca \xcb \xcd \xce \xcf)
@@ -14,7 +14,7 @@ module Prawn
module Images
# A convenience class that wraps the logic for extracting the parts
# of a PNG image that we need to embed them in a PDF
- class PNG #nodoc
+ class PNG #:nodoc:
attr_reader :palette, :img_data, :transparency
attr_reader :width, :height, :bits
attr_reader :color_type, :compression_method, :filter_method

0 comments on commit 9eba518

Please sign in to comment.