kramdown 0.3.0 → 0.4.0

data/ChangeLog

@@ -1,3 +1,246 @@
+commit fa3d9d59c3e912a011a26f10a74ee0858cafe4dd
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Fri Jan 22 17:41:32 2010 +0100
+
+    Small fix for testing script
+
+benchmark/testing.sh
+
+commit 8c765d5783b460a46fdd8b547eeca91e7f48f0da
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Fri Jan 22 17:38:10 2010 +0100
+
+    Updated release file and homepage
+
+doc/index.page
+doc/news/release_0_4_0.page
+
+commit c6f7bcea913b19cc8c255f9a0358188db54cead4
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Fri Jan 22 17:37:53 2010 +0100
+
+    Updated benchmark data
+
+benchmark/historic-jruby-1.4.0.dat
+benchmark/historic-ruby-1.8.6.dat
+benchmark/historic-ruby-1.8.7.dat
+benchmark/historic-ruby-1.9.1p243.dat
+benchmark/historic-ruby-1.9.2dev.dat
+doc/img/graph-jruby-1.4.0.png
+doc/img/graph-ruby-1.8.6.png
+doc/img/graph-ruby-1.8.7.png
+doc/img/graph-ruby-1.9.1p243.png
+doc/img/graph-ruby-1.9.2dev.png
+
+commit 2d531e0984e9db1656e1d7dbde0dbc3c96383d05
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Fri Jan 22 16:55:48 2010 +0100
+
+    Small fix for syntax highlighting test
+
+test/testcases/block/12_extension/options3.html
+
+commit e3f053d87d85ba0c36befe489fe777b954f04079
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Wed Jan 20 18:39:25 2010 +0100
+
+    Implemented syntax highlighting of codeblocks via CodeRay library
+
+doc/index.page
+doc/news/release_0_4_0.page
+doc/syntax.page
+lib/kramdown/converter.rb
+lib/kramdown/document.rb
+lib/kramdown/extension.rb
+lib/kramdown/parser/kramdown/attribute_list.rb
+test/testcases/block/12_extension/options3.html
+test/testcases/block/12_extension/options3.text
+
+commit 9753aa172982fe6b9766b032017a747d00b1a1b3
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Wed Jan 20 18:37:09 2010 +0100
+
+    Various small fixes
+
+Rakefile
+doc/news/release_0_1_0.page
+doc/quickref.page
+doc/syntax.page
+
+commit 5c6215f4b8bf26801f6f4af81591ce5714e4abfc
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Wed Jan 20 17:51:21 2010 +0100
+
+    Updated codeblock parser implementation
+    
+    Codeblock lines separated by blank lines are not parsed separately anymore
+
+lib/kramdown/parser/kramdown/codeblock.rb
+lib/kramdown/parser/kramdown/footnote.rb
+test/testcases/block/06_codeblock/with_blank_line.text
+test/testcases/block/11_ial/simple.html
+test/testcases/block/11_ial/simple.text
+
+commit b9de73dd48590e47a5753f272478f88378ada709
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Wed Jan 20 15:46:43 2010 +0100
+
+    Clarified how options set through the options extension are used
+
+doc/syntax.page
+
+commit e371bd8ecbbfe1df200240ccd13562dcb8927940
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Tue Jan 19 14:58:32 2010 +0100
+
+    Fixed problem with too many alignment definitions on header sep line
+
+lib/kramdown/parser/kramdown/table.rb
+test/testcases/block/14_table/header.html
+test/testcases/block/14_table/header.text
+
+commit 8360bed28e436ee621848f60b7db7c2f29ffb573
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Tue Jan 19 14:49:19 2010 +0100
+
+    Updated table spec and implementation sothat header sep lines are a subset of sep lines
+
+doc/syntax.page
+lib/kramdown/parser/kramdown/table.rb
+test/testcases/block/14_table/header.html
+test/testcases/block/14_table/header.text
+
+commit 59cf34d9a9efd70a69b324097148199bf70b8189
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Sat Jan 16 08:13:18 2010 +0100
+
+    Small fix in table separator line regexps
+
+lib/kramdown/parser/kramdown/table.rb
+
+commit 6e77f79a5bc37e94267da8b4a42be6da036e6f81
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Fri Jan 15 12:14:42 2010 +0100
+
+    Fixed problem with escaped characters
+    
+    * Added colon to the list of escaped characters in the syntax document
+    * Added test cases for escaped colons and pipes
+    * Fixed bug in regexp for escaped characters
+
+doc/news/release_0_4_0.page
+doc/syntax.page
+lib/kramdown/parser/kramdown/escaped_chars.rb
+test/testcases/block/13_definition_list/no_def_list.html
+test/testcases/block/13_definition_list/no_def_list.text
+test/testcases/block/14_table/no_table.html
+test/testcases/block/14_table/no_table.text
+test/testcases/span/escaped_chars/normal.html
+test/testcases/span/escaped_chars/normal.text
+
+commit df5ac74abffb0d78ac3ed05c155c36a83e4af273
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Thu Jan 14 12:09:55 2010 +0100
+
+    Two small doc fixes
+
+doc/syntax.page
+
+commit a1f6c3c755c1b18502403c1ac6236a5dbcd47dd8
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Thu Jan 14 08:45:04 2010 +0100
+
+    Fixed test case for table headers
+
+test/testcases/block/14_table/header.html
+
+commit b79822c8a78729be53a1d9a9db3f783c3b22a0ae
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Thu Jan 14 08:44:17 2010 +0100
+
+    Reimplemented HTML converter to use post- instead of pre-order iteration
+    
+    This is needed to ease the implementation of the td/th conversion.
+    It is also a little bit faster than the old version.
+
+lib/kramdown/converter.rb
+
+commit 17caef2da4cbe065e0509ca59e04daee8baca425
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Wed Jan 13 15:36:34 2010 +0100
+
+    Changed CSS class name kramdown-footnotes to footnotes
+
+doc/news/release_0_4_0.page
+lib/kramdown/converter.rb
+test/testcases/block/12_extension/options.html
+test/testcases/block/12_extension/options2.html
+test/testcases/span/04_footnote/footnote_nr.html
+test/testcases/span/04_footnote/markers.html
+
+commit d446c6ee421e983bd4cd5a13d3f3341523a3d594
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Wed Jan 13 15:25:46 2010 +0100
+
+    Bumped version number and added release notes file
+
+doc/news/release_0_4_0.page
+lib/kramdown/version.rb
+
+commit 0473b0c40d6a20749772042b64472c5f6514ec0b
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Wed Jan 13 15:10:57 2010 +0100
+
+    Updated table syntax and implemented it
+
+doc/quickref.page
+doc/syntax.page
+lib/kramdown/converter.rb
+lib/kramdown/parser/kramdown.rb
+lib/kramdown/parser/kramdown/table.rb
+test/testcases/block/14_table/errors.html
+test/testcases/block/14_table/errors.text
+test/testcases/block/14_table/footer.html
+test/testcases/block/14_table/footer.text
+test/testcases/block/14_table/header.html
+test/testcases/block/14_table/header.text
+test/testcases/block/14_table/simple.html
+test/testcases/block/14_table/simple.text
+
+commit d8d032bcb399593d77a15d8269ada8884ba14fa0
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Wed Jan 13 10:04:57 2010 +0100
+
+    Clarified one point regarding HTML span parsing
+
+doc/syntax.page
+test/testcases/block/09_html/parse_as_span.html
+test/testcases/block/09_html/parse_as_span.text
+
+commit 423ec50ba84518d1b734c396000492da217f5b99
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Mon Jan 4 21:52:15 2010 +0100
+
+    Third table syntax proposal
+
+doc/syntax.page
+
+commit 66427040dea52007c24ea4df0dd6484b53b11f30
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Thu Dec 31 09:26:17 2009 +0100
+
+    Second table syntax proposal
+
+doc/syntax.page
+
+commit 4b2d39389cee746ee384e35bdfa60bf5c7313eb4
+Author: Thomas Leitner <t_leitner@gmx.at>
+Date:   Wed Dec 30 08:53:15 2009 +0100
+
+    First table syntax proposal
+
+doc/syntax.page
+
 commit fff933c46a6345aca7ee2333b6c71d9466b0e297
 Author: Thomas Leitner <t_leitner@gmx.at>
 Date:   Sun Dec 20 16:20:10 2009 +0100

