RubyGems - rdoc - Versions diffs - 3.12.2 → 4.0.0.preview2 - Mend

rdoc 3.12.2 → 4.0.0.preview2

Potentially problematic release.

This version of rdoc might be problematic. Click here for more details.

Files changed (200) hide show

checksums.yaml +6 -6
checksums.yaml.gz.sig +0 -0
data.tar.gz.sig +0 -0
data/.autotest +3 -2
data/DEVELOPERS.rdoc +53 -0
data/History.rdoc +159 -25
data/LEGAL.rdoc +12 -0
data/Manifest.txt +56 -3
data/README.rdoc +87 -19
data/Rakefile +11 -2
data/TODO.rdoc +20 -13
data/bin/rdoc +4 -0
data/lib/gauntlet_rdoc.rb +1 -1
data/lib/rdoc.rb +32 -71
data/lib/rdoc/any_method.rb +75 -21
data/lib/rdoc/attr.rb +49 -10
data/lib/rdoc/class_module.rb +182 -32
data/lib/rdoc/code_object.rb +54 -12
data/lib/rdoc/comment.rb +8 -1
data/lib/rdoc/constant.rb +100 -6
data/lib/rdoc/context.rb +93 -41
data/lib/rdoc/context/section.rb +143 -28
data/lib/rdoc/cross_reference.rb +58 -50
data/lib/rdoc/encoding.rb +34 -29
data/lib/rdoc/erb_partial.rb +18 -0
data/lib/rdoc/extend.rb +117 -0
data/lib/rdoc/generator.rb +11 -6
data/lib/rdoc/generator/darkfish.rb +250 -62
data/lib/rdoc/generator/json_index.rb +20 -12
data/lib/rdoc/generator/markup.rb +10 -12
data/lib/rdoc/generator/ri.rb +7 -60
data/lib/rdoc/generator/template/darkfish/_head.rhtml +7 -7
data/lib/rdoc/generator/template/darkfish/_sidebar_extends.rhtml +16 -0
data/lib/rdoc/generator/template/darkfish/_sidebar_in_files.rhtml +1 -1
data/lib/rdoc/generator/template/darkfish/_sidebar_installed.rhtml +14 -0
data/lib/rdoc/generator/template/darkfish/_sidebar_methods.rhtml +1 -1
data/lib/rdoc/generator/template/darkfish/_sidebar_table_of_contents.rhtml +13 -0
data/lib/rdoc/generator/template/darkfish/class.rhtml +15 -1
data/lib/rdoc/generator/template/darkfish/images/arrow_up.png +0 -0
data/lib/rdoc/generator/template/darkfish/index.rhtml +3 -3
data/lib/rdoc/generator/template/darkfish/js/darkfish.js +7 -9
data/lib/rdoc/generator/template/darkfish/page.rhtml +2 -0
data/lib/rdoc/generator/template/darkfish/rdoc.css +31 -0
data/lib/rdoc/generator/template/darkfish/servlet_not_found.rhtml +18 -0
data/lib/rdoc/generator/template/darkfish/servlet_root.rhtml +37 -0
data/lib/rdoc/generator/template/darkfish/table_of_contents.rhtml +3 -3
data/lib/rdoc/include.rb +12 -3
data/lib/rdoc/markdown.kpeg +1186 -0
data/lib/rdoc/markdown.rb +16336 -0
data/lib/rdoc/markdown/entities.rb +2128 -0
data/lib/rdoc/markdown/literals_1_8.kpeg +18 -0
data/lib/rdoc/markdown/literals_1_8.rb +454 -0
data/lib/rdoc/markdown/literals_1_9.kpeg +22 -0
data/lib/rdoc/markdown/literals_1_9.rb +417 -0
data/lib/rdoc/markup.rb +69 -10
data/lib/rdoc/markup/attr_changer.rb +2 -5
data/lib/rdoc/markup/attribute_manager.rb +23 -14
data/lib/rdoc/markup/attributes.rb +70 -0
data/lib/rdoc/markup/block_quote.rb +14 -0
data/lib/rdoc/markup/document.rb +20 -4
data/lib/rdoc/markup/formatter.rb +17 -6
data/lib/rdoc/markup/formatter_test_case.rb +93 -24
data/lib/rdoc/markup/hard_break.rb +31 -0
data/lib/rdoc/markup/heading.rb +1 -1
data/lib/rdoc/markup/indented_paragraph.rb +14 -0
data/lib/rdoc/markup/list.rb +23 -4
data/lib/rdoc/markup/list_item.rb +17 -4
data/lib/rdoc/markup/paragraph.rb +14 -0
data/lib/rdoc/markup/parser.rb +107 -60
data/lib/rdoc/markup/raw.rb +4 -4
data/lib/rdoc/markup/special.rb +3 -3
data/lib/rdoc/markup/to_ansi.rb +7 -1
data/lib/rdoc/markup/to_html.rb +42 -14
data/lib/rdoc/markup/to_html_crossref.rb +10 -9
data/lib/rdoc/markup/to_html_snippet.rb +20 -4
data/lib/rdoc/markup/to_joined_paragraph.rb +68 -0
data/lib/rdoc/markup/to_label.rb +20 -1
data/lib/rdoc/markup/to_markdown.rb +134 -0
data/lib/rdoc/markup/to_rdoc.rb +36 -5
data/lib/rdoc/markup/to_table_of_contents.rb +6 -1
data/lib/rdoc/markup/to_tt_only.rb +11 -2
data/lib/rdoc/markup/verbatim.rb +19 -0
data/lib/rdoc/method_attr.rb +33 -19
data/lib/rdoc/normal_class.rb +26 -7
data/lib/rdoc/normal_module.rb +10 -5
data/lib/rdoc/options.rb +95 -21
data/lib/rdoc/parser.rb +6 -2
data/lib/rdoc/parser/c.rb +212 -97
data/lib/rdoc/parser/markdown.rb +23 -0
data/lib/rdoc/parser/ruby.rb +115 -35
data/lib/rdoc/parser/ruby_tools.rb +8 -3
data/lib/rdoc/rd.rb +8 -4
data/lib/rdoc/rd/block_parser.rb +1 -1
data/lib/rdoc/rd/block_parser.ry +1 -1
data/lib/rdoc/rdoc.rb +45 -21
data/lib/rdoc/ri/driver.rb +322 -76
data/lib/rdoc/ri/paths.rb +90 -31
data/lib/rdoc/ri/store.rb +2 -353
data/lib/rdoc/ruby_lex.rb +5 -21
data/lib/rdoc/ruby_token.rb +2 -3
data/lib/rdoc/rubygems_hook.rb +21 -9
data/lib/rdoc/servlet.rb +302 -0
data/lib/rdoc/stats.rb +28 -20
data/lib/rdoc/store.rb +881 -0
data/lib/rdoc/task.rb +2 -1
data/lib/rdoc/test_case.rb +103 -1
data/lib/rdoc/text.rb +5 -4
data/lib/rdoc/tom_doc.rb +17 -16
data/lib/rdoc/top_level.rb +43 -285
data/test/MarkdownTest_1.0.3/Amps and angle encoding.text +21 -0
data/test/MarkdownTest_1.0.3/Auto links.text +13 -0
data/test/MarkdownTest_1.0.3/Backslash escapes.text +120 -0
data/test/MarkdownTest_1.0.3/Blockquotes with code blocks.text +11 -0
data/test/MarkdownTest_1.0.3/Code Blocks.text +14 -0
data/test/MarkdownTest_1.0.3/Code Spans.text +6 -0
data/test/MarkdownTest_1.0.3/Hard-wrapped paragraphs with list-like lines.text +8 -0
data/test/MarkdownTest_1.0.3/Horizontal rules.text +67 -0
data/test/MarkdownTest_1.0.3/Inline HTML (Advanced).text +15 -0
data/test/MarkdownTest_1.0.3/Inline HTML (Simple).text +69 -0
data/test/MarkdownTest_1.0.3/Inline HTML comments.text +13 -0
data/test/MarkdownTest_1.0.3/Links, inline style.text +12 -0
data/test/MarkdownTest_1.0.3/Links, reference style.text +71 -0
data/test/MarkdownTest_1.0.3/Links, shortcut references.text +20 -0
data/test/MarkdownTest_1.0.3/Literal quotes in titles.text +7 -0
data/test/MarkdownTest_1.0.3/Markdown Documentation - Basics.text +306 -0
data/test/MarkdownTest_1.0.3/Markdown Documentation - Syntax.text +888 -0
data/test/MarkdownTest_1.0.3/Nested blockquotes.text +5 -0
data/test/MarkdownTest_1.0.3/Ordered and unordered lists.text +131 -0
data/test/MarkdownTest_1.0.3/Strong and em together.text +7 -0
data/test/MarkdownTest_1.0.3/Tabs.text +21 -0
data/test/MarkdownTest_1.0.3/Tidyness.text +5 -0
data/test/test_attribute_manager.rb +7 -4
data/test/test_rdoc_any_method.rb +84 -13
data/test/test_rdoc_attr.rb +59 -9
data/test/test_rdoc_class_module.rb +670 -73
data/test/test_rdoc_code_object.rb +21 -1
data/test/test_rdoc_comment.rb +1 -1
data/test/test_rdoc_constant.rb +132 -0
data/test/test_rdoc_context.rb +84 -18
data/test/test_rdoc_context_section.rb +99 -15
data/test/test_rdoc_cross_reference.rb +1 -1
data/test/test_rdoc_encoding.rb +17 -1
data/test/test_rdoc_extend.rb +94 -0
data/test/test_rdoc_generator_darkfish.rb +45 -19
data/test/test_rdoc_generator_json_index.rb +27 -7
data/test/test_rdoc_generator_markup.rb +3 -3
data/test/test_rdoc_generator_ri.rb +11 -9
data/test/test_rdoc_include.rb +12 -0
data/test/test_rdoc_markdown.rb +977 -0
data/test/test_rdoc_markdown_test.rb +1891 -0
data/test/test_rdoc_markup.rb +1 -1
data/test/test_rdoc_markup_attribute_manager.rb +2 -2
data/test/test_rdoc_markup_attributes.rb +39 -0
data/test/test_rdoc_markup_document.rb +16 -1
data/test/test_rdoc_markup_formatter.rb +7 -4
data/test/test_rdoc_markup_hard_break.rb +31 -0
data/test/test_rdoc_markup_indented_paragraph.rb +14 -0
data/test/test_rdoc_markup_paragraph.rb +15 -1
data/test/test_rdoc_markup_parser.rb +152 -89
data/test/test_rdoc_markup_to_ansi.rb +23 -2
data/test/test_rdoc_markup_to_bs.rb +24 -0
data/test/test_rdoc_markup_to_html.rb +50 -19
data/test/test_rdoc_markup_to_html_crossref.rb +23 -5
data/test/test_rdoc_markup_to_html_snippet.rb +49 -8
data/test/test_rdoc_markup_to_joined_paragraph.rb +32 -0
data/test/test_rdoc_markup_to_label.rb +63 -1
data/test/test_rdoc_markup_to_markdown.rb +352 -0
data/test/test_rdoc_markup_to_rdoc.rb +22 -2
data/test/test_rdoc_markup_to_table_of_contents.rb +44 -39
data/test/test_rdoc_markup_to_tt_only.rb +20 -0
data/test/test_rdoc_markup_verbatim.rb +13 -0
data/test/test_rdoc_method_attr.rb +5 -0
data/test/test_rdoc_normal_class.rb +24 -5
data/test/test_rdoc_normal_module.rb +1 -1
data/test/test_rdoc_options.rb +21 -6
data/test/test_rdoc_parser.rb +24 -0
data/test/test_rdoc_parser_c.rb +151 -26
data/test/test_rdoc_parser_markdown.rb +55 -0
data/test/test_rdoc_parser_rd.rb +2 -2
data/test/test_rdoc_parser_ruby.rb +468 -109
data/test/test_rdoc_parser_simple.rb +2 -2
data/test/test_rdoc_rd_block_parser.rb +0 -4
data/test/test_rdoc_rdoc.rb +110 -22
data/test/test_rdoc_ri_driver.rb +415 -80
data/test/test_rdoc_ri_paths.rb +122 -13
data/test/test_rdoc_ruby_lex.rb +5 -61
data/test/test_rdoc_ruby_token.rb +19 -0
data/test/test_rdoc_rubygems_hook.rb +64 -43
data/test/test_rdoc_servlet.rb +429 -0
data/test/test_rdoc_stats.rb +83 -24
data/test/{test_rdoc_ri_store.rb → test_rdoc_store.rb} +395 -22
data/test/test_rdoc_task.rb +2 -2
data/test/test_rdoc_text.rb +37 -11
data/test/test_rdoc_tom_doc.rb +59 -62
data/test/test_rdoc_top_level.rb +71 -113
data/test/xref_test_case.rb +7 -9
metadata +122 -39
metadata.gz.sig +0 -0
data/CVE-2013-0256.rdoc +0 -49
data/lib/rdoc/markup/attribute.rb +0 -51

