daqing_kramdown 2.3.1

data/lib/kramdown/converter/syntax_highlighter/rouge.rb

@@ -0,0 +1,85 @@
+# -*- coding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# Copyright (C) 2009-2019 Thomas Leitner <t_leitner@gmx.at>
+#
+# This file is part of kramdown which is licensed under the MIT.
+#++
+#
+
+module Kramdown::Converter::SyntaxHighlighter
+
+  # Uses Rouge which is CSS-compatible to Pygments to highlight code blocks and code spans.
+  module Rouge
+
+    begin
+      require 'rouge'
+
+      # Highlighting via Rouge is available if this constant is +true+.
+      AVAILABLE = true
+    rescue LoadError, SyntaxError
+      AVAILABLE = false # :nodoc:
+    end
+
+    def self.call(converter, text, lang, type, call_opts)
+      opts = options(converter, type)
+      call_opts[:default_lang] = opts[:default_lang]
+      return nil unless lang || opts[:default_lang] || opts[:guess_lang]
+
+      lexer = ::Rouge::Lexer.find_fancy(lang || opts[:default_lang], text)
+      return nil if opts[:disable] || !lexer || (lexer.tag == "plaintext" && !opts[:guess_lang])
+
+      opts[:css_class] ||= 'highlight' # For backward compatibility when using Rouge 2.0
+      formatter = formatter_class(opts).new(opts)
+      formatter.format(lexer.lex(text))
+    end
+
+    def self.options(converter, type)
+      prepare_options(converter)
+      converter.data[:syntax_highlighter_rouge][type]
+    end
+
+    def self.prepare_options(converter)
+      return if converter.data.key?(:syntax_highlighter_rouge)
+
+      cache = converter.data[:syntax_highlighter_rouge] = {}
+
+      opts = converter.options[:syntax_highlighter_opts].dup
+
+      span_opts = opts.delete(:span)&.dup || {}
+      block_opts = opts.delete(:block)&.dup || {}
+      normalize_keys(span_opts)
+      normalize_keys(block_opts)
+
+      cache[:span] = opts.merge(span_opts)
+      cache[:span][:wrap] = false
+
+      cache[:block] = opts.merge(block_opts)
+    end
+
+    def self.normalize_keys(hash)
+      return if hash.empty?
+
+      hash.keys.each do |k|
+        hash[k.kind_of?(String) ? Kramdown::Options.str_to_sym(k) : k] = hash.delete(k)
+      end
+    end
+
+    def self.formatter_class(opts = {})
+      case formatter = opts[:formatter]
+      when Class
+        formatter
+      when /\A[[:upper:]][[:alnum:]_]*\z/
+        ::Rouge::Formatters.const_get(formatter)
+      else
+        # Available in Rouge 2.0 or later
+        ::Rouge::Formatters::HTMLLegacy
+      end
+    rescue NameError
+      # Fallback to Rouge 1.x
+      ::Rouge::Formatters::HTML
+    end
+
+  end
+
+end

data/lib/kramdown/converter/toc.rb

@@ -0,0 +1,69 @@
+# -*- coding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# Copyright (C) 2009-2019 Thomas Leitner <t_leitner@gmx.at>
+#
+# This file is part of kramdown which is licensed under the MIT.
+#++
+#
+
+require 'kramdown/converter'
+
+module Kramdown
+
+  module Converter
+
+    # Converts a Kramdown::Document to an element tree that represents the table of contents.
+    #
+    # The returned tree consists of Element objects of type :toc where the root element is just used
+    # as container object. Each :toc element contains as value the wrapped :header element and under
+    # the attribute key :id the header ID that should be used (note that this ID may not exist in
+    # the wrapped element).
+    #
+    # Since the TOC tree consists of special :toc elements, one cannot directly feed this tree to
+    # other converters!
+    class Toc < Base
+
+      def initialize(root, options)
+        super
+        @toc = Element.new(:toc)
+        @stack = []
+        @options[:template] = ''
+      end
+
+      def convert(el)
+        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']) if attr['id']
+        else
+          el.children.each {|child| convert(child) }
+        end
+        @toc
+      end
+
+      private
+
+      def add_to_toc(el, id)
+        toc_element = Element.new(:toc, el, id: id)
+
+        success = false
+        until success
+          if @stack.empty?
+            @toc.children << toc_element
+            @stack << toc_element
+            success = true
+          elsif @stack.last.value.options[:level] < el.options[:level]
+            @stack.last.children << toc_element
+            @stack << toc_element
+            success = true
+          else
+            @stack.pop
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/kramdown/document.rb

