kramdown 0.14.1 → 0.14.2

data/doc/options.page

@@ -0,0 +1,10 @@
+---
+title: Options
+---
+## Available Options
+
+The behaviour of kramdown can be adjusted via the available options. Below is a list of all
+currently available options. Have a look at the documentation of a converter or parser to see
+directly which options they support!
+
+{options: {items: all}}

data/doc/quickref.page

@@ -5,7 +5,7 @@ sort_info: 9
 --- name:sidebar
 <h1>Contents</h1>
 
-{menu: {used_nodes: fragments, min_levels: 4, max_levels: 6}}
+{menu: {options: {descendants: true, levels: [2,6]}}}
 --- name:content
 # Quick Reference
 
@@ -23,14 +23,16 @@ text phrases as emphasized, as a link and so on.
 All examples below feature the kramdown source, the converted HTML source (shown when hovering over
 the kramdown source) and the output as it 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>
+<table class="kdexample">
+<tr>
+<td><pre class="kdexample-before"><code>kramdown example code</code></pre></td>
+<td><pre class="kdexample-after-source"><code>Example code converted to HTML</code></pre>
 <div class="kdexample-after-live" style="clear:none">
 Live browser view of example code
 </div>
-</div>
-<div class="clear"></div>
+</td>
+</tr>
+</table>
 
 
 # Block-level Elements - Main Structural Elements

data/doc/sidebar.template

@@ -1,7 +1,7 @@
 <h2>News</h2>
 
-<p>The latest version of kramdown is <b>0.14.1</b> and it was released
-on <b>2012-11-30</b>.</p>
+<p>The latest version of kramdown is <b>0.14.2</b> and it was released
+on <b>2013-01-20</b>.</p>
 
 <p>More <a href="{relocatable: news.html}">news</a>…</p>
 

data/doc/syntax.page

@@ -5,7 +5,7 @@ sort_info: 10
 --- name:sidebar
 <h1>Contents</h1>
 
-{menu: {used_nodes: fragments, min_levels: 4, max_levels: 6}}
+{menu: {options: {descendants: true, levels: [2,6]}}}
 --- name:content
 
 # kramdown Syntax

data/doc/tests.page

@@ -1,8 +1,9 @@
 ---
 title: Tests and Benchmark
 ---
+# Tests and Benchmark
 