data/Rakefile

@@ -59,7 +59,6 @@ if defined? Webgen
       config['sources'] = [['/', "Webgen::Source::FileSystem", 'doc']]
       config['output'] = ['Webgen::Output::FileSystem', 'htmldoc']
       config.default_processing_pipeline('Page' => 'erb,tags,kramdown,blocks,fragments')
-      config['contentprocessor.map']['kramdown'] = 'Kramdown::KDConverter'
     end
   end
 
@@ -259,22 +258,6 @@ task :clobber => ['dev:clobber']
 
 module Kramdown
 
-  # Processes content in kramdown format using the +maruku+ library.
-  class KDConverter
-
-    # Convert the content in +context+ to HTML.
-    def call(context)
-      extend Webgen::Loggable
-      doc = ::Kramdown::Document.new(context.content)
-      context.content = doc.to_html
-      doc.warnings.each do |warn|
-        log(:warn) { "Warning while parsing #{context.ref_node.alcn} with kramdown: #{warn}" }
-      end
-      context
-    end
-
-  end
-
   class Extension
 
     def parse_kdexample(parser, opts, body)

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

data/benchmark/historic-jruby-1.4.0.dat

@@ -1,7 +1,7 @@
-#  kramdown 0.1.0 ||  kramdown 0.2.0 ||  kramdown 2009-03-10 ||  kramdown 2009-11-05 ||  kramdown 0.3.0
-    1    0.21300    0.31800    0.20500    0.24800    0.16800
-    2    0.20700    0.22600    0.27200    0.22900    0.26700
-    4    0.22000    0.21700    0.21600    0.19600    0.20400
-    8    0.36300    0.44500    0.39300    0.34300    0.30100
-   16    0.45400    0.53400    1.01400    0.41100    0.46200
-   32    1.02800    0.98100    1.70100    0.84600    0.84600
+#  kramdown 0.1.0 ||  kramdown 0.2.0 ||  kramdown 2009-03-10 ||  kramdown 2009-11-05 ||  kramdown 0.3.0 ||  kramdown 0.4.0
+    1    0.21300    0.31800    0.20500    0.24800    0.16800    0.30400
+    2    0.20700    0.22600    0.27200    0.22900    0.26700    0.23400
+    4    0.22000    0.21700    0.21600    0.19600    0.20400    0.19300
+    8    0.36300    0.44500    0.39300    0.34300    0.30100    0.29500
+   16    0.45400    0.53400    1.01400    0.41100    0.46200    0.48900
+   32    1.02800    0.98100    1.70100    0.84600    0.84600    0.81900

