kramdown 0.11.0 → 0.12.0

data/lib/kramdown/converter/kramdown.rb

@@ -26,14 +26,14 @@ module Kramdown
 
   module Converter
 
-    # Converts a Kramdown::Document to the kramdown format.
+    # Converts an element tree to the kramdown format.
     class Kramdown < Base
 
       # :stopdoc:
 
-      include ::Kramdown::Utils::HTML
+      include ::Kramdown::Utils::Html
 
-      def initialize(doc)
+      def initialize(root, options)
         super
         @linkrefs = []
         @footnotes = []
@@ -45,12 +45,12 @@ module Kramdown
         res = send("convert_#{el.type}", el, opts)
         if el.type != :html_element && el.type != :li && el.type != :dd && (ial = ial_for_element(el))
           res << ial
-          res << "\n\n" if el.options[:category] == :block
+          res << "\n\n" if Element.category(el) == :block
         elsif [:ul, :dl, :ol, :codeblock].include?(el.type) && opts[:next] &&
             ([el.type, :codeblock].include?(opts[:next].type) ||
              (opts[:next].type == :blank && opts[:nnext] && [el.type, :codeblock].include?(opts[:nnext].type)))
           res << "^\n\n"
-        elsif el.options[:category] == :block && ![:li, :dd, :dt, :td, :th, :tr, :thead, :tbody, :tfoot, :blank].include?(el.type) &&
+        elsif Element.category(el) == :block && ![:li, :dd, :dt, :td, :th, :tr, :thead, :tbody, :tfoot, :blank].include?(el.type) &&
             (el.type != :p || !el.options[:transparent])
           res << "\n"
         end
@@ -77,7 +77,7 @@ module Kramdown
         ""
       end
 
