~ubuntu-branches/ubuntu/wily/tdiary/wily

« back to all changes in this revision

Viewing changes to vendor/rdtool-0.6.38/doc/rd-draft.html

  • Committer: Package Import Robot
  • Author(s): Hideki Yamane
  • Date: 2013-05-19 16:14:01 UTC
  • mfrom: (12.1.1 experimental)
  • Revision ID: package-import@ubuntu.com-20130519161401-hf5oyr8g8a94fsew
Tags: 3.2.2-2
Upload to unstable 

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
<?xml version="1.0" ?>
 
2
<!DOCTYPE html 
 
3
  PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 
4
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 
5
<html xmlns="http://www.w3.org/1999/xhtml">
 
6
<head>
 
7
<title>doc/rd-draft.rd</title>
 
8
</head>
 
9
<body>
 
10
<h1><a name="label-0" id="label-0">RD working draft</a></h1><!-- RDLabel: "RD working draft" -->
 
11
<p>Japanese version is <a href="http://www.ruby-lang.org/~rubikitch/RDP.cgi?cmd=view&amp;name=RD">here</a>.</p>
 
12
<h2><a name="label-1" id="label-1">What is RD?</a></h2><!-- RDLabel: "What is RD?" -->
 
13
<p>RD is Ruby's POD, embeddable documentation format in script file. </p>
 
14
<p>RD is influenced mainly from plain2, a program to translate from plain text to
 
15
some mark-up language. So, RD looks like plain text, and its simpleness and
 
16
neatness make it easy to read and write.</p>
 
17
<h2><a name="label-2" id="label-2">How does the interpreter work for RD?</a></h2><!-- RDLabel: "How does the interpreter work for RD?" -->
 
18
<p>Ruby's interpreter, <code>ruby</code>, simply ignores text between a line beginning
 
19
with "<code>=begin</code>" and one beginning with "<code>=end</code>". So, RD is not only 
 
20
embeddable. You can write anything between <code>=begin</code> and <code>=end</code>. RD is
 
21
one of them, but RD will be a standard one.<a name="footmark-1" id="footmark-1" href="#foottext-1"><sup><small>*1</small></sup></a></p>
 
22
<h2><a name="label-3" id="label-3">Concepts and Syntax</a></h2><!-- RDLabel: "Concepts and Syntax" -->
 
23
<h3><a name="label-4" id="label-4">Element, Block and Inline</a></h3><!-- RDLabel: "Element, Block and Inline" -->
 
24
<p>We will use the term "Element" for features of RD which add information
 
25
of document structure to text. In addition, we use a term
 
26
"<a href="#label-5">Block</a>" for Elements for large and global structures, and a term
 
27
"<a href="#label-35">Inline</a>" for ones for small and local decorations.</p>
 
28
<p>Paragraph, headline or list is a kind of Block. RD uses indentation and
 
29
special characters to describe Blocks. You can also write complicated
 
30
structure to nested Blocks. And this style of Block looks naturally like
 
31
plain text format.  See <a href="#label-5">Block</a> for details.</p>
 
32
<p>Emphasis, code or reference is a kind of Inline. Parentheses and special
 
33
characters, like ((? ... ?)), are used for Inline. Almost all
 
34
Inline may be nested inside each other. See <a href="#label-35">Inline</a> for more details.</p>
 
35
<h3><a name="label-5" id="label-5">Block</a></h3><!-- RDLabel: "Block" -->
 
36
<h4><a name="label-6" id="label-6">Basic Syntax</a></h4><!-- RDLabel: "Basic Syntax" -->
 
37
<p>Block has line oriented syntax. i.e. each character on the same line belongs to the
 
38
same Block. And the indentation of the line represents nesting level and type of Block.
 
39
The first character of the line represents the type of Block.</p>
 
40
<h5><a name="label-7" id="label-7">Concepts and Terms</a></h5><!-- RDLabel: "Concepts and Terms" -->
 
41
<dl>
 
42
<dt><a name="label-8" id="label-8">Baseline</a></dt><!-- RDLabel: "Baseline" -->
 
43
<dd>
 
44
Baseline is standard depth of indent. Relative depth between indent of one
 
