kramdown 0.8.0 → 0.9.0

data/README

@@ -21,7 +21,7 @@ kramdown has a basic *Cloth API, so using kramdown is as easy as
 Just clone the git repository as described in doc/installation.page you are good to go. You probably
 want to install `rake` so that you can use the provided rake tasks. Aside from that:
 
-* The `tidy` binary needs to be installed for the html-to-html tests to work.
+* The `tidy` binary needs to be installed for the automatically derived tests to work.
 * The `latex` binary needs to be installed for the latex-compilation tests to work.
 
 

data/VERSION

@@ -1 +1 @@
-0.8.0
+0.9.0

data/doc/{default.less.css → default.scss.css}

@@ -1,5 +1,5 @@
-@text-color: #354146;
-@link-color: #1666A3;
+$text-color: #354146;
+$link-color: #1666A3;
 
 * {
     padding: 0;
@@ -32,7 +32,7 @@ body, table, code {
 }
 
 #header {
-    .with-margin;
+    @extend .with-margin;
 
     position: relative;
     padding: 0 0 0 30px;
@@ -66,7 +66,7 @@ body, table, code {
 }
 
 #nav {
-    .with-margin;
+    @extend .with-margin;
 
     ul {
         height: 40px;
@@ -120,7 +120,8 @@ body, table, code {
 }
 
 #intro {
-    .with-margin;
+    @extend .with-margin;
+
     background: #e6e8e9;
     height: auto;
 
@@ -133,7 +134,7 @@ body, table, code {
     }
 
     a {
-        color: @link-color;
+        color: $link-color;
         background-color: inherit;
         text-decoration: underline;
     }
@@ -146,7 +147,8 @@ body, table, code {
 
 /* content */
 #container {
-    .with-margin;
+    @extend .with-margin;
+
     position: relative;
     clear: both;
     background-color: #fff;
@@ -154,7 +156,7 @@ body, table, code {
     background-image: -webkit-gradient(linear, 0 0, 0 200, from(#eee), to(#fff));
 
     a {
-        color: @link-color;
+        color: $link-color;
         background-color: inherit;
         text-decoration: underline;
     }
@@ -462,7 +464,8 @@ body, table, code {
 
 /* footer */
 #footer {
-    .with-margin;
+    @extend .with-margin;
+
     clear: both;
     margin-top: 20px;
     padding: 5px 20px 30px;

data/doc/documentation.page

@@ -10,7 +10,7 @@ HTML. However, due to its modular architecture it is able to support additional
 formats. The following input and output formats are currently supported:
 
 * Input: [kramdown](parser/kramdown.html) (a superset of Markdown), [html](parser/html.html)
-* Output: [HTML](converter/html.html), [LaTeX](converter/latex.html)
+* Output: [HTML](converter/html.html), [LaTeX](converter/latex.html), [kramdown](converter/kramdown.html)
 
 
 ## Usage

data/doc/index.page

@@ -8,8 +8,42 @@ sort_info: 1
 If you want to get started with kramdown, have a look at the [installation page](installation.html)
 to see how you can install it on your system. Then look through the
 [documentation](documentation.html) for finding information about how to actually use kramdown and
-what parsers/converters it supports. The [syntax](syntax.html) provides a detailed description of
-the superset of Markdown which kramdown supports.
+its parsers/converters. The [syntax](syntax.html) provides a detailed description of the superset of
+Markdown which kramdown supports.
+
+{tikz:: path: overview.png
+img_attr: {style: 'background:transparent'}
+libraries: [mindmap, trees, arrows]
+transparent: true
+resolution: 300 100
+opts: |
+  mindmap, concept color=black, text=white,
+  root concept/.append style={font=\Large},
+  level 1 concept/.append style={font=\Large, minimum size=2.6cm},
+  level 2 concept/.append style={font=\Large},
+}
+\node[concept, font=\Large] (lib) {kramdown's internal representation}
+  child[concept color=orange, grow=150, ->] {node[concept] (i-kramdown) {kramdown}}
+  child[concept color=orange, grow=210] {node[concept] (i-html) {HTML}}
+  child[concept color=green!50!black, grow=40] {node[concept] (o-html) {HTML}}
+  child[concept color=green!50!black, grow=0] {node[concept] (o-kramdown) {kramdown}}
+  child[concept color=green!50!black, grow=-45] {
+    node[concept] (o-latex) {\LaTeX}
+    child[grow=0] {
+      node[concept] (o-latex-pdf) {PDF}
+    }
+  }
+  child[concept color=green!50!black, grow=-45] {node[concept] {\LaTeX}}
+;
+\draw [dash pattern=on 0pt off 2pt,line width=5pt,arrows=-angle 60,shorten >=15pt,shorten <=10pt,color=orange]
+   (i-kramdown) edge(lib)
+   (i-html) edge (lib);
+\draw [dash pattern=on 0pt off 2pt,line width=5pt,arrows=-angle 60,shorten >=10pt,shorten <=15pt,color=green!50!black]
+   (lib) edge(o-html)
+   (lib) edge (o-kramdown)
+   (lib) edge (o-latex);
+{tikz}
+{: style="text-align: center"}
 
 
 ## Bugs, Forums, Mailing Lists
@@ -55,7 +89,7 @@ It is probably the fastest pure-Ruby Markdown converter available (June 2010), b
 than [Maruku] and about 9x faster than [BlueFeather].
 
 <p class="a-center">
-The latest version of kramdown is <b>0.8.0</b> and it was released on <b>2010-06-08</b>.
+The latest version of kramdown is <b>0.9.0</b> and it was released on <b>2010-06-23</b>.
 </p>
 
 [PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/

data/doc/syntax.page

@@ -530,8 +530,9 @@ after the list item marker:
 Definition lists allow you to assign one or more definitions to one or more terms.
 
 A definition list is started when a normal paragraph is followed by a line with a definition marker
-(a colon which may be optionally indented up to three spaces), then at least one tab or one space
-and then the first part of the definition. The line with the definition marker may optionally be
+(a colon which may be optionally indented up to three spaces), then at least one tab or one space,
+optionally followed by an [IAL](#inline-attribute-lists) that should be applied to the list item and
+then the first part of the definition. The line with the definition marker may optionally be
 separated from the preceding paragraph by a blank line. The leading tabs or spaces are stripped away
 from this first line of the definition to allow for a nice alignment with the following definition
 content. Each line of the preceding paragraph is taken to be a term and the lines separately parsed
@@ -984,9 +985,9 @@ As the wording suggests, inline links provide all information inline in the text
 style links only provide the link text in the text flow and everything else is defined
 elsewhere. This also allows you to reuse link definitions.
 
-An inline style link can be created by surrounding the link text with square brackets, followed
-immediately by the link URL (and an optional title in single or double quotes preceded by at least
-one space) in normal parentheses. For example:
+An inline style link can be created by surrounding the link text which must contain at least one
+character with square brackets, followed immediately by the link URL (and an optional title in
+single or double quotes preceded by at least one space) in normal parentheses. For example:
 
     This is [a link](http://rubyforge.org) to a page.
     A [link](../test "local URI") can also have a title.
@@ -1049,11 +1050,13 @@ The link definition has the following structure:
 
 Images can be specified via a syntax that is similar to the one used by links. The difference is
 that you have to use an exclamation mark before the first square bracket and that the link text of a
-normal link becomes the alternative text of the image link. As with normal links, image links can be
-written inline or reference style. For example:
+normal link, which may also be the empty string in case of image links, becomes the alternative text
+of the image link. As with normal links, image links can be written inline or reference style. For
+example:
 
     Here comes a ![smiley](../images/smiley.png)! And here
     ![too](../images/other.png 'Title text'). Or ![here].
+    With empty alt text ![](see.jpg)
 
 The link definition for images is exactly the same as the link definition for normal links.
 

data/lib/kramdown/converter.rb

@@ -35,6 +35,7 @@ module Kramdown
     autoload :Base, 'kramdown/converter/base'
     autoload :Html, 'kramdown/converter/html'
     autoload :Latex, 'kramdown/converter/latex'
+    autoload :Kramdown, 'kramdown/converter/kramdown'
 
   end
 

data/lib/kramdown/converter/html.rb

@@ -29,6 +29,14 @@ module Kramdown
     # Converts a Kramdown::Document to HTML.
     class Html < Base
 
+      include ::Kramdown::Utils::HTML
+
+      # DEPRECATED: use #html_attributes
+      def options_for_element(el)
+        warn("DEPRECATION WARNING: this method will be deprecated in the next release, use #html_attributes instead")
+        html_attributes(el)
+      end
+
       # :stopdoc:
 
       # Defines the amount of indentation used when nesting HTML tags.
@@ -73,41 +81,41 @@ module Kramdown
         escape_html(el.value, :text)
       end
 
-      def convert_eob(el, indent, opts)
-        ''
-      end
-
       def convert_p(el, indent, opts)
-        "#{' '*indent}<p#{options_for_element(el)}>#{inner(el, indent, opts)}</p>\n"
+        if el.options[:transparent]
+          "#{inner(el, indent, opts)}"
+        else
+          "#{' '*indent}<p#{html_attributes(el)}>#{inner(el, indent, opts)}</p>\n"
+        end
       end
 
       def convert_codeblock(el, indent, opts)
-        if el.value && el.options[:attr] && el.options[:attr]['lang'] && HIGHLIGHTING_AVAILABLE
+        if 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],
             :bold_every => @doc.options[:coderay_bold_every], :css => @doc.options[:coderay_css]}
           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"
+          "#{' '*indent}<div#{html_attributes(el)}>#{result}#{' '*indent}</div>\n"
         else
-          result = (el.value ? escape_html(el.value) : inner(el, indent, opts))
+          result = escape_html(el.value)
           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' : ''))
               m.scan(/./).map do |c|
                 case c
                 when "\t" then "<span class=\"ws-tab#{suffix}\">\t</span>"
-                when " " then "<span class=\"ws-space#{suffix}\">&sdot;</span>"
+                when " " then "<span class=\"ws-space#{suffix}\">&#8901;</span>"
                 end
               end.join('')
             end
           end
-          "#{' '*indent}<pre#{options_for_element(el)}><code>#{result}#{result =~ /\n\Z/ ? '' : "\n"}</code></pre>\n"
+          "#{' '*indent}<pre#{html_attributes(el)}><code>#{result}#{result =~ /\n\Z/ ? '' : "\n"}</code></pre>\n"
         end
       end
 
       def convert_blockquote(el, indent, opts)
-        "#{' '*indent}<blockquote#{options_for_element(el)}>\n#{inner(el, indent, opts)}#{' '*indent}</blockquote>\n"
+        "#{' '*indent}<blockquote#{html_attributes(el)}>\n#{inner(el, indent, opts)}#{' '*indent}</blockquote>\n"
       end
 
       def convert_header(el, indent, opts)
@@ -115,8 +123,12 @@ module Kramdown
         if @doc.options[:auto_ids] && !(el.options[:attr] && el.options[:attr]['id'])
           (el.options[:attr] ||= {})['id'] = generate_id(el.options[:raw_text])
         end
-        @toc << [el.options[:level], el.options[:attr]['id'], el.children] if el.options[:attr] && el.options[:attr]['id']
-        "#{' '*indent}<h#{el.options[:level]}#{options_for_element(el)}>#{inner(el, indent, opts)}</h#{el.options[:level]}>\n"
+        @toc << [el.options[:level], el.options[:attr]['id'], el.children] if el.options[:attr] && el.options[:attr]['id'] && within_toc_depth?(el)
+        "#{' '*indent}<h#{el.options[:level]}#{html_attributes(el)}>#{inner(el, indent, opts)}</h#{el.options[:level]}>\n"
+      end
+
+      def within_toc_depth?(el)
+        @doc.options[:toc_depth] <= 0 || el.options[:level] <= @doc.options[:toc_depth]
       end
 
       def convert_hr(el, indent, opts)
@@ -128,16 +140,16 @@ module Kramdown
           @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"
+          "#{' '*indent}<#{el.type}#{html_attributes(el)}>\n#{inner(el, indent, opts)}#{' '*indent}</#{el.type}>\n"
         end
       end
       alias :convert_ol :convert_ul
       alias :convert_dl :convert_ul
 
       def convert_li(el, indent, opts)
-        output = ' '*indent << "<#{el.type}" << options_for_element(el) << ">"
+        output = ' '*indent << "<#{el.type}" << html_attributes(el) << ">"
         res = inner(el, indent, opts)
-        if el.children.empty? || el.children.first.options[:category] != :block
+        if el.children.empty? || (el.children.first.type == :p && el.children.first.options[:transparent])
           output << res << (res =~ /\n\Z/ ? ' '*indent : '')
         else
           output << "\n" << res << ' '*indent
@@ -147,22 +159,19 @@ module Kramdown
       alias :convert_dd :convert_li
 
       def convert_dt(el, indent, opts)
-        "#{' '*indent}<dt#{options_for_element(el)}>#{inner(el, indent, opts)}</dt>\n"
+        "#{' '*indent}<dt#{html_attributes(el)}>#{inner(el, indent, opts)}</dt>\n"
       end
 
       HTML_TAGS_WITH_BODY=['div', 'script']
 
       def convert_html_element(el, indent, opts)
         res = inner(el, indent, opts)
-        if @doc.options[:filter_html].include?(el.value)
-          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}>" : " />")
+        if el.options[:category] == :span
+          "<#{el.value}#{html_attributes(el)}" << (!res.empty? ? ">#{res}</#{el.value}>" : " />")
         else
           output = ''
           output << ' '*indent if !el.options[:parent_is_raw]
-          output << "<#{el.value}#{options_for_element(el)}"
+          output << "<#{el.value}#{html_attributes(el)}"
           if !res.empty? && el.options[:parse_type] != :block
             output << ">#{res}</#{el.value}>"
           elsif !res.empty?
@@ -195,11 +204,11 @@ module Kramdown
             "#{' '*(indent + INDENTATION)}" + (a == :default ? "<col />" : "<col align=\"#{a}\" />") + "\n"
           end.join('')
         end
-        "#{' '*indent}<table#{options_for_element(el)}>\n#{alignment}#{inner(el, indent, opts)}#{' '*indent}</table>\n"
+        "#{' '*indent}<table#{html_attributes(el)}>\n#{alignment}#{inner(el, indent, opts)}#{' '*indent}</table>\n"
       end
 
       def convert_thead(el, indent, opts)
-        "#{' '*indent}<#{el.type}#{options_for_element(el)}>\n#{inner(el, indent, opts)}#{' '*indent}</#{el.type}>\n"
+        "#{' '*indent}<#{el.type}#{html_attributes(el)}>\n#{inner(el, indent, opts)}#{' '*indent}</#{el.type}>\n"
       end
       alias :convert_tbody :convert_thead
       alias :convert_tfoot :convert_thead
@@ -207,10 +216,18 @@ module Kramdown
 
       def convert_td(el, indent, opts)
         res = inner(el, indent, opts)
-        "#{' '*indent}<#{el.type}#{options_for_element(el)}>#{res.empty? ? "&nbsp;" : res}</#{el.type}>\n"
+        "#{' '*indent}<#{el.type}#{html_attributes(el)}>#{res.empty? ? "&nbsp;" : res}</#{el.type}>\n"
       end
       alias :convert_th :convert_td
 
+      def convert_comment(el, indent, opts)
+        if el.options[:category] == :block
+          "#{' '*indent}<!-- #{el.value} -->\n"
+        else
+          "<!-- #{el.value} -->"
+        end
+      end
+
       def convert_br(el, indent, opts)
         "<br />"
       end
@@ -225,15 +242,15 @@ module Kramdown
         end
         res = inner(el, indent, opts)
         res = obfuscate(res) if do_obfuscation
-        "<a#{options_for_element(el)}>#{res}</a>"
+        "<a#{html_attributes(el)}>#{res}</a>"
       end
 
       def convert_img(el, indent, opts)
-        "<img#{options_for_element(el)} />"
+        "<img#{html_attributes(el)} />"
       end
 
       def convert_codespan(el, indent, opts)
-        "<code#{options_for_element(el)}>#{el.value ? escape_html(el.value) : inner(el, indent, opts)}</code>"
+        "<code#{html_attributes(el)}>#{escape_html(el.value)}</code>"
       end
 
       def convert_footnote(el, indent, opts)
@@ -244,29 +261,33 @@ module Kramdown
       end
 
       def convert_raw(el, indent, opts)
-        el.value
+        el.value + (el.options[:category] == :block ? "\n" : '')
       end
 
       def convert_em(el, indent, opts)
-        "<#{el.type}#{options_for_element(el)}>#{inner(el, indent, opts)}</#{el.type}>"
+        "<#{el.type}#{html_attributes(el)}>#{inner(el, indent, opts)}</#{el.type}>"
       end
       alias :convert_strong :convert_em
 
       def convert_entity(el, indent, opts)
-        "&#{el.value.kind_of?(Integer) ? '#' : ''}#{el.value};"
+        entity_to_str(el.value)
       end
 
       TYPOGRAPHIC_SYMS = {
-        :mdash => '&mdash;', :ndash => '&ndash;', :hellip => '&hellip;',
-        :laquo_space => '&laquo;&nbsp;', :raquo_space => '&nbsp;&raquo;',
-        :laquo => '&laquo;', :raquo => '&raquo;'
+        :mdash => [::Kramdown::Utils::Entities.entity('mdash')],
+        :ndash => [::Kramdown::Utils::Entities.entity('ndash')],
+        :hellip => [::Kramdown::Utils::Entities.entity('hellip')],
+        :laquo_space => [::Kramdown::Utils::Entities.entity('laquo'), ::Kramdown::Utils::Entities.entity('nbsp')],
+        :raquo_space => [::Kramdown::Utils::Entities.entity('nbsp'), ::Kramdown::Utils::Entities.entity('raquo')],
+        :laquo => [::Kramdown::Utils::Entities.entity('laquo')],
+        :raquo => [::Kramdown::Utils::Entities.entity('raquo')]
       }
       def convert_typographic_sym(el, indent, opts)
-        TYPOGRAPHIC_SYMS[el.value]
+        TYPOGRAPHIC_SYMS[el.value].map {|e| entity_to_str(e)}.join('')
       end
 
       def convert_smart_quote(el, indent, opts)
-        "&#{el.value};"
+        entity_to_str(::Kramdown::Utils::Entities.entity(el.value.to_s))
       end
 
       def convert_math(el, indent, opts)
@@ -276,7 +297,7 @@ module Kramdown
         el.options[:attr]['class'] += (el.options[:attr]['class'].empty? ? '' : ' ') + 'math'
         type = 'span'
         type = 'div' if el.options[:category] == :block
-        "<#{type}#{options_for_element(el)}>#{escape_html(el.value, :text)}</#{type}>#{type == 'div' ? "\n" : ''}"
+        "<#{type}#{html_attributes(el)}>#{escape_html(el.value)}</#{type}>#{type == 'div' ? "\n" : ''}"
       end
 
       def convert_abbreviation(el, indent, opts)
@@ -305,9 +326,10 @@ module Kramdown
         stack = []
         toc.each do |level, id, children|
           li = Element.new(:li, nil, {:level => level})
+          li.children << Element.new(:p, nil, {:transparent => true})
           a = Element.new(:a, nil, {:attr => {:href => "##{id}"}})
           a.children += children
-          li.children << a
+          li.children.last.children << a
           li.children << Element.new(type)
 
           success = false
@@ -363,34 +385,6 @@ module Kramdown
         (ol.children.empty? ? '' : "<div class=\"footnotes\">\n#{convert(ol, 2)}</div>\n")
       end
 
-      # Return the string with the attributes of the element +el+.
-      def options_for_element(el)
-        (el.options[:attr] || {}).map {|k,v| v.nil? ? '' : " #{k}=\"#{escape_html(v.to_s, :no_entities)}\"" }.sort.join('')
-      end
-
-      ESCAPE_MAP = {
-        '<' => '&lt;',
-        '>' => '&gt;',
-        '&' => '&amp;',
-        '"' => '&quot;'
-      }
-      ESCAPE_ALL_RE = Regexp.union(*ESCAPE_MAP.collect {|k,v| k})
-      ESCAPE_NO_ENTITIES_RE = Regexp.union(REXML::Parsers::BaseParser::REFERENCE_RE, ESCAPE_ALL_RE)
-      ESCAPE_NORMAL = Regexp.union(REXML::Parsers::BaseParser::REFERENCE_RE, /<|>|&/)
-      ESCAPE_RE_FROM_TYPE = {
-        :all => ESCAPE_ALL_RE,
-        :no_entities => ESCAPE_NO_ENTITIES_RE,
-        :text => ESCAPE_NORMAL
-      }
-
-      # Escape the special HTML characters in the string +str+. The parameter +type+ specifies what
-      # is escaped: <tt>:all</tt> - all special HTML characters as well as entities,
-      # <tt>:no_entities</tt> - all special HTML characters but no entities, <tt>:text</tt> - all
-      # special HTML characters except the quotation mark but no entities.
-      def escape_html(str, type = :all)
-        str.gsub(ESCAPE_RE_FROM_TYPE[type]) {|m| ESCAPE_MAP[m] || m}
-      end
-
     end
 
   end