data/benchmark/historic-ruby-1.8.6.dat

@@ -1,7 +1,7 @@
-#  kramdown 0.1.0 ||  kramdown 0.2.0 ||  kramdown 2009-03-10 ||  kramdown 2009-11-05 ||  kramdown 0.3.0
-    1    0.01211    0.01274    0.01406    0.01150    0.01385
-    2    0.02449    0.02582    0.02545    0.02329    0.02924
-    4    0.08228    0.08475    0.07402    0.07921    0.08600
-    8    0.12842    0.13410    0.24217    0.12481    0.14426
-   16    0.22743    0.27748    0.84538    0.21843    0.29497
-   32    0.45690    0.51838    3.95635    0.51363    0.54252
+#  kramdown 0.1.0 ||  kramdown 0.2.0 ||  kramdown 2009-03-10 ||  kramdown 2009-11-05 ||  kramdown 0.3.0 ||  kramdown 0.4.0
+    1    0.01211    0.01274    0.01406    0.01150    0.01385    0.01359
+    2    0.02449    0.02582    0.02545    0.02329    0.02924    0.02691
+    4    0.08228    0.08475    0.07402    0.07921    0.08600    0.09013
+    8    0.12842    0.13410    0.24217    0.12481    0.14426    0.13687
+   16    0.22743    0.27748    0.84538    0.21843    0.29497    0.28115
+   32    0.45690    0.51838    3.95635    0.51363    0.54252    0.51869