45
line and Baseline affects its Block-type.
 
46
</dd>
 
47
<dt><a name="label-9" id="label-9">Head Char</a></dt><!-- RDLabel: "Head Char" -->
 
48
<dd>
 
49
Head Char is the first character of line, except whitespace.
 
50
</dd>
 
51
<dt><a name="label-10" id="label-10">STRINGLINE</a></dt><!-- RDLabel: "STRINGLINE" -->
 
52
<dd>
 
53
STRINGLINE is line which consists of strings.
 
54
STRINGLINE doesn't have "<code>*</code>", "<code>(<var>num</var>)</code>", "<code>:</code>", "<code>=</code>"
 
55
nor "<code>+</code>" as Head Char. But if the line is indented, "<code>=</code>" and "<code>+</code>"
 
56
can be Head Char.
 
57
</dd>
 
58
<dt><a name="label-11" id="label-11">WHITELINE</a></dt><!-- RDLabel: "WHITELINE" -->
 
59
<dd>
 
60
WHITELINE is a line which consists of whitespace, "<code>\s</code>", "<code>\t</code>" and
 
61
"<code>\n</code>".
 
62
</dd>
 
63
<dt><a name="label-12" id="label-12">Comment</a></dt><!-- RDLabel: "Comment" -->
 
64
<dd>
 
65
A line which is matched with <code>/^#/</code> is regarded as a comment.
 
66
</dd>
 
67
</dl>
 
68
<h5><a name="label-13" id="label-13">How Baseline is defined and how it works</a></h5><!-- RDLabel: "How Baseline is defined and how it works" -->
 
69
<p>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,</p>
 
71
<pre>Example: "|" means Baseline
 
72
  |Regard this line as one of TextBlock's in top level.
 
73
  |&lt;- So this Baseline is at the left-most position.
 
74
    *|it is in List. (1)
 
75
     |&lt;- this Baseline is defined by the marked with a (1).
 
76
    *    |Different Item of List can have different Baseline inside.
 
77
         |&lt;- So this Baseline differs from one of this list's first item.</pre>
 
78
<p>|Regard this line as one of TextBlock's in top level.
 
79
|&lt;- So this Baseline is at the left-most position.</p>
 
80
<ul>
 
81
<li>|it is in List. (1)
 
82
   |&lt;- this Baseline is defined by the marked with a (1).</li>
 
83
<li>|Different Items in Lists can have different Baselines inside.
 
84
       |&lt;- So this Baseline differs from the one of this list's first item.</li>
 
85
</ul>
 
86
<p>If one Block is nested in another Block, the Baseline of the inside Blocks is deeper
 
87
than the Baseline of outside Blocks.</p>
 
88
<p>The relative position between Baseline and indent affects the type of Block.
 
89
If a <a href="#label-10">STRINGLINE</a> has same indent with Baseline, it belongs to
 
90
<a href="#label-20">TextBlock</a>, otherwise, i.e. it has deeper indent than Baseline,
 
91
it belongs to <a href="#label-21">Verbatim</a>.</p>
 
92
<h4><a name="label-14" id="label-14">Types of Block</a></h4><!-- RDLabel: "Types of Block" -->
 
93
<h5><a name="label-15" id="label-15">Headline</a></h5><!-- RDLabel: "Headline" -->
 
94
<p>Headline consists of a line which <a href="#label-9">Head Char</a> is "<code>=</code>" or
 
95
"<code>+</code>". And Headline can't include more than one line. Headline can
 
96
be on only top level.</p>
 
97
<pre>Example:
 
98
|&lt;- Regard this as top level Baseline.
 
99
= Headline 1.
 
100
=== Headline 1.1.1.
 
101
+ Headline 1.1.1.1.1.</pre>
 
102
<h1><a name="label-16" id="label-16">Headline 1.</a></h1><!-- RDLabel: "Headline 1." -->
 
103
<h3><a name="label-17" id="label-17">Headline 1.1.1.</a></h3><!-- RDLabel: "Headline 1.1.1." -->
 
104
<h5><a name="label-18" id="label-18">Headline 1.1.1.1.1.</a></h5><!-- RDLabel: "Headline 1.1.1.1.1." -->
 
