rdtool 0.6.23

Sign up to get free protection for your applications and to get access to all the features.
Files changed (94) hide show
  1. data/COPYING.txt +674 -0
  2. data/Gemfile +9 -0
  3. data/HISTORY +284 -0
  4. data/LICENSE.txt +58 -0
  5. data/MANIFEST +89 -0
  6. data/README.html +44 -0
  7. data/README.ja.html +46 -0
  8. data/README.rd +52 -0
  9. data/README.rd.ja +54 -0
  10. data/Rakefile +29 -0
  11. data/TODO +15 -0
  12. data/VERSION +1 -0
  13. data/bin/rd2 +281 -0
  14. data/bin/rdswap.rb +207 -0
  15. data/doc/rd-draft.rd +479 -0
  16. data/doc/rd-draft.rd.ja +487 -0
  17. data/lib/rd/block-element.rb +114 -0
  18. data/lib/rd/complex-list-item.rb +65 -0
  19. data/lib/rd/desclist.rb +55 -0
  20. data/lib/rd/document-struct.rb +46 -0
  21. data/lib/rd/dot.rd2rc +18 -0
  22. data/lib/rd/element.rb +160 -0
  23. data/lib/rd/filter.rb +255 -0
  24. data/lib/rd/inline-element.rb +233 -0
  25. data/lib/rd/labeled-element.rb +14 -0
  26. data/lib/rd/list.rb +57 -0
  27. data/lib/rd/loose-struct.rb +11 -0
  28. data/lib/rd/methodlist.rb +57 -0
  29. data/lib/rd/output-format-visitor.rb +28 -0
  30. data/lib/rd/package.rb +4 -0
  31. data/lib/rd/parser-util.rb +14 -0
  32. data/lib/rd/post-install +1 -0
  33. data/lib/rd/rbl-file.rb +69 -0
  34. data/lib/rd/rbl-suite.rb +37 -0
  35. data/lib/rd/rd-struct.rb +86 -0
  36. data/lib/rd/rd2html-lib.rb +490 -0
  37. data/lib/rd/rd2html-opt.rb +67 -0
  38. data/lib/rd/rd2man-lib.rb +241 -0
  39. data/lib/rd/rd2rdo-lib.rb +19 -0
  40. data/lib/rd/rd2rmi-lib.rb +32 -0
  41. data/lib/rd/rdblockparser.ry +518 -0
  42. data/lib/rd/rdblockparser.tab.rb +1050 -0
  43. data/lib/rd/rdfmt.rb +15 -0
  44. data/lib/rd/rdinlineparser.ry +503 -0
  45. data/lib/rd/rdinlineparser.tab.rb +1243 -0
  46. data/lib/rd/rdvisitor.rb +214 -0
  47. data/lib/rd/reference-resolver.rb +114 -0
  48. data/lib/rd/search-file.rb +14 -0
  49. data/lib/rd/tree.rb +103 -0
  50. data/lib/rd/version.rb +39 -0
  51. data/lib/rd/visitor.rb +86 -0
  52. data/makerdtool.rb +75 -0
  53. data/setup.rb +1596 -0
  54. data/test.rb +33 -0
  55. data/test/data/includee1.html +1 -0
  56. data/test/data/includee2.html +1 -0
  57. data/test/data/includee3.nothtml +1 -0
  58. data/test/data/includee4.xhtml +0 -0
  59. data/test/data/label.rbl +2 -0
  60. data/test/data/label2.rbl +2 -0
  61. data/test/data/sub/includee2.html +1 -0
  62. data/test/data/sub/includee4.html +0 -0
  63. data/test/dummy-observer.rb +6 -0
  64. data/test/dummy.rb +33 -0
  65. data/test/temp-dir.rb +19 -0
  66. data/test/test-block-parser.rb +46 -0
  67. data/test/test-desclist-item.rb +219 -0
  68. data/test/test-document-element.rb +46 -0
  69. data/test/test-document-struct.rb +66 -0
  70. data/test/test-element.rb +46 -0
  71. data/test/test-headline.rb +80 -0
  72. data/test/test-inline-parser.rb +46 -0
  73. data/test/test-list-item.rb +54 -0
  74. data/test/test-list.rb +53 -0
  75. data/test/test-methodlist-item.rb +73 -0
  76. data/test/test-nonterminal-element.rb +170 -0
  77. data/test/test-nonterminal-inline.rb +33 -0
  78. data/test/test-output-format-visitor.rb +48 -0
  79. data/test/test-parser-util.rb +41 -0
  80. data/test/test-rbl-file.rb +156 -0
  81. data/test/test-rbl-suite.rb +43 -0
  82. data/test/test-rd2html-lib.rb +496 -0
  83. data/test/test-rdtree.rb +17 -0
  84. data/test/test-rdvisitor.rb +29 -0
  85. data/test/test-reference-resolver.rb +202 -0
  86. data/test/test-reference.rb +132 -0
  87. data/test/test-search-file.rb +22 -0
  88. data/test/test-terminal-inline.rb +41 -0
  89. data/test/test-textblock.rb +44 -0
  90. data/test/test-tree.rb +82 -0
  91. data/test/test-version.rb +57 -0
  92. data/test/test-visitor.rb +230 -0
  93. data/utils/rd-mode.el +425 -0
  94. metadata +203 -0