data/benchmark/historic-ruby-1.8.7.dat

@@ -1,7 +1,7 @@
-#  kramdown 0.1.0 ||  kramdown 0.2.0 ||  kramdown 2009-03-10 ||  kramdown 2009-11-05 ||  kramdown 0.3.0
-    1    0.01259    0.01329    0.01446    0.01219    0.01580
-    2    0.02472    0.02672    0.02637    0.02406    0.02858
-    4    0.09610    0.08355    0.07451    0.07719    0.05439
-    8    0.13269    0.13811    0.24393    0.12766    0.10869
-   16    0.27243    0.27540    0.93940    0.25091    0.28680
-   32    0.52890    0.55667    4.93810    0.50113    0.54547
+#  kramdown 0.1.0 ||  kramdown 0.2.0 ||  kramdown 2009-03-10 ||  kramdown 2009-11-05 ||  kramdown 0.3.0 ||  kramdown 0.4.0
+    1    0.01259    0.01329    0.01446    0.01219    0.01580    0.01397
+    2    0.02472    0.02672    0.02637    0.02406    0.02858    0.02849
+    4    0.09610    0.08355    0.07451    0.07719    0.05439    0.05232
+    8    0.13269    0.13811    0.24393    0.12766    0.10869    0.10471
+   16    0.27243    0.27540    0.93940    0.25091    0.28680    0.27240
+   32    0.52890    0.55667    4.93810    0.50113    0.54547    0.52283

data/benchmark/historic-ruby-1.9.1p243.dat

@@ -1,7 +1,7 @@
-#  kramdown 0.1.0 ||  kramdown 0.2.0 ||  kramdown 2009-03-10 ||  kramdown 2009-11-05 ||  kramdown 0.3.0
-    1    0.02062    0.02216    0.01349    0.02013    0.02152
-    2    0.04097    0.04290    0.03316    0.03738    0.03939
-    4    0.07696    0.08015    0.07079    0.07084    0.09122
-    8    0.16986    0.16998    0.17800    0.14978    0.16856
-   16    0.33684    0.34800    0.60818    0.30365    0.35242
-   32    0.68273    0.70498    2.77191    0.61580    0.74138
+#  kramdown 0.1.0 ||  kramdown 0.2.0 ||  kramdown 2009-03-10 ||  kramdown 2009-11-05 ||  kramdown 0.3.0 ||  kramdown 0.4.0
+    1    0.02062    0.02216    0.01349    0.02013    0.02152    0.02025
+    2    0.04097    0.04290    0.03316    0.03738    0.03939    0.03956
+    4    0.07696    0.08015    0.07079    0.07084    0.09122    0.07573
+    8    0.16986    0.16998    0.17800    0.14978    0.16856    0.16380
+   16    0.33684    0.34800    0.60818    0.30365    0.35242    0.33358
+   32    0.68273    0.70498    2.77191    0.61580    0.74138    0.66569

data/benchmark/historic-ruby-1.9.2dev.dat