105
<p>Headline Mark represents level of Headline. See following figure. first
 
106
Mark is biggest one, and last Mark has two parts.</p>
 
107
<pre>Fig: Headline Marks
 
108
=
 
109
==
 
110
===
 
111
====
 
112
+
 
113
++</pre>
 
114
<p>Text which follows Mark is title of Headline. It is also used as Label of
 
115
<a href="#label-46">Reference</a>.</p>
 
116
<p>Title of Headline can contain <a href="#label-35">Inline</a>s except for <a href="#label-46">Reference</a> and
 
117
Footnote.</p>
 
118
<h5><a name="label-19" id="label-19">Include</a></h5><!-- RDLabel: "Include" -->
 
119
<p>Include is a line that line head  "<code>&lt;&lt;&lt;</code>" and included file name. 
 
120
You can input from other file text, both RD and target format, with Include.</p>
 
121
<p>When you include RD file, included file name have to have ".rd" or ".rb" as
 
122
suffix, like "foo.rd", and write full name (not full path) of file after
 
123
"<code>&lt;&lt;&lt;</code>". For example,</p>
 
124
<pre>&lt;&lt;&lt; foo.rd</pre>
 
125
<p>When you include target format file, include file name have to have suffix
 
126
of target format standard one, for example ".html" in the case of outputting
 
127
HTML, ".texi" in the case of outputting Texinfo, and write base name of file
 
128
after "<code>&lt;&lt;&lt;</code>". For example,</p>
 
129
<pre>&lt;&lt;&lt; foo</pre>
 
130
<p>RD formatter include "foo.html" to output HTML, and include "foo.texi" to
 
131
output Texinfo. If you want to use Include for target format, you should
 
132
prepare plural type of included file. </p>
 
133
<h5><a name="label-20" id="label-20">TextBlock</a></h5><!-- RDLabel: "TextBlock" -->
 
134
<p>TextBlock is composed of <a href="#label-10">STRINGLINE</a>s, but the <a href="#label-10">STRINGLINE</a>s
 
135
must have same indent with <a href="#label-8">Baseline</a>. If its indent is deeper
 
136
than <a href="#label-8">Baseline</a>, the <a href="#label-10">STRINGLINE</a> belongs to <a href="#label-21">Verbatim</a>.</p>
 
137
<p>TextBlock can include <a href="#label-35">Inline</a> inside.</p>
 
138
<pre>Example:
 
139
|
 
140
This is TextBlock. 
 
141
Second line of same TextBlock.
 
142
  This line is not TextBlock, but Verbatim.
 
143
* And this line is List. (But this line is exactly TextBlock in ListItem.)</pre>
 
144
<p>And this example is formatted such like:</p>
 
145
<p>This is TextBlock. 
 
146
Second line of same TextBlock.</p>
 
147
<pre>This line is not TextBlock, but Verbatim.</pre>
 
148
<ul>
 
149
<li>And this line is List. (But this line is exactly TextBlock in ListItem.)</li>
 
150
</ul>
 
151
<h5><a name="label-21" id="label-21">Verbatim</a></h5><!-- RDLabel: "Verbatim" -->
 
152
<p>You can use Verbatim to cite Ruby script. Verbatim is composed of
 
153
<a href="#label-10">STRINGLINE</a>s, and they must be indented deeper than
 
154
<a href="#label-8">Baseline</a>. Verbatim can also include a line whose <a href="#label-9">Head Char</a> is
 
155
"<code>*</code>", "<code>(1)</code>" and "<code>:</code>", But it can't be first line of
 
156
Verbatim, it is regarded as <a href="#label-22">List</a>.  Verbatim can't include a line
 
157
which is indented shallower than first line.  Verbatim can include
 
158
<a href="#label-11">WHITELINE</a>.</p>
 
159
<p>You can't use <a href="#label-35">Inline</a> in Verbatim.</p>
 
160
<pre>Example:
 
161
 This is Verbatim.
 
162
   Even if a line is indented deeper than first line, it is also in same
 
163
   Verbatim.
 
164
 * A line seems like list is also included in Verbatim.
 