@@ -0,0 +1,139 @@
+# -*- coding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# Copyright (C) 2009-2019 Thomas Leitner <t_leitner@gmx.at>
+#
+# This file is part of kramdown which is licensed under the MIT.
+#++
+#
+# = kramdown
+#
+# kramdown is fast, pure Ruby Markdown superset converter, using a strict syntax definition and
+# supporting several common extensions.
+#
+# The kramdown library is mainly written to support the kramdown-to-HTML conversion chain. However,
+# due to its flexibility it supports other input and output formats as well. Here is a list of the
+# supported formats:
+#
+# * input formats: kramdown (a Markdown superset), Markdown, GFM, HTML
+# * output formats: HTML, kramdown, LaTeX (and therefore PDF), PDF via Prawn
+#
+# All the documentation on the available input and output formats is available at
+# http://kramdown.gettalong.org.
+#
+# == Usage
+#
+# kramdown has a simple API, so using kramdown is as easy as
+#
+#     require 'kramdown'
+#
+#     Kramdown::Document.new(text).to_html
+#
+# For detailed information have a look at the *\Kramdown::Document* class.
+#
+# == License
+#
+# MIT - see the COPYING file.
+
+require 'kramdown/version'
+require 'kramdown/element'
+require 'kramdown/error'
+require 'kramdown/parser'
+require 'kramdown/converter'
+require 'kramdown/options'
+require 'kramdown/utils'
+
+module Kramdown
+
+  # Return the data directory for kramdown.
+  def self.data_dir
+    unless defined?(@data_dir)
+      require 'rbconfig'
+      @data_dir = File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'data', 'kramdown'))
+      @data_dir = File.expand_path(File.join(RbConfig::CONFIG["datadir"], "kramdown")) unless File.exist?(@data_dir)
+      raise "kramdown data directory not found! This is a bug, please report it!" unless File.directory?(@data_dir)
+    end
+    @data_dir
+  end
+
+  # The main interface to kramdown.
+  #
+  # This class provides a one-stop-shop for using kramdown to convert text into various output
+  # formats. Use it like this:
+  #
+  #   require '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. 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 ::new for more information!
+  class Document
+
+    # 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.
+    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.
+    attr_reader :warnings
+
+    # 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.
+    #
+    # The special options key :input can be used to select the parser that should parse the
+    # +source+. It has to be the name of a class in the Kramdown::Parser module. For example, to
+    # select the kramdown parser, one would set the :input 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 root element is
+    # immediately available and the output can be generated.
+    def initialize(source, options = {})
+      @options = Options.merge(options).freeze
+      parser = (@options[:input] || 'kramdown').to_s
+      parser = parser[0..0].upcase + parser[1..-1]
+      try_require('parser', parser)
+      if Parser.const_defined?(parser)
+        @root, @warnings = Parser.const_get(parser).parse(source, @options)
+      else
+        raise Kramdown::Error, "kramdown has no parser to handle the specified " \
+          "input format: #{@options[:input]}"
+      end
+    end
+
+    # Check if a method is invoked that begins with +to_+ and if so, try to instantiate a converter
+    # class (i.e. a class in the Kramdown::Converter module) and use it for converting the document.
+    #
+    # For example, +to_html+ would instantiate the Kramdown::Converter::Html class.
+    def method_missing(id, *attr, &block)
+      if id.to_s =~ /^to_(\w+)$/ && (name = Utils.camelize($1)) &&
+          try_require('converter', name) && 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} root=#{@root.inspect} warnings=#{@warnings.inspect}>"
+    end
+
+    # Try requiring a parser or converter class and don't raise an error if the file is not found.
+    def try_require(type, name)
+      require("kramdown/#{type}/#{Utils.snake_case(name)}")
+      true
+    rescue LoadError
+      true
+    end
+    protected :try_require
+
+  end
+
+end

data/lib/kramdown/element.rb

