srdperu-prawn-format 0.1.1.2 → 0.1.2

data/examples/document.rb

@@ -1,61 +0,0 @@
-#coding: utf-8
-
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
-require "prawn"
-require "prawn/format"
-
-Prawn::Document.generate("document.pdf") do
-  tags :h1 => { :font_size => "2em", :font_weight => :bold },
-       :h2 => { :font_size => "1.5em", :font_weight => :bold },
-       :stave => { :display => :break, :meta => { :name => :anchor }, :font_weight => :bold, :font_size => "2em" },
-       :title => { :font_weight => :bold, :font_size => "1.5em" },
-       :indent => { :width => "2em" }
-
-  font "Times-Roman", :size => 14
-  File.open("#{File.dirname(__FILE__)}/christmas-carol.txt") do |story|
-    line_number = 0
-    story.each_line do |line|
-      line_number += 1
-      next if line.strip == ""
-
-      type, data = line.match(/^(\w+)\.\s*(.*)/)[1,2]
-
-      case type
-      when "h1"
-        move_text_position 144
-        text "<h1>#{data}</h1>", :align => :center
-        move_text_position 72
-        
-      when "h2"
-        text "<h2>#{data}</h2>", :align => :center
-        move_text_position 72
-        
-      when "toc"
-        bounding_box [bounds.left+bounds.width/4, y-bounds.absolute_bottom], :width => bounds.width do
-          text(data)
-        end
-
-      when "stave"
-        start_new_page
-        text(data, :align => :center)
-        move_text_position 72
-
-      when "p"
-        text("<indent/>" + data, :align => :justify)
-
-      when "song"
-        move_text_position font_size/2
-        text(data, :align => :center)
-        move_text_position font_size/2
-
-      when "block"
-        text(data, :align => :justify)
-
-      when "stop"
-        break
-
-      else raise "unknown block type #{type.inspect} (line \##{line_number})"
-      end
-    end
-  end
-end

data/examples/flowing.rb

@@ -1,24 +0,0 @@
-#coding: utf-8
-
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
-require 'prawn'
-require 'prawn/format'
-
-dice = "#{Prawn::BASEDIR}/data/images/dice.png"
-Prawn::Document.generate "flowing.pdf" do
-  # first, position an image that we'll flow around
-  width = bounds.width / 2 - 18 # give us some padding on the left of the image
-  info = image(dice, :width => width, :position => :right)
-
-  # create the layout helper that we'll use to flow the text
-  layout(DATA.read, :align => :justify) do |helper|
-    # fill the first box
-    y = helper.fill(bounds.left, bounds.top, width, :height => info.scaled_height + font_size - 1)
-
-    # fill the rest
-    self.y = helper.fill(bounds.left, y, bounds.width)
-  end
-end
-
-__END__
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse ut neque. Maecenas scelerisque euismod purus. Nam venenatis. Sed velit mauris, cursus sit amet, semper vitae, sagittis quis, tortor. Nam at nisi. Sed ac nibh. Curabitur auctor ipsum nec tellus. Suspendisse potenti. Morbi dapibus magna a velit. Ut fringilla enim eu enim. Quisque lacinia, arcu dignissim gravida semper, eros quam tempor nisi, non scelerisque massa odio ut mi. Nullam ac ipsum. Proin volutpat tristique sem. Sed ipsum felis, volutpat vel, porttitor id, volutpat eu, mauris. Cras eget nulla sit amet dolor cursus semper. Curabitur nulla nunc, accumsan sit amet, vestibulum sit amet, adipiscing in, lorem. Pellentesque sodales purus sit amet odio. Cras commodo. Nam accumsan. Suspendisse potenti. Fusce posuere neque in nulla. Ut cursus blandit nisl. Phasellus ut nulla quis nunc tempus consequat. In hac habitasse platea dictumst. Praesent molestie nisl nec erat. Vivamus pretium nibh sit amet est. Integer dolor. Sed dictum blandit purus. Quisque et mauris vel diam dictum dignissim. Maecenas ultrices. Cras leo risus, tristique quis, hendrerit eu, condimentum tempor, mi. Nullam consectetur ante non nisl. Nulla dignissim sem in turpis. Cras purus felis, molestie ac, rhoncus sed, suscipit et, nisl. Donec tempus justo eu turpis. Aenean quis diam at dolor interdum tempor. Mauris sed nulla vitae erat lobortis lacinia. Nunc mauris. Aliquam mattis egestas ligula. Morbi magna dolor, convallis id, interdum lacinia, pellentesque eu, velit. In non arcu. Duis a nibh. Vestibulum volutpat erat et magna. Vivamus mi ante, aliquam et, vulputate sit amet, pretium non, ligula. Curabitur elementum, nisl ut gravida placerat, nisl sapien posuere augue, a placerat urna enim in velit. Cras nisi. Suspendisse volutpat. Ut eu lorem sed eros sollicitudin volutpat. Quisque blandit, libero sed mattis scelerisque, elit turpis ultricies purus, quis faucibus orci erat quis sem. Vestibulum imperdiet facilisis ante. Mauris dignissim, arcu vitae tincidunt congue, ante nulla aliquam purus, a porta tellus nisl at lectus. Phasellus commodo lacus et tortor. Etiam tortor leo, scelerisque sit amet, lobortis non, gravida vitae, mi. Donec eget augue. Sed ultrices ipsum eget risus. Aliquam rhoncus arcu vitae orci pellentesque pulvinar. Praesent ornare, lacus eget elementum ultrices, massa justo dignissim massa, a suscipit elit nibh quis arcu. Aliquam non massa. Etiam pharetra nisi at risus. Donec felis turpis, suscipit a, luctus vulputate, lobortis id, neque. Proin vitae nibh. Pellentesque nibh risus, volutpat sollicitudin, lobortis vitae, malesuada eu, elit. Duis felis nulla, sagittis id, faucibus luctus, viverra id, eros. Phasellus vulputate leo eget libero. Ut ut ipsum ac dui accumsan placerat. Integer porttitor. Quisque gravida dolor eu diam. Phasellus sodales sem sit amet urna. Morbi ornare viverra mauris. 