165
But if the line is indented shallower, it is not in same Verbatim.
 
166
It is in other Verbatim.</pre>
 
167
<p>And this example is formatted such like:</p>
 
168
<pre>This is Verbatim.
 
169
  Even if a line is indented deeper than first line, it is also in same
 
170
  Verbatim.
 
171
* A line seems like list is also included in Verbatim.</pre>
 
172
<pre>But if the line is indented shallower, it is not in same Verbatim.
 
173
It is in other Verbatim.</pre>
 
174
<h5><a name="label-22" id="label-22">List</a></h5><!-- RDLabel: "List" -->
 
175
<p>List is special <a href="#label-5">Block</a>. List is composed of ListItems, and
 
176
ListItem is composed of Blocks. So List can include Blocks inside,
 
177
even also List itself.<a name="footmark-2" id="footmark-2" href="#foottext-2"><sup><small>*2</small></sup></a></p>
 
178
<p>ListItem can include <a href="#label-11">WHITELINE</a>, and <a href="#label-20">TextBlock</a> can't
 
179
include WHITELINE, so when you want to write 2 TextBlock inside
 
180
ListItem, put a WHITELINE between TextBlocks.</p>
 
181
<p>There is 3 type of List, "<a href="#label-23">ItemList</a>", "<a href="#label-24">EnumList</a>",
 
182
"<a href="#label-25">DescList</a>" and "<a href="#label-28">MethodList</a>.</p>
 
183
<h6><a name="label-23" id="label-23">ItemList</a></h6><!-- RDLabel: "ItemList" -->
 
184
<p>ItemList is simple and not numbered List. ItemListItem begins by a line
 
185
whose <a href="#label-9">Head Char</a> is "<code>*</code>", and first Block of ItemListItem must be
 
186
<a href="#label-20">TextBlock</a>.</p>
 
187
<pre>Example:
 
188
* first item of parent list
 
189
    * first item of sub list
 
190
    * second item of sub list
 
191
  text block ( line of first item of parent list)</pre>
 
192
<p>And this example is formatted such like:</p>
 
193
<ul>
 
194
<li><p>first item of parent list</p>
 
195
<ul>
 
196
<li>first item of sub list</li>
 
197
<li>second item of sub list</li>
 
198
</ul>
 
199
<p>text block ( line of first item of parent list)</p></li>
 
200
</ul>
 
201
<h6><a name="label-24" id="label-24">EnumList</a></h6><!-- RDLabel: "EnumList" -->
 
202
<p>EnumList is numbered List. EnumListItem starts with a line whose
 
203
<a href="#label-9">Head Char</a> is "<code>(<var>num</var>)</code>"(<var>num</var> is integer). EnumList
 
204
is same as <a href="#label-23">ItemList</a> on other points.</p>
 
205
<pre>Example:
 
206
(1) first line of parent list
 
207
      * first line of sub list(ItemList)
 
208
(2) second list of parent list
 
209
(10) number is ignored...</pre>
 
210
<p>And this example is formatted such like:</p>
 
211
<ol>
 
212
<li>first line of parent list
 
213
<ul>
 
214
<li>first line of sub list(ItemList)</li>
 
215
</ul></li>
 
216
<li>second list of parent list</li>
 
217
<li>number is ignored...</li>
 
218
</ol>
 
219
<h6><a name="label-25" id="label-25">DescList</a></h6><!-- RDLabel: "DescList" -->
 
220
<p>DescList is List for descriptions. DescListItem has 2 part. One is Term part,
 
221
the other is Description part. Term of DescListItem is also used as Label 
 
222
for <a href="#label-46">Reference</a>.</p>
 
223
<p>Term part is composed of a line whose <a href="#label-9">Head Char</a> is "<code>:</code>",
 
224
and Term part is same as <a href="#label-15">Headline</a>, except that a line of Term
 
225
part can be indented.</p>
 
226
<p>Description part is starts with next line of Term part. <a href="#label-8">Baseline</a> of
 
227
Description part must be same or deeper than term of Term part of its pair.
 
228
For example, following style is illegal.</p>
 
229
<pre>Example:
 
230
:   |Term
 
