kramdown 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 32280f4fafeca55aeecb04530f975715e811f7f2
-  data.tar.gz: 093389e9fa3fcf20e987c12043377358ff03d632
+  metadata.gz: 762672bf30e0c2bcc71355e3b43edb552dc0680f
+  data.tar.gz: ab25e4ed7bc11403cf899f114b6ae468219adced
 SHA512:
-  metadata.gz: 62f5d75971e5d2a217d97638e9f961be1961d9d0f860a6b1bef082dd2471ae8207dd6eef5500a277ade27a02a60051c863a2d611f1973a3abfba0adf500b37b6
-  data.tar.gz: 78b3ec99523df42f35a0c3cbc264c2aa3b15ba4c6a9570b316673edc2d88edcb2c1d9e831afbddcd7c6bbd5ceac695f950bd8f94785275d020f1f7fef3c176ed
+  metadata.gz: c97487f81874d9c1e4109e94ec1050997c8c4998b8cc3a3d5c64e43513473e3942111b26060555bf508e3201b672b67ae3db44ebdb2f96ccdac0689abf8c0558
+  data.tar.gz: 89837ca84aa43bf437fb3aec9c6ac919cc9f424045746201b5e365b23a11b5962ef0d340357338587e06dc9fa0cb191e52a86d800365ac47b551c9c0486d51c9

data/CONTRIBUTERS

@@ -1,11 +1,12 @@
   Count Name
 ======= ====
-    603 Thomas Leitner <t_leitner@gmx.at>
+    631 Thomas Leitner <t_leitner@gmx.at>
       6 Gioele Barabucci <gioele@svario.it>
       4 Ted Pak <powerpak006@gmail.com>
       4 Arne Brasseur <arne@arnebrasseur.net>
       3 Henning Perl <perl@fast-sicher.de>
       3 gettalong <t_leitner@gmx.at>
+      3 Brandur <brandur@mutelight.org>
       3 Ben Armston <ben.armston@googlemail.com>
       3 Alex Marandon <contact@alexmarandon.com>
       2 Bran <m.versum@gmail.com>
@@ -15,9 +16,12 @@
       1 Tim Bates <tim@rumpuslabs.com>
       1 Simon Lydell <simon.lydell@gmail.com>
       1 Postmodern <postmodern.mod3@gmail.com>
+      1 Pete Michaud <michaudp@gmail.com>
       1 myqlarson <myqlarson@gmail.com>
       1 Michal Till <michal.till@gmail.com>
       1 Marcus Stollsteimer <sto.mar@web.de>
+      1 Luca Barbato <luca.barbato@gmail.com>
+      1 Jo Hund <jhund@clearcove.ca>
       1 John Croisant <jacius@gmail.com>
       1 Joe Fiorini <joe@faithfulgeek.org>
       1 Damien Pollet <damien.pollet@gmail.com>

data/README.md

@@ -6,7 +6,7 @@ kramdown was originally licensed under the GPL until the 1.0.0 release. However,
 requests it is now released under the MIT license and therefore can easily be used in commercial
 projects, too.
 