data/examples/style-classes.rb

@@ -1,12 +0,0 @@
-#coding: utf-8
-
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
-require 'prawn'
-require 'prawn/format'
-
-Prawn::Document.generate "style-classes.pdf" do
-  styles :quote => { :font_style => :italic },
-         :product => { :font_weight => :bold, :color => "#007" }
-
-  text "<span class='product'>Prawn</span> is a fantastic utility for formatting PDF's. Jamis Buck may once have said, speaking of <span class='product'>Prawn</span>, <span class='quote'>\"<span class='product'>Prawn</span> is <em>the</em> single most fantastic PDF creation library ever to be written. In Ruby. In 2008. By Greg Brown.\"</span>"
-end

data/examples/syntax-highlighting.rb

@@ -1,31 +0,0 @@
-#coding: utf-8
-
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
-require 'prawn'
-require 'prawn/format'
-
-begin
-  require 'coderay'
-rescue LoadError
-  abort "This example (#{__FILE__}) requires the 'coderay' gem.\n" +
-    "Please make sure it is installed."
-end
-
-# Use CodeRay to parse the source and return HTML
-html = CodeRay.scan(File.read(__FILE__), :ruby).html(:line_numbers => :inline)
-
-# Use prawn and prawn/format to parse and format the HTML
-Prawn::Document.generate "syntax-highlighting.pdf", :page_layout => :landscape do
-  styles :no  => { :color => "gray" },
-         :c   => { :color => "#666" },
-         :s   => { :color => "#d20" },
-         :dl  => { :color => "black" },
-         :co  => { :color => "#036", :font_weight => :bold },
-         :pc  => { :color => "#038", :font_weight => :bold },
-         :sy  => { :color => "#A60" },
-         :r   => { :color => "#080" },
-         :i   => { :color => "#00D", :font_weight => :bold },
-         :idl => { :color => "#888", :font_weight => :bold }
-
-  text "<pre>#{html}</pre>"
-end

data/examples/tags.rb