231
  |Description.</pre>
 
232
<p>Description part can include <a href="#label-5">Block</a>s. <a href="#label-22">List</a> can be first
 
233
Block of Description part. Term part can contain <a href="#label-35">Inline</a>s except
 
234
for <a href="#label-46">Reference</a> and <!-- Reference, RDLabel "Footnote" doesn't exist --><em class="label-not-found">Footnote</em><!-- Reference end -->.</p>
 
235
<pre>Example:
 
236
:Term
 
237
   first line of Description
 
238
   second line of Description
 
239
:Term2
 
240
   * also include List
 
241
   * ...</pre>
 
242
<p>And this example is formatted such like:</p>
 
243
<dl>
 
244
<dt><a name="label-26" id="label-26">Term</a></dt><!-- RDLabel: "Term" -->
 
245
<dd>
 
246
first line of definition.
 
247
second line of definition
 
248
</dd>
 
249
<dt><a name="label-27" id="label-27">Term2</a></dt><!-- RDLabel: "Term2" -->
 
250
<dd>
 
251
<ul>
 
252
<li>also include list</li>
 
253
<li>...</li>
 
254
</ul>
 
255
</dd>
 
256
</dl>
 
257
<h6><a name="label-28" id="label-28">MethodList</a></h6><!-- RDLabel: "MethodList" -->
 
258
<p>MethodList is the special type of <a href="#label-25">DescList</a> for explanation
 
259
methods of your classes. MethodList is similar with <a href="#label-25">DescList</a> in
 
260
almost all part, but it is labeled differently. RD formatters know it
 
261
is some kind of program code, e.g. method or constants of class in
 
262
Ruby or function prototype in C..., which is on Term part of
 
263
MethodList.  So, MethodList is labeled without the part which seems to
 
264
be parameters of methods. See <a href="#label-44">Label and Reference</a> for more
 
265
detail.</p>
 
266
<p>Each item of MethodList has Term part and Description part like
 
267
<a href="#label-25">DescList</a>. And its Term part start with its <a href="#label-9">Head Char</a>,
 
268
"<code>---</code>". Its Description part can contain <a href="#label-20">TextBlock</a>,
 
269
<a href="#label-21">Verbatim</a> and <a href="#label-22">List</a>. But you shouldn't write MethodList
 
270
in any kind of <a href="#label-22">List</a>. RD will come to deny it possibly in
 
271
future.</p>
 
272
<pre>Example:
 
273
--- Array#each {|i| ... } # =&gt; labeled as "Array#each"
 
274
      yield block for each item.
 
275
--- Array#index(val) # =&gt; labeled as "Array#index"
 
276
      return index of first item which equals with ((|val|)). if it hasn't
 
277
      same item, return (({nil})).</pre>
 
278
<p>And this example is formatted such like:</p>
 
279
<dl>
 
280
<dt><a name="label-29" id="label-29"><code>Array#each {|<var>i</var>| ... }</code></a></dt><!-- RDLabel: "Array#each" -->
 
281
<dd>
 
282
yield block for each item.</dd>
 
283
<dt><a name="label-30" id="label-30"><code>Array#index(<var>val</var>)</code></a></dt><!-- RDLabel: "Array#index" -->
 
284
<dd>
 
285
return index of first item which equals with <var>val</var>. if it hasn't
 
286
same item, return <code>nil</code>.</dd>
 
287
</dl>
 
288
<p>Some formatter assumes it is Ruby's methods, constants or etc. which
 
289
is in Term part of MethodList. it can format term part of MethodList
 
290
intelligently, but you have to write according as specific formula
 
291
to make the best of its feature. </p>
 
292
<p>Standard Ruby class reference formula is suggested such like: </p>
 
293
<dl>
 
294
<dt><a name="label-31" id="label-31">instance method</a></dt><!-- RDLabel: "instance method" -->
 
295
<dd>
 
296
<p>instance method <var>method</var> of class <var>Class</var></p>
 
297
<pre>Class#method(its params  ...) { parameter block }</pre>
 
298
</dd>
 
299
<dt><a name="label-32" id="label-32">class method (class singleton method)</a></dt><!-- RDLabel: "class method (class singleton method)" -->
 
