diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb
index 97293d5cba..dd21d7664b 100644
--- a/doc/rdoc/markup_reference.rb
+++ b/doc/rdoc/markup_reference.rb
@@ -1,5 +1,10 @@
require 'rdoc'
+# This page is about RDoc's +rdoc+ input format,
+# which here we'll call "RDoc markup" or simply "markup."
+#
+# == About This \Class
+#
# \Class \RDoc::MarkupReference exists only to provide a suitable home
# for a reference document for \RDoc markup.
#
@@ -21,9 +26,9 @@
# >>>
# Some stuff
#
-# == \RDoc Sources
+# == Markup Sources
#
-# The sources of \RDoc documentation vary according to the type of file:
+# The sources of markup documentation vary according to the type of file:
#
# - .rb (Ruby code file):
#
@@ -31,7 +36,7 @@
# 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:
+# - A markup directive may be found in:
#
# - A trailing comment (on the same line as code);
# see :nodoc:, :doc:, and :notnew:.
@@ -39,25 +44,32 @@
# see other {Directives}[rdoc-ref:RDoc::MarkupReference@Directives].
#
# - Documentation may be derived from the Ruby code itself;
-# see {Documentation Derived from Ruby Code}[rdoc-ref:RDoc::MarkupReference@Documentation+Derived+from+Ruby+Code].
+# see {Derived Documentation}[rdoc-ref:RDoc::MarkupReference@Derived+Documentation].
#
# - .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):
+# - .rdoc (markup 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:
+# Note that all of the above applies to \RDoc markup-formatted documentation:
+#
+# - A C- or \Ruby-coded file may contain markdown-formatted documentation,
+# though that format must be declared (because the default is +markup+).
+# - A markdown (.md) file contains only markdown-formatted documentation.
+#
+# == Markup Document
+#
+# The term markup document refers to one of:
#
# - 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).
+# that generates documentation (as above).
+# - An entire markup file (i.e., a file with extension .rdoc).
#
# === Blocks
#
@@ -1140,7 +1152,7 @@
# - A double escape character \\ that is rendered
# as a single backslash.
#
-# == Documentation Derived from Ruby Code
+# == Derived Documentation
#
# [Class]
#
@@ -1148,6 +1160,7 @@
#
# - \Class name.
# - Parent class.
+# - Included modules.
# - Singleton methods.
# - Instance methods.
# - Aliases.
@@ -1159,6 +1172,7 @@
# By default, \RDoc documents:
#
# - \Module name.
+# - Included modules.
# - \Singleton methods.
# - Instance methods.
# - Aliases.