-      ESCAPED_CHAR_RE = /(\$\$|[\\*_`\[\]\{"'])|^[ ]{0,3}(:)/
+      ESCAPED_CHAR_RE = /(\$\$|[\\*_`\[\]\{"'|])|^[ ]{0,3}(:)/
 
       def convert_text(el, opts)
         if opts[:raw_text]
@@ -90,10 +90,9 @@ module Kramdown
       end
 
       def convert_p(el, opts)
-        w = @doc.options[:line_width] - opts[:indent].to_s.to_i
+        w = @options[:line_width] - opts[:indent].to_s.to_i
         first, second, *rest = inner(el, opts).strip.gsub(/(.{1,#{w}})( +|$\n?)/, "\\1\n").split(/\n/)
-        first.gsub!(/^(?:(#)|(\d+)\.|([+-]\s))/) { $1 || $3 ? "\\#{$1 || $3}" : "#{$2}\\."}
-        first.gsub!(/\|/, '\\|')
+        first.gsub!(/^(?:(#|>)|(\d+)\.|([+-]\s))/) { $1 || $3 ? "\\#{$1 || $3}" : "#{$2}\\."} if first
         second.gsub!(/^([=-]+\s*?)$/, "\\\1") if second
         [first, second, *rest].compact.join("\n") + "\n"
       end
@@ -132,7 +131,7 @@ module Kramdown
                        ["#{opts[:index] + 1}.".ljust(4), 4]
                      end
         if ial = ial_for_element(el)
-          sym += ial + " "
+          sym << ial << " "
         end
 
         opts[:indent] += width
@@ -156,7 +155,7 @@ module Kramdown
       def convert_dd(el, opts)
         sym, width = ": ", (el.children.first.type == :codeblock ? 4 : 2)
         if ial = ial_for_element(el)
-          sym += ial + " "
+          sym << ial << " "
         end
 
         opts[:indent] += width
@@ -166,7 +165,7 @@ module Kramdown
         last = last.map {|l| " "*width + l}.join("\n")
         text = first + (last.empty? ? "" : "\n") + last + newlines
         text.chomp! if text =~ /\n\n\Z/ && opts[:next] && opts[:next].type == :dd
-        text += "\n" if text !~ /\n\n\Z/ && opts[:next] && opts[:next].type == :dt
+        text << "\n" if text !~ /\n\n\Z/ && opts[:next] && opts[:next].type == :dt
         if el.children.first.type == :p && !el.children.first.options[:transparent]
           "\n#{sym}#{text}"
         elsif el.children.first.type == :codeblock
@@ -184,19 +183,19 @@ module Kramdown
 
       def convert_html_element(el, opts)
         markdown_attr = el.options[:category] == :block && el.children.any? do |c|
-          c.type != :html_element && (c.type != :p || !c.options[:transparent]) && c.options[:category] == :block
+          c.type != :html_element && (c.type != :p || !c.options[:transparent]) && Element.category(c) == :block
         end
         opts[:force_raw_text] = true if %w{script pre code}.include?(el.value)
         opts[:raw_text] = opts[:force_raw_text] || opts[:block_raw_text] || (el.options[:category] != :span && !markdown_attr)
         opts[:block_raw_text] = true if el.options[:category] == :block && opts[:raw_text]
         res = inner(el, opts)
         if el.options[:category] == :span
-          "<#{el.value}#{html_attributes(el)}" << (!res.empty? || HTML_TAGS_WITH_BODY.include?(el.value) ? ">#{res}</#{el.value}>" : " />")
+          "<#{el.value}#{html_attributes(el.attr)}" << (!res.empty? || HTML_TAGS_WITH_BODY.include?(el.value) ? ">#{res}</#{el.value}>" : " />")
         else
           output = ''
-          output << "<#{el.value}#{html_attributes(el)}"
+          output << "<#{el.value}#{html_attributes(el.attr)}"
           output << " markdown=\"1\"" if markdown_attr
-          if !res.empty? && el.options[:parse_type] != :block
+          if !res.empty? && el.options[:content_model] != :block
             output << ">#{res}</#{el.value}>"
           elsif !res.empty?
             output << ">\n#{res}"  <<  "</#{el.value}>"
@@ -205,20 +204,19 @@ module Kramdown
           else
             output << " />"
           end
-          output << "\n" if @stack.last.type != :html_element || @stack.last.options[:parse_type] != :raw
+          output << "\n" if @stack.last.type != :html_element || @stack.last.options[:content_model] != :raw
           output
         end
       end
 
       def convert_xml_comment(el, opts)
-        if el.options[:category] == :block && (@stack.last.type != :html_element || @stack.last.options[:parse_type] != :raw)
+        if el.options[:category] == :block && (@stack.last.type != :html_element || @stack.last.options[:content_model] != :raw)
           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, opts)
         opts[:alignment] = el.options[:alignment]
@@ -257,9 +255,8 @@ module Kramdown
       end
 
       def convert_td(el, opts)
-        inner(el, opts).gsub(/\|/, '\\|')
+        inner(el, opts)
       end
-      alias :convert_th :convert_td
 
       def convert_comment(el, opts)
         if el.options[:category] == :block
@@ -310,7 +307,7 @@ module Kramdown
       end
 
       def convert_footnote(el, opts)
-        @footnotes << [el.options[:name], @doc.parse_infos[:footnotes][el.options[:name]]]
+        @footnotes << [el.options[:name], el.value]
         "[^#{el.options[:name]}]"
       end
 
@@ -381,15 +378,15 @@ module Kramdown
         res = ''
         @footnotes.each do |name, data|
           res << "[^#{name}]:\n"
-          res << inner(data[:content]).chomp.split(/\n/).map {|l| "    #{l}"}.join("\n") + "\n\n"
+          res << inner(data).chomp.split(/\n/).map {|l| "    #{l}"}.join("\n") + "\n\n"
         end
         res
       end
 
       def create_abbrev_defs
-        return '' unless @doc.parse_infos[:abbrev_defs]
+        return '' unless @root.options[:abbrev_defs]
         res = ''
-        @doc.parse_infos[:abbrev_defs].each do |name, text|
+        @root.options[:abbrev_defs].each do |name, text|
           res << "*[#{name}]: #{text}\n"
         end
         res
@@ -415,6 +412,8 @@ module Kramdown
         res.strip.empty? ? nil : "{:#{res}}"
       end
 
+      # :startdoc:
+
     end
 
   end

data/lib/kramdown/converter/latex.rb

@@ -26,24 +26,37 @@ module Kramdown
 
   module Converter
 
-    # Converts a Kramdown::Document to LaTeX. This converter uses ideas from other Markdown-to-LaTeX
-    # converters like Pandoc and Maruku.
+    # Converts an element tree to LaTeX.
+    #
+    # This converter uses ideas from other Markdown-to-LaTeX converters like Pandoc and Maruku.
+    #
+    # You can customize this converter by sub-classing it and overriding the <tt>convert_NAME</tt>
+    # methods. Each such method takes the following parameters:
+    #
+    # [+el+] The element of type +NAME+ to be converted.
+    #
+    # [+opts+] A hash containing processing options that are passed down from parent elements. The
+    #          key <tt>:parent</tt> is always set and contains the parent element as value.
+    #
+    # The return value of such a method has to be a string containing the element +el+ formatted
+    # correctly as LaTeX markup.
     class Latex < Base
 
-      # :stopdoc:
-
-      # Initialize the LaTeX converter with the given Kramdown document +doc+.
-      def initialize(doc)
+      # Initialize the LaTeX converter with the +root+ element and the conversion +options+.
+      def initialize(root, options)
         super
         #TODO: set the footnote counter at the beginning of the document
-        @doc.options[:footnote_nr]
-        @doc.conversion_infos[:packages] = Set.new
+        @options[:footnote_nr]
+        @data[:packages] = Set.new
       end
 
+      # Dispatch the conversion of the element +el+ to a <tt>convert_TYPE</tt> method using the
+      # +type+ of the element.
       def convert(el, opts = {})
         send("convert_#{el.type}", el, opts)
       end
 
+      # Return the converted content of the children of +el+ as a string.
       def inner(el, opts)
         result = ''
         options = opts.dup.merge(:parent => el)
@@ -75,6 +88,8 @@ module Kramdown
         end
       end
 
+      # Helper method used by +convert_p+ to convert a paragraph that only contains a single
+      # <tt>:img</tt> element.
       def convert_standalone_image(el, opts, img)
         attrs = attribute_list(el)
         "\\begin{figure}#{attrs}\n\\begin{center}\n#{img}\n\\end{center}\n\\caption{#{escape(el.children.first.attr['alt'])}}\n\\end{figure}#{attrs}\n"
@@ -85,37 +100,23 @@ module Kramdown
         lang = el.attr['lang']
         if show_whitespace || lang
           result = "\\lstset{showspaces=%s,showtabs=%s}\n" % (show_whitespace ? ['true', 'true'] : ['false', 'false'])
-          result += "\\lstset{language=#{lang}}\n" if lang
-          result += "\\lstset{basicstyle=\\ttfamily\\footnotesize}\\lstset{columns=fixed,frame=tlbr}\n"
+          result << "\\lstset{language=#{lang}}\n" if lang
+          result << "\\lstset{basicstyle=\\ttfamily\\footnotesize}\\lstset{columns=fixed,frame=tlbr}\n"
           attrs = attribute_list(el)
-          "#{result}\\begin{lstlisting}#{attrs}\n#{el.value}\n\\end{lstlisting}#{attrs}\n"
+          result << "\\begin{lstlisting}#{attrs}\n#{el.value}\n\\end{lstlisting}#{attrs}\n"
         else
           "\\begin{verbatim}#{el.value}\\end{verbatim}\n"
         end
       end
 
-      def latex_environment(type, el, text)
-        attrs = attribute_list(el)
-        "\\begin{#{type}}#{attrs}\n#{text.rstrip}\n\\end{#{type}}#{attrs}\n"
-      end
-
       def convert_blockquote(el, opts)
         latex_environment(el.children.size > 1 ? 'quotation' : 'quote', el, inner(el, opts))
       end
 
-      HEADER_TYPES = {
-        1 => 'section',
-        2 => 'subsection',
-        3 => 'subsubsection',
-        4 => 'paragraph',
-        5 => 'subparagraph',
-        6 => 'subparagraph'
-      }
       def convert_header(el, opts)
-        type = HEADER_TYPES[el.options[:level]]
+        type = @options[:latex_headers][el.options[:level] - 1]
         if ((id = el.attr['id']) ||
-            (@doc.options[:auto_ids] && (id = generate_id(el.options[:raw_text])))) &&
-            (@doc.options[:toc_depth] <= 0 || el.options[:level] <= @doc.options[:toc_depth])
+            (@options[:auto_ids] && (id = generate_id(el.options[:raw_text])))) && in_toc?(el)
           "\\hypertarget{#{id}}{}\\#{type}{#{inner(el, opts)}}\\label{#{id}}\n\n"
         else
           "\\#{type}*{#{inner(el, opts)}}\n\n"
@@ -128,8 +129,8 @@ module Kramdown
       end
 
       def convert_ul(el, opts)
-        if !@doc.conversion_infos[:has_toc] && (el.options[:ial][:refs].include?('toc') rescue nil)
-          @doc.conversion_infos[:has_toc] = true
+        if !@data[:has_toc] && (el.options[:ial][:refs].include?('toc') rescue nil)
+          @data[:has_toc] = true
           '\tableofcontents'
         else
           latex_environment(el.type == :ul ? 'itemize' : 'enumerate', el, inner(el, opts))
@@ -159,7 +160,7 @@ module Kramdown
         elsif el.value == 'b'
           "\\emph{#{inner(el, opts)}}"
         else
-          @doc.warnings << "Can't convert HTML element"
+          warning("Can't convert HTML element")
           ''
         end
       end
@@ -169,12 +170,11 @@ module Kramdown
       end
 
       def convert_xml_pi(el, opts)
-        @doc.warnings << "Can't convert XML PI/HTML document type"
+        warning("Can't convert XML PI")
         ''
       end
-      alias :convert_html_doctype :convert_xml_pi
 
-      TABLE_ALIGNMENT_CHAR = {:default => 'l', :left => 'l', :center => 'c', :right => 'r'}
+      TABLE_ALIGNMENT_CHAR = {:default => 'l', :left => 'l', :center => 'c', :right => 'r'} # :nodoc:
 
       def convert_table(el, opts)
         align = el.options[:alignment].map {|a| TABLE_ALIGNMENT_CHAR[a]}.join('|')
@@ -201,7 +201,6 @@ module Kramdown
       def convert_td(el, opts)
         inner(el, opts)
       end
-      alias :convert_th :convert_td
 
       def convert_comment(el, opts)
         el.value.split(/\n/).map {|l| "% #{l}"}.join("\n") + "\n"
@@ -209,7 +208,7 @@ module Kramdown
 
       def convert_br(el, opts)
         res = "\\newline"
-        res += "\n" if (c = opts[:parent].children[opts[:index]+1]) && (c.type != :text || c.value !~ /^\s*\n/)
+        res << "\n" if (c = opts[:parent].children[opts[:index]+1]) && (c.type != :text || c.value !~ /^\s*\n/)
         res
       end
 
@@ -224,13 +223,13 @@ module Kramdown
 
       def convert_img(el, opts)
         if el.attr['src'] =~ /^(https?|ftps?):\/\//
-          @doc.warnings << "Cannot include non-local image"
+          warning("Cannot include non-local image")
           ''
         elsif !el.options.attr['src'].empty?
-          @doc.conversion_infos[:packages] << 'graphicx'
+          @data[:packages] << 'graphicx'
           "\\includegraphics{#{el.attr['src']}}"
         else
-          @doc.warnings << "Cannot include image with empty path"
+          warning("Cannot include image with empty path")
           ''
         end
       end
@@ -240,8 +239,8 @@ module Kramdown
       end
 
       def convert_footnote(el, opts)
-        @doc.conversion_infos[:packages] << 'fancyvrb'
-        "\\footnote{#{inner(@doc.parse_infos[:footnotes][el.options[:name]][:content], opts).rstrip}}"
+        @data[:packages] << 'fancyvrb'
+        "\\footnote{#{inner(el.value, opts).rstrip}}"
       end
 
       def convert_raw(el, opts)
@@ -504,16 +503,16 @@ module Kramdown
         253 => ['\\\'y'],
         254 => ['\thorn', 'wasysym'],
         255 => ['\"y'],
-      }
+      } # :nodoc:
       ENTITY_CONV_TABLE.each {|k,v| ENTITY_CONV_TABLE[k] = v.unshift(v.shift + '{}')}
 
       def convert_entity(el, opts)
         text, package = ENTITY_CONV_TABLE[el.value.code_point]
         if text
-          @doc.conversion_infos[:packages] << package if package
+          @data[:packages] << package if package
           text
         else
-          @doc.warnings << "Couldn't find entity in substitution table!"
+          warning("Couldn't find entity in substitution table!")
           ''
         end
       end
@@ -522,20 +521,20 @@ module Kramdown
         :mdash => '---', :ndash => '--', :hellip => '\ldots{}',
         :laquo_space => '\guillemotleft{}~', :raquo_space => '~\guillemotright{}',
         :laquo => '\guillemotleft{}', :raquo => '\guillemotright{}'
-      }
+      } # :nodoc:
       def convert_typographic_sym(el, opts)
         TYPOGRAPHIC_SYMS[el.value]
       end
 
-      SMART_QUOTE_SYMS = {:lsquo => '`', :rsquo => '\'', :ldquo => '``', :rdquo => '\'\''}
+      SMART_QUOTE_SYMS = {:lsquo => '`', :rsquo => '\'', :ldquo => '``', :rdquo => '\'\''} # :nodoc:
       def convert_smart_quote(el, opts)
         res = SMART_QUOTE_SYMS[el.value]
-        res += "{}" if (nel = opts[:parent].children[opts[:index]+1]) && nel.type == :smart_quote
+        res << "{}" if (nel = opts[:parent].children[opts[:index]+1]) && nel.type == :smart_quote
         res
       end
 
       def convert_math(el, opts)
-        @doc.conversion_infos[:packages] += %w[amssymb amsmath amsthm amsfonts]
+        @data[:packages] += %w[amssymb amsmath amsthm amsfonts]
         if el.options[:category] == :block
           if el.value =~ /\A\s*\\begin\{/
             el.value
@@ -551,6 +550,22 @@ module Kramdown
         el.value
       end
 
+      # Wrap the +text+ inside a LaTeX environment of type +type+. The element +el+ is passed on to
+      # the method #attribute_list -- the resulting string is appended to both the <tt>\\begin</tt>
+      # and the <tt>\\end</tt> lines of the LaTeX environment for easier post-processing of LaTeX
+      # environments.
+      def latex_environment(type, el, text)
+        attrs = attribute_list(el)
+        "\\begin{#{type}}#{attrs}\n#{text.rstrip}\n\\end{#{type}}#{attrs}\n"
+      end
+
+      # Return a LaTeX comment containing all attributes as <tt>key="value"</tt> pairs.
+      def attribute_list(el)
+        attrs = el.attr.map {|k,v| v.nil? ? '' : " #{k}=\"#{v.to_s}\""}.compact.sort.join('')
+        attrs = "   % #{attrs}" if !attrs.empty?
+        attrs
+      end
+
       ESCAPE_MAP = {
         "^"  => "\\^{}",
         "\\" => "\\textbackslash{}",
@@ -558,19 +573,14 @@ module Kramdown
         "|"  => "\\textbar{}",
         "<"  => "\\textless{}",
         ">"  => "\\textgreater{}"
-      }.merge(Hash[*("{}$%&_#".scan(/./).map {|c| [c, "\\#{c}"]}.flatten)])
-      ESCAPE_RE = Regexp.union(*ESCAPE_MAP.collect {|k,v| k})
+      }.merge(Hash[*("{}$%&_#".scan(/./).map {|c| [c, "\\#{c}"]}.flatten)]) # :nodoc:
+      ESCAPE_RE = Regexp.union(*ESCAPE_MAP.collect {|k,v| k}) # :nodoc:
 
+      # Escape the special LaTeX characters in the string +str+.
       def escape(str)
         str.gsub(ESCAPE_RE) {|m| ESCAPE_MAP[m]}
       end
 
-      def attribute_list(el)
-        attrs = el.attr.map {|k,v| v.nil? ? '' : " #{k}=\"#{v.to_s}\""}.compact.sort.join('')
-        attrs = "   % #{attrs}" if !attrs.empty?
-        attrs
-      end
-
     end
 
   end

data/lib/kramdown/document.rb

@@ -52,32 +52,24 @@ module Kramdown
   #   doc = Kramdown::Document.new('This *is* some kramdown text')
   #   puts doc.to_html
   #
-  # The #to_html method is a shortcut for using the Converter::Html class.
+  # The #to_html method is a shortcut for using the Converter::Html class. See #method_missing for
+  # more information.
   #
-  # The second argument to the #new method is an options hash for customizing the behaviour of the
-  # used parser and the converter. See Document#new for more information!
+  # The second argument to the ::new method is an options hash for customizing the behaviour of the
+  # used parser and the converter. See ::new for more information!
   class Document
 
-    # The element tree of the document. It is immediately available after the #new method has been
-    # called.
-    attr_accessor :tree
+    # The root Element of the element tree. It is immediately available after the ::new method has
+    # been called.
+    attr_accessor :root
 
-    # The options hash which holds the options for parsing/converting the Kramdown document. It is
-    # possible that these values get changed during the parsing phase.
+    # The options hash which holds the options for parsing/converting the Kramdown document.
     attr_reader :options
 
     # An array of warning messages. It is filled with warnings during the parsing phase (i.e. in
-    # #new) and the conversion phase.
+    # ::new) and the conversion phase.
     attr_reader :warnings
 
-    # Holds needed parse information which is dependent on the used parser, like ALDs, link
-    # definitions and so on. This information may be used by converters afterwards.
-    attr_reader :parse_infos
-
-    # Holds conversion information which is dependent on the used converter. A converter clears this
-    # variable before doing the conversion.
-    attr_reader :conversion_infos
-
 
     # Create a new Kramdown document from the string +source+ and use the provided +options+. The
     # options that can be used are defined in the Options module.
@@ -87,18 +79,14 @@ module Kramdown
     # select the kramdown parser, one would set the <tt>:input</tt> key to +Kramdown+. If this key
     # is not set, it defaults to +Kramdown+.
     #
-    # The +source+ is immediately parsed by the selected parser so that the document tree is
+    # The +source+ is immediately parsed by the selected parser so that the root element is
     # immediately available and the output can be generated.
     def initialize(source, options = {})
-      @options = Options.merge(options)
-      @warnings = []
-      @parse_infos = {}
-      @parse_infos[:encoding] = source.encoding if RUBY_VERSION >= '1.9'
-      @conversion_infos = {}
+      @options = Options.merge(options).freeze
       parser = (options[:input] || 'kramdown').to_s
       parser = parser[0..0].upcase + parser[1..-1]
       if Parser.const_defined?(parser)
-        @tree = Parser.const_get(parser).parse(source, self)
+        @root, @warnings = Parser.const_get(parser).parse(source, @options)
       else
         raise Kramdown::Error.new("kramdown has no parser to handle the specified input format: #{options[:input]}")
       end
@@ -109,24 +97,468 @@ module Kramdown
     #
     # For example, +to_html+ would instantiate the Kramdown::Converter::Html class.
     def method_missing(id, *attr, &block)
-      if id.to_s =~ /^to_(\w+)$/
-        Converter.const_get($1[0..0].upcase + $1[1..-1]).convert(self)
+      if id.to_s =~ /^to_(\w+)$/ && (name = $1[0..0].upcase + $1[1..-1]) && Converter.const_defined?(name)
+        output, warnings = Converter.const_get(name).convert(@root, @options)
+        @warnings.concat(warnings)
+        output
       else
         super
       end
     end
 
     def inspect #:nodoc:
-      "<KD:Document: options=#{@options.inspect} tree=#{@tree.inspect} warnings=#{@warnings.inspect}>"
+      "<KD:Document: options=#{@options.inspect} root=#{@root.inspect} warnings=#{@warnings.inspect}>"
     end
 
   end
 
 
-  # Represents all elements in the parse tree.
+  # Represents all elements in the element tree.
   #
-  # kramdown only uses this one class for representing all available elements in a parse tree
+  # kramdown only uses this one class for representing all available elements in an element tree
   # (paragraphs, headers, emphasis, ...). The type of element can be set via the #type accessor.
+  #
+  # Following is a description of all supported element types.
+  #
+  # == Structural Elements
+  #
+  # === :root
+  #
+  # [Category] None
+  # [Usage context] As the root element of a document
+  # [Content model] Block-level elements
+  #
+  # Represents the root of a kramdown document.
+  #
+  # The root element contains the following option keys:
+  #
+  # <tt>:encoding</tt>:: When running on Ruby 1.9 this key has to be set to the encoding used for
+  #                      the text parts of the kramdown document.
+  #
+  # <tt>:abbrev_defs</tt>:: This key may be used to store the mapping of abbreviation to
+  #                         abbreviation definition.
+  #
+  #
+  # === :blank
+  #
+  # [Category] Block-level element
+  # [Usage context] Where block-level elements are expected
+  # [Content model] Empty
+  #
+  # Represents one or more blank lines. It is not allowed to have two or more consecutive blank
+  # elements.
+  #
+  # The +value+ field may contain the original content of the blank lines.
+  #
+  #
+  # === :p
+  #
+  # [Category] Block-level element
+  # [Usage context] Where block-level elements are expected
+  # [Content model] Span-level elements
+  #
+  # Represents a paragraph.
+  #
+  # If the option <tt>:transparent</tt> is +true+, this element just represents a block of text.
+  # I.e. this element just functions as a container for span-level elements.
+  #
+  #
+  # === :header
+  #
+  # [Category] Block-level element
+  # [Usage context] Where block-level elements are expected
+  # [Content model] Span-level elements
+  #
+  # Represents a header.
+  #
+  # The option <tt>:level</tt> specifies the header level and has to contain a number between 1 and
+  # \6. The option <tt>:raw_text</tt> has to contain the raw header text.
+  #
+  #
+  # === :blockquote
+  #
+  # [Category] Block-level element
+  # [Usage context] Where block-level elements are expected
+  # [Content model] Block-level elements
+  #
+  # Represents a blockquote.
+  #
+  #
+  # === :codeblock
+  #
+  # [Category] Block-level element
+  # [Usage context] Where block-level elements are expected
+  # [Content model] Empty
+  #
+  # Represents a code block, i.e. a block of text that should be used as-is.
+  #
+  # The +value+ field has to contain the content of the code block.
+  #
+  #
+  # === :ul
+  #
+  # [Category] Block-level element
+  # [Usage context] Where block-level elements are expected
+  # [Content model] One or more :li elements
+  #
+  # Represents an unordered list.
+  #
+  #
+  # === :ol
+  #
+  # [Category] Block-level element
+  # [Usage context] Where block-level elements are expected
+  # [Content model] One or more :li elements
+  #
+  # Represents an ordered list.
+  #
+  #
+  # === :li
+  #
+  # [Category] None
+  # [Usage context] Inside :ol and :ul elements
+  # [Content model] Block-level elements
+  #
+  # Represents a list item of an ordered or unordered list.
+  #
+  #
+  # === :dl
+  #
+  # [Category] Block-level element
+  # [Usage context] Where block-level elements are expected
+  # [Content model] One or more groups each consisting of one or more :dt elements followed by one
+  #                 or more :dd elements.
+  #
+  # Represents a definition list which contains groups consisting of terms and definitions for them.
+  #
+  #
+  # === :dt
+  #
+  # [Category] None
+  # [Usage context] Before :dt or :dd elements inside a :dl elment
+  # [Content model] Span-level elements
+  #
+  # Represents the term part of a term-definition group in a definition list.
+  #
+  #
+  # === :dd
+  #
+  # [Category] None
+  # [Usage context] After :dt or :dd elements inside a :dl elment
+  # [Content model] Block-level elements
+  #
+  # Represents the definition part of a term-definition group in a definition list.
+  #
+  #
+  # === :hr
+  #
+  # [Category] Block-level element
+  # [Usage context] Where block-level elements are expected
+  # [Content model] None
+  #
+  # Represents a horizontal line.
+  #
+  #
+  # === :table
+  #
+  # [Category] Block-level element
+  # [Usage context] Where block-level elements are expected
+  # [Content model] Zero or one :thead elements, one or more :tbody elements, zero or one :tfoot
+  #                 elements
+  #
+  # Represents a table. Each table row (i.e. :tr element) of the table has to contain the same
+  # number of :td elements.
+  #
+  # The option <tt>:alignment</tt> has to be an array containing the alignment values, exactly one
+  # for each column of the table. The possible alignment values are <tt>:left</tt>,
+  # <tt>:center</tt>, <tt>:right</tt> and <tt>:default</tt>.
+  #
+  #
+  # === :thead
+  #
+  # [Category] None
+  # [Usage context] As first element inside a :table element
+  # [Content model] One or more :tr elements
+  #
+  # Represents the table header.
+  #
+  #
+  # === :tbody
+  #
+  # [Category] None
+  # [Usage context] After a :thead element but before a :tfoot element inside a :table element
+  # [Content model] One or more :tr elements
+  #
+  # Represents a table body.
+  #
+  #
+  # === :tfoot
+  #
+  # [Category] None
+  # [Usage context] As last element inside a :table element
+  # [Content model] One or more :tr elements
+  #
+  # Represents the table footer.
+  #
+  #
+  # === :tr
+  #
+  # [Category] None
+  # [Usage context] Inside :thead, :tbody and :tfoot elements
+  # [Content model] One or more :td elements
+  #
+  # Represents a table row.
+  #
+  #
+  # === :td
+  #
+  # [Category] None
+  # [Usage context] Inside :tr elements
+  # [Content model] As child of :thead/:tr span-level elements, as child of :tbody/:tr and
+  #                 :tfoot/:tr block-level elements
+  #
+  # Represents a table cell.
+  #
+  #
+  # === :math
+  #
+  # [Category] Block/span-level element
+  # [Usage context] Where block/span-level elements are expected
+  # [Content model] None
+  #
+  # Represents mathematical text that is written in LaTeX.
+  #
+  # The +value+ field has to contain the actual mathematical text.
+  #
+  # The option <tt>:category</tt> has to be set to either <tt>:span</tt> or <tt>:block</tt>
+  # depending on the context where the element is used.
+  #
+  #
+  # == Text Markup Elements
+  #
+  # === :text
+  #
+  # [Category] Span-level element
+  # [Usage context] Where span-level elements are expected
+  # [Content model] None
+  #
+  # Represents text.
+  #
+  # The +value+ field has to contain the text itself.
+  #
+  #
+  # === :br
+  #
+  # [Category] Span-level element
+  # [Usage context] Where span-level elements are expected
+  # [Content model] None
+  #
+  # Represents a hard line break.
+  #
+  #
+  # === :a
+  #
+  # [Category] Span-level element
+  # [Usage context] Where span-level elements are expected
+  # [Content model] Span-level elements
+  #
+  # Represents a link to an URL.
+  #
+  # The attribute +href+ has to be set to the URL to which the link points. The attribute +title+
+  # optionally contains the title of the link.
+  #
+  #
+  # === :img
+  #
+  # [Category] Span-level element
+  # [Usage context] Where span-level elements are expected
+  # [Content model] None
+  #
+  # Represents an image.
+  #
+  # The attribute +src+ has to be set to the URL of the image. The attribute +alt+ has to contain a
+  # text description of the image. The attribute +title+ optionally contains the title of the image.
+  #
+  #
+  # === :codespan
+  #
+  # [Category] Span-level element
+  # [Usage context] Where span-level elements are expected
+  # [Content model] None
+  #
+  # Represents verbatim text.
+  #
+  # The +value+ field has to contain the content of the code span.
+  #
+  #
+  # === :footnote
+  #
+  # [Category] Span-level element
+  # [Usage context] Where span-level elements are expected
+  # [Content model] None
+  #
+  # Represents a footnote marker.
+  #
+  # The +value+ field has to contain an element whose children are the content of the footnote. The
+  # option <tt>:name</tt> has to contain a valid and unique footnote name. A valid footnote name
+  # consists of a word character or a digit and then optionally followed by other word characters,
+  # digits or dashes.
+  #
+  #
+  # === :em
+  #
+  # [Category] Span-level element
+  # [Usage context] Where span-level elements are expected
+  # [Content model] Span-level elements
+  #
+  # Represents emphasis of its contents.
+  #
+  #
+  # === :strong
+  #
+  # [Category] Span-level element
+  # [Usage context] Where span-level elements are expected
+  # [Content model] Span-level elements
+  #
+  # Represents strong importance for its contents.
+  #
+  #
+  # === :entity
+  #
+  # [Category] Span-level element
+  # [Usage context] Where span-level elements are expected
+  # [Content model] None
+  #
+  # Represents an HTML entity.
+  #
+  # The +value+ field has to contain an instance of Kramdown::Utils::Entities::Entity. The option
+  # <tt>:original</tt> can be used to store the original representation of the entity.
+  #
+  #
+  # === :typographic_sym
+  #
+  # [Category] Span-level element
+  # [Usage context] Where span-level elements are expected
+  # [Content model] None
+  #
+  # Represents a typographic symbol.
+  #
+  # The +value+ field needs to contain a Symbol representing the specific typographic symbol from
+  # the following list:
+  #
+  # <tt>:mdash</tt>:: An mdash character (---)
+  # <tt>:ndash</tt>:: An ndash character (--)
+  # <tt>:hellip</tt>:: An ellipsis (...)
+  # <tt>:laquo</tt>:: A left guillemet (<<)
+  # <tt>:raquo</tt>:: A right guillemet (>>)
+  # <tt>:laquo_space</tt>:: A left guillemet with a space (<< )
+  # <tt>:raquo_space</tt>:: A right guillemet with a space ( >>)
+  #
+  #
+  # === :smart_quote
+  #
+  # [Category] Span-level element
+  # [Usage context] Where span-level elements are expected
+  # [Content model] None
+  #
+  # Represents a quotation character.
+  #
+  # The +value+ field needs to contain a Symbol representing the specific quotation character:
+  #
+  # <tt>:lsquo</tt>:: Left single quote
+  # <tt>:rsquo</tt>:: Right single quote
+  # <tt>:ldquo</tt>:: Left double quote
+  # <tt>:rdquo</tt>:: Right double quote
+  #
+  #
+  # === :abbreviation
+  #
+  # [Category] Span-level element
+  # [Usage context] Where span-level elements are expected
+  # [Content model] None
+  #
+  # Represents a text part that is an abbreviation.
+  #
+  # The +value+ field has to contain the text part that is the abbreviation. The definition of the
+  # abbreviation is stored in the <tt>:root</tt> element of the document.
+  #
+  #
+  # == Other Elements
+  #
+  # === :html_element
+  #
+  # [Category] Block/span-level element
+  # [Usage context] Where block/span-level elements or raw HTML elements are expected
+  # [Content model] Depends on the element
+  #
+  # Represents an HTML element.
+  #
+  # The +value+ field has to contain the name of the HTML element the element is representing.
+  #
+  # The option <tt>:category</tt> has to be set to either <tt>:span</tt> or <tt>:block</tt>
+  # depending on the whether the element is a block-level or a span-level element. The option
+  # <tt>:content_model</tt> has to be set to the content model for the element (either
+  # <tt>:block</tt> if it contains block-level elements, <tt>:span</tt> if it contains span-level
+  # elements or <tt>:raw</tt> if it contains raw content).
+  #
+  #
+  # === :xml_comment
+  #
+  # [Category] Block/span-level element
+  # [Usage context] Where block/span-level elements are expected or in raw HTML elements
+  # [Content model] None
+  #
+  # Represents an XML/HTML comment.
+  #
+  # The +value+ field has to contain the whole XML/HTML comment including the delimiters.
+  #
+  # The option <tt>:category</tt> has to be set to either <tt>:span</tt> or <tt>:block</tt>
+  # depending on the context where the element is used.
+  #
+  #
+  # === :xml_pi
+  #
+  # [Category] Block/span-level element
+  # [Usage context] Where block/span-level elements are expected or in raw HTML elements
+  # [Content model] None
+  #
+  # Represents an XML/HTML processing instruction.
+  #
+  # The +value+ field has to contain the whole XML/HTML processing instruction including the
+  # delimiters.
+  #
+  # The option <tt>:category</tt> has to be set to either <tt>:span</tt> or <tt>:block</tt>
+  # depending on the context where the element is used.
+  #
+  #
+  # === :comment
+  #
+  # [Category] Block/span-level element
+  # [Usage context] Where block/span-level elements are expected
+  # [Content model] None
+  #
+  # Represents a comment.
+  #
+  # The +value+ field has to contain the comment.
+  #
+  # The option <tt>:category</tt> has to be set to either <tt>:span</tt> or <tt>:block</tt>
+  # depending on the context where the element is used.
+  #
+  #
+  # === :raw
+  #
+  # [Category] Block/span-level element
+  # [Usage context] Where block/span-level elements are expected
+  # [Content model] None
+  #
+  # Represents a raw string that should not be modified. For example, the element could contain some
+  # HTML code that should be output as-is without modification and escaping.
+  #
+  # The +value+ field has to contain the actual raw text.
+  #
+  # The option <tt>:category</tt> has to be set to either <tt>:span</tt> or <tt>:block</tt>
+  # depending on the context where the element is used. The option <tt>:type</tt> can be set to an
+  # array of strings to define for which converters the raw string is valid.
   class Element
 
     # A symbol representing the element type. For example, <tt>:p</tt> or <tt>:blockquote</tt>.
@@ -136,32 +568,45 @@ module Kramdown
     # Many elements don't use this field.
     attr_accessor :value
 
-    # The attributes of the element. Uses an Utils::OrderedHash to retain the insertion order.
-    attr_reader :attr
-
-    # The options hash for the element. It is used for storing arbitray options as well as the
-    # following special contents:
-    #
-    # - Category of the element, either <tt>:block</tt> or <tt>:span</tt>, under the
-    #   <tt>:category</tt> key. If this key is absent, it can be assumed that the element is in the
-    #   <tt>:span</tt> category.
-    attr_accessor :options
-
     # The child elements of this element.
     attr_accessor :children
 
 
     # Create a new Element object of type +type+. The optional parameters +value+, +attr+ and
     # +options+ can also be set in this constructor for convenience.
-    def initialize(type, value = nil, attr = nil, options = {})
-      @type, @value, @attr, @options = type, value, Utils::OrderedHash.new(attr), options
+    def initialize(type, value = nil, attr = nil, options = nil)
+      @type, @value, @attr, @options = type, value, (Utils::OrderedHash.new.merge!(attr) if attr), options
       @children = []
     end
 
+    # The attributes of the element. Uses an Utils::OrderedHash to retain the insertion order.
+    def attr
+      @attr ||= Utils::OrderedHash.new
+    end
+
+    # The options hash for the element. It is used for storing arbitray options.
+    def options
+      @options ||= {}
+    end
+
     def inspect #:nodoc:
       "<kd:#{@type}#{@value.nil? ? '' : ' ' + @value.inspect} #{@attr.inspect}#{options.empty? ? '' : ' ' + @options.inspect}#{@children.empty? ? '' : ' ' + @children.inspect}>"
     end
 
+    CATEGORY = {} # :nodoc:
+    [:blank, :p, :header, :blockquote, :codeblock, :ul, :ol, :dl, :table, :hr].each {|b| CATEGORY[b] = :block}
+    [:text, :a, :br, :img, :codespan, :footnote, :em, :strong, :entity, :typographic_sym,
+     :smart_quote, :abbreviation].each {|b| CATEGORY[b] = :span}
+
+    # Return the category of +el+ which can be <tt>:block</tt>, <tt>:span</tt> or +nil+.
+    #
+    # Most elements have a fixed category, however, some elements can either appear in a block-level
+    # or a span-level context. These elements need to have the option <tt>:category</tt> correctly
+    # set.
+    def self.category(el)
+      CATEGORY[el.type] || el.options[:category]
+    end
+
   end
 
 end