300
<dd>
 
301
<p>class method <var>method</var> of class <var>Class</var></p>
 
302
<pre>Class.method(its params ...) { parameter block }</pre>
 
303
</dd>
 
304
<dt><a name="label-33" id="label-33">class constants</a></dt><!-- RDLabel: "class constants" -->
 
305
<dd>
 
306
<p>constant <var>Const</var> of class <var>Class</var></p>
 
307
<pre>Class::Const</pre>
 
308
</dd>
 
309
<dt><a name="label-34" id="label-34">functions (private methods on top level)</a></dt><!-- RDLabel: "functions (private methods on top level)" -->
 
310
<dd>
 
311
<p>function <var>func</var></p>
 
312
<pre>function#func(its params ...) { parameter block }</pre>
 
313
</dd>
 
314
</dl>
 
315
<p>Ruby use some symbol characters (e.g. [], []=, +, - or &lt;&lt;) for the names
 
316
of methods. ruby, Ruby interpreter, parses them with different manner from
 
317
normal methods, but write them as same as others in this formula.</p>
 
318
<pre>Example:
 
319
  --- Array#[](key)
 
320
        return value which in at index ((|key|)).
 
321
  --- Array#[]=(key, value)
 
322
        put ((|value|)) into cell of index ((|key|)).
 
323
  --- Array#+(other)
 
324
        return concatenated (({Array})).</pre>
 
325
<h3><a name="label-35" id="label-35">Inline</a></h3><!-- RDLabel: "Inline" -->
 
326
<p>You can use Inline in <a href="#label-20">TextBlock</a>, <a href="#label-15">Headline</a> and Term part of
 
327
<a href="#label-25">DescList</a>. Common style of parentheses is used for Inline. Inline
 
328
can nest each other.</p>
 
329
<p>in following list of Inlines, preformatted text is on left hand side
 
330
and postformatted text is on right hand side.</p>
 
331
<dl>
 
332
<dt><a name="label-36" id="label-36">((*Em*)) =&gt; <em>Em</em></a></dt><!-- RDLabel: "((*Em*)) => Em" -->
 
333
<dd>
 
334
Emphasis.
 
335
</dd>
 
336
<dt><a name="label-37" id="label-37">(({while gets...})) =&gt; <code>while gets...</code></a></dt><!-- RDLabel: "(({while gets...})) => while gets..." -->
 
337
<dd>
 
338
Code.
 
339
</dd>
 
340
<dt><a name="label-38" id="label-38">((|var|)) =&gt; <var>var</var></a></dt><!-- RDLabel: "((|var|)) => var" -->
 
341
<dd>
 
342
Var.<a name="footmark-3" id="footmark-3" href="#foottext-3"><sup><small>*3</small></sup></a>
 
343
</dd>
 
344
<dt><a name="label-39" id="label-39">((%ruby -v%)) =&gt; <kbd>ruby -v</kbd></a></dt><!-- RDLabel: "((%ruby -v%)) => ruby -v" -->
 
345
<dd>
 
346
Keyboard.
 
347
</dd>
 
348
<dt><a name="label-40" id="label-40">((:Term:))</a></dt><!-- RDLabel: "((:Term:))" -->
 
349
<dd>
 
350
<p>=&gt; <a name="index-0" id="index-0">Term</a></p>
 
351
<p>Term of Index.</p>
 
352
</dd>
 
353
<dt><a name="label-41" id="label-41">((&lt;Identity or URL&gt;))</a></dt><!-- RDLabel: "((<Identity or URL>))" -->
 
354
<dd>
 
355
<p>=&gt; <!-- Reference, RDLabel "Identity or URL" doesn't exist --><em class="label-not-found">Identity or URL</em><!-- Reference end --></p>
 
356
<p>Link, Reference. See <a href="RD">Label and Reference</a> for more detail.</p>
 
357
</dd>
 
358
<dt><a name="label-42" id="label-42">((-Footnote-))</a></dt><!-- RDLabel: "((-Footnote-))" -->
 
359
<dd>
 
