diff --git a/.document b/.document
index ad81ce07da..6f9390978b 100644
--- a/.document
+++ b/.document
@@ -3,3 +3,4 @@ LICENSE.txt
README.txt
RI.txt
lib
+doc
diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb
index a1bbe13e2d..9e51cc4f0c 100644
--- a/doc/rdoc/markup_reference.rb
+++ b/doc/rdoc/markup_reference.rb
@@ -7,72 +7,61 @@
# attributes, and constants -- are solely for illustrating \RDoc markup,
# and have no other legitimate use.
#
-# = \RDoc Markup Reference
-#
-# Notes:
+# == About the Examples
#
# - Examples in this reference are Ruby code and comments;
# certain differences from other sources
# (such as C code and comments) are noted.
+# - Almost all examples on this page are all RDoc-like;
+# that is, they have no explicit comment markers like Ruby #
+# or C /* ... */.
# - An example that shows rendered HTML output
# displays that output in a blockquote:
#
-# Rendered HTML:
# >>>
# Some stuff
#
-# \RDoc-generated documentation is derived from and controlled by:
-#
-# - Single-line or multi-line comments that precede certain definitions;
-# see {Markup in Comments}[rdoc-ref:RDoc::MarkupReference@Markup+in+Comments].
-# - \RDoc directives in trailing comments (on the same line as code);
-# see :nodoc:, :doc:, and :notnew:.
-# - \RDoc directives in single-line comments;
-# see other {Directives}[rdoc-ref:RDoc::MarkupReference@Directives].
-# - The Ruby code itself (but not from C code);
-# see {Documentation Derived from Ruby Code}[rdoc-ref:RDoc::MarkupReference@Documentation+Derived+from+Ruby+Code].
-#
-# == Markup in Comments
-#
-# The treatment of markup in comments varies according to the type of file:
+# == \RDoc Sources
#
-# - .rb (Ruby code file): markup is parsed from Ruby comments.
-# - .c (C code file): markup is parsed from C comments.
-# - .rdoc (RDoc text file): markup is parsed from the entire file.
-#
-# The comment associated with
-# a Ruby class, module, method, alias, constant, or attribute
-# becomes the documentation for that defined object:
-#
-# - In a Ruby file, that comment immediately precedes
-# the definition of the object.
-# - In a C file, that comment immediately precedes
-# the function that implements a method,
-# or otherwise immediately precedes the definition of the object.
+# The sources of \RDoc documentation vary according to the type of file:
#
-# In either a Ruby or a C file,
-# \RDoc ignores comments that do not precede object definitions.
+# - .rb (Ruby code file):
#
-# In an \RDoc file, the text is not associated with any code object,
-# but may (depending on how the documentation is built),
-# become a separate page.
+# - Markup may be found in Ruby comments:
+# A comment that immediately precedes the definition
+# of a Ruby class, module, method, alias, constant, or attribute
+# becomes the documentation for that defined object.
+# - An \RDoc directive may be found in:
#
-# Almost all examples on this page are all RDoc-like;
-# that is, they have no comment markers like Ruby #
-# or C /* ... */.
+# - A trailing comment (on the same line as code);
+# see :nodoc:, :doc:, and :notnew:.
+# - A single-line comment;
+# see other {Directives}[rdoc-ref:RDoc::MarkupReference@Directives].
#
-# === Margins
+# - Documentation may be derived from the Ruby code itself;
+# see {Documentation Derived from Ruby Code}[rdoc-ref:RDoc::MarkupReference@Documentation+Derived+from+Ruby+Code].
#
-# In a multi-line comment,
-# \RDoc looks for the comment's natural left margin,
-# which becomes the base margin for the comment
-# and is the initial current margin for the comment.
-#
-# The current margin can change, and does so, for example in a list.
+# - .c (C code file): markup is parsed from C comments.
+# A comment that immediately precedes
+# a function that implements a Ruby method,
+# or otherwise immediately precedes the definition of a Ruby object,
+# becomes the documentation for that object.
+# - .rdoc (\RDoc markup text file) or .md (\RDoc markdown text file):
+# markup is parsed from the entire file.
+# The text is not associated with any code object,
+# but may (depending on how the documentation is built)
+# become a separate page.
+#
+# An RDoc document:
+#
+# - A (possibly multi-line) comment in a Ruby or C file
+# that generates \RDoc documentation (as above).
+# - The entire markup (.rdoc) file or markdown (.md) file
+# (which is usually multi-line).
#
# === Blocks
#
-# It's convenient to think of \RDoc markup input as a sequence of _blocks_
+# It's convenient to think of an \RDoc document as a sequence of _blocks_
# of various types (details at the links):
#
# - {Paragraph}[rdoc-ref:RDoc::MarkupReference@Paragraphs]:
@@ -88,7 +77,7 @@
# - {List}[rdoc-ref:RDoc::MarkupReference@Lists]: items for
# a bullet list, numbered list, lettered list, or labeled list.
# - {Heading}[rdoc-ref:RDoc::MarkupReference@Headings]:
-# a section heading.
+# a heading.
# - {Horizontal rule}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules]:
# a line across the rendered page.
# - {Directive}[rdoc-ref:RDoc::MarkupReference@Directives]:
@@ -103,6 +92,10 @@
# - Any block may appear independently
# (that is, not nested in another block);
# some blocks may be nested, as detailed below.
+# - In a multi-line block,
+# \RDoc looks for the block's natural left margin,
+# which becomes the base margin for the block
+# and is the initial current margin for the block.
#
# ==== Paragraphs
#