rdoc 3.1 → 6.3.3
Sign up to get free protection for your applications and to get access to all the features.
Potentially problematic release.
This version of rdoc might be problematic. Click here for more details.
- checksums.yaml +7 -0
- data/CONTRIBUTING.rdoc +220 -0
- data/CVE-2013-0256.rdoc +49 -0
- data/ExampleMarkdown.md +37 -0
- data/ExampleRDoc.rdoc +208 -0
- data/Gemfile +12 -0
- data/History.rdoc +1666 -0
- data/LEGAL.rdoc +50 -0
- data/LICENSE.rdoc +57 -0
- data/README.rdoc +129 -0
- data/RI.rdoc +57 -0
- data/Rakefile +84 -81
- data/TODO.rdoc +59 -0
- data/bin/console +7 -0
- data/bin/setup +6 -0
- data/{bin → exe}/rdoc +11 -2
- data/exe/ri +12 -0
- data/lib/rdoc/alias.rb +1 -2
- data/lib/rdoc/anon_class.rb +3 -2
- data/lib/rdoc/any_method.rb +234 -40
- data/lib/rdoc/attr.rb +79 -11
- data/lib/rdoc/class_module.rb +443 -71
- data/lib/rdoc/code_object.rb +216 -20
- data/lib/rdoc/code_objects.rb +4 -21
- data/lib/rdoc/comment.rb +250 -0
- data/lib/rdoc/constant.rb +110 -9
- data/lib/rdoc/context/section.rb +232 -0
- data/lib/rdoc/context.rb +392 -172
- data/lib/rdoc/cross_reference.rb +202 -0
- data/lib/rdoc/encoding.rb +83 -28
- data/lib/rdoc/erb_partial.rb +19 -0
- data/lib/rdoc/erbio.rb +8 -3
- data/lib/rdoc/extend.rb +10 -0
- data/lib/rdoc/generator/darkfish.rb +507 -84
- data/lib/rdoc/generator/json_index.rb +300 -0
- data/lib/rdoc/generator/markup.rb +27 -74
- data/lib/rdoc/generator/pot/message_extractor.rb +68 -0
- data/lib/rdoc/generator/pot/po.rb +84 -0
- data/lib/rdoc/generator/pot/po_entry.rb +141 -0
- data/lib/rdoc/generator/pot.rb +98 -0
- data/lib/rdoc/generator/ri.rb +8 -62
- data/lib/rdoc/generator/template/darkfish/_footer.rhtml +5 -0
- data/lib/rdoc/generator/template/darkfish/_head.rhtml +22 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_VCS_info.rhtml +19 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_classes.rhtml +9 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_extends.rhtml +15 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_in_files.rhtml +9 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_includes.rhtml +15 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_installed.rhtml +15 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_methods.rhtml +12 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_navigation.rhtml +11 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_pages.rhtml +12 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_parent.rhtml +11 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_search.rhtml +14 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_sections.rhtml +11 -0
- data/lib/rdoc/generator/template/darkfish/_sidebar_table_of_contents.rhtml +18 -0
- data/lib/rdoc/generator/template/darkfish/class.rhtml +172 -0
- data/lib/rdoc/generator/template/darkfish/css/fonts.css +167 -0
- data/lib/rdoc/generator/template/darkfish/css/rdoc.css +639 -0
- data/lib/rdoc/generator/template/darkfish/fonts/Lato-Light.ttf +0 -0
- data/lib/rdoc/generator/template/darkfish/fonts/Lato-LightItalic.ttf +0 -0
- data/lib/rdoc/generator/template/darkfish/fonts/Lato-Regular.ttf +0 -0
- data/lib/rdoc/generator/template/darkfish/fonts/Lato-RegularItalic.ttf +0 -0
- data/lib/rdoc/generator/template/darkfish/fonts/SourceCodePro-Bold.ttf +0 -0
- data/lib/rdoc/generator/template/darkfish/fonts/SourceCodePro-Regular.ttf +0 -0
- data/lib/rdoc/generator/template/darkfish/images/add.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/arrow_up.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/delete.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/tag_blue.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/transparent.png +0 -0
- data/lib/rdoc/generator/template/darkfish/index.rhtml +18 -60
- data/lib/rdoc/generator/template/darkfish/js/darkfish.js +51 -83
- data/lib/rdoc/generator/template/darkfish/js/search.js +110 -0
- data/lib/rdoc/generator/template/darkfish/page.rhtml +18 -0
- data/lib/rdoc/generator/template/darkfish/servlet_not_found.rhtml +18 -0
- data/lib/rdoc/generator/template/darkfish/servlet_root.rhtml +62 -0
- data/lib/rdoc/generator/template/darkfish/table_of_contents.rhtml +58 -0
- data/lib/rdoc/generator/template/json_index/.document +1 -0
- data/lib/rdoc/generator/template/json_index/js/navigation.js +105 -0
- data/lib/rdoc/generator/template/json_index/js/searcher.js +229 -0
- data/lib/rdoc/generator.rb +24 -13
- data/lib/rdoc/ghost_method.rb +1 -2
- data/lib/rdoc/i18n/locale.rb +102 -0
- data/lib/rdoc/i18n/text.rb +126 -0
- data/lib/rdoc/i18n.rb +10 -0
- data/lib/rdoc/include.rb +5 -95
- data/lib/rdoc/known_classes.rb +5 -2
- data/lib/rdoc/markdown/entities.rb +2132 -0
- data/lib/rdoc/markdown/literals.kpeg +23 -0
- data/lib/rdoc/markdown/literals.rb +416 -0
- data/lib/rdoc/markdown.kpeg +1237 -0
- data/lib/rdoc/markdown.rb +16684 -0
- data/lib/rdoc/markup/attr_changer.rb +23 -0
- data/lib/rdoc/markup/attr_span.rb +36 -0
- data/lib/rdoc/markup/attribute_manager.rb +135 -62
- data/lib/rdoc/markup/attributes.rb +71 -0
- data/lib/rdoc/markup/blank_line.rb +1 -0
- data/lib/rdoc/markup/block_quote.rb +15 -0
- data/lib/rdoc/markup/document.rb +96 -9
- data/lib/rdoc/markup/formatter.rb +138 -25
- data/lib/rdoc/markup/hard_break.rb +32 -0
- data/lib/rdoc/markup/heading.rb +61 -2
- data/lib/rdoc/markup/include.rb +43 -0
- data/lib/rdoc/markup/indented_paragraph.rb +48 -0
- data/lib/rdoc/markup/list.rb +25 -4
- data/lib/rdoc/markup/list_item.rb +18 -4
- data/lib/rdoc/markup/paragraph.rb +15 -0
- data/lib/rdoc/markup/parser.rb +180 -88
- data/lib/rdoc/markup/pre_process.rb +183 -38
- data/lib/rdoc/markup/raw.rb +6 -5
- data/lib/rdoc/markup/regexp_handling.rb +41 -0
- data/lib/rdoc/markup/rule.rb +1 -0
- data/lib/rdoc/markup/table.rb +47 -0
- data/lib/rdoc/markup/to_ansi.rb +17 -7
- data/lib/rdoc/markup/to_bs.rb +5 -8
- data/lib/rdoc/markup/to_html.rb +238 -137
- data/lib/rdoc/markup/to_html_crossref.rb +125 -152
- data/lib/rdoc/markup/to_html_snippet.rb +285 -0
- data/lib/rdoc/markup/to_joined_paragraph.rb +47 -0
- data/lib/rdoc/markup/to_label.rb +75 -0
- data/lib/rdoc/markup/to_markdown.rb +192 -0
- data/lib/rdoc/markup/to_rdoc.rb +85 -15
- data/lib/rdoc/markup/to_table_of_contents.rb +89 -0
- data/lib/rdoc/markup/to_test.rb +2 -4
- data/lib/rdoc/markup/to_tt_only.rb +121 -0
- data/lib/rdoc/markup/verbatim.rb +39 -0
- data/lib/rdoc/markup.rb +388 -110
- data/lib/rdoc/meta_method.rb +1 -2
- data/lib/rdoc/method_attr.rb +87 -21
- data/lib/rdoc/mixin.rb +121 -0
- data/lib/rdoc/normal_class.rb +39 -10
- data/lib/rdoc/normal_module.rb +22 -7
- data/lib/rdoc/options.rb +613 -73
- data/lib/rdoc/parser/c.rb +621 -287
- data/lib/rdoc/parser/changelog.rb +335 -0
- data/lib/rdoc/parser/markdown.rb +24 -0
- data/lib/rdoc/parser/rd.rb +23 -0
- data/lib/rdoc/parser/ripper_state_lex.rb +590 -0
- data/lib/rdoc/parser/ruby.rb +1368 -762
- data/lib/rdoc/parser/ruby_tools.rb +42 -35
- data/lib/rdoc/parser/simple.rb +23 -11
- data/lib/rdoc/parser/text.rb +12 -0
- data/lib/rdoc/parser.rb +162 -89
- data/lib/rdoc/rd/block_parser.rb +1056 -0
- data/lib/rdoc/rd/block_parser.ry +639 -0
- data/lib/rdoc/rd/inline.rb +72 -0
- data/lib/rdoc/rd/inline_parser.rb +1208 -0
- data/lib/rdoc/rd/inline_parser.ry +593 -0
- data/lib/rdoc/rd.rb +100 -0
- data/lib/rdoc/rdoc.rb +208 -115
- data/lib/rdoc/require.rb +1 -2
- data/lib/rdoc/ri/driver.rb +734 -239
- data/lib/rdoc/ri/formatter.rb +1 -0
- data/lib/rdoc/ri/paths.rb +91 -48
- data/lib/rdoc/ri/store.rb +3 -261
- data/lib/rdoc/ri/task.rb +71 -0
- data/lib/rdoc/ri.rb +5 -2
- data/lib/rdoc/rubygems_hook.rb +246 -0
- data/lib/rdoc/servlet.rb +451 -0
- data/lib/rdoc/single_class.rb +14 -2
- data/lib/rdoc/stats/normal.rb +19 -12
- data/lib/rdoc/stats/quiet.rb +1 -0
- data/lib/rdoc/stats/verbose.rb +1 -0
- data/lib/rdoc/stats.rb +262 -104
- data/lib/rdoc/store.rb +979 -0
- data/lib/rdoc/task.rb +84 -44
- data/lib/rdoc/text.rb +117 -72
- data/lib/rdoc/token_stream.rb +73 -4
- data/lib/rdoc/tom_doc.rb +263 -0
- data/lib/rdoc/top_level.rb +111 -261
- data/lib/rdoc/version.rb +8 -0
- data/lib/rdoc.rb +127 -64
- data/man/ri.1 +247 -0
- data/rdoc.gemspec +249 -0
- metadata +171 -291
- data/.autotest +0 -16
- data/.document +0 -5
- data/History.txt +0 -594
- data/LICENSE.txt +0 -57
- data/Manifest.txt +0 -158
- data/README.txt +0 -45
- data/RI.txt +0 -58
- data/bin/ri +0 -5
- data/lib/rdoc/gauntlet.rb +0 -52
- data/lib/rdoc/generator/template/darkfish/classpage.rhtml +0 -296
- data/lib/rdoc/generator/template/darkfish/filepage.rhtml +0 -124
- data/lib/rdoc/generator/template/darkfish/js/jquery.js +0 -32
- data/lib/rdoc/generator/template/darkfish/js/quicksearch.js +0 -114
- data/lib/rdoc/generator/template/darkfish/js/thickbox-compressed.js +0 -10
- data/lib/rdoc/generator/template/darkfish/rdoc.css +0 -706
- data/lib/rdoc/markup/formatter_test_case.rb +0 -689
- data/lib/rdoc/markup/inline.rb +0 -137
- data/lib/rdoc/markup/text_formatter_test_case.rb +0 -116
- data/lib/rdoc/ruby_lex.rb +0 -1291
- data/lib/rdoc/ruby_token.rb +0 -416
- data/test/README +0 -1
- data/test/binary.dat +0 -0
- data/test/hidden.zip.txt +0 -1
- data/test/test.ja.rdoc +0 -10
- data/test/test.ja.txt +0 -8
- data/test/test.txt +0 -1
- data/test/test_attribute_manager.rb +0 -120
- data/test/test_rdoc_alias.rb +0 -13
- data/test/test_rdoc_any_method.rb +0 -126
- data/test/test_rdoc_attr.rb +0 -61
- data/test/test_rdoc_class_module.rb +0 -233
- data/test/test_rdoc_code_object.rb +0 -165
- data/test/test_rdoc_constant.rb +0 -15
- data/test/test_rdoc_context.rb +0 -370
- data/test/test_rdoc_encoding.rb +0 -166
- data/test/test_rdoc_generator_darkfish.rb +0 -119
- data/test/test_rdoc_generator_ri.rb +0 -76
- data/test/test_rdoc_include.rb +0 -96
- data/test/test_rdoc_markup.rb +0 -37
- data/test/test_rdoc_markup_attribute_manager.rb +0 -240
- data/test/test_rdoc_markup_document.rb +0 -51
- data/test/test_rdoc_markup_paragraph.rb +0 -9
- data/test/test_rdoc_markup_parser.rb +0 -1395
- data/test/test_rdoc_markup_pre_process.rb +0 -185
- data/test/test_rdoc_markup_raw.rb +0 -27
- data/test/test_rdoc_markup_to_ansi.rb +0 -328
- data/test/test_rdoc_markup_to_bs.rb +0 -341
- data/test/test_rdoc_markup_to_html.rb +0 -335
- data/test/test_rdoc_markup_to_html_crossref.rb +0 -169
- data/test/test_rdoc_markup_to_rdoc.rb +0 -327
- data/test/test_rdoc_method_attr.rb +0 -122
- data/test/test_rdoc_normal_class.rb +0 -17
- data/test/test_rdoc_normal_module.rb +0 -31
- data/test/test_rdoc_options.rb +0 -342
- data/test/test_rdoc_parser.rb +0 -83
- data/test/test_rdoc_parser_c.rb +0 -912
- data/test/test_rdoc_parser_ruby.rb +0 -1754
- data/test/test_rdoc_parser_simple.rb +0 -99
- data/test/test_rdoc_rdoc.rb +0 -164
- data/test/test_rdoc_require.rb +0 -25
- data/test/test_rdoc_ri_driver.rb +0 -846
- data/test/test_rdoc_ri_paths.rb +0 -43
- data/test/test_rdoc_ri_store.rb +0 -352
- data/test/test_rdoc_ruby_lex.rb +0 -23
- data/test/test_rdoc_stats.rb +0 -38
- data/test/test_rdoc_task.rb +0 -92
- data/test/test_rdoc_text.rb +0 -251
- data/test/test_rdoc_top_level.rb +0 -120
- data/test/xref_data.rb +0 -62
- data/test/xref_test_case.rb +0 -61
- data.tar.gz.sig +0 -3
- metadata.gz.sig +0 -0
data/lib/rdoc/markup.rb
CHANGED
@@ -1,5 +1,4 @@
|
|
1
|
-
|
2
|
-
|
1
|
+
# frozen_string_literal: true
|
3
2
|
##
|
4
3
|
# RDoc::Markup parses plain text documents and attempts to decompose them into
|
5
4
|
# their constituent parts. Some of these parts are high-level: paragraphs,
|
@@ -8,11 +7,44 @@ require 'rdoc'
|
|
8
7
|
# is similar in spirit to that used on WikiWiki webs, where folks create web
|
9
8
|
# pages using a simple set of formatting rules.
|
10
9
|
#
|
11
|
-
# RDoc::Markup
|
12
|
-
#
|
10
|
+
# RDoc::Markup and other markup formats do no output formatting, this is
|
11
|
+
# handled by the RDoc::Markup::Formatter subclasses.
|
12
|
+
#
|
13
|
+
# = Supported Formats
|
14
|
+
#
|
15
|
+
# Besides the RDoc::Markup format, the following formats are built in to RDoc:
|
16
|
+
#
|
17
|
+
# markdown::
|
18
|
+
# The markdown format as described by
|
19
|
+
# http://daringfireball.net/projects/markdown/. See RDoc::Markdown for
|
20
|
+
# details on the parser and supported extensions.
|
21
|
+
# rd::
|
22
|
+
# The rdtool format. See RDoc::RD for details on the parser and format.
|
23
|
+
# tomdoc::
|
24
|
+
# The TomDoc format as described by http://tomdoc.org/. See RDoc::TomDoc
|
25
|
+
# for details on the parser and supported extensions.
|
26
|
+
#
|
27
|
+
# You can choose a markup format using the following methods:
|
28
|
+
#
|
29
|
+
# per project::
|
30
|
+
# If you build your documentation with rake use RDoc::Task#markup.
|
31
|
+
#
|
32
|
+
# If you build your documentation by hand run:
|
13
33
|
#
|
14
|
-
#
|
15
|
-
#
|
34
|
+
# rdoc --markup your_favorite_format --write-options
|
35
|
+
#
|
36
|
+
# and commit <tt>.rdoc_options</tt> and ship it with your packaged gem.
|
37
|
+
# per file::
|
38
|
+
# At the top of the file use the <tt>:markup:</tt> directive to set the
|
39
|
+
# default format for the rest of the file.
|
40
|
+
# per comment::
|
41
|
+
# Use the <tt>:markup:</tt> directive at the top of a comment you want
|
42
|
+
# to write in a different format.
|
43
|
+
#
|
44
|
+
# = RDoc::Markup
|
45
|
+
#
|
46
|
+
# RDoc::Markup is extensible at runtime: you can add \new markup elements to
|
47
|
+
# be recognized in the documents that RDoc::Markup parses.
|
16
48
|
#
|
17
49
|
# RDoc::Markup is intended to be the basis for a family of tools which share
|
18
50
|
# the common requirement that simple, plain-text should be rendered in a
|
@@ -26,42 +58,40 @@ require 'rdoc'
|
|
26
58
|
# the +convert+ method, so you can use the same RDoc::Markup converter to
|
27
59
|
# convert multiple input strings.
|
28
60
|
#
|
29
|
-
# require 'rdoc
|
61
|
+
# require 'rdoc'
|
30
62
|
#
|
31
|
-
# h = RDoc::Markup::ToHtml.new
|
63
|
+
# h = RDoc::Markup::ToHtml.new(RDoc::Options.new)
|
32
64
|
#
|
33
65
|
# puts h.convert(input_string)
|
34
66
|
#
|
35
|
-
# You can extend the RDoc::Markup parser to
|
36
|
-
# sequences, and to add
|
37
|
-
#
|
38
|
-
#
|
39
|
-
# strike-through text. When then subclass the HTML output class to deal
|
67
|
+
# You can extend the RDoc::Markup parser to recognize new markup
|
68
|
+
# sequences, and to add regexp handling. Here we make WikiWords significant to
|
69
|
+
# the parser, and also make the sequences {word} and \<no>text...</no> signify
|
70
|
+
# strike-through text. We then subclass the HTML output class to deal
|
40
71
|
# with these:
|
41
72
|
#
|
42
|
-
# require 'rdoc
|
43
|
-
# require 'rdoc/markup/to_html'
|
73
|
+
# require 'rdoc'
|
44
74
|
#
|
45
75
|
# class WikiHtml < RDoc::Markup::ToHtml
|
46
|
-
# def
|
47
|
-
# "<font color=red>" +
|
76
|
+
# def handle_regexp_WIKIWORD(target)
|
77
|
+
# "<font color=red>" + target.text + "</font>"
|
48
78
|
# end
|
49
79
|
# end
|
50
80
|
#
|
51
|
-
#
|
52
|
-
#
|
53
|
-
#
|
81
|
+
# markup = RDoc::Markup.new
|
82
|
+
# markup.add_word_pair("{", "}", :STRIKE)
|
83
|
+
# markup.add_html("no", :STRIKE)
|
54
84
|
#
|
55
|
-
#
|
85
|
+
# markup.add_regexp_handling(/\b([A-Z][a-z]+[A-Z]\w+)/, :WIKIWORD)
|
56
86
|
#
|
57
|
-
# wh = WikiHtml.new
|
87
|
+
# wh = WikiHtml.new RDoc::Options.new, markup
|
58
88
|
# wh.add_tag(:STRIKE, "<strike>", "</strike>")
|
59
89
|
#
|
60
90
|
# puts "<body>#{wh.convert ARGF.read}</body>"
|
61
91
|
#
|
62
92
|
# == Encoding
|
63
93
|
#
|
64
|
-
# Where Encoding support is available RDoc will automatically convert all
|
94
|
+
# Where Encoding support is available, RDoc will automatically convert all
|
65
95
|
# documents to the same output encoding. The output encoding can be set via
|
66
96
|
# RDoc::Options#encoding and defaults to Encoding.default_external.
|
67
97
|
#
|
@@ -96,7 +126,12 @@ require 'rdoc'
|
|
96
126
|
# have been removed. In addition, the verbatim text has been shifted
|
97
127
|
# left, so the amount of indentation of verbatim text is unimportant.
|
98
128
|
#
|
99
|
-
#
|
129
|
+
# For HTML output RDoc makes a small effort to determine if a verbatim section
|
130
|
+
# contains Ruby source code. If so, the verbatim block will be marked up as
|
131
|
+
# HTML. Triggers include "def", "class", "module", "require", the "hash
|
132
|
+
# rocket"# (=>) or a block call with a parameter.
|
133
|
+
#
|
134
|
+
# === Headers
|
100
135
|
#
|
101
136
|
# A line starting with an equal sign (=) is treated as a
|
102
137
|
# heading. Level one headings have one equals sign, level two headings
|
@@ -104,30 +139,50 @@ require 'rdoc'
|
|
104
139
|
# (seven hyphens or more result in a level six heading).
|
105
140
|
#
|
106
141
|
# For example, the above header was obtained with:
|
107
|
-
# == Headers and Rules
|
108
142
|
#
|
109
|
-
#
|
110
|
-
#
|
111
|
-
#
|
143
|
+
# === Headers
|
144
|
+
#
|
145
|
+
# In HTML output headers have an id matching their name. The above example's
|
146
|
+
# HTML is:
|
112
147
|
#
|
113
|
-
#
|
114
|
-
#
|
115
|
-
#
|
148
|
+
# <h3 id="label-Headers">Headers</h3>
|
149
|
+
#
|
150
|
+
# If a heading is inside a method body the id will be prefixed with the
|
151
|
+
# method's id. If the above header where in the documentation for a method
|
152
|
+
# such as:
|
153
|
+
#
|
154
|
+
# ##
|
155
|
+
# # This method does fun things
|
156
|
+
# #
|
157
|
+
# # = Example
|
158
|
+
# #
|
159
|
+
# # Example of fun things goes here ...
|
160
|
+
#
|
161
|
+
# def do_fun_things
|
162
|
+
# end
|
163
|
+
#
|
164
|
+
# The header's id would be:
|
165
|
+
#
|
166
|
+
# <h1 id="method-i-do_fun_things-label-Example">Example</h1>
|
167
|
+
#
|
168
|
+
# The label can be linked-to using <tt>SomeClass@Headers</tt>. See
|
169
|
+
# {Links}[RDoc::Markup@Links] for further details.
|
170
|
+
#
|
171
|
+
# === Rules
|
172
|
+
#
|
173
|
+
# A line starting with three or more hyphens (at the current indent)
|
174
|
+
# generates a horizontal rule.
|
116
175
|
#
|
117
176
|
# ---
|
118
|
-
# -----
|
119
|
-
# -----------------------------------------------------
|
120
177
|
#
|
121
178
|
# produces:
|
122
179
|
#
|
123
180
|
# ---
|
124
|
-
# -----
|
125
|
-
# -----------------------------------------------------
|
126
181
|
#
|
127
182
|
# === Simple Lists
|
128
183
|
#
|
129
184
|
# If a paragraph starts with a "*", "-", "<digit>." or "<letter>.",
|
130
|
-
# then it is taken to be the start of a list. The margin
|
185
|
+
# then it is taken to be the start of a list. The margin is increased to be
|
131
186
|
# the first non-space following the list start flag. Subsequent lines
|
132
187
|
# should be indented to this new margin until the list ends. For example:
|
133
188
|
#
|
@@ -240,7 +295,6 @@ require 'rdoc'
|
|
240
295
|
# verbatim text outside of the list (the list is therefore closed)
|
241
296
|
# regular paragraph after the list
|
242
297
|
#
|
243
|
-
#
|
244
298
|
# == Text Markup
|
245
299
|
#
|
246
300
|
# === Bold, Italic, Typewriter Text
|
@@ -269,40 +323,77 @@ require 'rdoc'
|
|
269
323
|
# preceding the first character with a backslash (see <i>Escaping
|
270
324
|
# Text Markup</i>, below).
|
271
325
|
#
|
272
|
-
# ===
|
326
|
+
# === Links
|
327
|
+
#
|
328
|
+
# Links to starting with +http:+, +https:+, +mailto:+, +ftp:+ or +www.+
|
329
|
+
# are recognized. An HTTP url that references an external image is converted
|
330
|
+
# into an inline image element.
|
273
331
|
#
|
274
|
-
#
|
275
|
-
#
|
276
|
-
#
|
277
|
-
#
|
278
|
-
#
|
332
|
+
# Classes and methods will be automatically linked to their definition. For
|
333
|
+
# example, <tt>RDoc::Markup</tt> will link to this documentation. By default
|
334
|
+
# methods will only be automatically linked if they contain an <tt>_</tt> (all
|
335
|
+
# methods can be automatically linked through the <tt>--hyperlink-all</tt>
|
336
|
+
# command line option).
|
279
337
|
#
|
280
|
-
#
|
281
|
-
#
|
282
|
-
#
|
283
|
-
#
|
338
|
+
# Single-word methods can be linked by using the <tt>#</tt> character for
|
339
|
+
# instance methods or <tt>::</tt> for class methods. For example,
|
340
|
+
# <tt>#convert</tt> links to #convert. A class or method may be combined like
|
341
|
+
# <tt>RDoc::Markup#convert</tt>.
|
284
342
|
#
|
285
|
-
#
|
343
|
+
# A heading inside the documentation can be linked by following the class
|
344
|
+
# or method by an <tt>@</tt> then the heading name.
|
345
|
+
# <tt>RDoc::Markup@Links</tt> will link to this section like this:
|
346
|
+
# RDoc::Markup@Links. Spaces in headings with multiple words must be escaped
|
347
|
+
# with <tt>+</tt> like <tt>RDoc::Markup@Escaping+Text+Markup</tt>.
|
348
|
+
# Punctuation and other special characters must be escaped like CGI.escape.
|
286
349
|
#
|
287
|
-
#
|
288
|
-
#
|
350
|
+
# The <tt>@</tt> can also be used to link to sections. If a section and a
|
351
|
+
# heading share the same name the section is preferred for the link.
|
352
|
+
#
|
353
|
+
# Links can also be of the form <tt>label[url]</tt>, in which case +label+ is
|
354
|
+
# used in the displayed text, and +url+ is used as the target. If +label+
|
355
|
+
# contains multiple words, put it in braces: <tt>{multi word label}[url]</tt>.
|
356
|
+
# The +url+ may be an +http:+-type link or a cross-reference to a class,
|
357
|
+
# module or method with a label.
|
358
|
+
#
|
359
|
+
# Links with the <code>rdoc-image:</code> scheme will create an image tag for
|
360
|
+
# HTML output. Only fully-qualified URLs are supported.
|
361
|
+
#
|
362
|
+
# Links with the <tt>rdoc-ref:</tt> scheme will link to the referenced class,
|
363
|
+
# module, method, file, etc. If the referenced item is does not exist
|
364
|
+
# no link will be generated and <tt>rdoc-ref:</tt> will be removed from the
|
365
|
+
# resulting text.
|
366
|
+
#
|
367
|
+
# Links starting with <tt>rdoc-label:label_name</tt> will link to the
|
368
|
+
# +label_name+. You can create a label for the current link (for
|
369
|
+
# bidirectional links) by supplying a name for the current link like
|
370
|
+
# <tt>rdoc-label:label-other:label-mine</tt>.
|
371
|
+
#
|
372
|
+
# Links starting with +link:+ refer to local files whose path is relative to
|
373
|
+
# the <tt>--op</tt> directory. Use <tt>rdoc-ref:</tt> instead of
|
374
|
+
# <tt>link:</tt> to link to files generated by RDoc as the link target may
|
375
|
+
# be different across RDoc generators.
|
376
|
+
#
|
377
|
+
# Example links:
|
378
|
+
#
|
379
|
+
# https://github.com/ruby/rdoc
|
289
380
|
# mailto:user@example.com
|
290
381
|
# {RDoc Documentation}[http://rdoc.rubyforge.org]
|
291
|
-
# {RDoc Markup}[
|
382
|
+
# {RDoc Markup}[rdoc-ref:RDoc::Markup]
|
292
383
|
#
|
293
384
|
# === Escaping Text Markup
|
294
385
|
#
|
295
386
|
# Text markup can be escaped with a backslash, as in \<tt>, which was obtained
|
296
|
-
# with
|
297
|
-
# to produce a backslash
|
387
|
+
# with <tt>\\<tt></tt>. Except in verbatim sections and between \<tt> tags,
|
388
|
+
# to produce a backslash you have to double it unless it is followed by a
|
298
389
|
# space, tab or newline. Otherwise, the HTML formatter will discard it, as it
|
299
|
-
# is used to escape potential
|
390
|
+
# is used to escape potential links:
|
300
391
|
#
|
301
392
|
# * The \ must be doubled if not followed by white space: \\.
|
302
393
|
# * But not in \<tt> tags: in a Regexp, <tt>\S</tt> matches non-space.
|
303
394
|
# * This is a link to {ruby-lang}[www.ruby-lang.org].
|
304
395
|
# * This is not a link, however: \{ruby-lang.org}[www.ruby-lang.org].
|
305
|
-
# * This will not be
|
396
|
+
# * This will not be linked to \RDoc::RDoc#document
|
306
397
|
#
|
307
398
|
# generates:
|
308
399
|
#
|
@@ -310,16 +401,16 @@ require 'rdoc'
|
|
310
401
|
# * But not in \<tt> tags: in a Regexp, <tt>\S</tt> matches non-space.
|
311
402
|
# * This is a link to {ruby-lang}[www.ruby-lang.org]
|
312
403
|
# * This is not a link, however: \{ruby-lang.org}[www.ruby-lang.org]
|
313
|
-
# * This will not be
|
404
|
+
# * This will not be linked to \RDoc::RDoc#document
|
314
405
|
#
|
315
|
-
# Inside \<tt> tags, more precisely, leading backslashes are removed
|
316
|
-
#
|
317
|
-
#
|
318
|
-
#
|
319
|
-
#
|
406
|
+
# Inside \<tt> tags, more precisely, leading backslashes are removed only if
|
407
|
+
# followed by a markup character (<tt><*_+</tt>), a backslash, or a known link
|
408
|
+
# reference (a known class or method). So in the example above, the backslash
|
409
|
+
# of <tt>\S</tt> would be removed if there was a class or module named +S+ in
|
410
|
+
# the current context.
|
320
411
|
#
|
321
|
-
# This behavior is inherited from RDoc version 1, and has been kept
|
322
|
-
#
|
412
|
+
# This behavior is inherited from RDoc version 1, and has been kept for
|
413
|
+
# compatibility with existing RDoc documentation.
|
323
414
|
#
|
324
415
|
# === Conversion of characters
|
325
416
|
#
|
@@ -378,11 +469,10 @@ require 'rdoc'
|
|
378
469
|
# # ...
|
379
470
|
# end
|
380
471
|
#
|
381
|
-
# Names of classes, files, and any method names containing an
|
382
|
-
#
|
383
|
-
#
|
384
|
-
#
|
385
|
-
# or in the superclass).
|
472
|
+
# Names of classes, files, and any method names containing an underscore or
|
473
|
+
# preceded by a hash character are automatically linked from comment text to
|
474
|
+
# their description. This linking works inside the current class or module,
|
475
|
+
# and with ancestor methods (in included modules or in the superclass).
|
386
476
|
#
|
387
477
|
# Method parameter lists are extracted and displayed with the method
|
388
478
|
# description. If a method calls +yield+, then the parameters passed to yield
|
@@ -430,10 +520,10 @@ require 'rdoc'
|
|
430
520
|
#
|
431
521
|
# [+:nodoc:+ / <tt>:nodoc: all</tt>]
|
432
522
|
# This directive prevents documentation for the element from
|
433
|
-
# being generated. For classes and modules,
|
523
|
+
# being generated. For classes and modules, methods, aliases,
|
434
524
|
# constants, and attributes directly within the affected class or
|
435
525
|
# module also will be omitted. By default, though, modules and
|
436
|
-
# classes within that class
|
526
|
+
# classes within that class or module _will_ be documented. This is
|
437
527
|
# turned off by adding the +all+ modifier.
|
438
528
|
#
|
439
529
|
# module MyModule # :nodoc:
|
@@ -478,12 +568,154 @@ require 'rdoc'
|
|
478
568
|
# so you won't see the documentation unless you use the +-a+ command line
|
479
569
|
# option.
|
480
570
|
#
|
571
|
+
# === Method arguments
|
572
|
+
#
|
573
|
+
# [+:arg:+ or +:args:+ _parameters_]
|
574
|
+
# Overrides the default argument handling with exactly these parameters.
|
575
|
+
#
|
576
|
+
# ##
|
577
|
+
# # :args: a, b
|
578
|
+
#
|
579
|
+
# def some_method(*a)
|
580
|
+
# end
|
581
|
+
#
|
582
|
+
# [+:yield:+ or +:yields:+ _parameters_]
|
583
|
+
# Overrides the default yield discovery with these parameters.
|
584
|
+
#
|
585
|
+
# ##
|
586
|
+
# # :yields: key, value
|
587
|
+
#
|
588
|
+
# def each_thing &block
|
589
|
+
# @things.each(&block)
|
590
|
+
# end
|
591
|
+
#
|
592
|
+
# [+:call-seq:+]
|
593
|
+
# Lines up to the next blank line or lines with a common prefix in the
|
594
|
+
# comment are treated as the method's calling sequence, overriding the
|
595
|
+
# default parsing of method parameters and yield arguments.
|
596
|
+
#
|
597
|
+
# Multiple lines may be used.
|
598
|
+
#
|
599
|
+
# # :call-seq:
|
600
|
+
# # ARGF.readlines(sep=$/) -> array
|
601
|
+
# # ARGF.readlines(limit) -> array
|
602
|
+
# # ARGF.readlines(sep, limit) -> array
|
603
|
+
# #
|
604
|
+
# # ARGF.to_a(sep=$/) -> array
|
605
|
+
# # ARGF.to_a(limit) -> array
|
606
|
+
# # ARGF.to_a(sep, limit) -> array
|
607
|
+
# #
|
608
|
+
# # The remaining lines are documentation ...
|
609
|
+
#
|
610
|
+
# === Sections
|
611
|
+
#
|
612
|
+
# Sections allow you to group methods in a class into sensible containers. If
|
613
|
+
# you use the sections 'Public', 'Internal' and 'Deprecated' (the three
|
614
|
+
# allowed method statuses from TomDoc) the sections will be displayed in that
|
615
|
+
# order placing the most useful methods at the top. Otherwise, sections will
|
616
|
+
# be displayed in alphabetical order.
|
617
|
+
#
|
618
|
+
# [+:category:+ _section_]
|
619
|
+
# Adds this item to the named +section+ overriding the current section. Use
|
620
|
+
# this to group methods by section in RDoc output while maintaining a
|
621
|
+
# sensible ordering (like alphabetical).
|
622
|
+
#
|
623
|
+
# # :category: Utility Methods
|
624
|
+
# #
|
625
|
+
# # CGI escapes +text+
|
626
|
+
#
|
627
|
+
# def convert_string text
|
628
|
+
# CGI.escapeHTML text
|
629
|
+
# end
|
630
|
+
#
|
631
|
+
# An empty category will place the item in the default category:
|
632
|
+
#
|
633
|
+
# # :category:
|
634
|
+
# #
|
635
|
+
# # This method is in the default category
|
636
|
+
#
|
637
|
+
# def some_method
|
638
|
+
# # ...
|
639
|
+
# end
|
640
|
+
#
|
641
|
+
# Unlike the :section: directive, :category: is not sticky. The category
|
642
|
+
# only applies to the item immediately following the comment.
|
643
|
+
#
|
644
|
+
# Use the :section: directive to provide introductory text for a section of
|
645
|
+
# documentation.
|
646
|
+
#
|
647
|
+
# [+:section:+ _title_]
|
648
|
+
# Provides section introductory text in RDoc output. The title following
|
649
|
+
# +:section:+ is used as the section name and the remainder of the comment
|
650
|
+
# containing the section is used as introductory text. A section's comment
|
651
|
+
# block must be separated from following comment blocks. Use an empty title
|
652
|
+
# to switch to the default section.
|
653
|
+
#
|
654
|
+
# The :section: directive is sticky, so subsequent methods, aliases,
|
655
|
+
# attributes, and classes will be contained in this section until the
|
656
|
+
# section is changed. The :category: directive will override the :section:
|
657
|
+
# directive.
|
658
|
+
#
|
659
|
+
# A :section: comment block may have one or more lines before the :section:
|
660
|
+
# directive. These will be removed, and any identical lines at the end of
|
661
|
+
# the block are also removed. This allows you to add visual cues to the
|
662
|
+
# section.
|
663
|
+
#
|
664
|
+
# Example:
|
665
|
+
#
|
666
|
+
# # ----------------------------------------
|
667
|
+
# # :section: My Section
|
668
|
+
# # This is the section that I wrote.
|
669
|
+
# # See it glisten in the noon-day sun.
|
670
|
+
# # ----------------------------------------
|
671
|
+
#
|
672
|
+
# ##
|
673
|
+
# # Comment for some_method
|
674
|
+
#
|
675
|
+
# def some_method
|
676
|
+
# # ...
|
677
|
+
# end
|
678
|
+
#
|
481
679
|
# === Other directives
|
482
680
|
#
|
681
|
+
# [+:markup:+ _type_]
|
682
|
+
# Overrides the default markup type for this comment with the specified
|
683
|
+
# markup type. For Ruby files, if the first comment contains this directive
|
684
|
+
# it is applied automatically to all comments in the file.
|
685
|
+
#
|
686
|
+
# Unless you are converting between markup formats you should use a
|
687
|
+
# <code>.rdoc_options</code> file to specify the default documentation
|
688
|
+
# format for your entire project. See RDoc::Options@Saved+Options for
|
689
|
+
# instructions.
|
690
|
+
#
|
691
|
+
# At the top of a file the +:markup:+ directive applies to the entire file:
|
692
|
+
#
|
693
|
+
# # coding: UTF-8
|
694
|
+
# # :markup: TomDoc
|
695
|
+
#
|
696
|
+
# # TomDoc comment here ...
|
697
|
+
#
|
698
|
+
# class MyClass
|
699
|
+
# # ...
|
700
|
+
#
|
701
|
+
# For just one comment:
|
702
|
+
#
|
703
|
+
# # ...
|
704
|
+
# end
|
705
|
+
#
|
706
|
+
# # :markup: RDoc
|
707
|
+
# #
|
708
|
+
# # This is a comment in RDoc markup format ...
|
709
|
+
#
|
710
|
+
# def some_method
|
711
|
+
# # ...
|
712
|
+
#
|
713
|
+
# See Markup@CONTRIBUTING for instructions on adding a new markup format.
|
714
|
+
#
|
483
715
|
# [+:include:+ _filename_]
|
484
716
|
# Include the contents of the named file at this point. This directive
|
485
717
|
# must appear alone on one line, possibly preceded by spaces. In this
|
486
|
-
# position, it can be
|
718
|
+
# position, it can be escaped with a \ in front of the first colon.
|
487
719
|
#
|
488
720
|
# The file will be searched for in the directories listed by the +--include+
|
489
721
|
# option, or in the current directory by default. The contents of the file
|
@@ -498,29 +730,6 @@ require 'rdoc'
|
|
498
730
|
# [+:main:+ _name_]
|
499
731
|
# Equivalent to the <tt>--main</tt> command line parameter.
|
500
732
|
#
|
501
|
-
# [<tt>:section: title</tt>]
|
502
|
-
# Starts a new section in the output. The title following +:section:+ is
|
503
|
-
# used as the section heading, and the remainder of the comment containing
|
504
|
-
# the section is used as introductory text. Subsequent methods, aliases,
|
505
|
-
# attributes, and classes will be documented in this section. A :section:
|
506
|
-
# comment block may have one or more lines before the :section: directive.
|
507
|
-
# These will be removed, and any identical lines at the end of the block are
|
508
|
-
# also removed. This allows you to add visual cues such as:
|
509
|
-
#
|
510
|
-
# # ----------------------------------------
|
511
|
-
# # :section: My Section
|
512
|
-
# # This is the section that I wrote.
|
513
|
-
# # See it glisten in the noon-day sun.
|
514
|
-
# # ----------------------------------------
|
515
|
-
#
|
516
|
-
# <i>Note: Current formatters to not take sections into account.</i>
|
517
|
-
#
|
518
|
-
# [+:call-seq:+]
|
519
|
-
# Lines up to the next blank line in the comment are treated as the method's
|
520
|
-
# calling sequence, overriding the default parsing of method parameters and
|
521
|
-
# yield arguments.
|
522
|
-
#
|
523
|
-
# Further directives can be found in RDoc::Parser::Ruby and RDoc::Parser::C.
|
524
733
|
#--
|
525
734
|
# Original Author:: Dave Thomas, dave@pragmaticprogrammer.com
|
526
735
|
# License:: Ruby license
|
@@ -533,12 +742,40 @@ class RDoc::Markup
|
|
533
742
|
attr_reader :attribute_manager
|
534
743
|
|
535
744
|
##
|
536
|
-
#
|
745
|
+
# Parses +str+ into an RDoc::Markup::Document.
|
746
|
+
|
747
|
+
def self.parse str
|
748
|
+
RDoc::Markup::Parser.parse str
|
749
|
+
rescue RDoc::Markup::Parser::Error => e
|
750
|
+
$stderr.puts <<-EOF
|
751
|
+
While parsing markup, RDoc encountered a #{e.class}:
|
752
|
+
|
753
|
+
#{e}
|
754
|
+
\tfrom #{e.backtrace.join "\n\tfrom "}
|
755
|
+
|
756
|
+
---8<---
|
757
|
+
#{text}
|
758
|
+
---8<---
|
759
|
+
|
760
|
+
RDoc #{RDoc::VERSION}
|
761
|
+
|
762
|
+
Ruby #{RUBY_VERSION}-p#{RUBY_PATCHLEVEL} #{RUBY_RELEASE_DATE}
|
763
|
+
|
764
|
+
Please file a bug report with the above information at:
|
765
|
+
|
766
|
+
https://github.com/ruby/rdoc/issues
|
767
|
+
|
768
|
+
EOF
|
769
|
+
raise
|
770
|
+
end
|
771
|
+
|
772
|
+
##
|
773
|
+
# Take a block of text and use various heuristics to determine its
|
537
774
|
# structure (paragraphs, lists, and so on). Invoke an event handler as we
|
538
775
|
# identify significant chunks.
|
539
776
|
|
540
|
-
def initialize
|
541
|
-
@attribute_manager = RDoc::Markup::AttributeManager.new
|
777
|
+
def initialize attribute_manager = nil
|
778
|
+
@attribute_manager = attribute_manager || RDoc::Markup::AttributeManager.new
|
542
779
|
@output = nil
|
543
780
|
end
|
544
781
|
|
@@ -562,28 +799,69 @@ class RDoc::Markup
|
|
562
799
|
# Add to other inline sequences. For example, we could add WikiWords using
|
563
800
|
# something like:
|
564
801
|
#
|
565
|
-
# parser.
|
802
|
+
# parser.add_regexp_handling(/\b([A-Z][a-z]+[A-Z]\w+)/, :WIKIWORD)
|
566
803
|
#
|
567
|
-
# Each wiki word will be presented to the output formatter
|
568
|
-
# accept_special method.
|
804
|
+
# Each wiki word will be presented to the output formatter.
|
569
805
|
|
570
|
-
def
|
571
|
-
@attribute_manager.
|
806
|
+
def add_regexp_handling(pattern, name)
|
807
|
+
@attribute_manager.add_regexp_handling(pattern, name)
|
572
808
|
end
|
573
809
|
|
574
810
|
##
|
575
|
-
# We take +
|
576
|
-
# Visitor to render the result.
|
811
|
+
# We take +input+, parse it if necessary, then invoke the output +formatter+
|
812
|
+
# using a Visitor to render the result.
|
577
813
|
|
578
|
-
def convert
|
579
|
-
document =
|
814
|
+
def convert input, formatter
|
815
|
+
document = case input
|
816
|
+
when RDoc::Markup::Document then
|
817
|
+
input
|
818
|
+
else
|
819
|
+
RDoc::Markup::Parser.parse input
|
820
|
+
end
|
580
821
|
|
581
822
|
document.accept formatter
|
582
823
|
end
|
583
824
|
|
584
|
-
|
825
|
+
autoload :Parser, 'rdoc/markup/parser'
|
826
|
+
autoload :PreProcess, 'rdoc/markup/pre_process'
|
827
|
+
|
828
|
+
# Inline markup classes
|
829
|
+
autoload :AttrChanger, 'rdoc/markup/attr_changer'
|
830
|
+
autoload :AttrSpan, 'rdoc/markup/attr_span'
|
831
|
+
autoload :Attributes, 'rdoc/markup/attributes'
|
832
|
+
autoload :AttributeManager, 'rdoc/markup/attribute_manager'
|
833
|
+
autoload :RegexpHandling, 'rdoc/markup/regexp_handling'
|
834
|
+
|
835
|
+
# RDoc::Markup AST
|
836
|
+
autoload :BlankLine, 'rdoc/markup/blank_line'
|
837
|
+
autoload :BlockQuote, 'rdoc/markup/block_quote'
|
838
|
+
autoload :Document, 'rdoc/markup/document'
|
839
|
+
autoload :HardBreak, 'rdoc/markup/hard_break'
|
840
|
+
autoload :Heading, 'rdoc/markup/heading'
|
841
|
+
autoload :Include, 'rdoc/markup/include'
|
842
|
+
autoload :IndentedParagraph, 'rdoc/markup/indented_paragraph'
|
843
|
+
autoload :List, 'rdoc/markup/list'
|
844
|
+
autoload :ListItem, 'rdoc/markup/list_item'
|
845
|
+
autoload :Paragraph, 'rdoc/markup/paragraph'
|
846
|
+
autoload :Table, 'rdoc/markup/table'
|
847
|
+
autoload :Raw, 'rdoc/markup/raw'
|
848
|
+
autoload :Rule, 'rdoc/markup/rule'
|
849
|
+
autoload :Verbatim, 'rdoc/markup/verbatim'
|
585
850
|
|
586
|
-
|
587
|
-
|
588
|
-
|
851
|
+
# Formatters
|
852
|
+
autoload :Formatter, 'rdoc/markup/formatter'
|
853
|
+
|
854
|
+
autoload :ToAnsi, 'rdoc/markup/to_ansi'
|
855
|
+
autoload :ToBs, 'rdoc/markup/to_bs'
|
856
|
+
autoload :ToHtml, 'rdoc/markup/to_html'
|
857
|
+
autoload :ToHtmlCrossref, 'rdoc/markup/to_html_crossref'
|
858
|
+
autoload :ToHtmlSnippet, 'rdoc/markup/to_html_snippet'
|
859
|
+
autoload :ToLabel, 'rdoc/markup/to_label'
|
860
|
+
autoload :ToMarkdown, 'rdoc/markup/to_markdown'
|
861
|
+
autoload :ToRdoc, 'rdoc/markup/to_rdoc'
|
862
|
+
autoload :ToTableOfContents, 'rdoc/markup/to_table_of_contents'
|
863
|
+
autoload :ToTest, 'rdoc/markup/to_test'
|
864
|
+
autoload :ToTtOnly, 'rdoc/markup/to_tt_only'
|
865
|
+
|
866
|
+
end
|
589
867
|
|
data/lib/rdoc/meta_method.rb
CHANGED