360
<p>=&gt; <a name="footmark-4" id="footmark-4" href="#foottext-4"><sup><small>*4</small></sup></a></p>
 
361
<p>Footnote.</p>
 
362
</dd>
 
363
<dt><a name="label-43" id="label-43">(('verb')) =&gt; verb</a></dt><!-- RDLabel: "(('verb')) => verb" -->
 
364
<dd>
 
365
Inline Verbatim.
 
366
</dd>
 
367
</dl>
 
368
<h4><a name="label-44" id="label-44">Label and Reference</a></h4><!-- RDLabel: "Label and Reference" -->
 
369
<p>Reference needs Label. In RD, only title of <a href="#label-15">Headline</a> and Term of
 
370
<a href="#label-25">DescList</a> and <a href="#label-28">MethodList</a> is regarded as Label. So, you must
 
371
choose different titles for different <a href="#label-15">Headline</a>s. This problem
 
372
has not resolved yet.</p>
 
373
<h5><a name="label-45" id="label-45">How to RD generates Label from Headline, DescList or MethodList</a></h5><!-- RDLabel: "How to RD generates Label from Headline, DescList or MethodList" -->
 
374
<p>Title of <a href="#label-15">Headline</a> and Term part of <a href="#label-25">DescList</a> and <a href="#label-28">MethodList</a>
 
375
are regarded as Label. But they can contain <a href="#label-35">Inline</a>s, so the situation
 
376
isn't so simple.</p>
 
377
<p>First, <a href="#label-28">MethodList</a> is special in the part of Labeling. Term part of
 
378
<a href="#label-28">MethodList</a> can't contain <a href="#label-35">Inline</a>s, and RD assumes it is method
 
379
reference or such thing which is in Term part of <a href="#label-28">MethodList</a>. So 
 
380
it is Labeled under following rules.</p>
 
381
<ol>
 
382
<li>It is regarded as Label which is before a character of "<code>(</code>" or
 
383
      "<code>{</code>".<a name="footmark-5" id="footmark-5" href="#foottext-5"><sup><small>*5</small></sup></a></li>
 
384
</ol>
 
385
<p>Following example will help you to understand how this rule works. the Label
 
386
which is generated from the term part of <a href="#label-28">MethodList</a> is after mark of
 
387
"<code># =&gt;</code>".</p>
 
388
<pre>Example:
 
389
  --- Array.new([size[, val]]) # =&gt; Array.new
 
390
  --- Array#[]=(key, val) # =&gt; Array#[]=
 
391
  --- Array#each { ... } # =&gt; Array#each
 
392
  --- void rb_define_method(VALUE class, ...) # =&gt; void rb_define_method</pre>
 
393
<p>Second, in the case of title of <a href="#label-15">Headline</a> or term part of <a href="#label-25">DescList</a>,
 
394
there is not such a special rule. But you can use <a href="#label-35">Inline</a>s for text on
 
395
them, so there are rules to strip <a href="#label-35">Inline</a> mark-ups from text.</p>
 
396
<ol>
 
397
<li><p>Any <a href="#label-35">Inline</a> mark-ups makes any difference to Label. So, both</p>
 
398
<pre>= ((*Headline*))</pre>
 
399
<p>and</p>
 
400
<pre>= Headline</pre>
 
401
<p>are Labeled as "Headline".</p></li>
 
402
<li><p>But white spaces which is after open parenthesis and before close
 
403
      parenthesis of <a href="#label-35">Inline</a> are striped when RD generates Label from
 
404
      it. So, both</p>
 
405
<pre>= ((* Headline  *))</pre>
 
406
<p>and</p>
 
407
<pre>= ((*Headline*))</pre>
 
408
<p>are Labeled as "Headline".</p></li>
 
409
</ol>
 
410
<h5><a name="label-46" id="label-46">Reference</a></h5><!-- RDLabel: "Reference" -->
 
411
<p>You can refer Labeled element with Reference which is a kind of <a href="#label-35">Inline</a>
 
412
marked up with ((&lt;...&gt;)).</p>
 
413
<p>Most simple use of Reference is to write Label inside parenthesis.</p>
 
414
<pre>((&lt;Label&gt;))</pre>
 