data/lib/rdoc/generator/template/darkfish/servlet_not_found.rhtml ADDED

@@ -0,0 +1,18 @@
+<body>
+<nav id="metadata">
+  <%= render '_sidebar_navigation.rhtml' %>
+  <%= render '_sidebar_search.rhtml' %>
+  <div id="project-metadata">
+    <%= render '_sidebar_pages.rhtml' %>
+    <%= render '_sidebar_classes.rhtml' %>
+  </div>
+</nav>
+<div id="documentation" class="description">
+  <h1>Not Found</h1>
+  <p>The page <kbd><%=h path %></kbd> was not found
+</div>

data/lib/rdoc/generator/template/darkfish/servlet_root.rhtml ADDED

@@ -0,0 +1,37 @@
+<body>
+<nav id="metadata">
+<%= render '_sidebar_search.rhtml' %>
+<%= render '_sidebar_installed.rhtml' %>
+</nav>
+<div id="documentation" class="description">
+  <h1>Local RDoc Documentation</h1>
+  <p>Here you can browse local documentation from the ruby standard library and
+  your installed gems.
+<% gems = installed.select { |_, _, _, type,| type == :gem } %>
+<% missing = gems.reject { |_, _, exists,| exists } %>
+<% unless missing.empty? then %>
+  <h2>Missing Gem Documentation</h2>
+  <p>You are missing documentation for some of your installed gems.
+  You can install missing documentation for gems by running
+  <kbd>gem rdoc --all</kbd>.  After installing the missing documentation you
+  only need to reload this page.  The newly created documentation will
+  automatically appear.
+  <p>You can also install documentation for a specific gem by running one of
+  the following commands.
+  <ul>
+  <% names = missing.map { |name,| name.sub(/-([^-]*)$/, '') }.uniq %>
+  <% names.each do |name| %>
+    <li><kbd>gem rdoc <%=h name %></kbd>
+  <% end %>
+  </ul>
+<% end %>
+</div>

data/lib/rdoc/generator/template/darkfish/table_of_contents.rhtml CHANGED

@@ -30,8 +30,8 @@
   <li class="<%= klass.type %>">
     <a href="<%= klass.path %>"><%= klass.full_name %></a>
 <% table = []