data/bin/rdswap.rb ADDED
@@ -0,0 +1,207 @@
1
+ #! /usr/bin/ruby1.8 -s
2
+ #######
3
+ # rdswap.rb (c) C.Hintze <c.hintze@gmx.net> 30.08.1999
4
+ #######
5
+
6
+
7
+ require "ostruct";
8
+
9
+ if ARGV.size < 2 and not ($h or $help)
10
+ print "Wrong # of paramter! Use `-h' for help.\n";
11
+ exit 1;
12
+ elsif $h or $help
13
+ print eval('"'+DATA.read+'"');
14
+ exit 0;
15
+ end
16
+
17
+ srcfile = ARGV.select{|fn| fn =~ /\.rb$/o};
18
+ case srcfile.size
19
+ when 0
20
+ $stderr.print "Warning: No `.rb' file given! Take first file as source.\n";
21
+ srcfile = ARGV[0];
22
+ when 1
23
+ srcfile = srcfile[0];
24
+ else
25
+ print "Sorry! Only one source file (`.rb') allowed!\n";
26
+ exit(1);
27
+ end
28
+
29
+ docs = {};
30
+ srcs = {};
31
+
32
+ rddoc, rddocs = nil, [];
33
+ source, sources = [], [[]];
34
+
35
+ while gets
36
+ lang = $1 if File::basename(String($<)) =~ /^.*?([^.]+)$/o;
37
+ if /^=begin/o .. /^=end/o
38
+ title = $2 if /^=begin(\s+(.*))?$/o;
39
+ unless rddoc.nil?
40
+ unless /^=end/o
41
+ rddoc.lines << $_;
42
+ else
43
+ rddocs << rddoc;
44
+ sources << [];
45
+ rddoc = nil;
46
+ title = nil;
47
+ end
48
+ else # New RD block found! Instantiate data container.
49
+ rddoc = OpenStruct.new
50
+ rddoc.kind, rddoc.lines = title, [];
51
+ end
52
+ else # It is not a RD block means, it is a source line!
53
+ sources[-1] << $_;
54
+ end
55
+ if $<.eof? # One file finished. Remember data and proceed.
56
+ docs[lang] = rddocs;
57
+ srcs[lang] = sources;
58
+ rddoc, rddocs = nil, [];
59
+ source, sources = [], [[]];
60
+ end
61
+ end
62
+
63
+ langs = docs.keys;
64
+ langs.delete("rb"); # `rb' is not a language but the script!
65
+ source = srcs["rb"]; # Assign it for preventing later look-ups
66
+ srcdoc = docs["rb"];
67
+ sourcesize = source.size; # Do not recalculate size again and again.
68
+ srcdocsize = srcdoc.size;
69
+
70
+ for lang in langs
71
+ docblk = docs[lang];
72
+ max = [sourcesize, srcdocsize, docblk.size].max;
73
+ filename = File.join(srcfile+"."+lang);
74
+ open(filename, "w+") do |fd|
75
+ j = 0;
76
+ for i in 0...max # Goto every block; be it source or RD.
77
+ fd.print source[i].join unless source[i].nil? || source[i].empty?;
78
+ sblk, dblk = srcdoc[i], docblk[j];
79
+ blk = (dblk and (dblk.kind == sblk.kind)) ? dblk : sblk;
80
+ next unless blk;
81
+ j += 1 if blk == dblk;
82
+ fd.print "=begin #{blk && blk.kind}\n", blk.lines.join, "=end\n";
83
+ end
84
+ end
85
+ print "File `#{filename}' created.\n" if $v;
86
+ end
87
+
88
+ exit(0);
89
+
90
+ __END__
91
+
92
+ Purpose:
93
+ This tool is written to support you to write multi-language documents
94
+ using the Ruby-Document-Format (RD).
95
+
96
+ The idea for such a tool was originated by
97
+
98
+ Minero Aoki <aamine@dp.u-netsurf.ne.jp>,
99
+
100
+ how has thought about, how to make life easier for developers who have to
101
+ write and maintain scripts in more than one language.
102
+
103
+ You have to specify at least two filenames on the command line. One
104
+ containing the Ruby script, the second containing a translated RD. If the
105
+ script does *not* end with `.rb', it has to be the first filename mentioned
106
+ on the command line! In opposition, all files containing translations *must
107
+ not* ending with `.rb'! They should use a extension that describes the
108
+ language. So that would give us the following picture:
109
+
110
+ - sample.rb : Script contains the original documentation.
111
+ - sample.jp : Documentation written in Japanese.
112
+ - sample.de : Translation to German.
113
+
114
+ The tool doesn't care about the language extensions. You can name them as
115
+ you like! So the file containing the Japanese translation above, could also
116
+ be names e.g. `sample.japan' or even `japantranslation.japan'.
117
+
118
+ For every translation file, a new file will be created. The name is build
119
+ from the script filename plus the language extension. So regarding the
120
+ example above, following files would be created:
121
+
122
+ - sample.rb.jp
123
+ - sample.rb.de
124
+
125
+ or, given the alternative translation filename as mentioned above...
126
+
127
+ - sample.rb.japan
128
+
129
+ How does it work?
130
+ The contents of all files will be split into source and RD blocks. The
131
+ source of the translation files, will be discarded! Every RD block may
132
+ be of a certain type. The type will be taken from the contents directly
133
+ following the `=begin' on the same line. If there is only a lonely `=begin'
134
+ on a line by itself, the type of the block is `nil'. That means in
135
+
136
+ :
137
+ =begin
138
+ bla bla
139
+ =end
140
+ :
141
+ =begin whatever or not
142
+ blub blub
143
+ =end
144
+ :
145
+
146
+ the first block would be of type `nil' and the second one of type `whatever
147
+ or not'.
148
+
149
+ Block types are important for the translation. If a source will be
150
+ generated from a script and a translation file, only these blocks are taken
151
+ from the translation files, that comes in the right sequence *and* contains
152
+ the same type as the block in the script! For example:
153
+
154
+ # File sample.rb
155
+ :
156
+ =begin gnark
157
+ Some comment
158
+ =end
159
+ :
160
+ =begin
161
+ block 2
162
+ =end
163
+ :
164
+ =begin
165
+ block 3
166
+ =end
167
+ :
168
+
169
+ # File sample.de
170
+ :
171
+ =begin
172
+ Block zwei
173
+ =end
174
+ :
175
+ =begin
176
+ Block drei
177
+ =end
178
+ :
179
+
180
+ Here, the first block of `sample.rb' will *not* be translated, as there is
181
+ no translation block with that type in sample.de! So the first block would
182
+ be inserted as-it-is into the translated script. The blocks afterwards,
183
+ however, are translated as the block type does match (it is `nil' there).
184
+
185
+ Attention: In a translation file, a second block will only be used, if
186
+ a first one was already used (matched). A third block will
187
+ only be used, if a second one was used already!
188
+
189
+ That means, if the first block of `sample.de' would be of type e.g. `Never
190
+ match', then no block would ever be taken to replace anyone of `sample.rb'.
191
+
192
+ Syntax:
193
+ #{File::basename $0} [-h|-v] <filename>...
194
+
195
+ Whereby:
196
+ -h shows this help text.
197
+ -v shows some more text during processing.
198
+ <filename> Means a file, that contains RD and/or Ruby code.
199
+
200
+ Examples:
201
+ #{File::basename $0} -v sample.rb sample.ja sample.de
202
+ #{File::basename $0} -v sample.ja sample.rb sample.de
203
+ #{File::basename $0} -v sample.ja sample.de sample.rb
204
+ #{File::basename $0} -v sample.??
205
+
206
+ Author:
207
+ Clemens Hintze <c.hintze@gmx.net>.
data/doc/rd-draft.rd ADDED
@@ -0,0 +1,479 @@
1
+ = RD working draft
2
+ Japanese version is ((<here|URL:http://www.ruby-lang.org/~rubikitch/RDP.cgi?cmd=view&name=RD>)).
3
+
4
+ == What is RD?
5
+
6
+ RD is Ruby's POD, embeddable documentation format in script file.
7
+
8
+ RD is influenced mainly from plain2, a program to translate from plain text to
9
+ some mark-up language. So, RD looks like plain text, and its simpleness and
10
+ neatness make it easy to read and write.
11
+
12
+ == How does the interpreter work for RD?
13
+
14
+ Ruby's interpreter, (({ruby})), simply ignores text between a line beginning
15
+ with "(({=begin}))" and one beginning with "(({=end}))". So, RD is not only
16
+ embeddable. You can write anything between (({=begin})) and (({=end})). RD is
17
+ one of them, but RD will be a standard one.((- If you are interested in others,
18
+ see rubyapi2
19
+ ((<URL:http://www.ueda.info.waseda.ac.jp/~igarashi/ruby/xml.html#rubyapi2>))
20
+ for example. -))
21
+
22
+ == Concepts and Syntax
23
+ === Element, Block and Inline
24
+
25
+ We will use the term "Element" for features of RD which add information
26
+ of document structure to text. In addition, we use a term
27
+ "((<Block>))" for Elements for large and global structures, and a term
28
+ "((<Inline>))" for ones for small and local decorations.
29
+
30
+ Paragraph, headline or list is a kind of Block. RD uses indentation and
31
+ special characters to describe Blocks. You can also write complicated
32
+ structure to nested Blocks. And this style of Block looks naturally like
33
+ plain text format. See ((<Block>)) for details.
34
+
35
+ Emphasis, code or reference is a kind of Inline. Parentheses and special
36
+ characters, like (('((? ... ?))')), are used for Inline. Almost all
37
+ Inline may be nested inside each other. See ((<Inline>)) for more details.
38
+
39
+ === Block
40
+ ==== Basic Syntax
41
+
42
+ Block has line oriented syntax. i.e. each character on the same line belongs to the
43
+ same Block. And the indentation of the line represents nesting level and type of Block.
44
+ The first character of the line represents the type of Block.
45
+
46
+ + Concepts and Terms
47
+
48
+ :Baseline
49
+ Baseline is standard depth of indent. Relative depth between indent of one
50
+ line and Baseline affects its Block-type.
51
+
52
+ :Head Char
53
+ Head Char is the first character of line, except whitespace.
54
+
55
+ :STRINGLINE
56
+ STRINGLINE is line which consists of strings.
57
+ STRINGLINE doesn't have "(({*}))", "(({(((|num|)))}))", "(({:}))", "(({=}))"
58
+ nor "(({+}))" as Head Char. But if the line is indented, "(({=}))" and "(({+}))"
59
+ can be Head Char.
60
+
61
+ :WHITELINE
62
+ WHITELINE is a line which consists of whitespace, "(({\s}))", "(({\t}))" and
63
+ "(({\n}))".
64
+
65
+ :Comment
66
+ A line which is matched with (({/^#/})) is regarded as a comment.
67
+
68
+ + How Baseline is defined and how it works
69
+ At the top level, Baseline is at left end, i.e., indent is 0. In List,
70
+ Baseline is defined by first Block of ListItem. For example,
71
+
72
+ Example: "|" means Baseline
73
+ |Regard this line as one of TextBlock's in top level.
74
+ |<- So this Baseline is at the left-most position.
75
+ *|it is in List. (1)
76
+ |<- this Baseline is defined by the marked with a (1).
77
+ * |Different Item of List can have different Baseline inside.
78
+ |<- So this Baseline differs from one of this list's first item.
79
+
80
+ |Regard this line as one of TextBlock's in top level.
81
+ |<- So this Baseline is at the left-most position.
82
+ *|it is in List. (1)
83
+ |<- this Baseline is defined by the marked with a (1).
84
+ * |Different Items in Lists can have different Baselines inside.
85
+ |<- So this Baseline differs from the one of this list's first item.
86
+
87
+
88
+ If one Block is nested in another Block, the Baseline of the inside Blocks is deeper
89
+ than the Baseline of outside Blocks.
90
+
91
+ The relative position between Baseline and indent affects the type of Block.
92
+ If a ((<STRINGLINE>)) has same indent with Baseline, it belongs to
93
+ ((<TextBlock>)), otherwise, i.e. it has deeper indent than Baseline,
94
+ it belongs to ((<Verbatim>)).
95
+
96
+ ==== Types of Block
97
+ + Headline
98
+
99
+ Headline consists of a line which ((<Head Char>)) is "(({=}))" or
100
+ "(({+}))". And Headline can't include more than one line. Headline can
101
+ be on only top level.
102
+ Example:
103
+ |<- Regard this as top level Baseline.
104
+ = Headline 1.
105
+ === Headline 1.1.1.
106
+ + Headline 1.1.1.1.1.
107
+
108
+ = Headline 1.
109
+ === Headline 1.1.1.
110
+ + Headline 1.1.1.1.1.
111
+
112
+ Headline Mark represents level of Headline. See following figure. first
113
+ Mark is biggest one, and last Mark has two parts.
114
+ Fig: Headline Marks
115
+ =
116
+ ==
117
+ ===
118
+ ====
119
+ +
120
+ ++
121
+
122
+ Text which follows Mark is title of Headline. It is also used as Label of
123
+ ((<Reference>)).
124
+
125
+ Title of Headline can contain ((<Inline>))s except for ((<Reference>)) and
126
+ Footnote.
127
+
128
+ + Include
129
+
130
+ Include is a line that line head "(({<<<}))" and included file name.
131
+ You can input from other file text, both RD and target format, with Include.
132
+
133
+ When you include RD file, included file name have to have ".rd" or ".rb" as
134
+ suffix, like "foo.rd", and write full name (not full path) of file after
135
+ "(({<<<}))". For example,
136
+ <<< foo.rd
137
+
138
+ When you include target format file, include file name have to have suffix
139
+ of target format standard one, for example ".html" in the case of outputting
140
+ HTML, ".texi" in the case of outputting Texinfo, and write base name of file
141
+ after "(({<<<}))". For example,
142
+ <<< foo
143
+ RD formatter include "foo.html" to output HTML, and include "foo.texi" to
144
+ output Texinfo. If you want to use Include for target format, you should
145
+ prepare plural type of included file.
146
+
147
+ + TextBlock
148
+
149
+ TextBlock is composed of ((<STRINGLINE>))s, but the ((<STRINGLINE>))s
150
+ must have same indent with ((<Baseline>)). If its indent is deeper
151
+ than ((<Baseline>)), the ((<STRINGLINE>)) belongs to ((<Verbatim>)).
152
+
153
+ TextBlock can include ((<Inline>)) inside.
154
+
155
+ Example:
156
+ |
157
+ This is TextBlock.
158
+ Second line of same TextBlock.
159
+ This line is not TextBlock, but Verbatim.
160
+ * And this line is List. (But this line is exactly TextBlock in ListItem.)
161
+
162
+ And this example is formatted such like:
163
+
164
+ This is TextBlock.
165
+ Second line of same TextBlock.
166
+ This line is not TextBlock, but Verbatim.
167
+ * And this line is List. (But this line is exactly TextBlock in ListItem.)
168
+
169
+ + Verbatim
170
+
171
+ You can use Verbatim to cite Ruby script. Verbatim is composed of
172
+ ((<STRINGLINE>))s, and they must be indented deeper than
173
+ ((<Baseline>)). Verbatim can also include a line whose ((<Head Char>)) is
174
+ "(({*}))", "(({(1)}))" and "(({:}))", But it can't be first line of
175
+ Verbatim, it is regarded as ((<List>)). Verbatim can't include a line
176
+ which is indented shallower than first line. Verbatim can include
177
+ ((<WHITELINE>)).
178
+
179
+ You can't use ((<Inline>)) in Verbatim.
180
+
181
+ Example:
182
+ This is Verbatim.
183
+ Even if a line is indented deeper than first line, it is also in same
184
+ Verbatim.
185
+ * A line seems like list is also included in Verbatim.
186
+ But if the line is indented shallower, it is not in same Verbatim.
187
+ It is in other Verbatim.
188
+
189
+ And this example is formatted such like:
190
+
191
+ This is Verbatim.
192
+ Even if a line is indented deeper than first line, it is also in same
193
+ Verbatim.
194
+ * A line seems like list is also included in Verbatim.
195
+ But if the line is indented shallower, it is not in same Verbatim.
196
+ It is in other Verbatim.
197
+
198
+ + List
199
+
200
+ List is special ((<Block>)). List is composed of ListItems, and
201
+ ListItem is composed of Blocks. So List can include Blocks inside,
202
+ even also List itself.((- But List can't include ((<Headline>))
203
+ nor ((<Include>)). -))
204
+
205
+ ListItem can include ((<WHITELINE>)), and ((<TextBlock>)) can't
206
+ include WHITELINE, so when you want to write 2 TextBlock inside
207
+ ListItem, put a WHITELINE between TextBlocks.
208
+
209
+ There is 3 type of List, "((<ItemList>))", "((<EnumList>))",
210
+ "((<DescList>))" and "((<MethodList>)).
211
+
212
+ ++ ItemList
213
+
214
+ ItemList is simple and not numbered List. ItemListItem begins by a line
215
+ whose ((<Head Char>)) is "(({*}))", and first Block of ItemListItem must be
216
+ ((<TextBlock>)).
217
+
218
+ Example:
219
+ * first item of parent list
220
+ * first item of sub list
221
+ * second item of sub list
222
+ text block ( line of first item of parent list)
223
+
224
+ And this example is formatted such like:
225
+
226
+ * first item of parent list
227
+ * first item of sub list
228
+ * second item of sub list
229
+ text block ( line of first item of parent list)
230
+
231
+ ++ EnumList
232
+
233
+ EnumList is numbered List. EnumListItem starts with a line whose
234
+ ((<Head Char>)) is "(({(((|num|)))}))"(((|num|)) is integer). EnumList
235
+ is same as ((<ItemList>)) on other points.
236
+
237
+ Example:
238
+ (1) first line of parent list
239
+ * first line of sub list(ItemList)
240
+ (2) second list of parent list
241
+ (10) number is ignored...
242
+
243
+ And this example is formatted such like:
244
+
245
+ (1) first line of parent list
246
+ * first line of sub list(ItemList)
247
+ (2) second list of parent list
248
+ (10) number is ignored...
249
+
250
+ ++ DescList
251
+
252
+ DescList is List for descriptions. DescListItem has 2 part. One is Term part,
253
+ the other is Description part. Term of DescListItem is also used as Label
254
+ for ((<Reference>)).
255
+
256
+ Term part is composed of a line whose ((<Head Char>)) is "(({:}))",
257
+ and Term part is same as ((<Headline>)), except that a line of Term
258
+ part can be indented.
259
+
260
+ Description part is starts with next line of Term part. ((<Baseline>)) of
261
+ Description part must be same or deeper than term of Term part of its pair.
262
+ For example, following style is illegal.
263
+ Example:
264
+ : |Term
265
+ |Description.
266
+
267
+ Description part can include ((<Block>))s. ((<List>)) can be first
268
+ Block of Description part. Term part can contain ((<Inline>))s except
269
+ for ((<Reference>)) and ((<Footnote>)).
270
+
271
+ Example:
272
+ :Term
273
+ first line of Description
274
+ second line of Description
275
+ :Term2
276
+ * also include List
277
+ * ...
278
+
279
+ And this example is formatted such like:
280
+
281
+ :Term
282
+ first line of definition.
283
+ second line of definition
284
+ :Term2
285
+ * also include list
286
+ * ...
287
+
288
+ ++ MethodList
289
+
290
+ MethodList is the special type of ((<DescList>)) for explanation
291
+ methods of your classes. MethodList is similar with ((<DescList>)) in
292
+ almost all part, but it is labeled differently. RD formatters know it
293
+ is some kind of program code, e.g. method or constants of class in
294
+ Ruby or function prototype in C..., which is on Term part of
295
+ MethodList. So, MethodList is labeled without the part which seems to
296
+ be parameters of methods. See ((<Label and Reference>)) for more
297
+ detail.
298
+
299
+ Each item of MethodList has Term part and Description part like
300
+ ((<DescList>)). And its Term part start with its ((<Head Char>)),
301
+ "(({---}))". Its Description part can contain ((<TextBlock>)),
302
+ ((<Verbatim>)) and ((<List>)). But you shouldn't write MethodList
303
+ in any kind of ((<List>)). RD will come to deny it possibly in
304
+ future.
305
+
306
+ Example:
307
+ --- Array#each {|i| ... } # => labeled as "Array#each"
308
+ yield block for each item.
309
+ --- Array#index(val) # => labeled as "Array#index"
310
+ return index of first item which equals with ((|val|)). if it hasn't
311
+ same item, return (({nil})).
312
+
313
+ And this example is formatted such like:
314
+
315
+ --- Array#each {|i| ... }
316
+ yield block for each item.
317
+ --- Array#index(val)
318
+ return index of first item which equals with ((|val|)). if it hasn't
319
+ same item, return (({nil})).
320
+
321
+ Some formatter assumes it is Ruby's methods, constants or etc. which
322
+ is in Term part of MethodList. it can format term part of MethodList
323
+ intelligently, but you have to write according as specific formula
324
+ to make the best of its feature.
325
+
326
+ Standard Ruby class reference formula is suggested such like:
327
+ : instance method
328
+ instance method ((|method|)) of class ((|Class|))
329
+ Class#method(its params ...) { parameter block }
330
+ : class method (class singleton method)
331
+ class method ((|method|)) of class ((|Class|))
332
+ Class.method(its params ...) { parameter block }
333
+ : class constants
334
+ constant ((|Const|)) of class ((|Class|))
335
+ Class::Const
336
+ : functions (private methods on top level)
337
+ function ((|func|))
338
+ function#func(its params ...) { parameter block }
339
+
340
+ Ruby use some symbol characters (e.g. [], []=, +, - or <<) for the names
341
+ of methods. ruby, Ruby interpreter, parses them with different manner from
342
+ normal methods, but write them as same as others in this formula.
343
+
344
+ Example:
345
+ --- Array#[](key)
346
+ return value which in at index ((|key|)).
347
+ --- Array#[]=(key, value)
348
+ put ((|value|)) into cell of index ((|key|)).
349
+ --- Array#+(other)
350
+ return concatenated (({Array})).
351
+
352
+ === Inline
353
+
354
+ You can use Inline in ((<TextBlock>)), ((<Headline>)) and Term part of
355
+ ((<DescList>)). Common style of parentheses is used for Inline. Inline
356
+ can nest each other.
357
+
358
+ in following list of Inlines, preformatted text is on left hand side
359
+ and postformatted text is on right hand side.
360
+
361
+ :(('((*Em*))')) => ((*Em*))
362
+ Emphasis.
363
+
364
+ :(('(({while gets...}))')) => (({while gets...}))
365
+ Code.
366
+
367
+ :(('((|var|))')) => ((|var|))
368
+ Var.((- You can read very good explanation about Var in texinfo.info. -))
369
+
370
+ :(('((%ruby -v%))')) => ((%ruby -v%))
371
+ Keyboard.
372
+
373
+ :(('((:Term:))'))
374
+ => ((:Term:))
375
+
376
+ Term of Index.
377
+
378
+ :(('((<Identity or URL>))'))
379
+ => ((<Identity or URL>))
380
+
381
+ Link, Reference. See ((<RD/Label and Reference>)) for more detail.
382
+
383
+ :(('((-Footnote-))'))
384
+ => ((-Footnote-))
385
+
386
+ Footnote.
387
+
388
+ :(('(('verb\'))')) => (('verb'))
389
+ Inline Verbatim.
390
+
391
+ ==== Label and Reference
392
+
393
+ Reference needs Label. In RD, only title of ((<Headline>)) and Term of
394
+ ((<DescList>)) and ((<MethodList>)) is regarded as Label. So, you must
395
+ choose different titles for different ((<Headline>))s. This problem
396
+ has not resolved yet.
397
+
398
+ + How to RD generates Label from Headline, DescList or MethodList
399
+
400
+ Title of ((<Headline>)) and Term part of ((<DescList>)) and ((<MethodList>))
401
+ are regarded as Label. But they can contain ((<Inline>))s, so the situation
402
+ isn't so simple.
403
+
404
+ First, ((<MethodList>)) is special in the part of Labeling. Term part of
405
+ ((<MethodList>)) can't contain ((<Inline>))s, and RD assumes it is method
406
+ reference or such thing which is in Term part of ((<MethodList>)). So
407
+ it is Labeled under following rules.
408
+
409
+ (1) It is regarded as Label which is before a character of "(({(}))" or
410
+ "(({{}))".((- text inside "(({(...)}))" is regarded as parameters
411
+ of method, and text inside "(({{...}}))" is regarded as parameter
412
+ block of methods.-))
413
+
414
+ Following example will help you to understand how this rule works. the Label
415
+ which is generated from the term part of ((<MethodList>)) is after mark of
416
+ "(({# =>}))".
417
+
418
+ Example:
419
+ --- Array.new([size[, val]]) # => Array.new
420
+ --- Array#[]=(key, val) # => Array#[]=
421
+ --- Array#each { ... } # => Array#each
422
+ --- void rb_define_method(VALUE class, ...) # => void rb_define_method
423
+
424
+ Second, in the case of title of ((<Headline>)) or term part of ((<DescList>)),
425
+ there is not such a special rule. But you can use ((<Inline>))s for text on
426
+ them, so there are rules to strip ((<Inline>)) mark-ups from text.
427
+
428
+ (1) Any ((<Inline>)) mark-ups makes any difference to Label. So, both
429
+ = ((*Headline*))
430
+ and
431
+ = Headline
432
+ are Labeled as "Headline".
433
+ (2) But white spaces which is after open parenthesis and before close
434
+ parenthesis of ((<Inline>)) are striped when RD generates Label from
435
+ it. So, both
436
+ = ((* Headline *))
437
+ and
438
+ = ((*Headline*))
439
+ are Labeled as "Headline".
440
+
441
+ + Reference
442
+
443
+ You can refer Labeled element with Reference which is a kind of ((<Inline>))
444
+ marked up with (('((<...>))')).
445
+
446
+ Most simple use of Reference is to write Label inside parenthesis.
447
+ ((<Label>))
448
+ This works as reference to Label of "Label" and text "Label" is used
449
+ also for display such like: ((<Label>)).((- There is no element Labeled
450
+ "Label", so it doesn't seems to be Reference probably. -))
451
+
452
+ When you want to refer a resource pointed with URL, write such like:
453
+ ((<URL:http://www.ruby-lang.org/en/raa.html>))
454
+ RD formatter will format it as hyper-link to its URL if possible
455
+ such like:((<URL:http://www.ruby-lang.org/en/raa.html>)).
456
+
457
+ When you want to use other text than Label for display, write such like:
458
+ ((<Text for display|Label>))
459
+ "Text for display" is used for display and "Label" is used as Label to
460
+ refer such like: ((<Text for display|Label>))
461
+
462
+ Text for display can contain some ((<Inline>)), except for Footnotes and
463
+ Reference.
464
+
465
+ In Reference, "|" and "/" are syntax keywords. So if you will write them
466
+ inside Reference, you have to double-quote the part it's inside, such like:
467
+ ((<"Bar | inside display text"|Label>))
468
+ ((<"Bar | inside display text"|Label>))
469
+
470
+ The situations are same whether you will write them inside Substitution
471
+ part, Filename part and Label part.
472
+
473
+ Of course, you can use the text for the display for Reference to URL resource.
474
+ ((<Ruby Application Archive|URL:http://www.ruby-lang.org/en/raa.html>))
475
+ ((<Ruby Application Archive|URL:http://www.ruby-lang.org/en/raa.html>))
476
+
477
+ When the text for the display is omitted, you can use ((<Inline>)) for Label.
478
+ ((<((*Label*))>))
479
+ ((<((*Label*))>))