-# Tests
+## Tests
 
 There exist several test suites for testing the correctness of a Markdown implementation. The
 original [Markdown Test Suite] is the standard which one needs to test against. The [PHP Markdown
@@ -26,19 +27,54 @@ If you believe you have found a bug in the implementation, please follow these s
 [bug report]: http://rubyforge.org/tracker/?atid=28673&group_id=7403&func=browse
 
 
-# Benchmark
+## Benchmark
 
 kramdown comes with a small benchmark to test how fast it is in regard to four other Ruby Markdown
-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 (February 2012) ~3-4x faster than Maruku, ~4-5x faster than BlueFeather but ~30x slower
-than BlueCloth and rdiscount:
+implementations: Maruku, BlueFeather, BlueCloth, RDiscount and Redcarpet. The first two are written
+using only Ruby, the latter three are written in C and need to be compiled.
+
+As one can see below, kramdown is currently (January 2013) ~3-4x faster than Maruku, ~4-5x faster
+than BlueFeather but ~30x slower than BlueCloth and RDiscount and ~100x slower than Redcarpet:
 
 <pre><code>
-{execute_cmd: {command: "ruby -Ilib -rubygems benchmark/benchmark.rb", process_output: false, escape_html: true}}
-</code>
-</pre>
+Running tests on 2013-01-13 under ruby 1.9.3p327 (2012-11-10 revision 37606) [x86_64-linux]
+
+Test using file mdsyntax.text and 20 runs
+Rehearsal ----------------------------------------------------
+kramdown 0.14.1    1.400000   0.010000   1.410000 (  1.428902)
+Maruku 0.6.0       4.520000   0.030000   4.550000 (  4.578439)
+BlueFeather 0.40   5.680000   0.020000   5.700000 (  5.707717)
+BlueCloth 2.2.0    0.060000   0.000000   0.060000 (  0.067857)
+RDiscount 1.6.8    0.030000   0.000000   0.030000 (  0.027722)
+redcarpet 2.2.2    0.010000   0.000000   0.010000 (  0.007642)
+------------------------------------------ total: 11.760000sec
+
+                       user     system      total        real
+kramdown 0.14.1    1.270000   0.000000   1.270000 (  1.273636)
+Maruku 0.6.0       4.400000   0.020000   4.420000 (  4.434123)
+BlueFeather 0.40   5.610000   0.000000   5.610000 (  5.631930)
+BlueCloth 2.2.0    0.070000   0.000000   0.070000 (  0.069900)
+RDiscount 1.6.8    0.040000   0.000000   0.040000 (  0.035793)
+redcarpet 2.2.2    0.010000   0.000000   0.010000 (  0.007520)
+
+Test using file mdbasics.text and 20 runs
+Rehearsal ----------------------------------------------------
+kramdown 0.14.1    0.230000   0.000000   0.230000 (  0.228075)
+Maruku 0.6.0       1.070000   0.000000   1.070000 (  1.079782)
+BlueFeather 0.40   1.440000   0.000000   1.440000 (  1.446999)
+BlueCloth 2.2.0    0.020000   0.000000   0.020000 (  0.019677)
+RDiscount 1.6.8    0.010000   0.000000   0.010000 (  0.008010)
+redcarpet 2.2.2    0.010000   0.000000   0.010000 (  0.002431)
+------------------------------------------- total: 2.780000sec
+
+                       user     system      total        real
+kramdown 0.14.1    0.230000   0.000000   0.230000 (  0.227214)
+Maruku 0.6.0       1.070000   0.000000   1.070000 (  1.070332)
+BlueFeather 0.40   1.430000   0.000000   1.430000 (  1.434958)
+BlueCloth 2.2.0    0.020000   0.000000   0.020000 (  0.021127)
+RDiscount 1.6.8    0.020000   0.000000   0.020000 (  0.009714)
+redcarpet 2.2.2    0.000000   0.000000   0.000000 (  0.002571)
+</code></pre>
 
 And here are some graphs which show the execution times of the various kramdown releases on
 different Ruby interpreters:
@@ -48,7 +84,8 @@ different Ruby interpreters:
 ![ruby 1.8.7p249]({relocatable: img/graph-ruby-1.8.7-249.png})
 ![ruby 1.8.7p302]({relocatable: img/graph-ruby-1.8.7-302.png})
 ![ruby 1.9.2p136]({relocatable: img/graph-ruby-1.9.2p136-136.png})
-![ruby 1.9.3p125]({relocatable: img/graph-ruby-1.9.3p125-125.png})
+![ruby 1.9.3p327]({relocatable: img/graph-ruby-1.9.3p327-327.png})
+![ruby 2.0.0dev]({relocatable: img/graph-ruby-2.0.0dev--1.png})
 
 [Markdown Test Suite]: http://daringfireball.net/projects/downloads/MarkdownTest_1.0.zip
 [MDTest]: http://www.michelf.com/docs/projets/mdtest-1.0.zip

data/lib/kramdown/converter/html.rb

@@ -105,7 +105,7 @@ module Kramdown
         if el.options[:transparent]
           inner(el, indent)
         else
-          "#{' '*indent}<p#{html_attributes(el.attr)}>#{inner(el, indent)}</p>\n"
+          format_as_block_html(el.type, el.attr, inner(el, indent), indent)
         end
       end
 
@@ -140,7 +140,7 @@ module Kramdown
       end
 
       def convert_blockquote(el, indent)
-        "#{' '*indent}<blockquote#{html_attributes(el.attr)}>\n#{inner(el, indent)}#{' '*indent}</blockquote>\n"
+        format_as_indented_block_html(el.type, el.attr, inner(el, indent), indent)
       end
 
       def convert_header(el, indent)
@@ -150,7 +150,7 @@ module Kramdown
         end
         @toc << [el.options[:level], attr['id'], el.children] if attr['id'] && in_toc?(el)
         level = output_header_level(el.options[:level])
-        "#{' '*indent}<h#{level}#{html_attributes(attr)}>#{inner(el, indent)}</h#{level}>\n"
+        format_as_block_html("h#{level}", attr, inner(el, indent), indent)
       end
 
       def convert_hr(el, indent)
@@ -162,7 +162,7 @@ module Kramdown
           @toc_code = [el.type, el.attr, (0..128).to_a.map{|a| rand(36).to_s(36)}.join]
           @toc_code.last
         else
-          "#{' '*indent}<#{el.type}#{html_attributes(el.attr)}>\n#{inner(el, indent)}#{' '*indent}</#{el.type}>\n"
+          format_as_indented_block_html(el.type, el.attr, inner(el, indent), indent)
         end
       end
       alias :convert_ol :convert_ul
@@ -181,7 +181,7 @@ module Kramdown
       alias :convert_dd :convert_li
 
       def convert_dt(el, indent)
-        "#{' '*indent}<dt#{html_attributes(el.attr)}>#{inner(el, indent)}</dt>\n"
+        format_as_block_html(el.type, el.attr, inner(el, indent), indent)
       end
 
       def convert_html_element(el, indent)
@@ -218,15 +218,12 @@ module Kramdown
       alias :convert_xml_pi :convert_xml_comment
 
       def convert_table(el, indent)
-        "#{' '*indent}<table#{html_attributes(el.attr)}>\n#{inner(el, indent)}#{' '*indent}</table>\n"
+        format_as_indented_block_html(el.type, el.attr, inner(el, indent), indent)
       end
-
-      def convert_thead(el, indent)
-        "#{' '*indent}<#{el.type}#{html_attributes(el.attr)}>\n#{inner(el, indent)}#{' '*indent}</#{el.type}>\n"
-      end
-      alias :convert_tbody :convert_thead
-      alias :convert_tfoot :convert_thead
-      alias :convert_tr  :convert_thead
+      alias :convert_thead :convert_table
+      alias :convert_tbody :convert_table
+      alias :convert_tfoot :convert_table
+      alias :convert_tr  :convert_table
 
       ENTITY_NBSP = ::Kramdown::Utils::Entities.entity('nbsp') # :nodoc:
 
@@ -239,7 +236,7 @@ module Kramdown
           attr = el.attr.dup
           attr['style'] = (attr.has_key?('style') ? "#{attr['style']}; ": '') << "text-align: #{alignment}"
         end
-        "#{' '*indent}<#{type}#{html_attributes(attr)}>#{res.empty? ? entity_to_str(ENTITY_NBSP) : res}</#{type}>\n"
+        format_as_block_html(type, attr, res.empty? ? entity_to_str(ENTITY_NBSP) : res, indent)
       end
 
       def convert_comment(el, indent)
@@ -262,7 +259,7 @@ module Kramdown
           attr['href'] = obfuscate('mailto') << ":" << obfuscate(mail_addr)
           res = obfuscate(res) if res == mail_addr
         end
-        "<a#{html_attributes(attr)}>#{res}</a>"
+        format_as_span_html(el.type, attr, res)
       end
 
       def convert_img(el, indent)
@@ -271,12 +268,12 @@ module Kramdown
 
       def convert_codespan(el, indent)
         lang = extract_code_language(el.attr)
-        if @coderay_enabled && lang
-          result = CodeRay.scan(el.value, lang.to_sym).html(:wrap => :span, :css => @options[:coderay_css]).chomp
-          "<code#{html_attributes(el.attr)}>#{result}</code>"
-        else
-          "<code#{html_attributes(el.attr)}>#{escape_html(el.value)}</code>"
-        end
+        result = if @coderay_enabled && lang
+                   CodeRay.scan(el.value, lang.to_sym).html(:wrap => :span, :css => @options[:coderay_css]).chomp
+                 else
+                   escape_html(el.value)
+                 end
+        format_as_span_html('code', el.attr, result)
       end
 
       def convert_footnote(el, indent)
@@ -295,7 +292,7 @@ module Kramdown
       end
 
       def convert_em(el, indent)
-        "<#{el.type}#{html_attributes(el.attr)}>#{inner(el, indent)}</#{el.type}>"
+        format_as_span_html(el.type, el.attr, inner(el, indent))
       end
       alias :convert_strong :convert_em
 
@@ -323,12 +320,17 @@ module Kramdown
       def convert_math(el, indent)
         block = (el.options[:category] == :block)
         value = (el.value =~ /<|&/ ? "% <![CDATA[\n#{el.value} %]]>" : el.value)
-        "<script type=\"math/tex#{block ? '; mode=display' : ''}\">#{value}</script>#{block ? "\n" : ''}"
+        type = {:type => "math/tex#{block ? '; mode=display' : ''}"}
+        if block
+          format_as_block_html('script', type, value, indent)
+        else
+          format_as_span_html('script', type, value)
+        end
       end
 
       def convert_abbreviation(el, indent)
         title = @root.options[:abbrev_defs][el.value]
-        "<abbr#{!title.empty? ? html_attributes(:title => title) : ''}>#{el.value}</abbr>"
+        format_as_span_html("abbr", {:title => (title.empty? ? nil : title)}, el.value)
       end
 
       def convert_root(el, indent)
@@ -346,6 +348,22 @@ module Kramdown
         result
       end
 
+      # Format the given element as span HTML.
+      def format_as_span_html(name, attr, body)
+        "<#{name}#{html_attributes(attr)}>#{body}</#{name}>"
+      end
+
+      # Format the given element as block HTML.
+      def format_as_block_html(name, attr, body, indent)
+        "#{' '*indent}<#{name}#{html_attributes(attr)}>#{body}</#{name}>\n"
+      end
+
+      # Format the given element as block HTML with a newline after the start tag and indentation
+      # before the end tag.
+      def format_as_indented_block_html(name, attr, body, indent)
+        "#{' '*indent}<#{name}#{html_attributes(attr)}>\n#{body}#{' '*indent}</#{name}>\n"
+      end
+
       # Generate and return an element tree for the table of contents.
       def generate_toc_tree(toc, type, attr)
         sections = Element.new(type, nil, attr)
@@ -417,7 +435,7 @@ module Kramdown
           end
           para.children << ref
         end
-        (ol.children.empty? ? '' : "<div class=\"footnotes\">\n#{convert(ol, 2)}</div>\n")
+        (ol.children.empty? ? '' : format_as_indented_block_html('div', {:class => "footnotes"}, convert(ol, 2), 0))
       end
 
     end

data/lib/kramdown/converter/toc.rb

@@ -48,7 +48,7 @@ module Kramdown
         if el.type == :header && in_toc?(el)
           attr = el.attr.dup
           attr['id'] = generate_id(el.options[:raw_text]) if @options[:auto_ids] && !attr['id']
-          add_to_toc(el, attr['id'], @toc) if attr['id']
+          add_to_toc(el, attr['id']) if attr['id']
         else
           el.children.each {|child| convert(child)}
         end
@@ -57,7 +57,7 @@ module Kramdown
 
       private
 
-      def add_to_toc(el, id, toc)
+      def add_to_toc(el, id)
         toc_element = Element.new(:toc, el, :id => id)
 
         success = false

data/lib/kramdown/options.rb

@@ -20,6 +20,8 @@
 #++
 #
 
+require 'yaml'
+
 module Kramdown
 
   # This module defines all options that are used by parsers and/or converters as well as providing
@@ -233,6 +235,36 @@ Default: false
 Used by: kramdown parser
 EOF
 
+    define(:link_defs, Object, {}, <<EOF) do |val|
+Pre-defines link definitions
+
+This option can be used to pre-define link definitions. The value needs
+to be a Hash where the keys are the link identifiers and the values are
+two element Arrays with the link URL and the link title.
+
+If the value is a String, it has to contain a valid YAML hash and the
+hash has to follow the above guidelines.
+
+Default: {}
+Used by: kramdown parser
+EOF
+      if String === val
+        begin
+          val = YAML.load(val)
+        rescue RuntimeError, ArgumentError, SyntaxError
+          raise Kramdown::Error, "Invalid YAML value for option link_defs"
+        end
+      end
+      raise Kramdown::Error, "Invalid type #{val.class} for option #{name}" if !(Hash === val)
+      val.each do |k,v|
+        if !(Array === v) || v.size > 2 || v.size < 1
+          raise Kramdown::Error, "Invalid structure for hash value of option #{name}"
+        end
+        v << nil if v.size == 1
+      end
+      val
+    end
+
     define(:footnote_nr, Integer, 1, <<EOF)
 The number of the first footnote
 

data/lib/kramdown/parser/kramdown.rb

@@ -82,6 +82,7 @@ module Kramdown
         @root.options[:abbrev_defs] = {}
         @alds = {}
         @link_defs = {}
+        @options[:link_defs].each {|k,v| @link_defs[normalize_link_id(k)] = v}
         @footnotes = {}
 
         @block_parsers = [:blank_line, :codeblock, :codeblock_fenced, :blockquote, :atx_header,

data/lib/kramdown/parser/kramdown/header.rb

@@ -52,9 +52,11 @@ module Kramdown
       def parse_atx_header
         return false if !after_block_boundary?
 
-        @src.scan(ATX_HEADER_MATCH)
-        level, text, id = @src[1], @src[2], @src[3]
-        text.strip!
+        @src.check(ATX_HEADER_MATCH)
+        level, text, id = @src[1], @src[2].to_s.strip, @src[3]
+        return false if text.empty?
+
+        @src.pos += @src.matched_size
         el = new_block_el(:header, nil, nil, :level => level.length, :raw_text => text)
         add_text(text, el)
         el.attr['id'] = id if id

data/lib/kramdown/version.rb

@@ -23,6 +23,6 @@
 module Kramdown
 
   # The kramdown version.
-  VERSION = '0.14.1'
+  VERSION = '0.14.2'
 
 end

data/man/man1/kramdown.1

@@ -126,6 +126,22 @@ Default: false
 Used by: kramdown parser
 
 
+.TP
+.B \-\-link-defs ARG
+
+Pre-defines link definitions
+
+This option can be used to pre-define link definitions. The value needs
+to be a Hash where the keys are the link identifiers and the values are
+two element Arrays with the link URL and the link title.
+
+If the value is a String, it has to contain a valid YAML hash and the
+hash has to follow the above guidelines.
+
+Default: {}
+Used by: kramdown parser
+
+
 .TP
 .B \-\-footnote-nr ARG
 

data/test/testcases/block/04_header/atx_header.html

@@ -26,6 +26,12 @@
 ### not a header</p>
 </blockquote>
 
+<h1>header</h1>
+
+<p># </p>
+
+<p>#</p>
+
 <h3 id="id">Header</h3>
 
 <h3 id="id">Header</h3>

data/test/testcases/block/04_header/atx_header.text

@@ -23,6 +23,13 @@ paragraph
 > blockquote
 ### not a header
 
+
+# header
+
+# 
+
+#
+
 ### Header {#id}
 
 ### Header ## {#id}