-   table.push(*klass.parse(klass.comment).table_of_contents)
-   table.push(*klass.section_contents)
+   table.concat klass.parse(klass.comment).table_of_contents
+   table.concat klass.section_contents
    unless table.empty? then %>
     <img class="toc-toggle" src="images/transparent.png" alt="" title="toggle headings">
@@ -47,7 +47,7 @@
 <h2 id="methods">Methods</h2>
 <ul>
-  <% RDoc::TopLevel.all_classes_and_modules.map do |mod|
+  <% @store.all_classes_and_modules.map do |mod|
        mod.method_list
      end.flatten.sort.each do |method| %>
     <li class="method"><a href="<%= method.path %>"><%= method.pretty_name %> &mdash; <%= method.parent.full_name %></a>

data/lib/rdoc/include.rb CHANGED

@@ -76,7 +76,7 @@ class RDoc::Include < RDoc::CodeObject
     # search the current context
     return @name unless parent
     full_name = parent.child_name(@name)
-    @module = RDoc::TopLevel.modules_hash[full_name]
+    @module = @store.modules_hash[full_name]
     return @module if @module
     return @name if @name =~ /^::/
@@ -86,7 +86,7 @@ class RDoc::Include < RDoc::CodeObject
       inc = i.module
       next if String === inc
       full_name = inc.child_name(@name)
-      @module = RDoc::TopLevel.modules_hash[full_name]
+      @module = @store.modules_hash[full_name]
       return @module if @module
     end
@@ -94,7 +94,7 @@ class RDoc::Include < RDoc::CodeObject
     up = parent.parent
     while up
       full_name = up.child_name(@name)
-      @module = RDoc::TopLevel.modules_hash[full_name]
+      @module = @store.modules_hash[full_name]
       return @module if @module
       up = up.parent
     end
@@ -102,6 +102,15 @@ class RDoc::Include < RDoc::CodeObject
     @name
   end
+  ##
+  # Sets the store for this class or module and its contained code objects.
+  def store= store
+    super
+    @file = @store.add_file @file.full_name if @file
+  end
   def to_s # :nodoc:
     "include #@name in: #{parent}"
   end

data/lib/rdoc/markdown.kpeg ADDED