415
<p>This works as reference to Label of "Label" and text "Label" is used
 
416
also for display such like: <!-- Reference, RDLabel "Label" doesn't exist --><em class="label-not-found">Label</em><!-- Reference end -->.<a name="footmark-6" id="footmark-6" href="#foottext-6"><sup><small>*6</small></sup></a></p>
 
417
<p>When you want to refer a resource pointed with URL, write such like:</p>
 
418
<pre>((&lt;URL:http://www.ruby-lang.org/en/raa.html&gt;))</pre>
 
419
<p>RD formatter will format it as hyper-link to its URL if possible
 
420
such like:<a href="http://www.ruby-lang.org/en/raa.html">&lt;URL:http://www.ruby-lang.org/en/raa.html&gt;</a>.</p>
 
421
<p>When you want to use other text than Label for display, write such like:</p>
 
422
<pre>((&lt;Text for display|Label&gt;))</pre>
 
423
<p>"Text for display" is used for display and "Label" is used as Label to
 
424
refer such like: <!-- Reference, RDLabel "Label" doesn't exist --><em class="label-not-found">Text for display</em><!-- Reference end --></p>
 
425
<p>Text for display can contain some <a href="#label-35">Inline</a>, except for Footnotes and
 
426
Reference.</p>
 
427
<p>In Reference, "|" and "/" are syntax keywords. So if you will write them
 
428
inside Reference, you have to double-quote the part it's inside, such like:</p>
 
429
<pre>((&lt;"Bar | inside display text"|Label&gt;))</pre>
 
430
<p><!-- Reference, RDLabel "Label" doesn't exist --><em class="label-not-found">Bar | inside display text</em><!-- Reference end --></p>
 
431
<p>The situations are same whether you will write them inside Substitution
 
432
part, Filename part and Label part.</p>
 
433
<p>Of course, you can use the text for the display for Reference to URL resource.</p>
 
434
<pre>((&lt;Ruby Application Archive|URL:http://www.ruby-lang.org/en/raa.html&gt;))</pre>
 
435
<p><a href="http://www.ruby-lang.org/en/raa.html">Ruby Application Archive</a></p>
 
436
<p>When the text for the display is omitted, you can use <a href="#label-35">Inline</a> for Label.</p>
 
437
<pre>((&lt;((*Label*))&gt;))</pre>
 
438
<p><!-- Reference, RDLabel "Label" doesn't exist --><em class="label-not-found"><em>Label</em></em><!-- Reference end --></p>
 
439
<hr />
 
440
<p class="foottext">
 
441
<a name="foottext-1" id="foottext-1" href="#footmark-1"><sup><small>*1</small></sup></a><small> If you are interested in others,
 
442
see rubyapi2
 
443
<a href="http://www.ueda.info.waseda.ac.jp/~igarashi/ruby/xml.html#rubyapi2">&lt;URL:http://www.ueda.info.waseda.ac.jp/~igarashi/ruby/xml.html#rubyapi2&gt;</a>
 
444
for example. </small><br />
 
445
<a name="foottext-2" id="foottext-2" href="#footmark-2"><sup><small>*2</small></sup></a><small> But List can't include <a href="#label-15">Headline</a>
 
446
nor <a href="#label-19">Include</a>. </small><br />
 
447
<a name="foottext-3" id="foottext-3" href="#footmark-3"><sup><small>*3</small></sup></a><small> You can read very good explanation about Var in texinfo.info. </small><br />
 
448
<a name="foottext-4" id="foottext-4" href="#footmark-4"><sup><small>*4</small></sup></a><small>Footnote</small><br />
 
449
<a name="foottext-5" id="foottext-5" href="#footmark-5"><sup><small>*5</small></sup></a><small> text inside "<code>(...)</code>" is regarded as parameters
 
450
      of method, and text inside "<code>{...}</code>" is regarded as parameter
 
451
      block of methods.</small><br />
 
452
<a name="foottext-6" id="foottext-6" href="#footmark-6"><sup><small>*6</small></sup></a><small> There is no element Labeled
 
453
"Label", so it doesn't seems to be Reference probably. </small><br />
 
454
</p>
 
455
</body>
 
456
</html>