@@ -1,7 +1,7 @@
-#  kramdown 0.1.0 ||  kramdown 0.2.0 ||  kramdown 2009-03-10 ||  kramdown 2009-11-05 ||  kramdown 0.3.0
-    1    0.01827    0.02000    0.01064    0.01981    0.01830
-    2    0.03951    0.04158    0.03260    0.03712    0.04056
-    4    0.08055    0.08419    0.05945    0.07256    0.08363
-    8    0.14925    0.15101    0.15053    0.14051    0.15830
-   16    0.31483    0.31485    0.46291    0.28562    0.31176
-   32    0.62318    0.64162    2.17304    0.56619    0.61918
+#  kramdown 0.1.0 ||  kramdown 0.2.0 ||  kramdown 2009-03-10 ||  kramdown 2009-11-05 ||  kramdown 0.3.0 ||  kramdown 0.4.0
+    1    0.01827    0.02000    0.01064    0.01981    0.01830    0.02061
+    2    0.03951    0.04158    0.03260    0.03712    0.04056    0.04378
+    4    0.08055    0.08419    0.05945    0.07256    0.08363    0.08286
+    8    0.14925    0.15101    0.15053    0.14051    0.15830    0.14567
+   16    0.31483    0.31485    0.46291    0.28562    0.31176    0.30726
+   32    0.62318    0.64162    2.17304    0.56619    0.61918    0.59270

data/benchmark/testing.sh

@@ -5,5 +5,5 @@ source ~/.bashrc
 for VERSION in 1.8.5 1.8.6 1.8.7 1.9.1 1.9.2 'jruby 1.4.0'; do
 	rvm $VERSION
 	echo $(ruby -v)
-	rake test
+	RUBYOPT=-rubygems rake test
 done

data/doc/index.page

@@ -27,6 +27,7 @@ The kramdown package provides two ways for using it:
       require 'kramdown'
 
       Kramdown::Document.new(text).to_html
+  {: lang='ruby'}
 
   The second parameter to the `new` call is an options hash for (de)activating certain features. For
   more information have a look at the [API documentation]({relocatable: rdoc/index.html}).
@@ -78,11 +79,11 @@ and [mailing lists][ml] available if you have any questions!
 written in Ruby, supports standard Markdown (with some minor modifications) and various extensions
 that have been made popular by the [PHP Markdown Extra] package and [Maruku].
 
-It is probably the fastest pure-Ruby Markdown converter available (November 2009), being 5x faster
-than [Maruku] and about 10x faster than [BlueFeather].
+It is probably the fastest pure-Ruby Markdown converter available (January 2010), being about 4.5x
+faster than [Maruku] and about 10x faster than [BlueFeather].
 
 <div class="a-center">
-The latest version of kramdown is <b>0.3.0</b> and it was released on <b>2009-12-20</b>.
+The latest version of kramdown is <b>0.4.0</b> and it was released on <b>2010-01-22</b>.
 </div>
 
 [PHP Markdown Extra]: http://michelf.com/projects/php-markdown/extra/

data/doc/quickref.page

@@ -10,7 +10,7 @@ the kramdown syntax is a superset of the Markdown syntax, only a small part of t
 is not available in standard Markdown syntax. Note, that only the most basic syntax information is
 given. However, a link to the detailed syntax for each element is provided (which also details the
 differences to the standard Markdown syntax). The quick reference is for version **<%=
-Kramdown::VERSION %>** of the syntax documentation.
+::Kramdown::VERSION %>** of the syntax documentation.
 
 kramdown has two main classes of elements: block and span level elements. Block level elements are
 used to create paragraphs, headers, lists and so on whereas span level elements are used to markup
@@ -252,6 +252,36 @@ This *is* a term
 {::kdexample:}
 
 