@@ -1,24 +0,0 @@
-#coding: utf-8
-
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
-require 'prawn'
-require 'prawn/format'
-
-CHINESE_FONT = "#{Prawn::BASEDIR}/data/fonts/gkai00mp.ttf"
-
-Prawn::Document.generate "tags.pdf" do
-  # tweak an existing tag
-  tags[:em][:color] = "red"
-  
-  # completely redefine an existing tag
-  tags[:strong] = { :text_decoration => :underline }
-
-  # define altogether new tags
-  tags :chinese => { :font_family => CHINESE_FONT },
-       :exp     => { :vertical_align => :super, :font_size => "70%", :color => "blue", :font_weight => :bold },
-       :header  => { :font_weight => :bold, :font_size => 24, :text_decoration => :underline }
-
-  text "<header>Fun with Tags</header>"
-
-  text "<em>Emphasized text</em>, <strong>strong text</strong>, <chinese>汉语</chinese>, and <code>E = mc<exp>2</exp></code>"
-end

data/manual/html.rb

@@ -1,187 +0,0 @@
-$LOAD_PATH.unshift "#{File.dirname(__FILE__)}/../lib"
-require 'prawn/format/version'
-require 'coderay'
-
-def process_style(document, style, content, line_number)
-  content = process_substitutions(content)
-
-  case style
-  when "h1"        then h1(document, content)
-  when "h2"        then h2(document, content)
-  when "p"         then paragraph(document, content)
-  when "fp"        then paragraph(document, content, false)
-  when "ul"        then start_list(document)
-  when "li"        then list_item(document, content)
-  when "/ul"       then end_list(document)
-  when "page"      then new_page(document)
-  when "highlight" then highlight(document, content)
-  when "hr"        then horiz_rule(document)
-  when "center"    then center(document, content)
-  else warn "unknown style #{style.inspect}"
-  end
-
-rescue Exception => err
-  puts "[error occurred while processing line ##{line_number}]"
-  raise
-end
-
-def process_substitutions(content)
-  content.
-    gsub(/%FORMAT:VERSION%/, Prawn::Format::Version::STRING).
-    gsub(/%NOW%/, Time.now.utc.strftime("%e %B %Y at %H:%M UTC")).
-    gsub(/%PDF\{(.*?)\}HTML\{(.*?)\}END%/, '\\2')
-end
-
-def center(document, content)
-  document << "<center>#{content}</center>\n"
-end
-
-def horiz_rule(document)
-  document << "<hr />\n"
-end
-
-def h1(document, content)
-  document << "<h1>#{content}</h1>\n"
-end
-
-def h2(document, content)
-  document << "<h2>#{content}</h2>\n"
-end
-
-def paragraph(document, content, indent=true)
-  return unless content.strip.length > 0
-  document << "<p class='#{indent ? 'indent' : ''}'>#{content}</p>\n"
-end
-
-def start_list(document)
-  document << "<ul>\n"
-end
-
-def list_item(document, content)
-  document << "<li>#{content}</li>\n"
-end
-
-def end_list(document)
-  document << "</ul>\n"
-end
-
-def new_page(document)
-  document << "<hr />\n"
-end
-
-def highlight(document, content)
-  file, syntax = content.split(/,/)
-  analyzed = CodeRay.scan(File.read(File.join(File.dirname(__FILE__), file)), syntax.to_sym)
-  document << "<pre class='highlight'>#{analyzed.html}</pre>"
-end
-
-File.open("prawn-format.html", "w") do |html|
-  html << "<html>\n<head>\n<style type='text/css'>#{DATA.read}</style>\n</head>"
-  html << "<body>\n"
-  File.open("#{File.dirname(__FILE__)}/manual.txt") do |source|
-    number = 0
-    source.each_line do |line|
-      number += 1
-      line.chomp!
-      next if line.length == 0
-
-      style, content = line.match(/^(\S+)\.\s*(.*)/)[1,2]
-      process_style(html, style, content, number)
-    end
-  end
-  html << "</body>\n</html>\n"
-end
-
-__END__
-body {
-  margin-left: 15%;
-  margin-right: 15%;
-  margin-top: 1em;
-}
-
-pre.highlight {
-  background-color: #f8f8f8;
-  border: 1px solid silver;
-  font-family: Courier, monospace;
-  font-size: 90%;
-  color: #100;
-  line-height: 1.1em;
-  padding: 1em;
-}
-
-.highlight .af { color:#00C }
-.highlight .an { color:#007 }
-.highlight .av { color:#700 }
-.highlight .aw { color:#C00 }
-.highlight .bi { color:#509; font-weight:bold }
-.highlight .c  { color:#888 }
-
-.highlight .ch { color:#04D }
-.highlight .ch .k { color:#04D }
-.highlight .ch .dl { color:#039 }
-
-.highlight .cl { color:#B06; font-weight:bold }
-.highlight .co { color:#036; font-weight:bold }
-.highlight .cr { color:#0A0 }
-.highlight .cv { color:#369 }
-.highlight .df { color:#099; font-weight:bold }
-.highlight .di { color:#088; font-weight:bold }
-.highlight .dl { color:black }
-.highlight .do { color:#970 }
-.highlight .ds { color:#D42; font-weight:bold }
-.highlight .e  { color:#666; font-weight:bold }
-.highlight .en { color:#800; font-weight:bold }
-.highlight .er { color:#F00; background-color:#FAA }
-.highlight .ex { color:#F00; font-weight:bold }
-.highlight .fl { color:#60E; font-weight:bold }
-.highlight .fu { color:#06B; font-weight:bold }
-.highlight .gv { color:#d70; font-weight:bold }
-.highlight .hx { color:#058; font-weight:bold }
-.highlight .i  { color:#00D; font-weight:bold }
-.highlight .ic { color:#B44; font-weight:bold }
-
-.highlight .il { background: #eee }
-.highlight .il .il { background: #ddd }
-.highlight .il .il .il { background: #ccc }
-.highlight .il .dl { font-weight: bold ! important; color: #888 ! important }
-
-.highlight .in { color:#B2B; font-weight:bold }
-.highlight .iv { color:#33B }
-.highlight .la { color:#970; font-weight:bold }
-.highlight .lv { color:#963 }
-.highlight .oc { color:#40E; font-weight:bold }
-.highlight .on { color:#000; font-weight:bold }
-.highlight .op { }
-.highlight .pc { color:#038; font-weight:bold }
-.highlight .pd { color:#369; font-weight:bold }
-.highlight .pp { color:#579 }
-.highlight .pt { color:#339; font-weight:bold }
-.highlight .r  { color:#080; font-weight:bold }
-
-.highlight .rx { background-color:#fff0ff }
-.highlight .rx .k { color:#808 }
-.highlight .rx .dl { color:#404 }
-.highlight .rx .mod { color:#C2C }
-.highlight .rx .fu  { color:#404; font-weight: bold }
-
-.highlight .s  { background-color:#fff0f0 }
-.highlight .s  .s { background-color:#ffe0e0 }
-.highlight .s  .s  .s { background-color:#ffd0d0 }
-.highlight .s  .k { color:#D20 }
-.highlight .s  .dl { color:#710 }
-
-.highlight .sh { background-color:#f0fff0 }
-.highlight .sh .k { color:#2B2 }
-.highlight .sh .dl { color:#161 }
-
-.highlight .sy { color:#A60 }
-.highlight .sy .k { color:#A60 }
-.highlight .sy .dl { color:#630 }
-
-.highlight .ta { color:#070 }
-.highlight .tf { color:#070; font-weight:bold }
-.highlight .ts { color:#D70; font-weight:bold }
-.highlight .ty { color:#339; font-weight:bold }
-.highlight .v  { color:#036 }
-.highlight .xt { color:#444 }
-

data/manual/include/basics.rb

@@ -1,6 +0,0 @@
-require 'prawn'
-require 'prawn/format'
-
-Prawn::Document.generate('basics.pdf') do
-  text "Some <b>bold</b> and <i>italic</i> text"
-end

data/manual/include/breaks.rb

@@ -1,13 +0,0 @@
-# renders all on one line
-text <<-TEXT
-  &bull; Item one
-  &bull; Item two
-  &bull; Item three
-TEXT
-
-# renders all on three separate lines
-text <<-TEXT
-  &bull; Item one<br/>
-  &bull; Item two<br/>
-  &bull; Item three
-TEXT

data/manual/include/custom-tags.rb

@@ -1,10 +0,0 @@
-Prawn::Document.generate('basics.pdf') do
-  tags :h1 => { :font_size => "3em", :font_weight => :bold },
-    :h2 => { :font_size => "2em", :font_style => :italic },
-    :product => { :color => "red",
-                  :text_decoration => :underline }
-
-  text "<h1>Manual</h1>"
-  text "<h2>Learning to do stuff</h2>"
-  text "<product>Prawn</product> is a PDF generator for Ruby"
-end

data/manual/include/custom-tags2.rb

@@ -1,2 +0,0 @@
-tags[:em][:color] = "red"
-text "This really <em>matters</em>!"

data/manual/include/indent.rb

@@ -1,4 +0,0 @@
-tags[:indent] = { :width => "2em" }
-
-text "<indent/>Once upon a time, far, far away..."
-text "<indent/>But the prince was not discouraged! ..."

data/manual/include/options.rb

@@ -1,15 +0,0 @@
-# force unformatted display
-text "Show <b>this</b> verbatim", :plain => true
-
-# force formatted display for full justification
-text "I want this to be fully justified", :plain => false,
-  :align => :justify
-
-# assume all text is blue
-text "Blue text", :plain => false,
-  :default_style => { :color => "blue" }
-
-# one-off tag and style definitions
-text "<nifty class='orange'>Nifty!</nifty>",
-  :tags => { :nifty => { :font_weight => :bold } },
-  :styles => { :orange => { :color => "#fa0" } }

data/manual/include/style-classes.rb

@@ -1,5 +0,0 @@
-styles :product => { :color => "navy" },
-       :ruby => { :color => "red", :font_family => "Courier",
-                  :white_space => :pre }
-text "In <b class='product'>Ruby</b>, you can write " +
-     "<code class='ruby'>1.upto(5) { |x| puts x }</code>"

data/manual/manual.txt

@@ -1,101 +0,0 @@
-h1. Prawn::Format %FORMAT:VERSION%
-p. %PDF{}HTML{<em>A PDF version of this document may be downloaded <a href="http://jamisbuck.org/files/prawn-format-%FORMAT:VERSION%.pdf">here</a>.</em>}END%
-fp. Prawn::Format is an extension library for the Prawn PDF generation library for Ruby, allowing you to easily embed formatting <em>tags</em> in your documents. It features:
-ul.
-li. Out-of-the-box support for many common HTML tags
-li. Intra-document hyperlinks
-li. Easily add your own tag definitions
-li. Style classes
-/ul.
-p. Sound good? It's not all roses, though. Prawn::Format currently has the following known warts:
-ul.
-li. No support for block-level tags (paragraphs, divs, tables, etc.)
-li. No support for inline images
-/ul.
-p. If that doesn't deter you, read on! This manual currently has information about the following topics:
-ul.
-li. <a href="#basic-usage">Basic usage</a>
-li. <a href="#custom-tags">Custom tags</a>
-li. <a href="#style-classes">Style classes</a>
-li. <a href="#text-options"><code>text()</code> options</a>
-/ul.
-p. Prawn::Format was written by Jamis Buck (jamis@jamisbuck.org). Although there are not currently plans to extend the functionality much beyond the current incarnation, Jamis is definitely amenable to patches. What this means is that if you've got a pet feature you'd like to see in Prawn::Format, your best bet is to get to work and implement it!
-p. Bug reports are welcome, and may be submitted at:
-center. <b>http://prawn.lighthouseapp.com/projects/23476</b>
-p. And if you're inclined to help out with patches and the like, the code is hosted at (where else?) GitHub:
-center. <b>http://github.com/jamis/prawn-format</b>
-p. Thanks!
-hr.
-fp. <about>This manual generated for Prawn::Format version %FORMAT:VERSION% on %NOW%.</about>
-
-page.
-h2. <a name="basic-usage"></a>Basic usage
-fp. For most uses, adding text to your documents is exactly the same as it is in Prawn. The only difference is that you now add formatting tags (HTML-ish in nature) to the strings:
-highlight. include/basics.rb,ruby
-p. Prawn::Format does not support even the majority of HTML tags by default, but it does include support for the most common ones (and you can easily <a href="#custom-tags">add others</a> if you so desire). The supported tags are:
-ul.
-li. <code>a</code> &mdash; for hyperlinks (the <code>name</code> attribute is for hyperlink anchors, and the <code>href</code> attribute is for the actual links, just like in HTML)
-li. <code>b</code> &mdash; bold-faced text (but only if the currently selected font family supports bold text)
-li. <code>br</code> &mdash; line break
-li. <code>code</code> &mdash; switch to monospaced font (Courier, by default)
-li. <code>em</code> &mdash; italicized text (but only if the currently selected font family supports italicized text)
-li. <code>font</code> &mdash; change font attributes, include <code>face</code> (to change font family), <code>color</code>, and <code>size</code>
-li. <code>i</code> &mdash; italicized text (see <code>em</code>)
-li. <code>pre</code> &mdash; "verbatim" text (preserving whitespace and newlines). Unlike the HTML <code>pre</code> tag, this is not a block tag
-li. <code>span</code> &mdash; has no formatting, by default, but is recognized so that you can apply <a href="#style-classes">style classes</a> to the tag
-li. <code>strong</code> &mdash; bold-faced text (see <code>b</code>)
-li. <code>sub</code> &mdash; subscript text
-li. <code>sup</code> &mdash; superscript text
-li. <code>tt</code> &mdash; monospaced font (see <code>code</code>)
-li. <code>u</code> &mdash; underlined text
-/ul.
-p. You've likely noticed, already, the conspicuous absence of such common HTML tags as <code>p</code>, <code>div</code>, and <code>table</code>. The reason these are missing is simple: Prawn::Format has no real box model. Turns out, implementing such a beast is a really, really complicated thing to do right. However, you can work around this limitation without too much effort. In fact, <em>%PDF{this entire manual is formatted using Prawn::Format!}HTML{the <a href="http://jamisbuck.org/files/prawn-format-%FORMAT:VERSION%.pdf">PDF version of this manual</a> was entirely formatted using Prawn::Format!}END%</em> (The source code for the manual is included in the Prawn::Format distribution; see <code>manual/pdf.rb</code> and <code>manual/html.rb</code>. Also, <code>examples/document.rb</code> has a simpler demonstration of wholesale document formatting.)
-p. One particularly important thing to note about Prawn::Format tags: these are XML tags, and not HTML tags! The distinction is moot in most cases, but what this means in practical terms is that you <em>cannot</em> have unclosed tags in Prawn::Format. Even tags like <code>&lt;br&gt;</code> (which HTML allows to exist unclosed) must be closed. However, Prawn::Format allows you to use the abbreviated "open/close" XML syntax, e.g., <code>&lt;br/&gt;</code>.
-p. Lastly, Prawn::Format will ignore whitespace, just like HTML. (Unless you're operating in verbatim mode, usually introduced via the <code>&lt;pre&gt;</code> tag.) This means that newlines in your text will <em>not</em> translate to newlines in your output; you need to use the line-break tag <code>&lt;br/&gt;</code> to put line-breaks in your output.
-highlight. include/breaks.rb,ruby
-p. Got all that? Great! Time to move on to more tricky stuff. Next up: <a href="#custom-tags">custom tags</a>!
-
-page.
-h2. <a name="custom-tags"></a>Custom tags
-fp. Prawn::Format makes it very easy to define your own tags, either for clearer semantic markup or to add support for HTML tags that are not supported out-of-the-box.
-highlight. include/custom-tags.rb,ruby
-p. If you want to tweak the definition of an existing tag, you can reach right into the tags hash directly and add or modify existing styles:
-highlight. include/custom-tags2.rb,ruby
-p. The supported style options are:
-ul.
-li. <code>font_size</code>
-li. <code>font_family</code> (this may be any font name that Prawn's <code>Document#font</code> method will support)
-li. <code>font_style</code> &mdash; either <code>:normal</code> or <code>:italic</code>
-li. <code>font_weight</code> &mdash; either <code>:normal</code> or <code>:bold</code>
-li. <code>color</code> &mdash; may be any valid HTML color definition
-li. <code>vertical_align</code> &mdash; either <code>:super</code> or <code>:sub</code>, or a number to indicate the vertical offset from the baseline
-li. <code>text_decoration</code> &mdash; either <code>:none</code> or <code>:underline</code>
-li. <code>white_space</code> &mdash; either <code>:normal</code>, or <code>:pre</code> (for verbatim text, where whitespace is preserved)
-li. <code>width</code> &mdash; a number, used primarily to fake text indents at paragraph starts. Any tag with this attribute will have a width of that value (in addition to any contents of the tag)
-li. <code>kerning</code> &mdash; either true or false, to indicate whether kerning should be done on the text
-/ul.
-p. As you can see, for the most part these follow the same naming and value schemes as CSS3, though of course the similarity is only superficial. Prawn::Format doesn't support cascading styles, or specifying <a href="#style-classes">style classes</a> by anything other than a bare class name. (Maybe someday this will change. If it does, it'll be thanks to some enterprising programmer who submits a patch.)
-p. Still, even with the limitations, you can do quite a bit. For example, suppose you want indent the first line of a paragraph in your own document. Prawn::Format doesn't support this out of the box, but it's easy to do; just define an <code>&lt;indent&gt;</code> tag and give it a width the size of the text indent; then prepend that tag to every paragraph:
-highlight. include/indent.rb,ruby
-p. Oh, and did you catch that? Just like in CSS, you can specify most measurements in ems (e.g. <code>"2em"</code>), picas (<code>"3pc"</code>), inches (<code>"0.5in"</code>), or PDF "points" (<code>14</code>). There are 72 PDF points to an inch, and 6 picas to an inch. Also, like CSS, you can specify relative measurements, using percentages, in which case it is relative to some appropriate value. (Setting width to <code>"25%"</code> will set it to 25% of the width of the line. Setting the font size to <code>"80%"</code> will set it to 80% of the current font size.)
-
-page.
-h2. <a name="style-classes"></a>Style classes
-fp. Adding a new tag for every different style in your document can get to be pretty cumbersome. For that reason, you can also define <em>style classes</em>. This is simply a style definition (just like you would use for <a href="#custom-tags">defining a new tag</a>). To apply the style to a tag, do just like you would in HTML: specify the style class in the <code>class</code> attribute of the tag:
-highlight. include/style-classes.rb,ruby
-p. As mentioned before, Prawn::Format doesn't support cascading styles (i.e. you can't specify the format of an element by the chain of elements and styles in it's ancestor elements). And sadly, in practice, this does limit the ease with which you can apply complex styles. However, with judicious use of both style classes and <a href="#custom-tags">custom tags</a> you can do quite a bit.
-
-page.
-h2. <a name="text-options"></a><code>text()</code> options
-fp. Prawn::Format overloads the existing functionality of Prawn's <code>Document#text</code> method. In fact, unless formatting tags or XML entities are detected in the text, Prawn::Format's <code>text</code> method will simply fall back to the original. (Why? Because if you don't need the formatting, it's <em>much</em> faster to skip all the extra work that Prawn::Format does.)
-p. What this means is that Prawn::Format tries very hard to support all of the options that Prawn's <code>text</code> method accepts.
-p. Prawn::Format does <em>add</em> several new options to <code>text</code>, though. They are as follows:
-ul.
-li. <code>:plain</code> &mdash; a boolean indicating whether the text is "plain" or not. Plain text is processed by the original <code>text</code> method. By default, Prawn::Format analyzes the text to determine plainness, but this option lets you force it one way or the other.
-li. <code>:align => :justify</code> &mdash; the original <code>text</code> method understood several text alignment methods, but not full-justification. Prawn::Format will understand all the original methods, and also <code>:justify</code>, for full justification.
-li. <code>:tags</code> &mdash; a hash of tag definitions to use for this one call. Prawn::Format will always use the tags defined via <code>Document#tags</code>, but anything you specify via the <code>:tags</code> option takes precedent.
-li. <code>:styles</code> &mdash; a hash of style class definitions to use for this one call. Prawn::Format will always use the style classes defined via <code>Document#styles</code>, but anything you specify via the <code>:styles</code> option takes precedent.
-li. <code>:default_style</code> &mdash; a hash of style definitions that defines the default style to use for any otherwise-unstyled text. This defaults to the current font and color settings on the document, but you can set something else via this option.
-/ul.
-p. Here are a few examples using these options:
-highlight. include/options.rb,ruby