@@ -0,0 +1,1186 @@
+%% name = RDoc::Markdown
+%% header {
+# coding: UTF-8
+# :markup: markdown
+##
+# RDoc::Markdown as described by the [markdown syntax][syntax].
+#
+# To choose Markdown as your only default format see
+# RDoc::Options@Saved+Options for instructions on setting up a `.doc_options`
+# file to store your project default.
+#
+# ## Extensions
+#
+# The following markdown extensions are supported by the parser, but not all
+# are used in RDoc output by default.
+#
+# ### RDoc
+#
+# The RDoc Markdown parser has the following built-in behaviors that cannot be
+# disabled.
+#
+# Underscores embedded in words are never interpreted as emphasis.  (While the
+# [markdown dingus][dingus] emphasizes in-word underscores, neither the
+# Markdown syntax nor MarkdownTest mention this behavior.)
+#
+# For HTML output, RDoc always auto-links bare URLs.
+#
+# ### Break on Newline
+#
+# The break_on_newline extension converts all newlines into hard line breaks
+# as in [Github Flavored Markdown][GFM].  This extension is disabled by
+# default.
+#
+# ### CSS
+#
+# The #css extension enables CSS blocks to be included in the output, but they
+# are not used for any built-in RDoc output format.  This extension is disabled
+# by default.
+#
+# Example:
+#
+#     <style type="text/css">
+#     h1 { font-size: 3em }
+#     </style>
+#
+# ### Definition Lists
+#
+# The definition_lists extension allows definition lists using the [PHP
+# Markdown Extra syntax][PHPE], but only one label and definition are supported
+# at this time.  This extension is enabled by default.
+#
+# Example:
+#
+# ```
+# cat
+# :   A small furry mammal
+# that seems to sleep a lot
+#
+# ant
+# :   A little insect that is known
+# to enjoy picnics
+#
+# ```
+#
+# Produces:
+#
+# cat
+# :   A small furry mammal
+# that seems to sleep a lot
+#
+# ant
+# :   A little insect that is known
+# to enjoy picnics
+#
+# ### Github
+#
+# The #github extension enables a partial set of [Github Flavored Markdown]
+# [GFM].  This extension is enabled by default.
+#
+# Supported github extensions include:
+#
+# #### Fenced code blocks
+#
+# Use ` ``` ` around a block of code instead of indenting it four spaces.
+#
+# #### Syntax highlighting
+#
+# Use ` ``` ruby ` as the start of a code fence to add syntax highlighting.
+# (Currently only `ruby` syntax is supported).
+#
+# ### HTML
+#
+# Enables raw HTML to be included in the output.  This extension is enabled by
+# default.
+#
+# Example:
+#
+#     <table>
+#     ...
+#     </table>
+#
+# ### Notes
+#
+# The #notes extension enables footnote support.  This extension is enabled by
+# default.
+#
+# Example:
+#
+#     Here is some text[^1] including an inline footnote ^[for short footnotes]
+#
+#     ...
+#
+#     [^1]: With the footnote text down at the bottom
+#
+# Produces:
+#
+# Here is some text[^1] including an inline footnote ^[for short footnotes]
+#
+# [^1]: With the footnote text down at the bottom
+#
+# ## Limitations
+#
+# * Link titles are not used
+# * Image links are not generated correctly
+# * Footnotes are collapsed into a single paragraph
+#
+# ## Author
+#
+# This markdown parser is a port to kpeg from [peg-markdown][pegmarkdown] by
+# John MacFarlane.
+#
+# It is used under the MIT license:
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# The port to kpeg was performed by Eric Hodel and Evan Phoenix
+#
+# [dingus]: http://daringfireball.net/projects/markdown/dingus
+# [GFM]: http://github.github.com/github-flavored-markdown/
+# [pegmarkdown]: https://github.com/jgm/peg-markdown
+# [PHPE]: http://michelf.com/projects/php-markdown/extra/#def-list
+# [syntax]: http://daringfireball.net/projects/markdown/syntax
+#--
+# Last updated to jgm/peg-markdown commit 8f8fc22ef0
+}
+%% {
+  require 'rubygems'
+  require 'rdoc'
+  require 'rdoc/markup/to_joined_paragraph'
+  require 'rdoc/markdown/entities'
+  if RUBY_VERSION > '1.9' then
+    require 'rdoc/markdown/literals_1_9'
+  else
+    require 'rdoc/markdown/literals_1_8'
+  end
+  ##
+  # Supported extensions
+  EXTENSIONS = []
+  ##
+  # Extensions enabled by default
+  DEFAULT_EXTENSIONS = [
+    :definition_lists,
+    :github,
+    :html,
+    :notes,
+  ]
+  # :section: Extensions
+  ##
+  # Creates extension methods for the `name` extension to enable and disable
+  # the extension and to query if they are active.
+  def self.extension name
+    EXTENSIONS << name
+    eval <<-RUBY
+      def #{name}?
+        extension? __method__
+      end
+      def #{name}= enable
+        extension __method__, enable
+      end
+    RUBY
+  end
+  ##
+  # Converts all newlines into hard breaks
+  extension :break_on_newline
+  ##
+  # Allow style blocks
+  extension :css
+  ##
+  # Allow PHP Markdown Extras style definition lists
+  extension :definition_lists
+  ##
+  # Allow Github Flavored Markdown
+  extension :github
+  ##
+  # Allow HTML
+  extension :html
+  ##
+  # Enables the notes extension
+  extension :notes
+  # :section:
+  ##
+  # Parses the `markdown` document into an RDoc::Document using the default
+  # extensions.
+  def self.parse markdown
+    parser = new
+    parser.parse markdown
+  end
+  # TODO remove when kpeg 0.10 is released
+  alias orig_initialize initialize # :nodoc:
+  ##
+  # Creates a new markdown parser that enables the given +extensions+.
+  def initialize extensions = DEFAULT_EXTENSIONS, debug = false
+    @debug      = debug
+    @formatter  = RDoc::Markup::ToJoinedParagraph.new
+    @extensions = extensions
+    @references          = nil
+    @unlinked_references = nil
+    @footnotes       = nil
+    @note_order      = nil
+  end
+  ##
+  # Wraps `text` in emphasis for rdoc inline formatting
+  def emphasis text
+    if text =~ /\A[a-z\d.\/]+\z/i then
+      "_#{text}_"
+    else
+      "<em>#{text}</em>"
+    end
+  end
+  ##
+  # :category: Extensions
+  #
+  # Is the extension `name` enabled?
+  def extension? name
+    name = name.to_s.delete('?').intern
+    @extensions.include? name
+  end
+  ##
+  # :category: Extensions
+  #
+  # Enables or disables the extension with `name`
+  def extension name, enable
+    name = name.to_s.delete('=').intern
+    if enable then
+      @extensions |= [name]
+    else
+      @extensions -= [name]
+    end
+  end
+  ##
+  # Parses `text` in a clone of this parser.  This is used for handling nested
+  # lists the same way as markdown_parser.
+  def inner_parse text # :nodoc:
+    parser = clone
+    parser.setup_parser text, @debug
+    parser.peg_parse
+    doc = parser.result
+    doc.accept @formatter
+    doc.parts
+  end
+  ##
+  # Finds a link reference for `label` and creates a new link to it with
+  # `content` as the link text.  If `label` was not encountered in the
+  # reference-gathering parser pass the label and content are reconstructed
+  # with the linking `text` (usually whitespace).
+  def link_to content, label = content, text = nil
+    raise 'enable notes extension' if
+      content.start_with? '^' and label.equal? content
+    if ref = @references[label] then
+      "{#{content}}[#{ref}]"
+    elsif label.equal? content then
+      "[#{content}]#{text}"
+    else
+      "[#{content}]#{text}[#{label}]"
+    end
+  end
+  ##
+  # Creates an RDoc::Markup::ListItem by parsing the `unparsed` content from
+  # the first parsing pass.
+  def list_item_from unparsed
+    parsed = inner_parse unparsed.join
+    RDoc::Markup::ListItem.new nil, *parsed
+  end
+  ##
+  # Stores `label` as a note and fills in previously unknown note references.
+  def note label
+    #foottext = "rdoc-label:foottext-#{label}:footmark-#{label}"
+    #ref.replace foottext if ref = @unlinked_notes.delete(label)
+    @notes[label] = foottext
+    #"{^1}[rdoc-label:footmark-#{label}:foottext-#{label}] "
+  end
+  ##
+  # Creates a new link for the footnote `reference` and adds the reference to
+  # the note order list for proper display at the end of the document.
+  def note_for ref
+    @note_order << ref
+    label = @note_order.length
+    "{*#{label}}[rdoc-label:foottext-#{label}:footmark-#{label}]"
+  end
+  ##
+  # The internal kpeg parse method
+  alias peg_parse parse # :nodoc:
+  ##
+  # Creates an RDoc::Markup::Paragraph from `parts` and including
+  # extension-specific behavior
+  def paragraph parts
+    parts = parts.map do |part|
+      if "\n" == part then
+        RDoc::Markup::HardBreak.new
+      else
+        part
+      end
+    end if break_on_newline?
+    RDoc::Markup::Paragraph.new(*parts)
+  end
+  ##
+  # Parses `markdown` into an RDoc::Document
+  def parse markdown
+    @references          = {}
+    @unlinked_references = {}
+    markdown += "\n\n"
+    setup_parser markdown, @debug
+    peg_parse 'References'
+    if notes? then
+      @footnotes       = {}
+      setup_parser markdown, @debug
+      peg_parse 'Notes'
+      # using note_order on the first pass would be a bug
+      @note_order      = []
+    end
+    setup_parser markdown, @debug
+    peg_parse
+    doc = result
+    if notes? and not @footnotes.empty? then
+      doc << RDoc::Markup::Rule.new(1)
+      @note_order.each_with_index do |ref, index|
+        label = index + 1
+        note = @footnotes[ref]
+        link = "{^#{label}}[rdoc-label:footmark-#{label}:foottext-#{label}] "
+        note.parts.unshift link
+        doc << note
+      end
+    end
+    doc.accept @formatter
+    doc
+  end
+  ##
+  # Stores `label` as a reference to `link` and fills in previously unknown
+  # link references.
+  def reference label, link
+    if ref = @unlinked_references.delete(label) then
+      ref.replace link
+    end
+    @references[label] = link
+  end
+  ##
+  # Wraps `text` in strong markup for rdoc inline formatting
+  def strong text
+    if text =~ /\A[a-z\d.\/-]+\z/i then
+      "*#{text}*"
+    else
+      "<b>#{text}</b>"
+    end
+  end
+}
+root = Doc
+Doc =       BOM? Block*:a { RDoc::Markup::Document.new(*a.compact) }
+Block =     BlankLine*
+            ( BlockQuote
+            | Verbatim
+            | CodeFence
+            | Note
+            | Reference
+            | HorizontalRule
+            | Heading
+            | OrderedList
+            | BulletList
+            | DefinitionList
+            | HtmlBlock
+            | StyleBlock
+            | Para
+            | Plain )
+Para =      NonindentSpace Inlines:a BlankLine+
+            { paragraph a }
+Plain =     Inlines:a
+            { paragraph a }
+AtxInline = !Newline !(Sp? "#"* Sp Newline) Inline
+AtxStart =  < ( "######" | "#####" | "####" | "###" | "##" | "#" ) >
+            { text.length }
+AtxHeading = AtxStart:s Sp? AtxInline+:a (Sp? "#"* Sp)?  Newline
+            { RDoc::Markup::Heading.new(s, a.join) }
+SetextHeading = SetextHeading1 | SetextHeading2
+SetextBottom1 = "===" "="* Newline
+SetextBottom2 = "---" "-"* Newline
+SetextHeading1 =  &(RawLine SetextBottom1)
+                  StartList:a ( !Endline Inline:b { a << b } )+ Sp? Newline
+                  SetextBottom1
+                  { RDoc::Markup::Heading.new(1, a.join) }
+SetextHeading2 =  &(RawLine SetextBottom2)
+                  StartList:a ( !Endline Inline:b { a << b })+ Sp? Newline
+                  SetextBottom2
+                  { RDoc::Markup::Heading.new(2, a.join) }
+Heading = SetextHeading | AtxHeading
+BlockQuote = BlockQuoteRaw:a
+             { RDoc::Markup::BlockQuote.new(*a) }
+BlockQuoteRaw =  StartList:a
+                 (( ">" " "? Line:l { a << l } )
+                  ( !">" !BlankLine Line:c { a << c } )*
+                  ( BlankLine:n { a << n } )*
+                 )+
+                 { inner_parse a.join }
+NonblankIndentedLine = !BlankLine IndentedLine
+VerbatimChunk = BlankLine*:a
+                NonblankIndentedLine+:b
+                { a.concat b }
+Verbatim =     VerbatimChunk+:a
+               { RDoc::Markup::Verbatim.new(*a.flatten) }
+HorizontalRule = NonindentSpace
+                 ( "*" Sp "*" Sp "*" (Sp "*")*
+                 | "-" Sp "-" Sp "-" (Sp "-")*
+                 | "_" Sp "_" Sp "_" (Sp "_")*)
+                 Sp Newline BlankLine+
+                 { RDoc::Markup::Rule.new 1 }
+Bullet = !HorizontalRule NonindentSpace ("+" | "*" | "-") Spacechar+
+BulletList = &Bullet (ListTight | ListLoose):a
+             { RDoc::Markup::List.new(:BULLET, *a) }
+ListTight = ListItemTight+:a
+            BlankLine* !(Bullet | Enumerator)
+            { a }
+ListLoose = StartList:a
+            ( ListItem:b BlankLine* { a << b } )+
+            { a }
+ListItem =  ( Bullet | Enumerator )
+            StartList:a
+            ListBlock:b { a << b }
+            ( ListContinuationBlock:c { a.push(*c) } )*
+            { list_item_from a }
+ListItemTight =
+            ( Bullet | Enumerator )
+            ListBlock:a
+            ( !BlankLine
+              ListContinuationBlock:b { a.push(*b) } )*
+            !ListContinuationBlock
+            { list_item_from a }
+ListBlock = !BlankLine Line:a
+            ListBlockLine*:c
+            { [a, *c] }
+ListContinuationBlock = StartList:a
+                        ( BlankLine*
+                          { a << "\n" } )
+                        ( Indent
+                          ListBlock:b { a.concat b } )+
+                        { a }
+Enumerator = NonindentSpace [0-9]+ "." Spacechar+
+OrderedList = &Enumerator (ListTight | ListLoose):a
+             { RDoc::Markup::List.new(:NUMBER, *a) }
+ListBlockLine = !BlankLine
+                !( Indent? (Bullet | Enumerator) )
+                !HorizontalRule
+                OptionallyIndentedLine
+# Parsers for different kinds of block-level HTML content.
+# This is repetitive due to constraints of PEG grammar.
+HtmlBlockOpenAddress = "<" Spnl ("address" | "ADDRESS") Spnl HtmlAttribute* ">"
+HtmlBlockCloseAddress = "<" Spnl "/" ("address" | "ADDRESS") Spnl ">"
+HtmlBlockAddress = HtmlBlockOpenAddress (HtmlBlockAddress | !HtmlBlockCloseAddress .)* HtmlBlockCloseAddress
+HtmlBlockOpenBlockquote = "<" Spnl ("blockquote" | "BLOCKQUOTE") Spnl HtmlAttribute* ">"
+HtmlBlockCloseBlockquote = "<" Spnl "/" ("blockquote" | "BLOCKQUOTE") Spnl ">"
+HtmlBlockBlockquote = HtmlBlockOpenBlockquote (HtmlBlockBlockquote | !HtmlBlockCloseBlockquote .)* HtmlBlockCloseBlockquote
+HtmlBlockOpenCenter = "<" Spnl ("center" | "CENTER") Spnl HtmlAttribute* ">"
+HtmlBlockCloseCenter = "<" Spnl "/" ("center" | "CENTER") Spnl ">"
+HtmlBlockCenter = HtmlBlockOpenCenter (HtmlBlockCenter | !HtmlBlockCloseCenter .)* HtmlBlockCloseCenter
+HtmlBlockOpenDir = "<" Spnl ("dir" | "DIR") Spnl HtmlAttribute* ">"
+HtmlBlockCloseDir = "<" Spnl "/" ("dir" | "DIR") Spnl ">"
+HtmlBlockDir = HtmlBlockOpenDir (HtmlBlockDir | !HtmlBlockCloseDir .)* HtmlBlockCloseDir
+HtmlBlockOpenDiv = "<" Spnl ("div" | "DIV") Spnl HtmlAttribute* ">"
+HtmlBlockCloseDiv = "<" Spnl "/" ("div" | "DIV") Spnl ">"
+HtmlBlockDiv = HtmlBlockOpenDiv (HtmlBlockDiv | !HtmlBlockCloseDiv .)* HtmlBlockCloseDiv
+HtmlBlockOpenDl = "<" Spnl ("dl" | "DL") Spnl HtmlAttribute* ">"
+HtmlBlockCloseDl = "<" Spnl "/" ("dl" | "DL") Spnl ">"
+HtmlBlockDl = HtmlBlockOpenDl (HtmlBlockDl | !HtmlBlockCloseDl .)* HtmlBlockCloseDl
+HtmlBlockOpenFieldset = "<" Spnl ("fieldset" | "FIELDSET") Spnl HtmlAttribute* ">"
+HtmlBlockCloseFieldset = "<" Spnl "/" ("fieldset" | "FIELDSET") Spnl ">"
+HtmlBlockFieldset = HtmlBlockOpenFieldset (HtmlBlockFieldset | !HtmlBlockCloseFieldset .)* HtmlBlockCloseFieldset
+HtmlBlockOpenForm = "<" Spnl ("form" | "FORM") Spnl HtmlAttribute* ">"
+HtmlBlockCloseForm = "<" Spnl "/" ("form" | "FORM") Spnl ">"
+HtmlBlockForm = HtmlBlockOpenForm (HtmlBlockForm | !HtmlBlockCloseForm .)* HtmlBlockCloseForm
+HtmlBlockOpenH1 = "<" Spnl ("h1" | "H1") Spnl HtmlAttribute* ">"
+HtmlBlockCloseH1 = "<" Spnl "/" ("h1" | "H1") Spnl ">"
+HtmlBlockH1 = HtmlBlockOpenH1 (HtmlBlockH1 | !HtmlBlockCloseH1 .)* HtmlBlockCloseH1
+HtmlBlockOpenH2 = "<" Spnl ("h2" | "H2") Spnl HtmlAttribute* ">"
+HtmlBlockCloseH2 = "<" Spnl "/" ("h2" | "H2") Spnl ">"
+HtmlBlockH2 = HtmlBlockOpenH2 (HtmlBlockH2 | !HtmlBlockCloseH2 .)* HtmlBlockCloseH2
+HtmlBlockOpenH3 = "<" Spnl ("h3" | "H3") Spnl HtmlAttribute* ">"
+HtmlBlockCloseH3 = "<" Spnl "/" ("h3" | "H3") Spnl ">"
+HtmlBlockH3 = HtmlBlockOpenH3 (HtmlBlockH3 | !HtmlBlockCloseH3 .)* HtmlBlockCloseH3
+HtmlBlockOpenH4 = "<" Spnl ("h4" | "H4") Spnl HtmlAttribute* ">"
+HtmlBlockCloseH4 = "<" Spnl "/" ("h4" | "H4") Spnl ">"
+HtmlBlockH4 = HtmlBlockOpenH4 (HtmlBlockH4 | !HtmlBlockCloseH4 .)* HtmlBlockCloseH4
+HtmlBlockOpenH5 = "<" Spnl ("h5" | "H5") Spnl HtmlAttribute* ">"
+HtmlBlockCloseH5 = "<" Spnl "/" ("h5" | "H5") Spnl ">"
+HtmlBlockH5 = HtmlBlockOpenH5 (HtmlBlockH5 | !HtmlBlockCloseH5 .)* HtmlBlockCloseH5
+HtmlBlockOpenH6 = "<" Spnl ("h6" | "H6") Spnl HtmlAttribute* ">"
+HtmlBlockCloseH6 = "<" Spnl "/" ("h6" | "H6") Spnl ">"
+HtmlBlockH6 = HtmlBlockOpenH6 (HtmlBlockH6 | !HtmlBlockCloseH6 .)* HtmlBlockCloseH6
+HtmlBlockOpenMenu = "<" Spnl ("menu" | "MENU") Spnl HtmlAttribute* ">"
+HtmlBlockCloseMenu = "<" Spnl "/" ("menu" | "MENU") Spnl ">"
+HtmlBlockMenu = HtmlBlockOpenMenu (HtmlBlockMenu | !HtmlBlockCloseMenu .)* HtmlBlockCloseMenu
+HtmlBlockOpenNoframes = "<" Spnl ("noframes" | "NOFRAMES") Spnl HtmlAttribute* ">"
+HtmlBlockCloseNoframes = "<" Spnl "/" ("noframes" | "NOFRAMES") Spnl ">"
+HtmlBlockNoframes = HtmlBlockOpenNoframes (HtmlBlockNoframes | !HtmlBlockCloseNoframes .)* HtmlBlockCloseNoframes
+HtmlBlockOpenNoscript = "<" Spnl ("noscript" | "NOSCRIPT") Spnl HtmlAttribute* ">"
+HtmlBlockCloseNoscript = "<" Spnl "/" ("noscript" | "NOSCRIPT") Spnl ">"
+HtmlBlockNoscript = HtmlBlockOpenNoscript (HtmlBlockNoscript | !HtmlBlockCloseNoscript .)* HtmlBlockCloseNoscript
+HtmlBlockOpenOl = "<" Spnl ("ol" | "OL") Spnl HtmlAttribute* ">"
+HtmlBlockCloseOl = "<" Spnl "/" ("ol" | "OL") Spnl ">"
+HtmlBlockOl = HtmlBlockOpenOl (HtmlBlockOl | !HtmlBlockCloseOl .)* HtmlBlockCloseOl
+HtmlBlockOpenP = "<" Spnl ("p" | "P") Spnl HtmlAttribute* ">"
+HtmlBlockCloseP = "<" Spnl "/" ("p" | "P") Spnl ">"
+HtmlBlockP = HtmlBlockOpenP (HtmlBlockP | !HtmlBlockCloseP .)* HtmlBlockCloseP
+HtmlBlockOpenPre = "<" Spnl ("pre" | "PRE") Spnl HtmlAttribute* ">"
+HtmlBlockClosePre = "<" Spnl "/" ("pre" | "PRE") Spnl ">"
+HtmlBlockPre = HtmlBlockOpenPre (HtmlBlockPre | !HtmlBlockClosePre .)* HtmlBlockClosePre
+HtmlBlockOpenTable = "<" Spnl ("table" | "TABLE") Spnl HtmlAttribute* ">"
+HtmlBlockCloseTable = "<" Spnl "/" ("table" | "TABLE") Spnl ">"
+HtmlBlockTable = HtmlBlockOpenTable (HtmlBlockTable | !HtmlBlockCloseTable .)* HtmlBlockCloseTable
+HtmlBlockOpenUl = "<" Spnl ("ul" | "UL") Spnl HtmlAttribute* ">"
+HtmlBlockCloseUl = "<" Spnl "/" ("ul" | "UL") Spnl ">"
+HtmlBlockUl = HtmlBlockOpenUl (HtmlBlockUl | !HtmlBlockCloseUl .)* HtmlBlockCloseUl
+HtmlBlockOpenDd = "<" Spnl ("dd" | "DD") Spnl HtmlAttribute* ">"
+HtmlBlockCloseDd = "<" Spnl "/" ("dd" | "DD") Spnl ">"
+HtmlBlockDd = HtmlBlockOpenDd (HtmlBlockDd | !HtmlBlockCloseDd .)* HtmlBlockCloseDd
+HtmlBlockOpenDt = "<" Spnl ("dt" | "DT") Spnl HtmlAttribute* ">"
+HtmlBlockCloseDt = "<" Spnl "/" ("dt" | "DT") Spnl ">"
+HtmlBlockDt = HtmlBlockOpenDt (HtmlBlockDt | !HtmlBlockCloseDt .)* HtmlBlockCloseDt
+HtmlBlockOpenFrameset = "<" Spnl ("frameset" | "FRAMESET") Spnl HtmlAttribute* ">"
+HtmlBlockCloseFrameset = "<" Spnl "/" ("frameset" | "FRAMESET") Spnl ">"
+HtmlBlockFrameset = HtmlBlockOpenFrameset (HtmlBlockFrameset | !HtmlBlockCloseFrameset .)* HtmlBlockCloseFrameset
+HtmlBlockOpenLi = "<" Spnl ("li" | "LI") Spnl HtmlAttribute* ">"
+HtmlBlockCloseLi = "<" Spnl "/" ("li" | "LI") Spnl ">"
+HtmlBlockLi = HtmlBlockOpenLi (HtmlBlockLi | !HtmlBlockCloseLi .)* HtmlBlockCloseLi
+HtmlBlockOpenTbody = "<" Spnl ("tbody" | "TBODY") Spnl HtmlAttribute* ">"
+HtmlBlockCloseTbody = "<" Spnl "/" ("tbody" | "TBODY") Spnl ">"
+HtmlBlockTbody = HtmlBlockOpenTbody (HtmlBlockTbody | !HtmlBlockCloseTbody .)* HtmlBlockCloseTbody
+HtmlBlockOpenTd = "<" Spnl ("td" | "TD") Spnl HtmlAttribute* ">"
+HtmlBlockCloseTd = "<" Spnl "/" ("td" | "TD") Spnl ">"
+HtmlBlockTd = HtmlBlockOpenTd (HtmlBlockTd | !HtmlBlockCloseTd .)* HtmlBlockCloseTd
+HtmlBlockOpenTfoot = "<" Spnl ("tfoot" | "TFOOT") Spnl HtmlAttribute* ">"
+HtmlBlockCloseTfoot = "<" Spnl "/" ("tfoot" | "TFOOT") Spnl ">"
+HtmlBlockTfoot = HtmlBlockOpenTfoot (HtmlBlockTfoot | !HtmlBlockCloseTfoot .)* HtmlBlockCloseTfoot
+HtmlBlockOpenTh = "<" Spnl ("th" | "TH") Spnl HtmlAttribute* ">"
+HtmlBlockCloseTh = "<" Spnl "/" ("th" | "TH") Spnl ">"
+HtmlBlockTh = HtmlBlockOpenTh (HtmlBlockTh | !HtmlBlockCloseTh .)* HtmlBlockCloseTh
+HtmlBlockOpenThead = "<" Spnl ("thead" | "THEAD") Spnl HtmlAttribute* ">"
+HtmlBlockCloseThead = "<" Spnl "/" ("thead" | "THEAD") Spnl ">"
+HtmlBlockThead = HtmlBlockOpenThead (HtmlBlockThead | !HtmlBlockCloseThead .)* HtmlBlockCloseThead
+HtmlBlockOpenTr = "<" Spnl ("tr" | "TR") Spnl HtmlAttribute* ">"
+HtmlBlockCloseTr = "<" Spnl "/" ("tr" | "TR") Spnl ">"
+HtmlBlockTr = HtmlBlockOpenTr (HtmlBlockTr | !HtmlBlockCloseTr .)* HtmlBlockCloseTr
+HtmlBlockOpenScript = "<" Spnl ("script" | "SCRIPT") Spnl HtmlAttribute* ">"
+HtmlBlockCloseScript = "<" Spnl "/" ("script" | "SCRIPT") Spnl ">"
+HtmlBlockScript = HtmlBlockOpenScript (!HtmlBlockCloseScript .)* HtmlBlockCloseScript
+HtmlBlockInTags = HtmlBlockAddress
+                | HtmlBlockBlockquote
+                | HtmlBlockCenter
+                | HtmlBlockDir
+                | HtmlBlockDiv
+                | HtmlBlockDl
+                | HtmlBlockFieldset
+                | HtmlBlockForm
+                | HtmlBlockH1
+                | HtmlBlockH2
+                | HtmlBlockH3
+                | HtmlBlockH4
+                | HtmlBlockH5
+                | HtmlBlockH6
+                | HtmlBlockMenu
+                | HtmlBlockNoframes
+                | HtmlBlockNoscript
+                | HtmlBlockOl
+                | HtmlBlockP
+                | HtmlBlockPre
+                | HtmlBlockTable
+                | HtmlBlockUl
+                | HtmlBlockDd
+                | HtmlBlockDt
+                | HtmlBlockFrameset
+                | HtmlBlockLi
+                | HtmlBlockTbody
+                | HtmlBlockTd
+                | HtmlBlockTfoot
+                | HtmlBlockTh
+                | HtmlBlockThead
+                | HtmlBlockTr
+                | HtmlBlockScript
+HtmlBlock = < ( HtmlBlockInTags | HtmlComment | HtmlBlockSelfClosing | HtmlUnclosed) >
+            BlankLine+
+            { if html? then
+                RDoc::Markup::Raw.new text
+              end }
+HtmlUnclosed = "<" Spnl HtmlUnclosedType Spnl HtmlAttribute* Spnl ">"
+HtmlUnclosedType = "HR" | "hr"
+HtmlBlockSelfClosing = "<" Spnl HtmlBlockType Spnl HtmlAttribute* "/" Spnl ">"
+HtmlBlockType = "ADDRESS" |
+                "BLOCKQUOTE" |
+                "CENTER" |
+                "DD" |
+                "DIR" |
+                "DIV" |
+                "DL" |
+                "DT" |
+                "FIELDSET" |
+                "FORM" |
+                "FRAMESET" |
+                "H1" |
+                "H2" |
+                "H3" |
+                "H4" |
+                "H5" |
+                "H6" |
+                "HR" |
+                "ISINDEX" |
+                "LI" |
+                "MENU" |
+                "NOFRAMES" |
+                "NOSCRIPT" |
+                "OL" |
+                "P" |
+                "PRE" |
+                "SCRIPT" |
+                "TABLE" |
+                "TBODY" |
+                "TD" |
+                "TFOOT" |
+                "TH" |
+                "THEAD" |
+                "TR" |
+                "UL" |
+                "address" |
+                "blockquote" |
+                "center" |
+                "dd" |
+                "dir" |
+                "div" |
+                "dl" |
+                "dt" |
+                "fieldset" |
+                "form" |
+                "frameset" |
+                "h1" |
+                "h2" |
+                "h3" |
+                "h4" |
+                "h5" |
+                "h6" |
+                "hr" |
+                "isindex" |
+                "li" |
+                "menu" |
+                "noframes" |
+                "noscript" |
+                "ol" |
+                "p" |
+                "pre" |
+                "script" |
+                "table" |
+                "tbody" |
+                "td" |
+                "tfoot" |
+                "th" |
+                "thead" |
+                "tr" |
+                "ul"
+StyleOpen =     "<" Spnl ("style" | "STYLE") Spnl HtmlAttribute* ">"
+StyleClose =    "<" Spnl "/" ("style" | "STYLE") Spnl ">"
+InStyleTags =   StyleOpen (!StyleClose .)* StyleClose
+StyleBlock =    < InStyleTags >
+                BlankLine*
+                { if css? then
+                    RDoc::Markup::Raw.new text
+                  end }
+Inlines  =  ( !Endline Inline:i { i }
+            | Endline:c &Inline { c } )+:chunks Endline?
+            { chunks }
+Inline  = Str
+        | Endline
+        | UlOrStarLine
+        | Space
+        | Strong
+        | Emph
+        | Image
+        | Link
+        | NoteReference
+        | InlineNote
+        | Code
+        | RawHtml
+        | Entity
+        | EscapedChar
+        | Symbol
+Space = Spacechar+ { " " }
+Str = StartList:a
+      < NormalChar+ > { a = text }
+      ( StrChunk:c { a << c } )* { a }
+StrChunk = < (NormalChar | "_"+ &Alphanumeric)+ > { text }
+EscapedChar =   "\\" !Newline < /[:\\`|*_{}\[\]()#+.!><-]/ > { text }
+Entity =    ( HexEntity | DecEntity | CharEntity ):a { a }
+Endline =   LineBreak | TerminalEndline | NormalEndline
+NormalEndline =   Sp Newline !BlankLine !">" !AtxStart
+                  !(Line ("===" "="* | "---" "-"*) Newline)
+                  { "\n" }
+TerminalEndline = Sp Newline Eof
+LineBreak = "  " NormalEndline { RDoc::Markup::HardBreak.new }
+Symbol = < SpecialChar >
+         { text }
+# This keeps the parser from getting bogged down on long strings of '*' or '_',
+# or strings of '*' or '_' with space on each side:
+UlOrStarLine =  (UlLine | StarLine):a { a }
+StarLine = < "****" "*"* > { text } |
+           < Spacechar "*"+ &Spacechar > { text }
+UlLine   = < "____" "_"* > { text } |
+           < Spacechar "_"+ &Spacechar > { text }
+Emph =      EmphStar | EmphUl
+OneStarOpen  =  !StarLine "*" !Spacechar !Newline
+OneStarClose =  !Spacechar !Newline Inline:a "*"
+                { a }
+EmphStar =  OneStarOpen
+            StartList:a
+            ( !OneStarClose Inline:l { a << l } )*
+            OneStarClose:l { a << l }
+            { emphasis a.join }
+OneUlOpen  =  !UlLine "_" !Spacechar !Newline
+OneUlClose =  !Spacechar !Newline Inline:a "_" # !Alphanumeric # TODO check
+              { a }
+EmphUl =    OneUlOpen
+            StartList:a
+            ( !OneUlClose Inline:l { a << l } )*
+            OneUlClose:l { a << l }
+            { emphasis a.join }
+Strong = StrongStar | StrongUl
+TwoStarOpen =   !StarLine "**" !Spacechar !Newline
+TwoStarClose =  !Spacechar !Newline Inline:a "**" { a }
+StrongStar =    TwoStarOpen
+                StartList:a
+                ( !TwoStarClose Inline:l { a << l } )*
+                TwoStarClose:l { a << l }
+                { strong a.join }
+TwoUlOpen =     !UlLine "__" !Spacechar !Newline
+TwoUlClose =    !Spacechar !Newline Inline:a "__" # !Alphanumeric # TODO check
+                { a }
+StrongUl =  TwoUlOpen
+            StartList:a
+            ( !TwoUlClose Inline:i { a << i } )*
+            TwoUlClose:l { a << l }
+            { strong a.join }
+# TODO image link support
+Image = "!" ( ExplicitLink | ReferenceLink ):a
+        { a }
+Link =  ExplicitLink | ReferenceLink | AutoLink
+ReferenceLink = ReferenceLinkDouble | ReferenceLinkSingle
+ReferenceLinkDouble = Label:content < Spnl > !"[]" Label:label
+                      { link_to content, label, text }
+ReferenceLinkSingle = Label:content < (Spnl "[]")? >
+                      { link_to content, content, text }
+ExplicitLink =  Label:l Spnl "(" Sp Source:s Spnl Title Sp ")"
+                { "{#{l}}[#{s}]" }
+Source  = ( "<" < SourceContents > ">" | < SourceContents > )
+          { text }
+SourceContents = ( ( !"(" !")" !">" Nonspacechar )+ | "(" SourceContents ")")*
+                 | ""
+Title = ( TitleSingle | TitleDouble | "" ):a
+        { a }
+TitleSingle = "'" ( !( "'" Sp ( ")" | Newline ) ) . )* "'"
+TitleDouble = "\"" ( !( "\"" Sp ( ")" | Newline ) ) . )* "\""
+AutoLink = AutoLinkUrl | AutoLinkEmail
+AutoLinkUrl =   "<" < /[A-Za-z]+/ "://" ( !Newline !">" . )+ > ">"
+                { text }
+AutoLinkEmail = "<" ("mailto:")? < /[\w+.\/!%~$-]+/i "@" ( !Newline !">" . )+ > ">"
+                { "mailto:#{text}" }
+Reference = NonindentSpace !"[]"
+              Label:label ":" Spnl RefSrc:link RefTitle BlankLine+
+            { # TODO use title
+              reference label, link
+              nil
+            }
+Label = "[" ( !"^" &{ notes? } | &. &{ !notes? } )
+        StartList:a
+        ( !"]" Inline:l { a << l } )*
+        "]"
+        { a.join.gsub(/\s+/, ' ') }
+RefSrc = < Nonspacechar+ > { text }
+RefTitle = ( RefTitleSingle | RefTitleDouble | RefTitleParens | EmptyTitle )
+EmptyTitle = ""
+RefTitleSingle = Spnl "'" < ( !( "'" Sp Newline | Newline ) . )* > "'" { text }
+RefTitleDouble = Spnl "\"" < ( !("\"" Sp Newline | Newline) . )* > "\"" { text }
+RefTitleParens = Spnl "(" < ( !(")" Sp Newline | Newline) . )* > ")" { text }
+References = ( Reference | SkipBlock )*
+Ticks1 = "`" !"`"
+Ticks2 = "``" !"`"
+Ticks3 = "```" !"`"
+Ticks4 = "````" !"`"
+Ticks5 = "`````" !"`"
+Code = ( Ticks1 Sp < (
+           ( !"`" Nonspacechar )+ | !Ticks1 "`"+ |
+           !( Sp Ticks1 ) ( Spacechar | Newline !BlankLine )
+         )+ > Sp Ticks1 |
+         Ticks2 Sp < (
+           ( !"`" Nonspacechar )+ |
+           !Ticks2 "`"+ |
+           !( Sp Ticks2 ) ( Spacechar | Newline !BlankLine )
+         )+ > Sp Ticks2 |
+         Ticks3 Sp < (
+           ( !"`" Nonspacechar )+ |
+           !Ticks3 "`"+ |
+           !( Sp Ticks3 ) ( Spacechar | Newline !BlankLine )
+         )+ > Sp Ticks3 |
+         Ticks4 Sp < (
+           ( !"`" Nonspacechar )+ |
+           !Ticks4 "`"+ |
+           !( Sp Ticks4 ) ( Spacechar | Newline !BlankLine )
+         )+ > Sp Ticks4 |
+         Ticks5 Sp < (
+           ( !"`" Nonspacechar )+ |
+           !Ticks5 "`"+ |
+           !( Sp Ticks5 ) ( Spacechar | Newline !BlankLine )
+         )+ > Sp Ticks5
+       )
+       { "<code>#{text}</code>" }
+RawHtml = < (HtmlComment | HtmlBlockScript | HtmlTag) >
+          { if html? then text else '' end }
+BlankLine =     Sp Newline { "\n" }
+Quoted =        "\"" (!"\"" .)* "\"" | "'" (!"'" .)* "'"
+HtmlAttribute = (AlphanumericAscii | "-")+ Spnl ("=" Spnl (Quoted | (!">" Nonspacechar)+))? Spnl
+HtmlComment =   "<!--" (!"-->" .)* "-->"
+HtmlTag =       "<" Spnl "/"? AlphanumericAscii+ Spnl HtmlAttribute* "/"? Spnl ">"
+Eof =           !.
+Nonspacechar =  !Spacechar !Newline .
+Sp =            Spacechar*
+Spnl =          Sp (Newline Sp)?
+SpecialChar =   "*" | "_" | "`" | "&" | "[" | "]" | "(" | ")" | "<" | "!" | "#" | "\\" | "'" | "\"" | ExtendedSpecialChar
+NormalChar =    !( SpecialChar | Spacechar | Newline ) .
+Digit = [0-9]
+%literals         = RDoc::Markdown::Literals
+Alphanumeric      = %literals.Alphanumeric
+AlphanumericAscii = %literals.AlphanumericAscii
+BOM               = %literals.BOM
+Newline           = %literals.Newline
+NonAlphanumeric   = %literals.NonAlphanumeric
+Spacechar         = %literals.Spacechar
+HexEntity  = "&" "#" /[Xx]/ < /[0-9a-fA-F]+/ > ";"
+             { [text.to_i(16)].pack 'U' }
+DecEntity  = "&" "#"        < /[0-9]+/       > ";"
+             { [text.to_i].pack 'U' }
+CharEntity = "&"            </[A-Za-z0-9]+/  > ";"
+             { if entity = HTML_ENTITIES[text] then
+                 entity.pack 'U*'
+               else
+                 "&#{text};"
+               end
+             }
+NonindentSpace =    "   " | "  " | " " | ""
+Indent =            "\t" | "    "
+IndentedLine =      Indent Line
+OptionallyIndentedLine = Indent? Line
+# StartList starts a list data structure that can be added to with cons:
+StartList = &.
+            { [] }
+Line =  RawLine:a { a }
+RawLine = ( < (!"\r" !"\n" .)* Newline >
+        | < .+ > Eof ) { text }
+SkipBlock = HtmlBlock
+          | ( !"#" !SetextBottom1 !SetextBottom2 !BlankLine RawLine )+
+            BlankLine*
+          | BlankLine+
+          | RawLine
+# Syntax extensions
+ExtendedSpecialChar = &{ notes? } ( "^" )
+NoteReference = &{ notes? }
+                RawNoteReference:ref
+                { note_for ref }
+RawNoteReference = "[^" < ( !Newline !"]" . )+ > "]" { text }
+# TODO multiple paragraphs for a footnote
+Note =          &{ notes? }
+                NonindentSpace RawNoteReference:ref ":" Sp
+                StartList:a
+                RawNoteBlock
+                ( &Indent RawNoteBlock:i { a.concat i } )*
+                { @footnotes[ref] = paragraph a
+                  nil
+                }
+InlineNote = &{ notes? }
+             "^["
+             StartList:a
+             ( !"]" Inline:l { a << l } )+
+             "]"
+             {
+               ref = [:inline, @note_order.length]
+               @footnotes[ref] = paragraph a
+               note_for ref
+             }
+Notes = ( Note | SkipBlock )*
+RawNoteBlock = StartList:a
+               ( !BlankLine OptionallyIndentedLine:l { a << l } )+
+               ( < BlankLine* > { a << text } )
+               { a }
+# Markdown extensions added by RDoc follow
+CodeFence = &{ github? }
+            Ticks3 (Sp StrChunk:format)? Spnl < (
+              ( !"`" Nonspacechar )+ |
+              !Ticks3 "`"+ |
+              Spacechar |
+              Newline
+            )+ > Ticks3 Sp Newline*
+            { verbatim = RDoc::Markup::Verbatim.new text
+              verbatim.format = format.intern if format
+              verbatim
+            }
+DefinitionList = &{ definition_lists? }
+                 ( DefinitionListItem+:list )
+                 { RDoc::Markup::List.new :NOTE, *list.flatten }
+DefinitionListItem = ( DefinitionListLabel+ ):label
+                     ( DefinitionListDefinition+ ):defns
+                     { list_items = []
+                       list_items <<
+                         RDoc::Markup::ListItem.new(label, defns.shift)
+                       list_items.concat defns.map { |defn|
+                         RDoc::Markup::ListItem.new nil, defn
+                       } unless list_items.empty?
+                       list_items
+                     }
+DefinitionListLabel = StrChunk:label Sp Newline
+                      { label }
+DefinitionListDefinition = NonindentSpace ":" Space Inlines:a BlankLine+
+                           { paragraph a }