-However, if you use kramdown in a commerical setting, please consider **contributing back any
+However, if you use kramdown in a commercial setting, please consider **contributing back any
 changes** for the benefit of the community and/or **making a donation** (see the links in the
 sidebar on the [kramdown homepage](http://kramdown.rubyforge.org/)!
 
@@ -30,6 +30,10 @@ supported formats:
 All the documentation on the available input and output formats is available in the **doc/**
 directory and online at <http://kramdown.rubyforge.org>.
 
+Starting from version 1.0.0 kramdown is using a versioning scheme with major, minor and patch parts
+in the version number where the major number changes on backwards-incompatible changes, the minor
+number on the introduction of new features and the patch number on everything else.
+
 
 ## Usage
 

data/Rakefile

@@ -101,7 +101,7 @@ if defined?(Webgen) && defined?(RDoc::Task)
 end
 
 tt = Rake::TestTask.new do |test|
-  test.warning = true
+  test.warning = false
   test.libs << 'test'
   test.test_files = FileList['test/test_*.rb']
 end
@@ -180,6 +180,7 @@ EOF
       s.require_path = 'lib'
       s.executables = ['kramdown']
       s.default_executable = 'kramdown'
+      s.add_development_dependency 'minitest', '~> 5.0'
       s.add_development_dependency 'coderay', '~> 1.0.0'
       s.add_development_dependency 'stringex', '~> 1.5.1'
 
@@ -192,7 +193,7 @@ EOF
 
       s.author = 'Thomas Leitner'
       s.email = 't_leitner@gmx.at'
-      s.homepage = "http://kramdown.rubyforge.org"
+      s.homepage = "http://kramdown.gettalong.org"
       s.rubyforge_project = 'kramdown'
     end
 
@@ -246,7 +247,8 @@ EOF
 
   desc "Upload the website to Rubyforge"
   task :publish_website => ['doc'] do
-    sh "rsync -avc --delete --exclude 'MathJax' --exclude 'robots.txt'  htmldoc/ gettalong@rubyforge.org:/var/www/gforge-projects/kramdown/"
+    puts "Transfer manually!!!"
+    # sh "rsync -avc --delete --exclude 'MathJax' --exclude 'robots.txt'  htmldoc/ gettalong@rubyforge.org:/var/www/gforge-projects/kramdown/"
   end
 
 

data/VERSION

@@ -1 +1 @@
-1.2.0
+1.3.0

data/benchmark/generate_data.rb

@@ -103,7 +103,7 @@ set title "Execution Time Performance for #{theruby}"
 set xlabel "File Multiplier (i.e. n times mdbasic.text)"
 set ylabel "Execution Time in secondes"
 set key left top
-set grid "on"
+set grid
 set terminal png
 set output "#{graph_name}"
 EOF

data/doc/default.template

@@ -8,7 +8,7 @@
     <meta name="keywords" content="ruby, kramdown, markdown, text markup" />
     <link href="{relocatable: default.css}" type="text/css" rel="stylesheet" media="screen,projection" />
     <link href="{relocatable: news.atom}" type="application/atom+xml" rel="alternate" />
-    <script src="http://kramdown.rubyforge.org/MathJax/MathJax.js" type="text/javascript"></script>
+    <script src="http://kramdown.gettalong.org/MathJax/MathJax.js" type="text/javascript"></script>
     <title>{title:} | kramdown</title>
   </head>
   <body>
@@ -44,7 +44,7 @@
 
     <footer>
       <div class="float-left">Copyright © 2009-2013 Thomas Leitner</div>
-      <div class="float-right">Generated by <a href="http://webgen.rubyforge.org">webgen</a></div>
+      <div class="float-right">Generated by <a href="http://webgen.gettalong.org">webgen</a></div>
     </footer>
 
     <!-- Start of StatCounter Code -->

data/doc/index.page

@@ -52,11 +52,10 @@ content_processor.tikz.opts: |
 
 ## Bugs, Forums, Mailing Lists
 
-If you have found a bug, you should [report it here][bug_report]. Also, there are [forums][forum]
-and [mailing lists][ml] available if you have any questions!
+If you have found a bug, you should [report it here][bug_report]. Also, there is a [mailing
+lists][ml] available if you have any questions!
 
-[bug_report]: http://rubyforge.org/tracker/?atid=28673&group_id=7403&func=browse
-[forum]: http://rubyforge.org/forum/?group_id=7403
+[bug_report]: http://github.com/gettalong/kramdown/issues
 [ml]: http://rubyforge.org/mail/?group_id=7403
 
 

data/doc/news.feed

@@ -2,7 +2,7 @@
 title: kramdown News
 description: kramdown - a fast, pure Ruby Markdown-superset converter
 author: Thomas Leitner
-author_url: http://kramdown.rubyforge.org
+author_url: http://kramdown.gettalong.org
 entries: {alcn: news/*.html, sort: sort_info, reverse: true, limit: 10}
 versions:
   atom:

data/doc/quickref.page

@@ -467,14 +467,14 @@ A simple link can be created by surrounding the text with square brackets and th
 parentheses:
 
 {kdexample::}
-A [link](http://kramdown.rubyforge.org)
+A [link](http://kramdown.gettalong.org)
 to the kramdown homepage.
 {kdexample}
 
 You can also add title information to the link:
 
 {kdexample::}
-A [link](http://kramdown.rubyforge.org "hp")
+A [link](http://kramdown.gettalong.org "hp")
 to the homepage.
 {kdexample}
 
@@ -486,7 +486,7 @@ the link URL:
 A [link][kramdown hp]
 to the homepage.
 
-[kramdown hp]: http://kramdown.rubyforge.org "hp"
+[kramdown hp]: http://kramdown.gettalong.org "hp"
 {kdexample}
 
 If the link text itself is the reference name, the second set of square brackets can be omitted:
@@ -494,7 +494,7 @@ If the link text itself is the reference name, the second set of square brackets
 {kdexample::}
 A link to the [kramdown hp].
 
-[kramdown hp]: http://kramdown.rubyforge.org "hp"
+[kramdown hp]: http://kramdown.gettalong.org "hp"
 {kdexample}
 
 Images can be created in a similar way: just use an exclamation mark before the square brackets. The

data/doc/sidebar.template

@@ -1,7 +1,7 @@
 <h2>News</h2>
 
-<p>The latest version of kramdown is <span class="inline-important">1.2.0</span> and it was released
-on <span class="inline-important">2013-08-31</span></p>
+<p>The latest version of kramdown is <span class="inline-important">1.3.0</span> and it was released
+on <span class="inline-important">2013-12-08</span></p>
 
 <p>More <a href="{relocatable: news.html}">news</a>…</p>
 
@@ -10,12 +10,11 @@ on <span class="inline-important">2013-08-31</span></p>
 <p>If you like kramdown and would like to support it, you are welcome to make a small
 donation (PayPal or Pledgie) -- it will surely be appreciated! Thanks!</p>
 
-<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
-<input type="hidden" name="cmd" value="_s-xclick" />
-<input type="hidden" name="encrypted" value="-----BEGIN PKCS7-----MIIHJwYJKoZIhvcNAQcEoIIHGDCCBxQCAQExggEwMIIBLAIBADCBlDCBjjELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNBMRYwFAYDVQQHEw1Nb3VudGFpbiBWaWV3MRQwEgYDVQQKEwtQYXlQYWwgSW5jLjETMBEGA1UECxQKbGl2ZV9jZXJ0czERMA8GA1UEAxQIbGl2ZV9hcGkxHDAaBgkqhkiG9w0BCQEWDXJlQHBheXBhbC5jb20CAQAwDQYJKoZIhvcNAQEBBQAEgYDA8HEgfduoLW7LANqmfG9shb8sk23qWHt1vJ65J7bcOHFW1Hw/aZV7O2Xf2hRtVmHBQemuFBMVCLFFYn1Tj667ay65xPWrbtNdOcxJ6diwwVcrxMJ/EyS7niUKuTfujgmq5ra9CgNy84WSa0Cw/sWSMrK6XMX9brALPBcKbB003TELMAkGBSsOAwIaBQAwgaQGCSqGSIb3DQEHATAUBggqhkiG9w0DBwQITt+KFiwA4NOAgYBJEwBt4G0KjfWMn428qsUqj7nBGl9dhhOT9FsHPoKHm5lmzadeIhtu7vPwqaH5cZAbE/nZBhkV9/MdgWCt9kMkDLD4Jq+TGLa4RDK+ltxErnPNgr9TYvBOGPAoYTXvA12w+KUewhV1cB/gSdz43oHrBPAyO6x4ZWUhndD2+yqZhKCCA4cwggODMIIC7KADAgECAgEAMA0GCSqGSIb3DQEBBQUAMIGOMQswCQYDVQQGEwJVUzELMAkGA1UECBMCQ0ExFjAUBgNVBAcTDU1vdW50YWluIFZpZXcxFDASBgNVBAoTC1BheVBhbCBJbmMuMRMwEQYDVQQLFApsaXZlX2NlcnRzMREwDwYDVQQDFAhsaXZlX2FwaTEcMBoGCSqGSIb3DQEJARYNcmVAcGF5cGFsLmNvbTAeFw0wNDAyMTMxMDEzMTVaFw0zNTAyMTMxMDEzMTVaMIGOMQswCQYDVQQGEwJVUzELMAkGA1UECBMCQ0ExFjAUBgNVBAcTDU1vdW50YWluIFZpZXcxFDASBgNVBAoTC1BheVBhbCBJbmMuMRMwEQYDVQQLFApsaXZlX2NlcnRzMREwDwYDVQQDFAhsaXZlX2FwaTEcMBoGCSqGSIb3DQEJARYNcmVAcGF5cGFsLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAwUdO3fxEzEtcnI7ZKZL412XvZPugoni7i7D7prCe0AtaHTc97CYgm7NsAtJyxNLixmhLV8pyIEaiHXWAh8fPKW+R017+EmXrr9EaquPmsVvTywAAE1PMNOKqo2kl4Gxiz9zZqIajOm1fZGWcGS0f5JQ2kBqNbvbg2/Za+GJ/qwUCAwEAAaOB7jCB6zAdBgNVHQ4EFgQUlp98u8ZvF71ZP1LXChvsENZklGswgbsGA1UdIwSBszCBsIAUlp98u8ZvF71ZP1LXChvsENZklGuhgZSkgZEwgY4xCzAJBgNVBAYTAlVTMQswCQYDVQQIEwJDQTEWMBQGA1UEBxMNTW91bnRhaW4gVmlldzEUMBIGA1UEChMLUGF5UGFsIEluYy4xEzARBgNVBAsUCmxpdmVfY2VydHMxETAPBgNVBAMUCGxpdmVfYXBpMRwwGgYJKoZIhvcNAQkBFg1yZUBwYXlwYWwuY29tggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEFBQADgYEAgV86VpqAWuXvX6Oro4qJ1tYVIT5DgWpE692Ag422H7yRIr/9j/iKG4Thia/Oflx4TdL+IFJBAyPK9v6zZNZtBgPBynXb048hsP16l2vi0k5Q2JKiPDsEfBhGI+HnxLXEaUWAcVfCsQFvd2A1sxRr67ip5y2wwBelUecP3AjJ+YcxggGaMIIBlgIBATCBlDCBjjELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNBMRYwFAYDVQQHEw1Nb3VudGFpbiBWaWV3MRQwEgYDVQQKEwtQYXlQYWwgSW5jLjETMBEGA1UECxQKbGl2ZV9jZXJ0czERMA8GA1UEAxQIbGl2ZV9hcGkxHDAaBgkqhkiG9w0BCQEWDXJlQHBheXBhbC5jb20CAQAwCQYFKw4DAhoFAKBdMBgGCSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTEwMDcxOTA2MzUwOVowIwYJKoZIhvcNAQkEMRYEFBdLGCmffPW6PMR/W24T+7ktQe1iMA0GCSqGSIb3DQEBAQUABIGAdn5PO7OJuHq/YpWaWKkJMDNhCqAyRyWpaM4LMQXzyA+ADoKvPnpgHrCdJpvB01L/Wk2apJ59CpB7iFerXh6QRgX85lE6HFl3C+GDRikabulgIn0F/1SMeUuvuRZ8g//Z3xcktOzdchB65K2LyUowAV8rpeWGmt8JFNwOZbeqcmw=-----END PKCS7-----
-" />
-<input type="image" src="https://www.paypal.com/en_US/i/btn/btn_donate_SM.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!" />
-<img alt="" border="0" src="https://www.paypal.com/en_US/i/scr/pixel.gif" width="1" height="1" />
+<form action="https://www.paypal.com/cgi-bin/webscr" method="post" target="_top">
+<input type="hidden" name="cmd" value="_s-xclick">
+<input type="hidden" name="hosted_button_id" value="99HUWKWPMUHWG">
+<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
+<img alt="" border="0" src="https://www.paypalobjects.com/de_DE/i/scr/pixel.gif" width="1" height="1">
 </form>
 
 <a href='http://www.pledgie.com/campaigns/16657'><img alt='Click here to lend your support to: kramdown and make a donation at www.pledgie.com !' src='http://www.pledgie.com/campaigns/16657.png?skin_name=chrome' border='0' /></a>

data/doc/syntax.page

@@ -1544,9 +1544,10 @@ key-value pairs
 ID name
 
 : An ID name is defined by using a hash and then the identifier name which needs to start with an
-  ASCII character, optionally followed by other ASCII characters, digits, dashes or colons. This is
-  a short hand for the key-value pair `id="IDNAME"` since this is often used. The ID name specifies
-  the unique ID of a block or span-level element. For example, an ID name looks like `#myid`.
+  ASCII alphabetic character (A-Z or a-z), optionally followed by other ASCII characters, digits,
+  dashes or colons. This is a short hand for the key-value pair `id="IDNAME"` since this is often
+  used. The ID name specifies the unique ID of a block or span-level element. For example, an ID
+  name looks like `#myid`.
 
 class names
 
@@ -1620,6 +1621,12 @@ Here are some examples for span IALs:
     This *is*{:.underline} some `code`{:#id}{:.class}.
     A [link](test.html){:rel='something'} and some **tools**{:.tools}.
 
+The special span IAL `{::}` contains no attributes but doesn't generate a warning either. It can be
+used to separate consecutive elements that would be falsely parsed if not separated. Here is an use
+case:
+
+    This *is italic*{::}*marked*{:.special} text
+
 
 ## Extensions
 

data/doc/tests.page

@@ -24,7 +24,7 @@ If you believe you have found a bug in the implementation, please follow these s
   fashion, please open a [bug report] and attach two files: one with the text and one with the HTML
   conversion you think is correct.
 
-[bug report]: http://rubyforge.org/tracker/?atid=28673&group_id=7403&func=browse
+[bug report]: http://github.com/gettalong/kramdown/issues
 
 
 ## Benchmark

data/lib/kramdown/converter.rb

@@ -23,6 +23,7 @@ module Kramdown
     autoload :Kramdown, 'kramdown/converter/kramdown'
     autoload :Toc, 'kramdown/converter/toc'
     autoload :RemoveHtmlTags, 'kramdown/converter/remove_html_tags'
+    autoload :Pdf, 'kramdown/converter/pdf'
 
   end
 

data/lib/kramdown/converter/base.rb

@@ -59,26 +59,52 @@ module Kramdown
       end
       private_class_method(:new, :allocate)
 
+      # Returns whether the template should be applied before the conversion of the tree.
+      #
+      # Defaults to false.
+      def apply_template_before?
+        false
+      end
+
+      # Returns whether the template should be applied ater the conversion of the tree.
+      #
+      # Defaults to true.
+      def apply_template_after?
+        true
+      end
+
       # Convert the element tree +tree+ and return the resulting conversion object (normally a
       # string) and an array with warning messages. The parameter +options+ specifies the conversion
       # options that should be used.
       #
       # Initializes a new instance of the calling class and then calls the #convert method with
-      # +tree+ as parameter. If the +template+ option is specified and non-empty, the result is
-      # rendered into the specified template. The template resolution is done in the following way:
+      # +tree+ as parameter.
+      #
+      # If the +template+ option is specified and non-empty, the template is evaluate with ERB
+      # before and/or after the tree conversion depending on the result of #apply_template_before?
+      # and #apply_template_after?. If the template is evaluated before, an empty string is used for
+      # the body; if evaluated after, the result is used as body. See ::apply_template.
+      #
+      # The template resolution is done in the following way (for the converter ConverterName):
       #
       # 1. Look in the current working directory for the template.
       #
-      # 2. Append +.convertername+ (e.g. +.html+) to the template name and look for the resulting
-      #    file in the current working directory.
+      # 2. Append +.converter_name+ (e.g. +.html+) to the template name and look for the resulting
+      #    file in the current working directory (the form +.convertername+ is deprecated).
+      #
+      # 3. Append +.converter_name+ to the template name and look for it in the kramdown data
+      #    directory (the form +.convertername+ is deprecated).
       #
-      # 3. Append +.convertername+ to the template name and look for it in the kramdown data
-      #    directory.
+      # 4. Check if the template name starts with 'string://' and if so, strip this prefix away and
+      #    use the rest as template.
       def self.convert(tree, options = {})
         converter = new(tree, ::Kramdown::Options.merge(options.merge(tree.options[:options] || {})))
+
+        apply_template(converter, '') if !converter.options[:template].empty? && converter.apply_template_before?
         result = converter.convert(tree)
-        result.encode!(tree.options[:encoding]) if result.respond_to?(:encode!)
-        result = apply_template(converter, result) if !converter.options[:template].empty?
+        result.encode!(tree.options[:encoding]) if result.respond_to?(:encode!) && result.encoding != Encoding::BINARY
+        result = apply_template(converter, result) if !converter.options[:template].empty? && converter.apply_template_after?
+
         [result, converter.warnings]
       end
 
@@ -90,6 +116,9 @@ module Kramdown
       end
 
       # Apply the +template+ using +body+ as the body string.
+      #
+      # The template is evaluated using ERB and the body is available in the @body instance variable
+      # and the converter object in the @converter instance variable.
       def self.apply_template(converter, body) # :nodoc:
         erb = ERB.new(get_template(converter.options[:template]))
         obj = Object.new
@@ -99,7 +128,8 @@ module Kramdown
       end
 
       # Return the template specified by +template+.
-      def self.get_template(template) # :nodoc:
+      def self.get_template(template)
+        #DEPRECATED: use content of #get_template_new in 2.0
         format_ext = '.' + self.name.split(/::/).last.downcase
         shipped = File.join(::Kramdown.data_dir, template + format_ext)
         if File.exist?(template)
@@ -108,6 +138,24 @@ module Kramdown
           File.read(template + format_ext)
         elsif File.exist?(shipped)
           File.read(shipped)
+        elsif template.start_with?('string://')
+          template.sub(/\Astring:\/\//, '')
+        else
+          get_template_new(template)
+        end
+      end
+
+      def self.get_template_new(template) # :nodoc:
+        format_ext = '.' + ::Kramdown::Utils.snake_case(self.name.split(/::/).last)
+        shipped = File.join(::Kramdown.data_dir, template + format_ext)
+        if File.exist?(template)
+          File.read(template)
+        elsif File.exist?(template + format_ext)
+          File.read(template + format_ext)
+        elsif File.exist?(shipped)
+          File.read(shipped)
+        elsif template.start_with?('string://')
+          template.sub(/\Astring:\/\//, '')
         else
           raise "The specified template file #{template} does not exist"
         end

data/lib/kramdown/converter/kramdown.rb

@@ -321,11 +321,13 @@ module Kramdown
       end
 
       def convert_em(el, opts)
-        "*#{inner(el, opts)}*"
+        "*#{inner(el, opts)}*" +
+          (opts[:next] && [:em, :strong].include?(opts[:next].type) && !ial_for_element(el) ? '{::}' : '')
       end
 
       def convert_strong(el, opts)
-        "**#{inner(el, opts)}**"
+        "**#{inner(el, opts)}**" +
+          (opts[:next] && [:em, :strong].include?(opts[:next].type) && !ial_for_element(el) ? '{::}' : '')
       end
 
       def convert_entity(el, opts)

data/lib/kramdown/converter/pdf.rb

@@ -0,0 +1,638 @@
+# -*- coding: utf-8 -*-
+#
+#--
+# Copyright (C) 2009-2013 Thomas Leitner <t_leitner@gmx.at>
+#
+# This file is part of kramdown which is licensed under the MIT.
+#++
+#
+
+require 'prawn'
+require 'kramdown/utils/entities'
+require 'open-uri'
+
+module Kramdown
+
+  module Converter
+
+    # Converts an element tree to a PDF using the prawn PDF library.
+    #
+    # This basic version provides a nice starting point for customizations but can also be used
+    # directly.
+    #
+    # There can be the following two methods for each element type: render_TYPE(el, opts) and
+    # TYPE_options(el, opts) where +el+ is a kramdown element and +opts+ an hash with rendering
+    # options.
+    #
+    # The render_TYPE(el, opts) is used for rendering the specific element. If the element is a span
+    # element, it should return a hash or an array of hashes that can be used by the #formatted_text
+    # method of Prawn::Document. This method can then be used in block elements to actually render
+    # the span elements.
+    #
+    # The rendering options are passed from the parent to its child elements. This allows one to
+    # define general options at the top of the tree (the root element) that can later be changed or
+    # amended.
+    #
+    #
+    # Currently supports the conversion of all elements except those of the following types:
+    #
+    #   :html_element, :img, :footnote
+    #
+    #
+    class Pdf < Base
+
+      include Prawn::Measurements
+
+      def initialize(root, options)
+        super
+        @stack = []
+        @dests = {}
+      end
+
+      # PDF templates are applied before conversion. They should contain code to augment the
+      # converter object (i.e. to override the methods).
+      def apply_template_before?
+        true
+      end
+
+      # Returns +false+.
+      def apply_template_after?
+        false
+      end
+
+      DISPATCHER_RENDER = Hash.new {|h,k| h[k] = "render_#{k}"} #:nodoc:
+      DISPATCHER_OPTIONS = Hash.new {|h,k| h[k] = "#{k}_options"} #:nodoc:
+
+      # Invoke the special rendering method for the given element +el+.
+      #
+      # A PDF destination is also added at the current location if th element has an ID or if the
+      # element is of type :header and the :auto_ids option is set.
+      def convert(el, opts = {})
+        id = el.attr['id']
+        id = generate_id(el.options[:raw_text]) if !id && @options[:auto_ids] && el.type == :header
+        if !id.to_s.empty? && !@dests.has_key?(id)
+          @pdf.add_dest(id, @pdf.dest_xyz(0, @pdf.y))
+          @dests[id] = @pdf.dest_xyz(0, @pdf.y)
+        end
+        send(DISPATCHER_RENDER[el.type], el, opts)
+      end
+
+      protected
+
+      # Render the children of this element with the given options and return the results as array.
+      #
+      # Each time a child is rendered, the +TYPE_options+ method is invoked (if it exists) to get
+      # the specific options for the element with which the given options are updated.
+      def inner(el, opts)
+        @stack.push([el, opts])
+        result = el.children.map do |inner_el|
+          options = opts.dup
+          options.update(send(DISPATCHER_OPTIONS[inner_el.type], inner_el, options))
+          convert(inner_el, options)
+        end.flatten.compact
+        @stack.pop
+        result
+      end
+
+
+      # ----------------------------
+      # :section: Element rendering methods
+      # ----------------------------
+
+
+      def root_options(root, opts)
+        {:font => 'Times-Roman', :size => 12, :leading => 2}
+      end
+
+      def render_root(root, opts)
+        @pdf = setup_document(root)
+        inner(root, root_options(root, opts))
+        create_outline(root)
+        finish_document(root)
+        @pdf.render
+      end
+
+      def header_options(el, opts)
+        size = opts[:size] * 1.15**(6 - el.options[:level])
+        {
+          :font => "Helvetica", :styles => (opts[:styles] || []) + [:bold],
+          :size => size, :bottom_padding => opts[:size], :top_padding => opts[:size]
+        }
+      end
+
+      def render_header(el, opts)
+        render_padded_and_formatted_text(el, opts)
+      end
+
+      def p_options(el, opts)
+        bpad = (el.options[:transparent] ? opts[:leading] : opts[:size])
+        {:align => :justify, :bottom_padding => bpad}
+      end
+
+      def render_p(el, opts)
+        if el.children.size == 1 && el.children.first.type == :img
+          render_standalone_image(el, opts)
+        else
+          render_padded_and_formatted_text(el, opts)
+        end
+      end
+
+      def render_standalone_image(el, opts)
+        img = el.children.first
+
+        if img.attr['src'].empty?
+          warning("Rendering an image without a source is not possible")
+          return nil
+        elsif img.attr['src'] !~ /\.jpe?g$|\.png$/
+          warning("Cannot render images other than JPEG or PNG, got #{img.attr['src']}")
+          return nil
+        end
+
+        img_dirs = (@options[:image_directories] || ['.']).dup
+        begin
+          img_path = File.join(img_dirs.shift, img.attr['src'])
+          image_obj, image_info = @pdf.build_image_object(open(img_path))
+        rescue
+          img_dirs.empty? ? raise : retry
+        end
+
+        options = {:position => :center}
+        if img.attr['height'] && img.attr['height'] =~ /px$/
+          options[:height] = img.attr['height'].to_i / (@options[:image_dpi] || 150.0) * 72
+        elsif img.attr['width'] && img.attr['width'] =~ /px$/
+          options[:width] = img.attr['width'].to_i / (@options[:image_dpi] || 150.0) * 72
+        else
+          options[:scale] =[(@pdf.bounds.width - mm2pt(20)) / image_info.width.to_f, 1].min
+        end
+
+        if img.attr['class'] =~ /\bright\b/
+          options[:position] = :right
+          @pdf.float { @pdf.embed_image(image_obj, image_info, options) }
+        else
+          with_block_padding(el, opts) do
+            @pdf.embed_image(image_obj, image_info, options)
+          end
+        end
+      end
+
+      def blockquote_options(el, opts)
+        {:styles => [:italic]}
+      end
+
+      def render_blockquote(el, opts)
+        @pdf.indent(mm2pt(10), mm2pt(10)) { inner(el, opts) }
+      end
+
+      def ul_options(el, opts)
+        {:bottom_padding => opts[:size]}
+      end
+
+      def render_ul(el, opts)
+        with_block_padding(el, opts) do
+          el.children.each do |li|
+            @pdf.float { @pdf.formatted_text([text_hash("•", opts)]) }
+            @pdf.indent(mm2pt(6)) { convert(li, opts) }
+          end
+        end
+      end
+
+      def ol_options(el, opts)
+        {:bottom_padding => opts[:size]}
+      end
+
+      def render_ol(el, opts)
+        with_block_padding(el, opts) do
+          el.children.each_with_index do |li, index|
+            @pdf.float { @pdf.formatted_text([text_hash("#{index+1}.", opts)]) }
+            @pdf.indent(mm2pt(6)) { convert(li, opts) }
+          end
+        end
+      end
+
+      def li_options(el, opts)
+        {}
+      end
+
+      def render_li(el, opts)
+        inner(el, opts)
+      end
+
+      def dl_options(el, opts)
+        {}
+      end
+
+      def render_dl(el, opts)
+        inner(el, opts)
+      end
+
+      def dt_options(el, opts)
+        {:styles => (opts[:styles] || []) + [:bold], :bottom_padding => 0}
+      end
+
+      def render_dt(el, opts)
+        render_padded_and_formatted_text(el, opts)
+      end
+
+      def dd_options(el, opts)
+        {}
+      end
+
+      def render_dd(el, opts)
+        @pdf.indent(mm2pt(10)) { inner(el, opts) }
+      end
+
+      def math_options(el, opts)
+        {}
+      end
+
+      def render_math(el, opts)
+        if el.options[:category] == :block
+          @pdf.formatted_text([{:text => el.value}], block_hash(opts))
+        else
+          {:text => el.value}
+        end
+      end
+
+      def hr_options(el, opts)
+        {:top_padding => opts[:size], :bottom_padding => opts[:size]}
+      end
+
+      def render_hr(el, opts)
+        with_block_padding(el, opts) do
+          @pdf.stroke_horizontal_line(@pdf.bounds.left + mm2pt(5), @pdf.bounds.right - mm2pt(5))
+        end
+      end
+
+      def codeblock_options(el, opts)
+        {
+          :font => 'Courier', :color => '880000',
+          :bottom_padding => opts[:size]
+        }
+      end
+
+      def render_codeblock(el, opts)
+        with_block_padding(el, opts) do
+          @pdf.formatted_text([text_hash(el.value, opts, false)], block_hash(opts))
+        end
+      end
+
+      def table_options(el, opts)
+        {:bottom_padding => opts[:size]}
+      end
+
+      def render_table(el, opts)
+        data = []
+        el.children.each do |container|
+          container.children.each do |row|
+            data << []
+            row.children.each do |cell|
+              if cell.children.any? {|child| child.options[:category] == :block}
+                warning("Can't render tables with cells containing block elements")
+                return
+              end
+              cell_data = inner(cell, opts)
+              data.last << cell_data.map {|c| c[:text]}.join('')
+            end
+          end
+        end
+        with_block_padding(el, opts) do
+          @pdf.table(data, :width => @pdf.bounds.right) do
+            el.options[:alignment].each_with_index do |alignment, index|
+              columns(index).align = alignment unless alignment == :default
+            end
+          end
+        end
+      end
+
+
+
+      def text_options(el, opts)
+        {}
+      end
+
+      def render_text(el, opts)
+        text_hash(el.value.to_s, opts)
+      end
+
+      def em_options(el, opts)
+        if opts[:styles] && opts[:styles].include?(:italic)
+          {:styles => opts[:styles].reject {|i| i == :italic}}
+        else
+          {:styles => (opts[:styles] || []) << :italic}
+        end
+      end
+
+      def strong_options(el, opts)
+        {:styles => (opts[:styles] || []) + [:bold]}
+      end
+
+      def a_options(el, opts)
+        hash = {:color => '000088'}
+        if el.attr['href'].start_with?('#')
+          hash[:anchor] = el.attr['href'].sub(/\A#/, '')
+        else
+          hash[:link] = el.attr['href']
+        end
+        hash
+      end
+
+      def render_em(el, opts)
+        inner(el, opts)
+      end
+      alias_method :render_strong, :render_em
+      alias_method :render_a, :render_em
+
+      def codespan_options(el, opts)
+        {:font => 'Courier', :color => '880000'}
+      end
+
+      def render_codespan(el, opts)
+        text_hash(el.value, opts)
+      end
+
+      def br_options(el, opts)
+        {}
+      end
+
+      def render_br(el, opts)
+        text_hash("\n", opts, false)
+      end
+
+      def smart_quote_options(el, opts)
+        {}
+      end
+
+      def render_smart_quote(el, opts)
+        text_hash(smart_quote_entity(el).char, opts)
+      end
+
+      def typographic_sym_options(el, opts)
+        {}
+      end
+
+      def render_typographic_sym(el, opts)
+        str = if el.value == :laquo_space
+                ::Kramdown::Utils::Entities.entity('laquo').char +
+                  ::Kramdown::Utils::Entities.entity('nbsp').char
+              elsif el.value == :raquo_space
+                ::Kramdown::Utils::Entities.entity('raquo').char +
+                  ::Kramdown::Utils::Entities.entity('nbsp').char
+              else
+                ::Kramdown::Utils::Entities.entity(el.value.to_s).char
+              end
+        text_hash(str, opts)
+      end
+
+      def entity_options(el, opts)
+        {}
+      end
+
+      def render_entity(el, opts)
+        text_hash(el.value.char, opts)
+      end
+
+      def abbreviation_options(el, opts)
+        {}
+      end
+
+      def render_abbreviation(el, opts)
+        text_hash(el.value, opts)
+      end
+
+      def img_options(el, opts)
+        {}
+      end
+
+      def render_img(el, *args) #:nodoc:
+        warning("Rendering span images is not supported for PDF converter")
+        nil
+      end
+
+
+
+      def xml_comment_options(el, opts) #:nodoc:
+        {}
+      end
+      alias_method :xml_pi_options, :xml_comment_options
+      alias_method :comment_options, :xml_comment_options
+      alias_method :blank_options, :xml_comment_options
+      alias_method :footnote_options, :xml_comment_options
+      alias_method :raw_options, :xml_comment_options
+      alias_method :html_element_options, :xml_comment_options
+
+      def render_xml_comment(el, opts) #:nodoc:
+        # noop
+      end
+      alias_method :render_xml_pi, :render_xml_comment
+      alias_method :render_comment, :render_xml_comment
+      alias_method :render_blank, :render_xml_comment
+
+      def render_footnote(el, *args) #:nodoc:
+        warning("Rendering #{el.type} not supported for PDF converter")
+        nil
+      end
+      alias_method :render_raw, :render_footnote
+      alias_method :render_html_element, :render_footnote
+
+
+      # ----------------------------
+      # :section: Organizational methods
+      #
+      # These methods are used, for example, to up the needed Prawn::Document instance or to create
+      # a PDF outline.
+      # ----------------------------
+
+
+      # This module gets mixed into the Prawn::Document instance.
+      module PrawnDocumentExtension
+
+        # Extension for the formatted box class to recognize images and move text around them.
+        module CustomBox
+
+          def available_width
+            return super unless @document.respond_to?(:converter) && @document.converter
+
+            @document.image_floats.each do |pn, x, y, w, h|
+              next if @document.page_number != pn
+              if @at[1] + @baseline_y <= y - @document.bounds.absolute_bottom &&
+                  (@at[1] + @baseline_y + @arranger.max_line_height + @leading >= y - h - @document.bounds.absolute_bottom)
+                return @width - w
+              end
+            end
+
+            return super
+          end
+
+        end
+
+        Prawn::Text::Formatted::Box.extensions << CustomBox
+
+        # Access the converter instance from within Prawn
+        attr_accessor :converter
+
+        def image_floats
+          @image_floats ||= []
+        end
+
+        # Override image embedding method for adding image positions to #image_floats.
+        def embed_image(pdf_obj, info, options)
+          # find where the image will be placed and how big it will be
+          w,h = info.calc_image_dimensions(options)
+
+          if options[:at]
+            x,y = map_to_absolute(options[:at])
+          else
+            x,y = image_position(w,h,options)
+            move_text_position h
+          end
+
+          #--> This part is new
+          if options[:position] == :right
+            image_floats << [page_number, x - 15, y, w + 15, h + 15]
+          end
+
+          # add a reference to the image object to the current page
+          # resource list and give it a label
+          label = "I#{next_image_id}"
+          state.page.xobjects.merge!(label => pdf_obj)
+
+          # add the image to the current page
+          instruct = "\nq\n%.3f 0 0 %.3f %.3f %.3f cm\n/%s Do\nQ"
+          add_content instruct % [ w, h, x, y - h, label ]
+        end
+
+      end
+
+
+      # Return a hash with options that are suitable for Prawn::Document.new.
+      #
+      # Used in #setup_document.
+      def document_options(root)
+        {
+          :page_size => 'A4', :page_layout => :portrait, :margin => mm2pt(20),
+          :info => {
+            :Creator => 'kramdown PDF converter',
+            :CreationDate => Time.now
+          },
+          :compress => true, :optimize_objects => true
+        }
+      end
+
+      # Create a Prawn::Document object and return it.
+      #
+      # Can be used to define repeatable content or register fonts.
+      #
+      # Used in #render_root.
+      def setup_document(root)
+        doc = Prawn::Document.new(document_options(root))
+        doc.extend(PrawnDocumentExtension)
+        doc.converter = self
+        doc
+      end
+
+      #
+      #
+      # Used in #render_root.
+      def finish_document(root)
+        # no op
+      end
+
+      # Create the PDF outline from the header elements in the TOC.
+      def create_outline(root)
+        patch_outline_object
+        toc = ::Kramdown::Converter::Toc.convert(root).first
+
+        text_of_header = lambda do |el|
+          if el.type == :text
+            el.value
+          else
+            el.children.map {|c| text_of_header.call(c)}.join('')
+          end
+        end
+
+        add_section = lambda do |item, parent|
+          text = text_of_header.call(item.value)
+          destination = @dests[item.attr[:id]]
+          if !parent
+            @pdf.outline.page(:title => text, :destination => destination)
+          else
+            @pdf.outline.add_subsection_to(parent) do
+              @pdf.outline.page(:title => text, :destination => destination)
+            end
+          end
+          item.children.each {|c| add_section.call(c, text)}
+        end
+
+        toc.children.each do |item|
+          add_section.call(item, nil)
+        end
+      end
+
+      # Patch the pdf_document.outline object to accept arbitrary destinations.
+      def patch_outline_object
+        def (@pdf.outline).create_outline_item(title, options)
+          outline_item = ::Prawn::OutlineItem.new(title, parent, options)
+
+          case options[:destination]
+          when Integer
+            page_index = options[:destination] - 1
+            outline_item.dest = [document.state.pages[page_index].dictionary, :Fit]
+          when Array
+            outline_item.dest = options[:destination]
+          end
+
+          outline_item.prev = prev if @prev
+          items[title] = document.ref!(outline_item)
+        end
+      end
+
+
+      # ----------------------------
+      # :section: Helper methods
+      # ----------------------------
+
+
+      # Move the prawn document cursor down before and/or after yielding the given block.
+      #
+      # The :top_padding and :bottom_padding options are used for determinig the padding amount.
+      def with_block_padding(el, opts)
+        @pdf.move_down(opts[:top_padding]) if opts.has_key?(:top_padding)
+        yield
+        @pdf.move_down(opts[:bottom_padding]) if opts.has_key?(:bottom_padding)
+      end
+
+      # Render the children of the given element as formatted text and respect the top/bottom
+      # padding (see #with_block_padding).
+      def render_padded_and_formatted_text(el, opts)
+        with_block_padding(el, opts) { @pdf.formatted_text(inner(el, opts), block_hash(opts)) }
+      end
+
+      # Helper function that returns a hash with valid "formatted text" options.
+      #
+      # The +text+ parameter is used as value for the :text key and if +squeeze_whitespace+ is
+      # +true+, all whitespace is converted into spaces.
+      def text_hash(text, opts, squeeze_whitespace = true)
+        text = text.gsub(/\s+/, ' ') if squeeze_whitespace
+        hash = {:text => text}
+        [:styles, :size, :character_spacing, :font, :color, :link,
+         :anchor, :draw_text_callback, :callback].each do |key|
+          hash[key] = opts[key] if opts.has_key?(key)
+        end
+        hash
+      end
+
+      # Helper function that returns a hash with valid options for the prawn #text_box extracted
+      # from the given options.
+      def block_hash(opts)
+        hash = {}
+        [:align, :valign, :mode, :final_gap, :leading, :fallback_fonts,
+         :direction, :indent_paragraphs].each do |key|
+          hash[key] = opts[key] if opts.has_key?(key)
+        end
+        hash
+      end
+
+    end
+
+  end
+end