+## Tables
+
+{::kdlink:: #tables part="tables"}
+
+kramdown supports a syntax for creating simple tables. A line starting with a pipe character (`|`)
+starts a table row. However, if the pipe characters is immediately followed by a dash (`-`), a
+separator line is created. Separator lines are used to split the table header from the table body
+(and optionally align the table columns) and to split the table body into multiple parts. If the
+pipe character is followed by an equal sign (`=`), the tables rows below it are part of the table
+footer.
+
+{::kdexample:}
+| A simple | table |
+| with multiple | lines|
+{::kdexample:}
+
+{::kdexample:}
+| Header1 | Header2 | Header3 |
+|:--------|:-------:|--------:|
+| cell1   | cell2   | cell3   |
+| cell4   | cell5   | cell6   |
+|----
+| cell1   | cell2   | cell3   |
+| cell4   | cell5   | cell6   |
+|=====
+| Foot1   | Foot2   | Foot3
+{: rules="groups"}
+{::kdexample:}
+
+
 ## HTML elements
 
 {::kdlink:: #html-blocks part="HTML blocks"}

data/doc/syntax.page

@@ -3,7 +3,7 @@ title: Syntax
 in_menu: true
 sort_info: 10
 ---
-This is version **<%= Kramdown::VERSION %>** of the syntax documentation.
+This is version **<%= ::Kramdown::VERSION %>** of the syntax documentation.
 
 Table of Contents:
 
@@ -78,6 +78,8 @@ Following is a list of all those characters (character sequences) that can be es
     !         bang
     <<        left guillemet
     >>        right guillemet
+    :         colon
+    |         pipe
 
 
 ## Typographic Symbols
@@ -403,20 +405,36 @@ code.
 ### Showing Whitespace in a Code Block
 
 If you add the class `show-whitespaces` to a code block (using a [block
-IAL](#block_inline_attribute_lists)), all spaces are replaced with `&sdot;` and additionally spaces
+IAL](#block-inline-attribute-lists)), all spaces are replaced with `&sdot;` and additionally spaces
 and tabs in the code block are marked up using HTML `span` tags and the CSS classes:
 
 * `ws-space-l`, `ws-tab-l`: leading spaces/tabs
 * `ws-space-r`, `ws-tab-r`: trailing spaces/tabs
 * `ws-space`, `ws-tab`: spaces/tabs in between
 
-Here is an example:
+Here is an example output:
 
     	  leading tab	and space
     trailing   tab and space    	
 {: .show-whitespaces}
 
 
+### Automatic Syntax Highlighting   {#syntax-highlighting}
+
+kramdown supports syntax highlighting of code through the [CodeRay](http://coderay.rubychan.de)
+library if it is installed and if the HTML converter is used. Syntax highlighting is activated when
+you add the key `lang` to a code block (using a [block IAL](#block-inline-attribute-lists)), its
+value has to be a language supported by CodeRay.
+
+Here is an example output:
+
+    require 'kramdown'
+
+    Kramdown::Document.new('* something').to_html
+    puts 1 + 1
+{: lang='ruby'}
+
+
 ## Horizontal Rules
 
 A horizontal rule is created by using three or more asterisks, dashes or underscores (these may not
@@ -676,6 +694,138 @@ The rules about having any block level element as first element in a list item a
 definition.
 
 
+## Tables
+
+> This syntax feature is not part of the original Markdown syntax. The syntax is based on the one
+> from the [PHP Markdown Extra] package.
+{: .markdown-difference}
+
+Sometimes one wants to include simple tabular data in a kramdown document for which using a
+full-blown HTML table is just too much. kramdown supports this with a simple syntax for ASCII
+tables.
+
+There are three different text line types that can be used in a table:
+
+* *Table rows* define the content of a table.
+
+  A table row is started with a pipe character, optionally indented up to three spaces, and then the
+  text of the first table cell. Subsequent table cells consist of a pipe character followed by the
+  cell text. One may optionally use a pipe character at the the end of a table row line.
+
+  Header rows, footer rows and normal rows are all made using these table rows. Table cells can only
+  contain a single line of text, no multiline text is supported. The text of a table cell is parsed
+  as span level elements. Note that literal pipe characters need to be escaped, even if they occur
+  in code spans!
+
+  Here are some example table rows:
+
+      | First cell|Second cell|Third cell
+      | First | Second | Third |
+
+* *Separator lines* are used to split the table body into multiple body parts.
+
+  A separator line is started with a pipe or plus character, optionally indented up to three spaces,
+  followed by an optional space, an optional colon, a dash and then any number and combination of
+  pipes, dashes, pluses, colons and spaces. The pipe and plus characters can be used to visually
+  separate columns although this is not needed. Multiple separator lines after another are treated
+  as one separator line.
+
+  Here are some example separator lines:
+
+      |----+----|
+      +----|----+
+      |---------|
+      |-
+      | :-----: |
+
+* The first separator line after at least one table row is treated specially, namely as *header
+  separator line*. It is used to demarcate header rows from normal table rows and/or to set column
+  alignments. All table rows above the header separator line are considered to be header rows.
+
+  The header separator line can be specially formatted to contain column alignment definitions: An
+  alignment definition consists of an optional space followed by an optional colon, one or more
+  dashes, an optional colon and another optional space. The colons of an alignment definition are
+  used to set the alignment of a column: if there are no colons, the column uses the default
+  alignment, if there is a colon only before the dashes, the column is left aligned, if there are
+  colons before and after the dashes, the column is center aligned and if there is only a colon
+  after the dashes, the column is right aligned. Each alignment definition sets the alignment for
+  one column, the first alignment definition for the first column, the second alignment definition
+  for the second column and so on.
+
+  Here are some example header separator lines with alignment definitions:
+
+      |---+---+---|
+      + :-: |:------| ---:|
+      | :-: :- -: -
+
+* A *footer separator line* is used to demarcate footer rows from normal table rows. All table rows
+  below the footer separator line are considered to be footer rows.
+
+  A footer separator line is like a normal separator line except that dashes are replaced by equal
+  signs. A footer separator line may only appear once in a table. If multiple footer separator lines
+  are used in one table, only the last is treated as footer separator line, all others are treated
+  as normal separator lines. Normal separator lines that are used after the footer separator line
+  are ignored.
+
+  Here are some example footer separator lines:
+
+      |====+====|
+      +====|====+
+      |=========|
+      |=
+
+Trailing spaces or tabs are ignored in all cases. To simplify table creation and maintenance,
+header, footer and normal separator lines need not specify the same number of columns as table rows;
+even `|-` and `|=` are a valid separators.
+
+Given the above components, a table is specified by
+
+* an optional separator line,
+* optionally followed by zero, one or more table rows followed by a header separator line,
+* one or more table rows, optionally interspersed with separator lines,
+* optionally followed by a footer separator line and zero, one or more table rows and
+* an optional trailing separator line.
+
+> The table syntax differs from the one used in [PHP Markdown Extra] as follows:
+>
+> * kramdown tables have to begin with a pipe character, this is optional in [PHP Markdown Extra].
+> * kramdown tables do not need to have a table header.
+> * kramdown tables can be structured using separator lines.
+> * kramdown tables can contain a table footer.
+{: .markdown-difference}
+
+Here is an example for a kramdown table with a table header row, two table bodies and a table footer
+row:
+
+    |-----------------+------------+-----------------+----------------|
+    | Default aligned |Left aligned| Center aligned  | Right aligned  |
+    |-----------------|:-----------|:---------------:|---------------:|
+    | First body part |Second cell | Third cell      | fourth cell    |
+    | Second line     |foo         | **strong**      | baz            |
+    | Third line      |quux        | baz             | bar            |
+    |-----------------+------------+-----------------+----------------|
+    | Second body     |            |                 |                |
+    | 2 line          |            |                 |                |
+    |=================+============+=================+================|
+    | Footer row      |            |                 |                |
+    |-----------------+------------+-----------------+----------------|
+
+The above example table is rather time-consuming to create without the help of an ASCII table
+editor. However, the table syntax is flexible and the above table could also be written like this:
+
+    |---
+    | Default aligned | Left aligned | Center aligned | Right aligned
+    |-|:-|:-:|-:
+    | First body part | Second cell | Third cell | fourth cell
+    | Second line |foo | **strong** | baz
+    | Third line |quux | baz | bar
+    |---
+    | Second body
+    | 2 line
+    |===
+    | Footer row
+
+
 ## HTML Blocks
 
 > The original Markdown syntax specifies that an HTML block must start at the left margin, i.e. no
@@ -716,7 +866,8 @@ content is parsed:
 
 * Parse as span level elements: If the HTML/XML tag content should be parsed as text containing span
   level elements, then all text until the *next* matching end tag or until the end of the document
-  will be the content of the tag and will later be parsed by the span level parser.
+  will be the content of the tag and will later be parsed by the span level parser. This also means
+  that if the matching end tag is inside what appears to be a code span, it is still used!
 
 If there is text after an end tag, it will be parsed as if it appears on a separate line except when
 inside a raw HTML block.
@@ -842,8 +993,8 @@ comments is not processed:
 This is an implementation of [Maruku]'s feature for adding attributes to block and span level
 elements (the naming is also taken from Maruku). This block level element is used to define
 attributes which can be referenced later. The [Block Inline Attribute
-List](#block_inline_attribute_lists) is used to attach attributes to a block level element and the
-[Span Inline Attribute List](#span_inline_attribute_lists) is used to attach attributes to a span
+List](#block-inline-attribute-lists) is used to attach attributes to a block level element and the
+[Span Inline Attribute List](#span-inline-attribute-lists) is used to attach attributes to a span
 level element.
 
 Following are some examples of attribute list definitions (ALDs) and afterwards comes the syntax
@@ -916,7 +1067,7 @@ ALDs are processed like they are defined in one ALD.
 {: .markdown-difference}
 
 This block level element is used to attach attributes to a block level element. A block inline
-attribute list (block IAL) has the same structure as an [ALD](#attribute_list_definitions) except
+attribute list (block IAL) has the same structure as an [ALD](#attribute-list-definitions) except
 that the colon/reference name/colon part is replaced by a colon. A block IAL (or two or more block
 IALs) has to be put directly after the block level element to which the attributes should be
 attached, otherwise it is ignored. This is, for example, the case when there is a blank line between
@@ -949,14 +1100,14 @@ An extension block has two forms, one with a body and one without a body:
 
 Without a body
 
-:   The extension block line has the same structure as an [ALD](#attribute_list_definitions) except
+:   The extension block line has the same structure as an [ALD](#attribute-list-definitions) except
     that the reference name needs to prefixed and postfixed with `:` and identifies the extension to
     be used. Attributes can be defined like it is done for an ALD.
 
 With a body
 
 :   The starting and ending lines of an extension block with a body have the same structure as an
-    [ALD](#attribute_list_definitions) except that the reference name needs to prefixed with `:` and
+    [ALD](#attribute-list-definitions) except that the reference name needs to prefixed with `:` and
     identifies the extension to be used; attributes can be defined on the starting or ending line.
     The text between the starting and ending line is passed to the extension and not parsed by
     kramdown. If no ending line is found, the starting line is ignored and the body is parsed
@@ -975,8 +1126,11 @@ the body is ignored. The following extensions are built-in:
 
 `options`
 
-:   Should be used without a body since the body is ignored. Is used for setting options for the
-    kramdown processor (for example, to enable automatic header ID generation).
+:   Should be used without a body since the body is ignored. Is used for setting the global options
+    for the kramdown processor (for example, to enable automatic header ID generation). Note that
+    options that are used by the parser are immediately effective whereas all other options are not!
+    This means, for example, that it is not possible to set converter options only for some part of
+    a kramdown document.
 
 Here are some examples for how extension blocks look like:
 
@@ -1282,7 +1436,7 @@ name, all footnote definitions but the last are ignored.
 > the [Maruku] package.
 {: .markdown-difference}
 
-This is a version of the [block inline attribute list](#block_inline_attribute_lists) for span level
+This is a version of the [block inline attribute list](#block-inline-attribute-lists) for span level
 elements. It has the same structure as the block IAL except that leading and trailing spaces are not
 allowed. A span IAL (or two or more span IALs) has to be put directly after the span level element,
 no additional character is allowed between.