diff options
Diffstat (limited to 'lib/rdoc/markup.rb')
| -rw-r--r-- | lib/rdoc/markup.rb | 702 |
1 files changed, 35 insertions, 667 deletions
diff --git a/lib/rdoc/markup.rb b/lib/rdoc/markup.rb index 92aed757cf..6e93030965 100644 --- a/lib/rdoc/markup.rb +++ b/lib/rdoc/markup.rb @@ -97,638 +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::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] -# -# === Escaping Text Markup -# -# Text markup can be escaped with a backslash, as in \<tt>, which was obtained -# with <tt>\\<tt></tt>. Except in verbatim sections and between \<tt> tags, -# to produce a backslash you have to double it unless it is followed by a -# space, tab or newline. Otherwise, the HTML formatter will discard it, as it -# is used to escape potential links: -# -# * The \ must be doubled if not followed by white space: \\. -# * But not in \<tt> tags: in a Regexp, <tt>\S</tt> matches non-space. -# * This is a link to {ruby-lang}[www.ruby-lang.org]. -# * This is not a link, however: \{ruby-lang.org}[www.ruby-lang.org]. -# * This will not be linked to \RDoc::RDoc#document -# -# generates: -# -# * The \ must be doubled if not followed by white space: \\. -# * But not in \<tt> tags: in a Regexp, <tt>\S</tt> matches non-space. -# * This is a link to {ruby-lang}[www.ruby-lang.org] -# * This is not a link, however: \{ruby-lang.org}[www.ruby-lang.org] -# * This will not be linked to \RDoc::RDoc#document -# -# Inside \<tt> tags, more precisely, leading backslashes are removed only if -# followed by a markup character (<tt><*_+</tt>), a backslash, or a known link -# reference (a known class or method). So in the example above, the backslash -# of <tt>\S</tt> would be removed if there was a class or module named +S+ in -# the current context. -# -# This behavior is inherited from RDoc version 1, and has been kept for -# compatibility with existing RDoc documentation. -# -# === Conversion of characters -# -# HTML will convert two/three dashes to an em-dash. Other common characters are -# converted as well: -# -# em-dash:: -- or --- -# ellipsis:: ... -# -# single quotes:: 'text' or `text' -# double quotes:: "text" or ``text'' -# -# copyright:: (c) -# registered trademark:: (r) -# -# produces: -# -# em-dash:: -- or --- -# ellipsis:: ... -# -# single quotes:: 'text' or `text' -# double quotes:: "text" or ``text'' -# -# copyright:: (c) -# registered trademark:: (r) -# -# -# == Documenting Source Code -# -# Comment blocks can be written fairly naturally, either using <tt>#</tt> on -# successive lines of the comment, or by including the comment in -# a <tt>=begin</tt>/<tt>=end</tt> block. If you use the latter form, -# the <tt>=begin</tt> line _must_ be flagged with an +rdoc+ tag: -# -# =begin rdoc -# Documentation to be processed by RDoc. -# -# ... -# =end -# -# RDoc stops processing comments if it finds a comment line starting -# with <tt>--</tt> right after the <tt>#</tt> character (otherwise, -# it will be treated as a rule if it has three dashes or more). -# This can be used to separate external from internal comments, -# or to stop a comment being associated with a method, class, or module. -# Commenting can be turned back on with a line that starts with <tt>++</tt>. -# -# ## -# # Extract the age and calculate the date-of-birth. -# #-- -# # FIXME: fails if the birthday falls on February 29th -# #++ -# # The DOB is returned as a Time object. -# -# def get_dob(person) -# # ... -# end -# -# Names of classes, files, and any method names containing an underscore or -# preceded by a hash character are automatically linked from comment text to -# their description. This linking works inside the current class or module, -# and with ancestor methods (in included modules or in the superclass). -# -# Method parameter lists are extracted and displayed with the method -# description. If a method calls +yield+, then the parameters passed to yield -# will also be displayed: -# -# def fred -# ... -# yield line, address -# -# This will get documented as: -# -# fred() { |line, address| ... } -# -# You can override this using a comment containing ':yields: ...' immediately -# after the method definition -# -# def fred # :yields: index, position -# # ... -# -# yield line, address -# -# which will get documented as -# -# fred() { |index, position| ... } -# -# +:yields:+ is an example of a documentation directive. These appear -# immediately after the start of the document element they are modifying. -# -# RDoc automatically cross-references words with underscores or camel-case. -# To suppress cross-references, prefix the word with a \ character. To -# include special characters like "<tt>\n</tt>", you'll need to use -# two \ characters in normal text, but only one in \<tt> text: -# -# "\\n" or "<tt>\n</tt>" -# -# produces: -# -# "\\n" or "<tt>\n</tt>" -# -# == Directives -# -# Directives are keywords surrounded by ":" characters. -# -# === Controlling what is documented -# -# [+:nodoc:+ / <tt>:nodoc: all</tt>] -# This directive prevents documentation for the element from -# being generated. For classes and modules, methods, aliases, -# constants, and attributes directly within the affected class or -# module also will be omitted. By default, though, modules and -# classes within that class or module _will_ be documented. This is -# turned off by adding the +all+ modifier. -# -# module MyModule # :nodoc: -# class Input -# end -# end -# -# module OtherModule # :nodoc: all -# class Output -# end -# end -# -# In the above code, only class <tt>MyModule::Input</tt> will be documented. -# -# The +:nodoc:+ directive, like +:enddoc:+, +:stopdoc:+ and +:startdoc:+ -# presented below, is local to the current file: if you do not want to -# document a module that appears in several files, specify +:nodoc:+ on each -# appearance, at least once per file. -# -# [+:stopdoc:+ / +:startdoc:+] -# Stop and start adding new documentation elements to the current container. -# For example, if a class has a number of constants that you don't want to -# document, put a +:stopdoc:+ before the first, and a +:startdoc:+ after the -# last. If you don't specify a +:startdoc:+ by the end of the container, -# disables documentation for the rest of the current file. -# -# [+:doc:+] -# Forces a method or attribute to be documented even if it wouldn't be -# otherwise. Useful if, for example, you want to include documentation of a -# particular private method. -# -# [+:enddoc:+] -# Document nothing further at the current level: directives +:startdoc:+ and -# +:doc:+ that appear after this will not be honored for the current container -# (file, class or module), in the current file. -# -# [+:notnew:+ / +:not_new:+ / +:not-new:+ ] -# Only applicable to the +initialize+ instance method. Normally RDoc -# assumes that the documentation and parameters for +initialize+ are -# actually for the +new+ method, and so fakes out a +new+ for the class. -# The +:notnew:+ directive stops this. Remember that +initialize+ is private, -# so you won't see the documentation unless you use the +-a+ command line -# option. -# -# === Method arguments -# -# [+:arg:+ or +:args:+ _parameters_] -# Overrides the default argument handling with exactly these parameters. -# -# ## -# # :args: a, b -# -# def some_method(*a) -# end -# -# [+:yield:+ or +:yields:+ _parameters_] -# Overrides the default yield discovery with these parameters. -# -# ## -# # :yields: key, value -# -# def each_thing &block -# @things.each(&block) -# end -# -# [+:call-seq:+] -# Lines up to the next blank line or lines with a common prefix in the -# comment are treated as the method's calling sequence, overriding the -# default parsing of method parameters and yield arguments. -# -# Multiple lines may be used. -# -# # :call-seq: -# # ARGF.readlines(sep=$/) -> array -# # ARGF.readlines(limit) -> array -# # ARGF.readlines(sep, limit) -> array -# # -# # ARGF.to_a(sep=$/) -> array -# # ARGF.to_a(limit) -> array -# # ARGF.to_a(sep, limit) -> array -# # -# # The remaining lines are documentation ... -# -# === Sections -# -# Sections allow you to group methods in a class into sensible containers. If -# you use the sections 'Public', 'Internal' and 'Deprecated' (the three -# allowed method statuses from TomDoc) the sections will be displayed in that -# order placing the most useful methods at the top. Otherwise, sections will -# be displayed in alphabetical order. -# -# [+:category:+ _section_] -# Adds this item to the named +section+ overriding the current section. Use -# this to group methods by section in RDoc output while maintaining a -# sensible ordering (like alphabetical). -# -# # :category: Utility Methods -# # -# # CGI escapes +text+ -# -# def convert_string text -# CGI.escapeHTML text -# end -# -# An empty category will place the item in the default category: -# -# # :category: -# # -# # This method is in the default category -# -# def some_method -# # ... -# end -# -# Unlike the :section: directive, :category: is not sticky. The category -# only applies to the item immediately following the comment. -# -# Use the :section: directive to provide introductory text for a section of -# documentation. -# -# [+:section:+ _title_] -# Provides section introductory text in RDoc output. The title following -# +:section:+ is used as the section name and the remainder of the comment -# containing the section is used as introductory text. A section's comment -# block must be separated from following comment blocks. Use an empty title -# to switch to the default section. -# -# The :section: directive is sticky, so subsequent methods, aliases, -# attributes, and classes will be contained in this section until the -# section is changed. The :category: directive will override the :section: -# directive. -# -# A :section: comment block may have one or more lines before the :section: -# directive. These will be removed, and any identical lines at the end of -# the block are also removed. This allows you to add visual cues to the -# section. -# -# Example: -# -# # ---------------------------------------- -# # :section: My Section -# # This is the section that I wrote. -# # See it glisten in the noon-day sun. -# # ---------------------------------------- -# -# ## -# # Comment for some_method -# -# def some_method -# # ... -# end -# -# === Other directives -# -# [+:markup:+ _type_] -# Overrides the default markup type for this comment with the specified -# markup type. For Ruby files, if the first comment contains this directive -# it is applied automatically to all comments in the file. -# -# Unless you are converting between markup formats you should use a -# <code>.rdoc_options</code> file to specify the default documentation -# format for your entire project. See RDoc::Options@Saved+Options for -# instructions. -# -# At the top of a file the +:markup:+ directive applies to the entire file: -# -# # coding: UTF-8 -# # :markup: TomDoc -# -# # TomDoc comment here ... -# -# class MyClass -# # ... -# -# For just one comment: -# -# # ... -# end -# -# # :markup: RDoc -# # -# # This is a comment in RDoc markup format ... -# -# def some_method -# # ... -# -# See Markup@CONTRIBUTING for instructions on adding a new markup format. -# -# [+:include:+ _filename_] -# Include the contents of the named file at this point. This directive -# must appear alone on one line, possibly preceded by spaces. In this -# position, it can be escaped with a \ in front of the first colon. -# -# The file will be searched for in the directories listed by the +--include+ -# option, or in the current directory by default. The contents of the file -# will be shifted to have the same indentation as the ':' at the start of -# the +:include:+ directive. -# -# [+:title:+ _text_] -# Sets the title for the document. Equivalent to the <tt>--title</tt> -# command line parameter. (The command line parameter overrides any :title: -# directive in the source). -# -# [+:main:+ _name_] -# Equivalent to the <tt>--main</tt> command line parameter. +# See RDoc::MarkupReference. # #-- # Original Author:: Dave Thomas, dave@pragmaticprogrammer.com @@ -822,46 +191,45 @@ https://github.com/ruby/rdoc/issues document.accept formatter end - autoload :Parser, 'rdoc/markup/parser' - autoload :PreProcess, 'rdoc/markup/pre_process' + autoload :Parser, "#{__dir__}/markup/parser" + autoload :PreProcess, "#{__dir__}/markup/pre_process" # Inline markup classes - autoload :AttrChanger, 'rdoc/markup/attr_changer' - autoload :AttrSpan, 'rdoc/markup/attr_span' - autoload :Attributes, 'rdoc/markup/attributes' - autoload :AttributeManager, 'rdoc/markup/attribute_manager' - autoload :RegexpHandling, 'rdoc/markup/regexp_handling' + autoload :AttrChanger, "#{__dir__}/markup/attr_changer" + autoload :AttrSpan, "#{__dir__}/markup/attr_span" + autoload :Attributes, "#{__dir__}/markup/attributes" + autoload :AttributeManager, "#{__dir__}/markup/attribute_manager" + autoload :RegexpHandling, "#{__dir__}/markup/regexp_handling" # RDoc::Markup AST - autoload :BlankLine, 'rdoc/markup/blank_line' - autoload :BlockQuote, 'rdoc/markup/block_quote' - autoload :Document, 'rdoc/markup/document' - autoload :HardBreak, 'rdoc/markup/hard_break' - autoload :Heading, 'rdoc/markup/heading' - autoload :Include, 'rdoc/markup/include' - autoload :IndentedParagraph, 'rdoc/markup/indented_paragraph' - autoload :List, 'rdoc/markup/list' - autoload :ListItem, 'rdoc/markup/list_item' - autoload :Paragraph, 'rdoc/markup/paragraph' - autoload :Table, 'rdoc/markup/table' - autoload :Raw, 'rdoc/markup/raw' - autoload :Rule, 'rdoc/markup/rule' - autoload :Verbatim, 'rdoc/markup/verbatim' + autoload :BlankLine, "#{__dir__}/markup/blank_line" + autoload :BlockQuote, "#{__dir__}/markup/block_quote" + autoload :Document, "#{__dir__}/markup/document" + autoload :HardBreak, "#{__dir__}/markup/hard_break" + autoload :Heading, "#{__dir__}/markup/heading" + autoload :Include, "#{__dir__}/markup/include" + autoload :IndentedParagraph, "#{__dir__}/markup/indented_paragraph" + autoload :List, "#{__dir__}/markup/list" + autoload :ListItem, "#{__dir__}/markup/list_item" + autoload :Paragraph, "#{__dir__}/markup/paragraph" + autoload :Table, "#{__dir__}/markup/table" + autoload :Raw, "#{__dir__}/markup/raw" + autoload :Rule, "#{__dir__}/markup/rule" + autoload :Verbatim, "#{__dir__}/markup/verbatim" # Formatters - autoload :Formatter, 'rdoc/markup/formatter' - - autoload :ToAnsi, 'rdoc/markup/to_ansi' - autoload :ToBs, 'rdoc/markup/to_bs' - autoload :ToHtml, 'rdoc/markup/to_html' - autoload :ToHtmlCrossref, 'rdoc/markup/to_html_crossref' - autoload :ToHtmlSnippet, 'rdoc/markup/to_html_snippet' - autoload :ToLabel, 'rdoc/markup/to_label' - autoload :ToMarkdown, 'rdoc/markup/to_markdown' - autoload :ToRdoc, 'rdoc/markup/to_rdoc' - autoload :ToTableOfContents, 'rdoc/markup/to_table_of_contents' - autoload :ToTest, 'rdoc/markup/to_test' - autoload :ToTtOnly, 'rdoc/markup/to_tt_only' + autoload :Formatter, "#{__dir__}/markup/formatter" + + autoload :ToAnsi, "#{__dir__}/markup/to_ansi" + autoload :ToBs, "#{__dir__}/markup/to_bs" + autoload :ToHtml, "#{__dir__}/markup/to_html" + autoload :ToHtmlCrossref, "#{__dir__}/markup/to_html_crossref" + autoload :ToHtmlSnippet, "#{__dir__}/markup/to_html_snippet" + autoload :ToLabel, "#{__dir__}/markup/to_label" + autoload :ToMarkdown, "#{__dir__}/markup/to_markdown" + autoload :ToRdoc, "#{__dir__}/markup/to_rdoc" + autoload :ToTableOfContents, "#{__dir__}/markup/to_table_of_contents" + autoload :ToTest, "#{__dir__}/markup/to_test" + autoload :ToTtOnly, "#{__dir__}/markup/to_tt_only" end - |