kramdown 0.7.0 → 0.8.0

data/doc/links.markdown

@@ -2,3 +2,5 @@
 [PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/
 [Pandoc]: http://johnmacfarlane.net/pandoc/
 [jsMath]: http://www.math.union.edu/~dpvc/jsMath/
+[BlueCloth]: http://deveiate.org/projects/BlueCloth
+[RedCloth]: http://redcloth.org/

data/doc/quickref.page

@@ -2,7 +2,11 @@
 title: Quick Reference
 in_menu: true
 sort_info: 9
----
+--- name:sidebar
+<h1>Contents</h1>
+
+{menu: {used_nodes: fragments, min_levels: 4, max_levels: 6}}
+--- name:content
 # Quick Reference
 
 Below are examples of all available structural elements that can be used in a kramdown text. Since
@@ -22,7 +26,7 @@ appears in the browser. This looks like this:
 <div class="kdexample">
 <pre class="kdexample-before"><code>kramdown example code</code></pre>
 <pre class="kdexample-after-source"><code>Example code converted to HTML</code></pre>
-<div class="kdexample-after-live">
+<div class="kdexample-after-live" style="clear:none">
 Live browser view of example code
 </div>
 </div>

data/doc/syntax.page

@@ -2,15 +2,16 @@
 title: Syntax
 in_menu: true
 sort_info: 10
----
-This is version **<%= ::Kramdown::VERSION %>** of the syntax documentation.
-
-Table of Contents:
+--- name:sidebar
+<h1>Contents</h1>
 
-{menu: {used_nodes: fragments, min_levels: 3}}
+{menu: {used_nodes: fragments, min_levels: 4, max_levels: 6}}
+--- name:content
 
 # kramdown Syntax
 
+This is version **<%= ::Kramdown::VERSION %>** of the syntax documentation.
+
 The kramdown syntax is based on the Markdown syntax and has been enhanced with features that are
 found in other Markdown implementations like [Maruku], [PHP Markdown Extra] and [Pandoc]. However,
 it strives to provide a strict syntax with definite rules and therefore isn't completely compatible
@@ -867,13 +868,13 @@ Parse as raw HTML block
 Parse as block level elements
 : 
         applet button blockquote colgroup dd div dl fieldset form iframe li
-        map noscript object ol table tbody td th thead tfoot tr ul
+        map noscript object ol table tbody thead tfoot tr td ul
 
 Parse as span level elements
 : 
         a abbr acronym address b bdo big cite caption code del dfn dt em
         h1 h2 h3 h4 h5 h6 i ins kbd label legend optgroup p pre q rb rbc
-        rp rt rtc ruby samp select small span strong sub sup tt var
+        rp rt rtc ruby samp select small span strong sub sup th tt var
 
 > Remember that all span level HTML tags like `a` or `b` do not start a HTML block! However, the
 > above lists also include span level HTML tags in the case the `markdown` attribute is used on a

data/doc/tests.page

@@ -23,7 +23,6 @@ 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.
 
-^
 
 # Benchmark
 
@@ -31,7 +30,7 @@ kramdown comes with a small benchmark to test how fast it is in regard to four o
 implementations: Maruku, BlueFeather, BlueCloth and RDiscount. The first two are written using only
 Ruby, the latter two use the C discount library for the actual hard work (which makes them really
 fast but they do not provide additional syntax elements). As one can see below, kramdown is
-currently (December 2009) ~5x faster than Maruku, ~10x faster than BlueFeather but ~30x slower than
+currently (June 2010) ~4x faster than Maruku, ~9x faster than BlueFeather but ~30x slower than
 BlueCloth and rdiscount:
 
 <pre><code>

data/lib/kramdown.rb

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
 #--
-# Copyright (C) 2009 Thomas Leitner <t_leitner@gmx.at>
+# Copyright (C) 2009-2010 Thomas Leitner <t_leitner@gmx.at>
 #
 # This file is part of kramdown.
 #

data/lib/kramdown/compatibility.rb

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
 #--
-# Copyright (C) 2009 Thomas Leitner <t_leitner@gmx.at>
+# Copyright (C) 2009-2010 Thomas Leitner <t_leitner@gmx.at>
 #
 # This file is part of kramdown.
 #

data/lib/kramdown/converter.rb

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
 #--
-# Copyright (C) 2009 Thomas Leitner <t_leitner@gmx.at>
+# Copyright (C) 2009-2010 Thomas Leitner <t_leitner@gmx.at>
 #
 # This file is part of kramdown.
 #
@@ -22,9 +22,14 @@
 
 module Kramdown
 
+  # == Converter Module
+  #
   # This module contains all available converters, i.e. classes that take a document and convert the
-  # document tree to a string in a specific format, for example, HTML. These converters use the Base
-  # class for common functionality - see its API documentation for how to create a converter class.
+  # document tree to a specific output format, normally a string. For example, the Html module
+  # converts the document tree into HTML.
+  #
+  # Converters use the Base class for common functionality (like applying a template to the output)-
+  # see its API documentation for how to create a converter class.
   module Converter
 
     autoload :Base, 'kramdown/converter/base'

data/lib/kramdown/converter/base.rb

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
 #--
-# Copyright (C) 2009 Thomas Leitner <t_leitner@gmx.at>
+# Copyright (C) 2009-2010 Thomas Leitner <t_leitner@gmx.at>
 #
 # This file is part of kramdown.
 #
@@ -26,7 +26,26 @@ module Kramdown
 
   module Converter
 
-    # This class servers as base class for all converters.
+    # == Base class for converters
+    #
+    # This class serves as base class for all converters. It provides methods that can/should be
+    # used by all converters (like #generate_id) as well as common functionality that is
+    # automatically applied to the result (for example, embedding the output into a template).
+    #
+    # == Implementing a converter
+    #
+    # Implementing a new converter is rather easy: just create a new sub class from this class and
+    # put it in the Kramdown::Converter module (the latter is only needed if auto-detection should
+    # work properly). Then you need to implement the #convert(tree) method which takes a document
+    # tree and should return the converted output.
+    #
+    # The document instance is automatically set as @doc in Base#initialize. Furthermore, the
+    # document instance provides a hash called `conversion_infos` that is also automatically cleared
+    # and can be used to store information about the conversion process.
+    #
+    # The actual transformation of the document tree can be done in any way. However, writing one
+    # method per tree element type is a straight forward way to do it - this is how the Html and
+    # Latex converters do the transformation.
     class Base
 
       # Initialize the converter with the given Kramdown document +doc+.
@@ -50,13 +69,16 @@ module Kramdown
       # Apply the template specified in the +doc+ options, using +body+ as the body string.
       def self.apply_template(doc, body)
         erb = ERB.new(get_template(doc.options[:template]))
-        erb.result(binding)
+        obj = Object.new
+        obj.instance_variable_set(:@doc, doc)
+        obj.instance_variable_set(:@body, body)
+        erb.result(obj.instance_eval{binding})
       end
 
       # Return the template specified by +template+.
       def self.get_template(template)
         format_ext = '.' + self.name.split(/::/).last.downcase
-        shipped = File.join(Kramdown.data_dir, template + format_ext)
+        shipped = File.join(::Kramdown.data_dir, template + format_ext)
         if File.exist?(template)
           File.read(template)
         elsif File.exist?(template + format_ext)
@@ -69,7 +91,7 @@ module Kramdown
       end
 
 
-      # Generate an alpha-numeric ID from the the string +str+.
+      # Generate an unique alpha-numeric ID from the the string +str+ for use as header ID.
       def generate_id(str)
         gen_id = str.gsub(/[^a-zA-Z0-9 -]/, '').gsub(/^[^a-zA-Z]*/, '').gsub(' ', '-').downcase
         gen_id = 'section' if gen_id.length == 0

data/lib/kramdown/converter/html.rb

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
 #--
-# Copyright (C) 2009 Thomas Leitner <t_leitner@gmx.at>
+# Copyright (C) 2009-2010 Thomas Leitner <t_leitner@gmx.at>
 #
 # This file is part of kramdown.
 #
@@ -82,7 +82,7 @@ module Kramdown
       end
 
       def convert_codeblock(el, indent, opts)
-        if el.options[:attr] && el.options[:attr]['lang'] && HIGHLIGHTING_AVAILABLE
+        if el.value && el.options[:attr] && el.options[:attr]['lang'] && HIGHLIGHTING_AVAILABLE
           el = Marshal.load(Marshal.dump(el)) # so that the original is not changed
           opts = {:wrap => @doc.options[:coderay_wrap], :line_numbers => @doc.options[:coderay_line_numbers],
             :line_number_start => @doc.options[:coderay_line_number_start], :tab_width => @doc.options[:coderay_tab_width],
@@ -90,7 +90,7 @@ module Kramdown
           result = CodeRay.scan(el.value, el.options[:attr].delete('lang').to_sym).html(opts).chomp + "\n"
           "#{' '*indent}<div#{options_for_element(el)}>#{result}#{' '*indent}</div>\n"
         else
-          result = escape_html(el.value)
+          result = (el.value ? escape_html(el.value) : inner(el, indent, opts))
           if el.options[:attr] && el.options[:attr].has_key?('class') && el.options[:attr]['class'] =~ /\bshow-whitespaces\b/
             result.gsub!(/(?:(^[ \t]+)|([ \t]+$)|([ \t]+))/) do |m|
               suffix = ($1 ? '-l' : ($2 ? '-r' : ''))
@@ -125,7 +125,7 @@ module Kramdown
 
       def convert_ul(el, indent, opts)
         if !@toc_code && (el.options[:ial][:refs].include?('toc') rescue nil) && (el.type == :ul || el.type == :ol)
-          @toc_code = [el.type, (0..128).to_a.map{|a| rand(36).to_s(36)}.join]
+          @toc_code = [el.type, el.options[:attr], (0..128).to_a.map{|a| rand(36).to_s(36)}.join]
           @toc_code.last
         else
           "#{' '*indent}<#{el.type}#{options_for_element(el)}>\n#{inner(el, indent, opts)}#{' '*indent}</#{el.type}>\n"
@@ -137,10 +137,10 @@ module Kramdown
       def convert_li(el, indent, opts)
         output = ' '*indent << "<#{el.type}" << options_for_element(el) << ">"
         res = inner(el, indent, opts)
-        if el.options[:first_is_block]
-          output << "\n" << res << ' '*indent
-        else
+        if el.children.empty? || el.children.first.options[:category] != :block
           output << res << (res =~ /\n\Z/ ? ' '*indent : '')
+        else
+          output << "\n" << res << ' '*indent
         end
         output << "</#{el.type}>\n"
       end
@@ -155,12 +155,13 @@ module Kramdown
       def convert_html_element(el, indent, opts)
         res = inner(el, indent, opts)
         if @doc.options[:filter_html].include?(el.value)
-          res.chomp + (el.options[:type] == :block ? "\n" : '')
-        elsif el.options[:type] == :span
+          warn("The filter_html option is deprecated and will be removed in the next release")
+          res.chomp + (el.options[:category] == :block ? "\n" : '')
+        elsif el.options[:category] == :span
           "<#{el.value}#{options_for_element(el)}" << (!res.empty? ? ">#{res}</#{el.value}>" : " />")
         else
           output = ''
-          output << ' '*indent if el.options[:parse_type] != :raw && !el.options[:parent_is_raw]
+          output << ' '*indent if !el.options[:parent_is_raw]
           output << "<#{el.value}#{options_for_element(el)}"
           if !res.empty? && el.options[:parse_type] != :block
             output << ">#{res}</#{el.value}>"
@@ -171,19 +172,20 @@ module Kramdown
           else
             output << " />"
           end
-          output << "\n" if el.options[:outer_element] || (el.options[:parse_type] != :raw && !el.options[:parent_is_raw])
+          output << "\n" if el.options[:outer_element] || !el.options[:parent_is_raw]
           output
         end
       end
 
-      def convert_html_text(el, indent, opts)
-        escape_html(el.value, :text)
-      end
-
       def convert_xml_comment(el, indent, opts)
-        el.value + (el.options[:type] == :block ? "\n" : '')
+        if el.options[:category] == :block && !el.options[:parent_is_raw]
+          ' '*indent + el.value + "\n"
+        else
+          el.value
+        end
       end
       alias :convert_xml_pi :convert_xml_comment
+      alias :convert_html_doctype :convert_xml_comment
 
       def convert_table(el, indent, opts)
         if el.options[:alignment].all? {|a| a == :default}
@@ -197,11 +199,6 @@ module Kramdown
       end
 
       def convert_thead(el, indent, opts)
-        opts[:cell_type] = case el.type
-                           when :thead then 'th'
-                           when :tbody, :tfoot then 'td'
-                           else opts[:cell_type]
-                           end
         "#{' '*indent}<#{el.type}#{options_for_element(el)}>\n#{inner(el, indent, opts)}#{' '*indent}</#{el.type}>\n"
       end
       alias :convert_tbody :convert_thead
@@ -210,8 +207,9 @@ module Kramdown
 
       def convert_td(el, indent, opts)
         res = inner(el, indent, opts)
-        "#{' '*indent}<#{opts[:cell_type]}#{options_for_element(el)}>#{res.empty? ? "&nbsp;" : res}</#{opts[:cell_type]}>\n"
+        "#{' '*indent}<#{el.type}#{options_for_element(el)}>#{res.empty? ? "&nbsp;" : res}</#{el.type}>\n"
       end
+      alias :convert_th :convert_td
 
       def convert_br(el, indent, opts)
         "<br />"
@@ -235,7 +233,7 @@ module Kramdown
       end
 
       def convert_codespan(el, indent, opts)
-        "<code#{options_for_element(el)}>#{escape_html(el.value)}</code>"
+        "<code#{options_for_element(el)}>#{el.value ? escape_html(el.value) : inner(el, indent, opts)}</code>"
       end
 
       def convert_footnote(el, indent, opts)
@@ -259,7 +257,7 @@ module Kramdown
       end
 
       TYPOGRAPHIC_SYMS = {
-        :mdash => '&mdash;', :ndash => '&ndash;', :ellipsis => '&hellip;',
+        :mdash => '&mdash;', :ndash => '&ndash;', :hellip => '&hellip;',
         :laquo_space => '&laquo;&nbsp;', :raquo_space => '&nbsp;&raquo;',
         :laquo => '&laquo;', :raquo => '&raquo;'
       }
@@ -277,7 +275,7 @@ module Kramdown
         el.options[:attr]['class'] ||= ''
         el.options[:attr]['class'] += (el.options[:attr]['class'].empty? ? '' : ' ') + 'math'
         type = 'span'
-        type = 'div' if el.options[:type] == :block
+        type = 'div' if el.options[:category] == :block
         "<#{type}#{options_for_element(el)}>#{escape_html(el.value, :text)}</#{type}>#{type == 'div' ? "\n" : ''}"
       end
 
@@ -291,7 +289,7 @@ module Kramdown
         result = inner(el, indent, opts)
         result << footnote_content
         if @toc_code
-          toc_tree = generate_toc_tree(@toc, @toc_code.first)
+          toc_tree = generate_toc_tree(@toc, @toc_code[0], @toc_code[1] || {})
           text = if toc_tree.children.size > 0
                    convert(toc_tree, 0)
                  else
@@ -302,8 +300,8 @@ module Kramdown
         result
       end
 
-      def generate_toc_tree(toc, type)
-        sections = Element.new(type, nil, {:attr => {:id => 'markdown-toc'}})
+      def generate_toc_tree(toc, type, attr)
+        sections = Element.new(type, nil, {:attr => {'id' => 'markdown-toc'}.merge(attr)})
         stack = []
         toc.each do |level, id, children|
           li = Element.new(:li, nil, {:level => level})

data/lib/kramdown/converter/latex.rb

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
 #--
-# Copyright (C) 2009 Thomas Leitner <t_leitner@gmx.at>
+# Copyright (C) 2009-2010 Thomas Leitner <t_leitner@gmx.at>
 #
 # This file is part of kramdown.
 #
@@ -73,6 +73,10 @@ module Kramdown
       end
 
       def convert_codeblock(el, opts)
+        if !el.value
+          @doc.warnings << "Cannot convert codeblock with entity references"
+          return ''
+        end
         show_whitespace = el.options[:attr] && el.options[:attr]['class'].to_s =~ /\bshow-whitespaces\b/
         lang = el.options[:attr] && el.options[:attr]['lang']
         if show_whitespace || lang
@@ -142,20 +146,25 @@ module Kramdown
       end
 
       def convert_html_element(el, opts)
-        @doc.warnings << "Can't convert HTML element"
-        ''
+        if el.value == 'i'
+          "\\emph{#{inner(el, opts)}}"
+        elsif el.value == 'b'
+          "\\emph{#{inner(el, opts)}}"
+        else
+          @doc.warnings << "Can't convert HTML element"
+          ''
+        end
       end
 
-      def convert_html_text(el, opts)
-        @doc.warnings << "Can't convert HTML text"
-        ''
+      def convert_xml_comment(el, opts)
+        el.value.split(/\n/).map {|l| "% #{l}"}.join("\n") + "\n"
       end
 
-      def convert_xml_comment(el, opts)
-        @doc.warnings << "Can't convert XML comment/PI"
+      def convert_xml_pi(el, opts)
+        @doc.warnings << "Can't convert XML PI/HTML document type"
         ''
       end
-      alias :convert_xml_pi :convert_xml_comment
+      alias :convert_html_doctype :convert_xml_pi
 
       TABLE_ALIGNMENT_CHAR = {:default => 'l', :left => 'l', :center => 'c', :right => 'r'}
 
@@ -183,6 +192,7 @@ module Kramdown
       def convert_td(el, opts)
         inner(el, opts)
       end
+      alias :convert_th :convert_td
 
       def convert_br(el, opts)
         "\\newline\n"
@@ -201,18 +211,22 @@ module Kramdown
         if el.options[:attr]['src'] =~ /^(https?|ftps?):\/\//
           @doc.warnings << "Cannot include non-local image"
           ''
-        else
+        elsif !el.options[:attr]['src'].empty?
           @doc.conversion_infos[:packages] << 'graphicx'
           "\\includegraphics{#{el.options[:attr]['src']}}"
+        else
+          @doc.warnings << "Cannot include image with empty path"
+          ''
         end
       end
 
       def convert_codespan(el, opts)
-        "{\\tt #{escape(el.value)}}"
+        "{\\tt #{el.value ? escape(el.value) : inner(el, opts)}}"
       end
 
       def convert_footnote(el, opts)
-        "\\footnote{#{inner(@doc.parse_infos[:footnotes][el.options[:name]])}}"
+        @doc.conversion_infos[:packages] << 'fancyvrb'
+        "\\footnote{#{inner(@doc.parse_infos[:footnotes][el.options[:name]][:content], opts)}}"
       end
 
       def convert_raw(el, opts)
@@ -491,7 +505,7 @@ EOF
       end
 
       TYPOGRAPHIC_SYMS = {
-        :mdash => '---', :ndash => '--', :ellipsis => '\ldots{}',
+        :mdash => '---', :ndash => '--', :hellip => '\ldots{}',
         :laquo_space => '\guillemotleft{}~', :raquo_space => '~\guillemotright{}',
         :laquo => '\guillemotleft{}', :raquo => '\guillemotright{}'
       }
@@ -506,7 +520,7 @@ EOF
 
       def convert_math(el, opts)
         @doc.conversion_infos[:packages] += %w[amssymb amsmath amsthm amsfonts]
-        if el.options[:type] == :block
+        if el.options[:category] == :block
           if el.value =~ /\A\s*\\begin\{/
             el.value
           else
@@ -517,7 +531,7 @@ EOF
         end
       end
 
-      def convert_abbreviation(el, indent, opts)
+      def convert_abbreviation(el, opts)
         el.value
       end