@@ -0,0 +1,551 @@
+# -*- coding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# Copyright (C) 2009-2019 Thomas Leitner <t_leitner@gmx.at>
+#
+# This file is part of kramdown which is licensed under the MIT.
+#++
+#
+
+module Kramdown
+
+  # Represents all elements in the element 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.
+  #
+  # The root of a kramdown element tree has to be an element of type :root. It needs to have certain
+  # option keys set so that conversions work correctly. If only a part of a tree should be
+  # converted, duplicate the root node and assign the #children appropriately, e.g:
+  #
+  #   root = doc.root
+  #   new_root = root.dup
+  #   new_root.children = [root.children[0]]  # assign new array with elements to convert
+  #
+  # Following is a description of all supported element types.
+  #
+  # Note that the option :location may contain the start line number of an element in the source
+  # document.
+  #
+  # == 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:
+  #
+  # :encoding:: When running on Ruby 1.9 this key has to be set to the encoding used for the text
+  #             parts of the kramdown document.
+  #
+  # :abbrev_defs:: This key may be used to store the mapping of abbreviation to abbreviation
+  #                definition.
+  #
+  # :abbrev_attr:: This key may be used to store the mapping of abbreviation to abbreviation
+  #                attributes.
+  #
+  # :options:: This key may be used to store options that were set during parsing of the document.
+  #
+  # :footnote_count:: This key stores the number of actually referenced footnotes of the document.
+  #
+  # === :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 :transparent 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 :level specifies the header level and has to contain a number between 1 and \6. The
+  # option :raw_text 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.
+  #
+  # The option :lang specifies a highlighting language with possible HTML style options (e.g.
+  # php?start_inline=1) and should be used instead of a possibly also available language embedded in
+  # a class name of the form 'language-LANG'.
+  #
+  #
+  # === :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] Block-level element
+  # [Usage context] Inside :ol and :ul elements
+  # [Content model] Block-level elements
+  #
+  # Represents a list item of an ordered or unordered list.
+  #
+  # Note that the first child of a list item must not be a :blank element!
+  #
+  #
+  # === :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] Block-level element
+  # [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] Block-level element
+  # [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 :alignment has to be an array containing the alignment values, exactly one for each
+  # column of the table. The possible alignment values are :left, :center, :right and :default.
+  #
+  #
+  # === :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] Block-level element
+  # [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 :category has to be set to either :span or :block 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 :name 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
+  # :original 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:
+  #
+  # :mdash:: An mdash character (---)
+  # :ndash:: An ndash character (--)
+  # :hellip:: An ellipsis (...)
+  # :laquo:: A left guillemet (<<)
+  # :raquo:: A right guillemet (>>)
+  # :laquo_space:: A left guillemet with a space (<< )
+  # :raquo_space:: 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:
+  #
+  # :lsquo:: Left single quote
+  # :rsquo:: Right single quote
+  # :ldquo:: Left double quote
+  # :rdquo:: 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 :root 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 :category has to be set to either :span or :block depending on the whether the
+  # element is a block-level or a span-level element. The option :content_model has to be set to the
+  # content model for the element (either :block if it contains block-level elements, :span if it
+  # contains span-level elements or :raw 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 :category has to be set to either :span or :block 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 :category has to be set to either :span or :block 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 :category has to be set to either :span or :block depending on the context where the
+  # element is used. If it is set to :span, then no blank lines are allowed in the comment.
+  #
+  #
+  # === :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 :category has to be set to either :span or :block depending on the context where the
+  # element is used. If it is set to :span, then no blank lines are allowed in the raw text.
+  #
+  # The option :type 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, :p or :blockquote.
+    attr_accessor :type
+
+    # The value of the element. The interpretation of this field depends on the type of the element.
+    # Many elements don't use this field.
+    attr_accessor :value
+
+    # 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 = nil)
+      @type, @value, @attr, @options = type, value, attr, options
+      @children = []
+    end
+
+    # The attributes of the element.
+    def attr
+      @attr ||= {}
+    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=' + value.inspect}" \
+        "#{attr.empty? ? '' : ' attr=' + attr.inspect}" \
+        "#{options.empty? ? '' : ' options=' + options.inspect}" \
+        "#{children.empty? ? '' : ' children=' + children.inspect}>"
+    end
+
+    CATEGORY = {} # :nodoc:
+    [:blank, :p, :header, :blockquote, :codeblock, :ul, :ol, :li, :dl, :dt, :dd,
+     :table, :td, :hr].each {|b| CATEGORY[b] = :block }
+    [:text, :a, :auto_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 :block, :span 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 :category correctly set.
+    def self.category(el)
+      CATEGORY[el.type] || el.options[:category]
+    end
+
+    # syntactic sugar to simplify calls such as +Kramdown::Element.category(el) == :block+ with
+    # +el.block?+.
+    #
+    # Returns boolean true or false.
+    def block?
+      (CATEGORY[type] || options[:category]) == :block
+    end
+
+    # syntactic sugar to simplify calls such as +Kramdown::Element.category(el) == :span+ with
+    # +el.span?+.
+    #
+    # Returns boolean true or false.
+    def span?
+      (CATEGORY[type] || options[:category]) == :span
+    end
+
+  end
+
+end