gitlab-rdoc 6.3.2
Sign up to get free protection for your applications and to get access to all the features.
- 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 +133 -0
- data/RI.rdoc +57 -0
- data/Rakefile +101 -0
- data/TODO.rdoc +59 -0
- data/bin/console +7 -0
- data/bin/setup +6 -0
- data/exe/rdoc +44 -0
- data/exe/ri +12 -0
- data/lib/rdoc/alias.rb +112 -0
- data/lib/rdoc/anon_class.rb +11 -0
- data/lib/rdoc/any_method.rb +361 -0
- data/lib/rdoc/attr.rb +176 -0
- data/lib/rdoc/class_module.rb +802 -0
- data/lib/rdoc/code_object.rb +421 -0
- data/lib/rdoc/code_objects.rb +6 -0
- data/lib/rdoc/comment.rb +250 -0
- data/lib/rdoc/constant.rb +187 -0
- data/lib/rdoc/context/section.rb +232 -0
- data/lib/rdoc/context.rb +1266 -0
- data/lib/rdoc/cross_reference.rb +202 -0
- data/lib/rdoc/encoding.rb +136 -0
- data/lib/rdoc/erb_partial.rb +19 -0
- data/lib/rdoc/erbio.rb +42 -0
- data/lib/rdoc/extend.rb +10 -0
- data/lib/rdoc/generator/darkfish.rb +790 -0
- data/lib/rdoc/generator/json_index.rb +300 -0
- data/lib/rdoc/generator/markup.rb +160 -0
- 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 +31 -0
- data/lib/rdoc/generator/template/darkfish/.document +0 -0
- 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/brick.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/brick_link.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/bug.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/bullet_black.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/bullet_toggle_minus.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/bullet_toggle_plus.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/date.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/delete.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/find.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/loadingAnimation.gif +0 -0
- data/lib/rdoc/generator/template/darkfish/images/macFFBgHack.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/package.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/page_green.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/page_white_text.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/page_white_width.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/plugin.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/ruby.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/tag_blue.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/tag_green.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/transparent.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/wrench.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/wrench_orange.png +0 -0
- data/lib/rdoc/generator/template/darkfish/images/zoom.png +0 -0
- data/lib/rdoc/generator/template/darkfish/index.rhtml +22 -0
- data/lib/rdoc/generator/template/darkfish/js/darkfish.js +84 -0
- 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 +51 -0
- data/lib/rdoc/ghost_method.rb +7 -0
- 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 +10 -0
- data/lib/rdoc/known_classes.rb +73 -0
- data/lib/rdoc/markdown/entities.rb +2132 -0
- data/lib/rdoc/markdown/literals.kpeg +23 -0
- data/lib/rdoc/markdown/literals.rb +417 -0
- data/lib/rdoc/markdown.kpeg +1237 -0
- data/lib/rdoc/markdown.rb +16685 -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 +409 -0
- data/lib/rdoc/markup/attributes.rb +71 -0
- data/lib/rdoc/markup/blank_line.rb +28 -0
- data/lib/rdoc/markup/block_quote.rb +15 -0
- data/lib/rdoc/markup/document.rb +165 -0
- data/lib/rdoc/markup/formatter.rb +266 -0
- data/lib/rdoc/markup/hard_break.rb +32 -0
- data/lib/rdoc/markup/heading.rb +79 -0
- data/lib/rdoc/markup/include.rb +43 -0
- data/lib/rdoc/markup/indented_paragraph.rb +48 -0
- data/lib/rdoc/markup/list.rb +102 -0
- data/lib/rdoc/markup/list_item.rb +100 -0
- data/lib/rdoc/markup/paragraph.rb +29 -0
- data/lib/rdoc/markup/parser.rb +575 -0
- data/lib/rdoc/markup/pre_process.rb +296 -0
- data/lib/rdoc/markup/raw.rb +70 -0
- data/lib/rdoc/markup/regexp_handling.rb +41 -0
- data/lib/rdoc/markup/rule.rb +21 -0
- data/lib/rdoc/markup/table.rb +47 -0
- data/lib/rdoc/markup/to_ansi.rb +94 -0
- data/lib/rdoc/markup/to_bs.rb +77 -0
- data/lib/rdoc/markup/to_html.rb +444 -0
- data/lib/rdoc/markup/to_html_crossref.rb +176 -0
- 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 +362 -0
- data/lib/rdoc/markup/to_table_of_contents.rb +89 -0
- data/lib/rdoc/markup/to_test.rb +70 -0
- data/lib/rdoc/markup/to_tt_only.rb +121 -0
- data/lib/rdoc/markup/verbatim.rb +84 -0
- data/lib/rdoc/markup.rb +867 -0
- data/lib/rdoc/meta_method.rb +7 -0
- data/lib/rdoc/method_attr.rb +419 -0
- data/lib/rdoc/mixin.rb +121 -0
- data/lib/rdoc/normal_class.rb +93 -0
- data/lib/rdoc/normal_module.rb +74 -0
- data/lib/rdoc/options.rb +1285 -0
- data/lib/rdoc/parser/c.rb +1225 -0
- 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 +2327 -0
- data/lib/rdoc/parser/ruby_tools.rb +167 -0
- data/lib/rdoc/parser/simple.rb +61 -0
- data/lib/rdoc/parser/text.rb +12 -0
- data/lib/rdoc/parser.rb +277 -0
- 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 +579 -0
- data/lib/rdoc/require.rb +52 -0
- data/lib/rdoc/ri/driver.rb +1572 -0
- data/lib/rdoc/ri/formatter.rb +6 -0
- data/lib/rdoc/ri/paths.rb +171 -0
- data/lib/rdoc/ri/store.rb +7 -0
- data/lib/rdoc/ri/task.rb +71 -0
- data/lib/rdoc/ri.rb +21 -0
- data/lib/rdoc/rubygems_hook.rb +246 -0
- data/lib/rdoc/servlet.rb +451 -0
- data/lib/rdoc/single_class.rb +26 -0
- data/lib/rdoc/stats/normal.rb +58 -0
- data/lib/rdoc/stats/quiet.rb +60 -0
- data/lib/rdoc/stats/verbose.rb +46 -0
- data/lib/rdoc/stats.rb +462 -0
- data/lib/rdoc/store.rb +979 -0
- data/lib/rdoc/task.rb +329 -0
- data/lib/rdoc/text.rb +304 -0
- data/lib/rdoc/token_stream.rb +119 -0
- data/lib/rdoc/tom_doc.rb +263 -0
- data/lib/rdoc/top_level.rb +289 -0
- data/lib/rdoc/version.rb +8 -0
- data/lib/rdoc.rb +201 -0
- data/man/ri.1 +247 -0
- data/rdoc.gemspec +249 -0
- metadata +279 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA256:
|
3
|
+
metadata.gz: 66e6a9acc9a652a4fb77d859310407d4e5412fb1657d7e61a3ec45c0b7143db4
|
4
|
+
data.tar.gz: 9890aab63569624b247e968f18626ca5c54ecf3d2420213572e434e41ce7a2f1
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: cca9af8aa3a8825f3f35374550ee62d1df1d7b928c228f34bded6b92ceedc72ca16b9590d69ddc39f49317f3598a1a8549e5d2c82dfeb6d22813583a772959e0
|
7
|
+
data.tar.gz: db39f0f7058eee4cf576ec113df39954ce19c1244945c2c34a8352c5eeac6be88c4a65056308e0a73251db60de631e42f6703d326d8a0b23ef53c0c304568350
|
data/CONTRIBUTING.rdoc
ADDED
@@ -0,0 +1,220 @@
|
|
1
|
+
= Developer Introduction
|
2
|
+
|
3
|
+
So you want to write a generator, fix a bug, or otherwise work with RDoc. This
|
4
|
+
document provides an overview of how RDoc works from parsing options to
|
5
|
+
generating output. Most of the documentation can be found in the specific
|
6
|
+
classes for each feature.
|
7
|
+
|
8
|
+
== Bugs
|
9
|
+
|
10
|
+
If you think you found a bug, file a ticket on the {issues
|
11
|
+
tracker}[https://github.com/ruby/rdoc/issues] on github.
|
12
|
+
|
13
|
+
If your bug involves an error RDoc produced please include a sample file that
|
14
|
+
illustrates the problem or link to the repository or gem that is associated
|
15
|
+
with the bug.
|
16
|
+
|
17
|
+
Please include steps to reproduce the issue. Here are some examples of good
|
18
|
+
issues:
|
19
|
+
|
20
|
+
* https://github.com/ruby/rdoc/issues/55
|
21
|
+
* https://github.com/ruby/rdoc/issues/61
|
22
|
+
|
23
|
+
== Developer Quick Start
|
24
|
+
|
25
|
+
RDoc uses bundler for development. To get ready to work on RDoc run:
|
26
|
+
|
27
|
+
$ gem install bundler
|
28
|
+
[...]
|
29
|
+
$ bundle install
|
30
|
+
[...]
|
31
|
+
$ rake
|
32
|
+
[...]
|
33
|
+
|
34
|
+
This will install all the necessary dependencies for development with rake,
|
35
|
+
generate documentation and run the tests for the first time.
|
36
|
+
|
37
|
+
If the tests don't pass on the first run check the {Travis CI page for
|
38
|
+
RDoc}[https://travis-ci.org/ruby/rdoc] to see if there are any known failures
|
39
|
+
(there shouldn't be).
|
40
|
+
|
41
|
+
You can now use `rake` and `autotest` to run the tests.
|
42
|
+
|
43
|
+
Note: the `rake` command must be used first before running any tests, because
|
44
|
+
its used to generate various parsers implemented in RDoc. Also `rake clean` is
|
45
|
+
helpful to delete these generated files.
|
46
|
+
|
47
|
+
== Glossary
|
48
|
+
|
49
|
+
Here are definitions for some common terms in the RDoc documentation. The
|
50
|
+
list also briefly describes how the components of RDoc interact.
|
51
|
+
|
52
|
+
parser::
|
53
|
+
Parses files and creates a documentation tree from the contents.
|
54
|
+
|
55
|
+
documentation tree::
|
56
|
+
The documentation tree represents files, classes, modules, methods,
|
57
|
+
constants, includes, comments and other ruby syntax features as a tree.
|
58
|
+
RDoc walks this tree with a generator to create documentation.
|
59
|
+
|
60
|
+
generator::
|
61
|
+
Walks the documentation tree and generates output.
|
62
|
+
|
63
|
+
RDoc ships with two generators, the Darkfish generator creates HTML and the
|
64
|
+
RI generator creates an RI data store.
|
65
|
+
|
66
|
+
markup parser::
|
67
|
+
Parses comments from a file into a generic markup tree.
|
68
|
+
|
69
|
+
The markup parsers allow RDoc to handle RDoc, TomDoc, rd and Markdown format
|
70
|
+
documentation with common formatters.
|
71
|
+
|
72
|
+
markup tree::
|
73
|
+
Each parsed comment has a markup tree that represents common markup items
|
74
|
+
such as headings, paragraphs, lists or verbatim text sections for example
|
75
|
+
code or output.
|
76
|
+
|
77
|
+
A generator uses a formatters to walks the tree to create output. Some
|
78
|
+
generators use multiple formatters on a markup tree to produce the output.
|
79
|
+
|
80
|
+
formatter::
|
81
|
+
Converts a parsed markup tree into some form other form of markup.
|
82
|
+
|
83
|
+
Formatters can either produce a one-to-one conversion, such as ToHtml, or
|
84
|
+
extract part of the parsed result, such as ToHtmlSnippet which outputs the
|
85
|
+
first 100 characters as HTML.
|
86
|
+
|
87
|
+
== Plugins
|
88
|
+
|
89
|
+
When 'rdoc/rdoc' is loaded RDoc looks for 'rdoc/discover' files in your
|
90
|
+
installed gems. This can be used to load parsers, alternate generators, or
|
91
|
+
additional preprocessor directives. An rdoc plugin layout should look
|
92
|
+
something like this:
|
93
|
+
|
94
|
+
lib/rdoc/discover.rb
|
95
|
+
lib/my/rdoc/plugin.rb
|
96
|
+
# etc.
|
97
|
+
|
98
|
+
In your rdoc/discover.rb file you will want to wrap the loading of your plugin
|
99
|
+
in an RDoc version check like this:
|
100
|
+
|
101
|
+
begin
|
102
|
+
gem 'rdoc', '~> 3'
|
103
|
+
require 'my/rdoc/plugin'
|
104
|
+
rescue Gem::LoadError
|
105
|
+
end
|
106
|
+
|
107
|
+
=== Plugin Types
|
108
|
+
|
109
|
+
In RDoc you can change the following behaviors:
|
110
|
+
|
111
|
+
* Add a parser for a new file format
|
112
|
+
* Add a new output generator
|
113
|
+
* Add a new markup directive
|
114
|
+
* Add a new type of documentation markup
|
115
|
+
* Add a new type of formatter
|
116
|
+
|
117
|
+
All of these are described below
|
118
|
+
|
119
|
+
== Option Parsing
|
120
|
+
|
121
|
+
Option parsing is handled by RDoc::Options. When you're writing a generator
|
122
|
+
you can provide the user with extra options by providing a class method
|
123
|
+
+setup_options+. The option parser will call this after your generator is
|
124
|
+
loaded. See RDoc::Generator for details.
|
125
|
+
|
126
|
+
== File Parsing
|
127
|
+
|
128
|
+
After options are parsed, RDoc parses files from the files and directories in
|
129
|
+
ARGV. RDoc compares the filename against what each parser claims it can parse
|
130
|
+
via RDoc::Parser#parse_files_matching. For example, RDoc::Parser::C can parse
|
131
|
+
C files, C headers, C++ files, C++ headers and yacc grammars.
|
132
|
+
|
133
|
+
Once a matching parser class is found it is instantiated and +scan+ is called.
|
134
|
+
The parser needs to extract documentation from the file and add it to the RDoc
|
135
|
+
document tree. Usually this involves starting at the root and adding a class
|
136
|
+
or a module (RDoc::TopLevel#add_class and RDoc::TopLevel#add_module) and
|
137
|
+
proceeding to add classes, modules and methods to each nested item.
|
138
|
+
|
139
|
+
When the parsers are finished the document tree is cleaned up to remove
|
140
|
+
dangling references to aliases and includes that were not found (and may exist
|
141
|
+
in a separate library) through RDoc::ClassModule#complete.
|
142
|
+
|
143
|
+
To write your own parser for a new file format see RDoc::Parser.
|
144
|
+
|
145
|
+
=== Documentation Tree
|
146
|
+
|
147
|
+
The parsers build a documentation tree that is composed of RDoc::CodeObject and
|
148
|
+
its subclasses. There are various methods to walk the tree to extract
|
149
|
+
information, see RDoc::Context and its subclasses.
|
150
|
+
|
151
|
+
Within a class or module, attributes, methods and constants are divided into
|
152
|
+
sections. The section represents a functional grouping of parts of the class.
|
153
|
+
TomDoc uses the sections "Public", "Internal" and "Deprecated". The sections
|
154
|
+
can be enumerated using RDoc::Context#each_section.
|
155
|
+
|
156
|
+
== Output Generation
|
157
|
+
|
158
|
+
An RDoc generator turns the documentation tree into some other kind of output.
|
159
|
+
RDoc comes with an HTML generator (RDoc::Generator::Darkfish) and an RI
|
160
|
+
database generator (RDoc::Generator::RI). The output a generator creates does
|
161
|
+
not have to be human-readable.
|
162
|
+
|
163
|
+
To create your own generator see RDoc::Generator.
|
164
|
+
|
165
|
+
=== Comments
|
166
|
+
|
167
|
+
In RDoc 3.10 and newer the comment on an RDoc::CodeObject is now an
|
168
|
+
RDoc::Comment object instead of a String. This is to support various
|
169
|
+
documentation markup formats like rdoc, TomDoc and rd. The comments are
|
170
|
+
normalized to remove comment markers and remove indentation then parsed lazily
|
171
|
+
via RDoc::Comment#document to create a generic markup tree that can be
|
172
|
+
processed by a formatter.
|
173
|
+
|
174
|
+
To add your own markup format see RDoc::Markup@Other+directives
|
175
|
+
|
176
|
+
==== Formatters
|
177
|
+
|
178
|
+
To transform a comment into some form of output an RDoc::Markup::Formatter
|
179
|
+
subclass is used like RDoc::Markup::ToHtml. A formatter is a visitor that
|
180
|
+
walks a parsed comment tree (an RDoc::Markup::Document) of any format. To help
|
181
|
+
write a formatter RDoc::Markup::FormatterTestCase exists for generic parsers,
|
182
|
+
and RDoc::Markup::TextFormatterTestCase which contains extra test cases for
|
183
|
+
text-type output (like +ri+ output).
|
184
|
+
|
185
|
+
RDoc ships with formatters that will turn a comment into HTML, rdoc-markup-like
|
186
|
+
text, ANSI or terminal backspace highlighted text, HTML, cross-referenced HTML,
|
187
|
+
an HTML snippet free of most markup, an HTML label for use in id attributes, a
|
188
|
+
table-of-contents page, and text with only code blocks.
|
189
|
+
|
190
|
+
The output of the formatter does not need to be text or text-like.
|
191
|
+
RDoc::Markup::ToLabel creates an HTML-safe label for use in an HTML id
|
192
|
+
attribute. A formatter could count the number of words and the average word
|
193
|
+
length for a comment, for example.
|
194
|
+
|
195
|
+
==== Directives
|
196
|
+
|
197
|
+
For comments in markup you can add new directives (:nodoc: is a directive).
|
198
|
+
Directives may replace text or store it off for later use.
|
199
|
+
|
200
|
+
See RDoc::Markup::PreProcess::register for details.
|
201
|
+
|
202
|
+
=== JSONIndex
|
203
|
+
|
204
|
+
RDoc contains a special generator, RDoc::Generator::JSONIndex, which creates a
|
205
|
+
JSON-based search index and includes a search engine for use with HTML output.
|
206
|
+
This generator can be used to add searching to any HTML output and is designed
|
207
|
+
to be called from inside an HTML generator.
|
208
|
+
|
209
|
+
== Markup
|
210
|
+
|
211
|
+
Additional documentation markup formats can be added to RDoc. A markup
|
212
|
+
parsing class must respond to \::parse and accept a String argument containing
|
213
|
+
the markup format. An RDoc::Document containing documentation items
|
214
|
+
(RDoc::Markup::Heading, RDoc::Markup::Paragraph, RDoc::Markup::Verbatim, etc.)
|
215
|
+
must be returned.
|
216
|
+
|
217
|
+
To register the parser with rdoc, add the markup type's name and class to the
|
218
|
+
RDoc::Text::MARKUP_FORMAT hash like:
|
219
|
+
|
220
|
+
RDoc::Text::MARKUP_FORMAT['rdoc'] = RDoc::Markup
|
data/CVE-2013-0256.rdoc
ADDED
@@ -0,0 +1,49 @@
|
|
1
|
+
= RDoc 2.3.0 through 3.12 XSS Exploit
|
2
|
+
|
3
|
+
RDoc documentation generated by rdoc 2.3.0 through rdoc 3.12 and prereleases up
|
4
|
+
to rdoc 4.0.0.preview2.1 are vulnerable to an XSS exploit. This exploit may
|
5
|
+
lead to cookie disclosure to third parties.
|
6
|
+
|
7
|
+
The exploit exists in darkfish.js which is copied from the RDoc install
|
8
|
+
location to the generated documentation.
|
9
|
+
|
10
|
+
RDoc is a static documentation generation tool. Patching the library itself
|
11
|
+
is insufficient to correct this exploit. Those hosting rdoc documentation will
|
12
|
+
need to apply the following patch. If applied while ignoring whitespace, this
|
13
|
+
patch will correct all affected versions:
|
14
|
+
|
15
|
+
diff --git darkfish.js darkfish.js
|
16
|
+
index 4be722f..f26fd45 100644
|
17
|
+
--- darkfish.js
|
18
|
+
+++ darkfish.js
|
19
|
+
@@ -109,13 +109,15 @@ function hookSearch() {
|
20
|
+
function highlightTarget( anchor ) {
|
21
|
+
console.debug( "Highlighting target '%s'.", anchor );
|
22
|
+
|
23
|
+
- $("a[name=" + anchor + "]").each( function() {
|
24
|
+
- if ( !$(this).parent().parent().hasClass('target-section') ) {
|
25
|
+
- console.debug( "Wrapping the target-section" );
|
26
|
+
- $('div.method-detail').unwrap( 'div.target-section' );
|
27
|
+
- $(this).parent().wrap( '<div class="target-section"></div>' );
|
28
|
+
- } else {
|
29
|
+
- console.debug( "Already wrapped." );
|
30
|
+
+ $("a[name]").each( function() {
|
31
|
+
+ if ( $(this).attr("name") == anchor ) {
|
32
|
+
+ if ( !$(this).parent().parent().hasClass('target-section') ) {
|
33
|
+
+ console.debug( "Wrapping the target-section" );
|
34
|
+
+ $('div.method-detail').unwrap( 'div.target-section' );
|
35
|
+
+ $(this).parent().wrap( '<div class="target-section"></div>' );
|
36
|
+
+ } else {
|
37
|
+
+ console.debug( "Already wrapped." );
|
38
|
+
+ }
|
39
|
+
}
|
40
|
+
});
|
41
|
+
};
|
42
|
+
|
43
|
+
RDoc 3.9.5, 3.12.1 and RDoc 4.0.0.rc.2 and newer are not vulnerable to this
|
44
|
+
exploit.
|
45
|
+
|
46
|
+
This exploit was discovered by Evgeny Ermakov <corwmh@gmail.com>.
|
47
|
+
|
48
|
+
This vulnerability has been assigned the CVE identifier CVE-2013-0256.
|
49
|
+
|
data/ExampleMarkdown.md
ADDED
@@ -0,0 +1,37 @@
|
|
1
|
+
This document contains example output to show RDoc styling. This file was
|
2
|
+
created from a Markdown file.
|
3
|
+
|
4
|
+
For the following styles, see ExampleRDoc.rdoc for style examples:
|
5
|
+
|
6
|
+
* Headings
|
7
|
+
* Paragraphs
|
8
|
+
* Code blocks (verbatim sections)
|
9
|
+
* Definition lists
|
10
|
+
* Ordered lists
|
11
|
+
* Unordered lists
|
12
|
+
|
13
|
+
These items all use the same styles as RDoc format files.
|
14
|
+
|
15
|
+
## Footnotes
|
16
|
+
|
17
|
+
Footnotes are rendered at the bottom of the documentation section[^1]. For
|
18
|
+
pages this will be at the bottom of the page. For method documentation this
|
19
|
+
will be at the end of the current method.
|
20
|
+
|
21
|
+
[^1]: Here is the footnote content. As you can see it is at the bottom of the
|
22
|
+
page.
|
23
|
+
|
24
|
+
## Blockquotes
|
25
|
+
|
26
|
+
Here is how a blockquote looks.
|
27
|
+
|
28
|
+
> We finished our first sensor sweep of the neutral zone. Now, how the hell do
|
29
|
+
> we defeat an enemy that knows us better than we know ourselves? and attack
|
30
|
+
> the Romulans.
|
31
|
+
>
|
32
|
+
> > Sorry, Data. I guess it's better to be lucky than good. The unexpected is
|
33
|
+
> > our normal routine. Could someone survive inside a transporter buffer for
|
34
|
+
> > 75 years?
|
35
|
+
|
36
|
+
This text is from [Riker Ipsum](http://rikeripsum.com)
|
37
|
+
|
data/ExampleRDoc.rdoc
ADDED
@@ -0,0 +1,208 @@
|
|
1
|
+
This document contains example output to show RDoc styling. This file was
|
2
|
+
created from a RDoc Markup file.
|
3
|
+
|
4
|
+
== Headings
|
5
|
+
|
6
|
+
You should not use headings beyond level 3, it is a sign of poor organization
|
7
|
+
of your code or documentation. It also becomes difficult for the user to
|
8
|
+
figure out what you are attempting to explain to them as they have to track
|
9
|
+
the multiple layers of nesting.
|
10
|
+
|
11
|
+
= Heading level 1
|
12
|
+
|
13
|
+
Above is a level one heading.
|
14
|
+
|
15
|
+
These paragraphs are filler that exist so you can see how the heading
|
16
|
+
interacts with paragraphs before and after the heading. As you can see each
|
17
|
+
different heading has a different amount of margin above and below.
|
18
|
+
|
19
|
+
This should be sufficient to give you a proper picture of how it will appear in
|
20
|
+
your documentation.
|
21
|
+
|
22
|
+
== Heading level 2
|
23
|
+
|
24
|
+
Above is a level two heading.
|
25
|
+
|
26
|
+
These paragraphs are filler that exist so you can see how the heading
|
27
|
+
interacts with paragraphs before and after the heading. As you can see each
|
28
|
+
different heading has a different amount of margin above and below.
|
29
|
+
|
30
|
+
This should be sufficient to give you a proper picture of how it will appear in
|
31
|
+
your documentation.
|
32
|
+
|
33
|
+
=== Heading level 3
|
34
|
+
|
35
|
+
Above is a level three heading.
|
36
|
+
|
37
|
+
These paragraphs are filler that exist so you can see how the heading
|
38
|
+
interacts with paragraphs before and after the heading. As you can see each
|
39
|
+
different heading has a different amount of margin above and below.
|
40
|
+
|
41
|
+
This should be sufficient to give you a proper picture of how it will appear in
|
42
|
+
your documentation.
|
43
|
+
|
44
|
+
==== Heading level 4
|
45
|
+
|
46
|
+
Above is a level four heading.
|
47
|
+
|
48
|
+
These paragraphs are filler that exist so you can see how the heading
|
49
|
+
interacts with paragraphs before and after the heading. As you can see each
|
50
|
+
different heading has a different amount of margin above and below.
|
51
|
+
|
52
|
+
This should be sufficient to give you a proper picture of how it will appear in
|
53
|
+
your documentation.
|
54
|
+
|
55
|
+
===== Heading level 5
|
56
|
+
|
57
|
+
Above is a level five heading.
|
58
|
+
|
59
|
+
These paragraphs are filler that exist so you can see how the heading
|
60
|
+
interacts with paragraphs before and after the heading. As you can see each
|
61
|
+
different heading has a different amount of margin above and below.
|
62
|
+
|
63
|
+
This should be sufficient to give you a proper picture of how it will appear in
|
64
|
+
your documentation.
|
65
|
+
|
66
|
+
====== Heading level 6
|
67
|
+
|
68
|
+
Above is a level six heading.
|
69
|
+
|
70
|
+
These paragraphs are filler that exist so you can see how the heading
|
71
|
+
interacts with paragraphs before and after the heading. As you can see each
|
72
|
+
different heading has a different amount of margin above and below.
|
73
|
+
|
74
|
+
This should be sufficient to give you a proper picture of how it will appear in
|
75
|
+
your documentation.
|
76
|
+
|
77
|
+
== Paragraphs
|
78
|
+
|
79
|
+
This is how a paragraph looks. Since it is difficult to generate good content
|
80
|
+
for paragraphs I have chosen to use {Riker Ipsum}[http://rikeripsum.com] for
|
81
|
+
nonsense filler content. In the previous sentence you can see how a link is
|
82
|
+
formatted.
|
83
|
+
|
84
|
+
Here is an example of *bold* and _emphasis_ styling. Try not to combine the
|
85
|
+
two or use them too often. Here is an example of <code>inline verbatim
|
86
|
+
text</code>. That should be enough of a taste of inline markup in paragraphs.
|
87
|
+
The Riker Ipsum filler follows:
|
88
|
+
|
89
|
+
Shields up! Rrrrred alert! Well, I'll say this for him - he's sure of himself.
|
90
|
+
and attack the Romulans. Worf, It's better than music. It's jazz. This should
|
91
|
+
be interesting. When has justice ever been as simple as a rule book? Flair is
|
92
|
+
what marks the difference between artistry and mere competence.
|
93
|
+
|
94
|
+
Sorry, Data. I think you've let your personal feelings cloud your judgement. We
|
95
|
+
finished our first sensor sweep of the neutral zone. Yes, absolutely, I do
|
96
|
+
indeed concur, wholeheartedly! Mr. Worf, you do remember how to fire phasers? A
|
97
|
+
lot of things can change in twelve years, Admiral. Your shields were failing,
|
98
|
+
sir.
|
99
|
+
|
100
|
+
== Verbatim sections
|
101
|
+
|
102
|
+
A verbatim section typically contains source code or example output. This is
|
103
|
+
how verbatim blocks of code looks:
|
104
|
+
|
105
|
+
def local responder
|
106
|
+
responder.ping do |value|
|
107
|
+
return value
|
108
|
+
end
|
109
|
+
end
|
110
|
+
|
111
|
+
def ping uri
|
112
|
+
@uri = uri
|
113
|
+
@remote = DRb::DRbObject.new_with_uri @uri
|
114
|
+
|
115
|
+
@remote.ping do |value|
|
116
|
+
return value
|
117
|
+
end
|
118
|
+
end
|
119
|
+
|
120
|
+
This is a paragraph following the verbatim block so you can see how leading and trailing paragraphs interact with it.
|
121
|
+
|
122
|
+
== Unordered lists
|
123
|
+
|
124
|
+
Here is an unordered list. As you can see it uses non-numeral markers for each list item:
|
125
|
+
|
126
|
+
* This is the top-most item in the list.
|
127
|
+
* This is a second item in the list.
|
128
|
+
|
129
|
+
Unlike the first item, this item has more than one paragraph so you can see
|
130
|
+
how they interact.
|
131
|
+
* This is a third item in the list. Like the item before it, this item has a
|
132
|
+
second paragraph.
|
133
|
+
|
134
|
+
Here is the second paragraph in the list item.
|
135
|
+
* A final list item.
|
136
|
+
|
137
|
+
== Ordered lists
|
138
|
+
|
139
|
+
Here is an ordered list. As you can see it uses numeral markers for each list
|
140
|
+
item:
|
141
|
+
|
142
|
+
1. This is the first item in the list.
|
143
|
+
1. This is the second item in the list.
|
144
|
+
|
145
|
+
Unlike the first item, this item has more than one paragraph so you can see
|
146
|
+
how they interact.
|
147
|
+
1. This is the third item in the list. Like the item before it, this item has
|
148
|
+
a second paragraph.
|
149
|
+
|
150
|
+
Here is the second paragraph in the third list item.
|
151
|
+
1. The fourth and final list item.
|
152
|
+
|
153
|
+
== Definition lists
|
154
|
+
|
155
|
+
=== "Note" list
|
156
|
+
|
157
|
+
The "note" syntax can be used to create a definition list:
|
158
|
+
|
159
|
+
note::
|
160
|
+
description
|
161
|
+
|
162
|
+
Here is such a definition list:
|
163
|
+
|
164
|
+
cat::
|
165
|
+
A cat is a small mammal that is commonly kept as a pet.
|
166
|
+
|
167
|
+
dog::
|
168
|
+
A dog is a mammal that is also kept as a pet. A dog may range in size from
|
169
|
+
smaller than a cat to larger than a human.
|
170
|
+
|
171
|
+
Typically dogs are easier to train to respond to commands than cats.
|
172
|
+
|
173
|
+
rabbit::
|
174
|
+
Rabbits are also mammals, but are infrequently kept as pets. Most rabbits
|
175
|
+
are wild.
|
176
|
+
|
177
|
+
=== "Label" list
|
178
|
+
|
179
|
+
The "label" syntax can be used to create a definition list:
|
180
|
+
|
181
|
+
[label]
|
182
|
+
description
|
183
|
+
|
184
|
+
Here is such a definition list:
|
185
|
+
|
186
|
+
[cat]
|
187
|
+
A cat is a small mammal that is commonly kept as a pet.
|
188
|
+
|
189
|
+
[dog]
|
190
|
+
A dog is a mammal that is also kept as a pet. A dog may range in size from
|
191
|
+
smaller than a cat to larger than a human.
|
192
|
+
|
193
|
+
Typically dogs are easier to train to respond to commands than cats.
|
194
|
+
|
195
|
+
[rabbit]
|
196
|
+
Rabbits are also mammals, but are infrequently kept as pets. Most rabbits
|
197
|
+
are wild.
|
198
|
+
|
199
|
+
== Rule
|
200
|
+
|
201
|
+
A rule is a horizontal divider between two paragraphs. Following this
|
202
|
+
paragraph is a rule.
|
203
|
+
|
204
|
+
---
|
205
|
+
|
206
|
+
In historic versions of RDoc you could control the height of the rule in HTML
|
207
|
+
output. This is no longer true as HTML 5 does not support this.
|
208
|
+
|