Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[DOC] Link from RDoc::Markup to RDoc::MarkupReference #906

Merged
merged 1 commit into from
Jul 28, 2022
Merged

[DOC] Link from RDoc::Markup to RDoc::MarkupReference #906

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
284 changes: 1 addition & 283 deletions lib/rdoc/markup.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,289 +97,7 @@
#
# = \RDoc Markup Reference
#
# == Block Markup
#
# === Paragraphs and Verbatim
#
# The markup engine looks for a document's natural left margin. This is
# used as the initial margin for the document.
#
# Consecutive lines starting at this margin are considered to be a
# paragraph. Empty lines separate paragraphs.
#
# Any line that starts to the right of the current margin is treated
# as verbatim text. This is useful for code listings:
#
# 3.times { puts "Ruby" }
#
# In verbatim text, two or more blank lines are collapsed into one,
# and trailing blank lines are removed:
#
# This is the first line
#
#
# This is the second non-blank line,
# after 2 blank lines in the source markup.
#
#
# There were two trailing blank lines right above this paragraph, that
# have been removed. In addition, the verbatim text has been shifted
# left, so the amount of indentation of verbatim text is unimportant.
#
# For HTML output RDoc makes a small effort to determine if a verbatim section
# contains Ruby source code. If so, the verbatim block will be marked up as
# HTML. Triggers include "def", "class", "module", "require", the "hash
# rocket"# (=>) or a block call with a parameter.
#
# === Headers
#
# A line starting with an equal sign (=) is treated as a
# heading. Level one headings have one equals sign, level two headings
# have two, and so on until level six, which is the maximum
# (seven hyphens or more result in a level six heading).
#
# For example, the above header was obtained with:
#
# === Headers
#
# In HTML output headers have an id matching their name. The above example's
# HTML is:
#
# <h3 id="label-Headers">Headers</h3>
#
# If a heading is inside a method body the id will be prefixed with the
# method's id. If the above header where in the documentation for a method
# such as:
#
# ##
# # This method does fun things
# #
# # = Example
# #
# # Example of fun things goes here ...
#
# def do_fun_things
# end
#
# The header's id would be:
#
# <h1 id="method-i-do_fun_things-label-Example">Example</h1>
#
# The label can be linked-to using <tt>SomeClass@Headers</tt>. See
# {Links}[rdoc-ref:RDoc::Markup@Links] for further details.
#
# === Rules
#
# A line starting with three or more hyphens (at the current indent)
# generates a horizontal rule.
#
# ---
#
# produces:
#
# ---
#
# === Simple Lists
#
# If a paragraph starts with a "*", "-", "<digit>." or "<letter>.",
# then it is taken to be the start of a list. The margin is increased to be
# the first non-space following the list start flag. Subsequent lines
# should be indented to this new margin until the list ends. For example:
#
# * this is a list with three paragraphs in
# the first item. This is the first paragraph.
#
# And this is the second paragraph.
#
# 1. This is an indented, numbered list.
# 2. This is the second item in that list
#
# This is the third conventional paragraph in the
# first list item.
#
# * This is the second item in the original list
#
# produces:
#
# * this is a list with three paragraphs in
# the first item. This is the first paragraph.
#
# And this is the second paragraph.
#
# 1. This is an indented, numbered list.
# 2. This is the second item in that list
#
# This is the third conventional paragraph in the
# first list item.
#
# * This is the second item in the original list
#
# === Labeled Lists
#
# You can also construct labeled lists, sometimes called description
# or definition lists. Do this by putting the label in square brackets
# and indenting the list body:
#
# [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
#
# If you want the list bodies to line up to the left of the labels,
# use two colons:
#
# 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
#
# Notice that blank lines right after the label are ignored in labeled lists:
#
# [one]
#
# definition 1
#
# [two]
#
# definition 2
#
# produces the same output as
#
# [one] definition 1
# [two] definition 2
#
#
# === Lists and Verbatim
#
# If you want to introduce a verbatim section right after a list, it has to be
# less indented than the list item bodies, but more indented than the list
# label, letter, digit or bullet. For instance:
#
# * point 1
#
# * point 2, first paragraph
#
# point 2, second paragraph
# verbatim text inside point 2
# point 2, third paragraph
# verbatim text outside of the list (the list is therefore closed)
# regular paragraph after the list
#
# produces:
#
# * point 1
#
# * point 2, first paragraph
#
# point 2, second paragraph
# verbatim text inside point 2
# point 2, third paragraph
# verbatim text outside of the list (the list is therefore closed)
# regular paragraph after the list
#
# == Text Markup
#
# === Bold, Italic, Typewriter Text
#
# You can use markup within text (except verbatim) to change the
# appearance of parts of that text. Out of the box, RDoc::Markup
# supports word-based and general markup.
#
# Word-based markup uses flag characters around individual words:
#
# <tt>\*_word_\*</tt>:: displays _word_ in a *bold* font
# <tt>\__word_\_</tt>:: displays _word_ in an _emphasized_ font
# <tt>\+_word_\+</tt>:: displays _word_ in a +code+ font
#
# General markup affects text between a start delimiter and an end
# delimiter. Not surprisingly, these delimiters look like HTML markup.
#
# <tt>\<b>_text_</b></tt>:: displays _text_ in a *bold* font
# <tt>\<em>_text_</em></tt>:: displays _text_ in an _emphasized_ font
# (alternate tag: <tt>\<i></tt>)
# <tt>\<tt>_text_\</tt></tt>:: displays _text_ in a +code+ font
# (alternate tag: <tt>\<code></tt>)
#
# Unlike conventional Wiki markup, general markup can cross line
# boundaries. You can turn off the interpretation of markup by
# preceding the first character with a backslash (see <i>Escaping
# Text Markup</i>, below).
#
# === Links
#
# Links to starting with +http:+, +https:+, +mailto:+, +ftp:+ or +www.+
# are recognized. An HTTP url that references an external image is converted
# into an inline image element.
#
# Classes and methods will be automatically linked to their definition. For
# example, <tt>RDoc::Markup</tt> will link to this documentation. By default
# methods will only be automatically linked if they contain an <tt>_</tt> (all
# methods can be automatically linked through the <tt>--hyperlink-all</tt>
# command line option).
#
# Single-word methods can be linked by using the <tt>#</tt> character for
# instance methods or <tt>::</tt> for class methods. For example,
# <tt>#convert</tt> links to #convert. A class or method may be combined like
# <tt>RDoc::Markup#convert</tt>.
#
# A heading inside the documentation can be linked by following the class
# or method by an <tt>@</tt> then the heading name.
# <tt>RDoc::Markup@Links</tt> will link to this section like this:
# RDoc::Markup@Links. Spaces in headings with multiple words must be escaped
# with <tt>+</tt> like <tt>RDoc::Markup@Escaping+Text+Markup</tt>.
# Punctuation and other special characters must be escaped like CGI.escape.
#
# The <tt>@</tt> can also be used to link to sections. If a section and a
# heading share the same name the section is preferred for the link.
#
# Links can also be of the form <tt>label[url]</tt>, in which case +label+ is
# used in the displayed text, and +url+ is used as the target. If +label+
# contains multiple words, put it in braces: <tt>{multi word label}[url]</tt>.
# The +url+ may be an +http:+-type link or a cross-reference to a class,
# module or method with a label.
#
# Links with the <code>rdoc-image:</code> scheme will create an image tag for
# HTML output. Only fully-qualified URLs are supported.
#
# Links with the <tt>rdoc-ref:</tt> scheme will link to the referenced class,
# module, method, file, etc. If the referenced item is does not exist
# no link will be generated and <tt>rdoc-ref:</tt> will be removed from the
# resulting text.
#
# Links starting with <tt>rdoc-label:label_name</tt> will link to the
# +label_name+. You can create a label for the current link (for
# bidirectional links) by supplying a name for the current link like
# <tt>rdoc-label:label-other:label-mine</tt>.
#
# Links starting with +link:+ refer to local files whose path is relative to
# the <tt>--op</tt> directory. Use <tt>rdoc-ref:</tt> instead of
# <tt>link:</tt> to link to files generated by RDoc as the link target may
# be different across RDoc generators.
#
# Example links:
#
# https://github.com/ruby/rdoc
# mailto:user@example.com
# {RDoc Documentation}[http://rdoc.rubyforge.org]
# {RDoc Markup}[rdoc-ref:RDoc::Markup]
# See RDoc::MarkupReference.
#
# === Escaping Text Markup
#
Expand Down