gerbil 1.0.0
Sign up to get free protection for your applications and to get access to all the features.
- data/LICENSE +23 -0
- data/README +1 -0
- data/Rakefile +48 -0
- data/bin/gerbil +275 -0
- data/doc/HelloWorld.input +37 -0
- data/doc/HelloWorld.spec +66 -0
- data/doc/gerbil.png +0 -0
- data/doc/gerbil.svg +330 -0
- data/doc/guide.erb +677 -0
- data/doc/guide.html +3416 -0
- data/fmt/html.icons/LICENSE +67 -0
- data/fmt/html.icons/README +30 -0
- data/fmt/html.icons/caution.png +0 -0
- data/fmt/html.icons/important.png +0 -0
- data/fmt/html.icons/note.png +0 -0
- data/fmt/html.icons/tip.png +0 -0
- data/fmt/html.icons/warning.png +0 -0
- data/fmt/html.yaml +897 -0
- data/fmt/latex.yaml +2 -0
- data/fmt/man.yaml +2 -0
- data/fmt/text.yaml +2 -0
- data/lib/gerbil.rb +11 -0
- data/lib/gerbil/html.rb +149 -0
- data/lib/gerbil/rdoc.rb +91 -0
- metadata +99 -0
data/doc/gerbil.png
ADDED
|
Binary file
|
data/doc/gerbil.svg
ADDED
|
@@ -0,0 +1,330 @@
|
|
|
1
|
+
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
2
|
+
<!-- Created with Inkscape (http://www.inkscape.org/) -->
|
|
3
|
+
<svg
|
|
4
|
+
xmlns:dc="http://purl.org/dc/elements/1.1/"
|
|
5
|
+
xmlns:cc="http://web.resource.org/cc/"
|
|
6
|
+
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
|
|
7
|
+
xmlns:svg="http://www.w3.org/2000/svg"
|
|
8
|
+
xmlns="http://www.w3.org/2000/svg"
|
|
9
|
+
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
10
|
+
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
|
|
11
|
+
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
|
|
12
|
+
width="744.09448819"
|
|
13
|
+
height="1052.3622047"
|
|
14
|
+
id="svg2"
|
|
15
|
+
sodipodi:version="0.32"
|
|
16
|
+
inkscape:version="0.45.1"
|
|
17
|
+
sodipodi:docbase="/home/sun/src/gerbil"
|
|
18
|
+
sodipodi:docname="gerbil.svg"
|
|
19
|
+
inkscape:output_extension="org.inkscape.output.svg.inkscape"
|
|
20
|
+
inkscape:export-filename="/home/sun/src/gerbil/gerbil.png"
|
|
21
|
+
inkscape:export-xdpi="84.379997"
|
|
22
|
+
inkscape:export-ydpi="84.379997">
|
|
23
|
+
<defs
|
|
24
|
+
id="defs4">
|
|
25
|
+
<linearGradient
|
|
26
|
+
id="linearGradient8514">
|
|
27
|
+
<stop
|
|
28
|
+
style="stop-color:#ff6600;stop-opacity:1;"
|
|
29
|
+
offset="0"
|
|
30
|
+
id="stop8516" />
|
|
31
|
+
<stop
|
|
32
|
+
style="stop-color:#ff6600;stop-opacity:0;"
|
|
33
|
+
offset="1"
|
|
34
|
+
id="stop8518" />
|
|
35
|
+
</linearGradient>
|
|
36
|
+
<linearGradient
|
|
37
|
+
id="linearGradient8496">
|
|
38
|
+
<stop
|
|
39
|
+
style="stop-color:#ff6600;stop-opacity:1;"
|
|
40
|
+
offset="0"
|
|
41
|
+
id="stop8498" />
|
|
42
|
+
<stop
|
|
43
|
+
style="stop-color:#ff6600;stop-opacity:0.19653179;"
|
|
44
|
+
offset="1"
|
|
45
|
+
id="stop8500" />
|
|
46
|
+
</linearGradient>
|
|
47
|
+
<linearGradient
|
|
48
|
+
id="linearGradient8478">
|
|
49
|
+
<stop
|
|
50
|
+
style="stop-color:#ff6804;stop-opacity:1;"
|
|
51
|
+
offset="0"
|
|
52
|
+
id="stop8480" />
|
|
53
|
+
<stop
|
|
54
|
+
id="stop8554"
|
|
55
|
+
offset="0.71910113"
|
|
56
|
+
style="stop-color:#ff802c;stop-opacity:0.5254902;" />
|
|
57
|
+
<stop
|
|
58
|
+
style="stop-color:#ff9955;stop-opacity:0.33526012;"
|
|
59
|
+
offset="1"
|
|
60
|
+
id="stop8482" />
|
|
61
|
+
</linearGradient>
|
|
62
|
+
<linearGradient
|
|
63
|
+
id="linearGradient8373">
|
|
64
|
+
<stop
|
|
65
|
+
style="stop-color:#ff6600;stop-opacity:1;"
|
|
66
|
+
offset="0"
|
|
67
|
+
id="stop8375" />
|
|
68
|
+
<stop
|
|
69
|
+
style="stop-color:#ff6600;stop-opacity:0;"
|
|
70
|
+
offset="1"
|
|
71
|
+
id="stop8377" />
|
|
72
|
+
</linearGradient>
|
|
73
|
+
<radialGradient
|
|
74
|
+
inkscape:collect="always"
|
|
75
|
+
xlink:href="#linearGradient8478"
|
|
76
|
+
id="radialGradient8484"
|
|
77
|
+
cx="304.75299"
|
|
78
|
+
cy="411.13791"
|
|
79
|
+
fx="304.75299"
|
|
80
|
+
fy="411.13791"
|
|
81
|
+
r="21.859919"
|
|
82
|
+
gradientTransform="matrix(1,0,0,0.9803922,0,8.0615136)"
|
|
83
|
+
gradientUnits="userSpaceOnUse" />
|
|
84
|
+
<radialGradient
|
|
85
|
+
inkscape:collect="always"
|
|
86
|
+
xlink:href="#linearGradient8496"
|
|
87
|
+
id="radialGradient8504"
|
|
88
|
+
cx="285.83987"
|
|
89
|
+
cy="395.33234"
|
|
90
|
+
fx="285.83987"
|
|
91
|
+
fy="395.33234"
|
|
92
|
+
r="5.6257143"
|
|
93
|
+
gradientTransform="matrix(1,0,0,1.4,0,-158.13293)"
|
|
94
|
+
gradientUnits="userSpaceOnUse" />
|
|
95
|
+
<radialGradient
|
|
96
|
+
inkscape:collect="always"
|
|
97
|
+
xlink:href="#linearGradient8514"
|
|
98
|
+
id="radialGradient8520"
|
|
99
|
+
cx="285.83987"
|
|
100
|
+
cy="395.33234"
|
|
101
|
+
fx="285.83987"
|
|
102
|
+
fy="395.33234"
|
|
103
|
+
r="5.6257143"
|
|
104
|
+
gradientTransform="matrix(1,0,0,1.4,0,-158.13293)"
|
|
105
|
+
gradientUnits="userSpaceOnUse" />
|
|
106
|
+
<radialGradient
|
|
107
|
+
inkscape:collect="always"
|
|
108
|
+
xlink:href="#linearGradient8496"
|
|
109
|
+
id="radialGradient8558"
|
|
110
|
+
gradientUnits="userSpaceOnUse"
|
|
111
|
+
gradientTransform="matrix(1,0,0,1.4,0,-158.13293)"
|
|
112
|
+
cx="285.83987"
|
|
113
|
+
cy="395.33234"
|
|
114
|
+
fx="285.83987"
|
|
115
|
+
fy="395.33234"
|
|
116
|
+
r="5.6257143" />
|
|
117
|
+
</defs>
|
|
118
|
+
<sodipodi:namedview
|
|
119
|
+
id="base"
|
|
120
|
+
pagecolor="#ffffff"
|
|
121
|
+
bordercolor="#666666"
|
|
122
|
+
borderopacity="1.0"
|
|
123
|
+
gridtolerance="10000"
|
|
124
|
+
guidetolerance="10"
|
|
125
|
+
objecttolerance="10"
|
|
126
|
+
inkscape:pageopacity="0.0"
|
|
127
|
+
inkscape:pageshadow="2"
|
|
128
|
+
inkscape:zoom="1.2347093"
|
|
129
|
+
inkscape:cx="352.98664"
|
|
130
|
+
inkscape:cy="566.52727"
|
|
131
|
+
inkscape:document-units="px"
|
|
132
|
+
inkscape:current-layer="layer1"
|
|
133
|
+
inkscape:window-width="1918"
|
|
134
|
+
inkscape:window-height="568"
|
|
135
|
+
inkscape:window-x="0"
|
|
136
|
+
inkscape:window-y="589"
|
|
137
|
+
showguides="true"
|
|
138
|
+
inkscape:guide-bbox="true">
|
|
139
|
+
<sodipodi:guide
|
|
140
|
+
orientation="horizontal"
|
|
141
|
+
position="621"
|
|
142
|
+
id="guide7308" />
|
|
143
|
+
<sodipodi:guide
|
|
144
|
+
orientation="vertical"
|
|
145
|
+
position="142"
|
|
146
|
+
id="guide2194" />
|
|
147
|
+
<sodipodi:guide
|
|
148
|
+
orientation="horizontal"
|
|
149
|
+
position="520"
|
|
150
|
+
id="guide2195" />
|
|
151
|
+
<sodipodi:guide
|
|
152
|
+
orientation="vertical"
|
|
153
|
+
position="601.5"
|
|
154
|
+
id="guide2201" />
|
|
155
|
+
<sodipodi:guide
|
|
156
|
+
orientation="vertical"
|
|
157
|
+
position="533"
|
|
158
|
+
id="guide3215" />
|
|
159
|
+
<sodipodi:guide
|
|
160
|
+
orientation="vertical"
|
|
161
|
+
position="483.5"
|
|
162
|
+
id="guide3217" />
|
|
163
|
+
<sodipodi:guide
|
|
164
|
+
orientation="vertical"
|
|
165
|
+
position="443.5"
|
|
166
|
+
id="guide3219" />
|
|
167
|
+
</sodipodi:namedview>
|
|
168
|
+
<metadata
|
|
169
|
+
id="metadata7">
|
|
170
|
+
<rdf:RDF>
|
|
171
|
+
<cc:Work
|
|
172
|
+
rdf:about="">
|
|
173
|
+
<dc:format>image/svg+xml</dc:format>
|
|
174
|
+
<dc:type
|
|
175
|
+
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
|
|
176
|
+
</cc:Work>
|
|
177
|
+
</rdf:RDF>
|
|
178
|
+
</metadata>
|
|
179
|
+
<g
|
|
180
|
+
inkscape:label="Layer 1"
|
|
181
|
+
inkscape:groupmode="layer"
|
|
182
|
+
id="layer1">
|
|
183
|
+
<text
|
|
184
|
+
xml:space="preserve"
|
|
185
|
+
style="font-size:27.56596375px;font-style:normal;font-weight:normal;line-height:100%;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans;stroke-miterlimit:4;stroke-dasharray:none"
|
|
186
|
+
x="140.16428"
|
|
187
|
+
y="526.9082"
|
|
188
|
+
id="text2160"
|
|
189
|
+
sodipodi:linespacing="117%"
|
|
190
|
+
inkscape:export-filename="/home/sun/path7293.png"
|
|
191
|
+
inkscape:export-xdpi="84.379997"
|
|
192
|
+
inkscape:export-ydpi="84.379997"><tspan
|
|
193
|
+
sodipodi:role="line"
|
|
194
|
+
id="tspan2162"
|
|
195
|
+
x="140.16428"
|
|
196
|
+
y="526.9082"
|
|
197
|
+
style="font-size:110.26385498px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:117%;writing-mode:lr;text-anchor:start;font-family:URW Palladio L;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none">G<tspan
|
|
198
|
+
style="font-size:110.26385498px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:117%;writing-mode:lr;text-anchor:start;fill:#ff0000;font-family:URW Palladio L;stroke:none;stroke-opacity:1;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none"
|
|
199
|
+
id="tspan2172">erb</tspan>il</tspan></text>
|
|
200
|
+
<path
|
|
201
|
+
sodipodi:type="arc"
|
|
202
|
+
style="fill:url(#radialGradient8484);fill-opacity:1.0"
|
|
203
|
+
id="path2282"
|
|
204
|
+
sodipodi:cx="304.75299"
|
|
205
|
+
sodipodi:cy="411.13791"
|
|
206
|
+
sodipodi:rx="21.859919"
|
|
207
|
+
sodipodi:ry="21.431293"
|
|
208
|
+
d="M 326.61291 411.13791 A 21.859919 21.431293 0 1 1 282.89307,411.13791 A 21.859919 21.431293 0 1 1 326.61291 411.13791 z"
|
|
209
|
+
transform="matrix(2.2971646,0,0,2.2971646,-167.03813,-448.06613)"
|
|
210
|
+
inkscape:export-filename="/home/sun/path7293.png"
|
|
211
|
+
inkscape:export-xdpi="84.379997"
|
|
212
|
+
inkscape:export-ydpi="84.379997" />
|
|
213
|
+
<path
|
|
214
|
+
sodipodi:type="arc"
|
|
215
|
+
style="fill:#000000"
|
|
216
|
+
id="path2286"
|
|
217
|
+
sodipodi:cx="309.46786"
|
|
218
|
+
sodipodi:cy="411.13791"
|
|
219
|
+
sodipodi:rx="3.4290068"
|
|
220
|
+
sodipodi:ry="3.4290068"
|
|
221
|
+
d="M 312.89687 411.13791 A 3.4290068 3.4290068 0 1 1 306.03886,411.13791 A 3.4290068 3.4290068 0 1 1 312.89687 411.13791 z"
|
|
222
|
+
transform="matrix(2.2971646,0,0,2.2971646,-196.97636,-461.29472)"
|
|
223
|
+
inkscape:export-filename="/home/sun/path7293.png"
|
|
224
|
+
inkscape:export-xdpi="84.379997"
|
|
225
|
+
inkscape:export-ydpi="84.379997" />
|
|
226
|
+
<path
|
|
227
|
+
sodipodi:type="arc"
|
|
228
|
+
style="fill:#000000"
|
|
229
|
+
id="path2288"
|
|
230
|
+
sodipodi:cx="304.75299"
|
|
231
|
+
sodipodi:cy="422.71082"
|
|
232
|
+
sodipodi:rx="3.8576326"
|
|
233
|
+
sodipodi:ry="3.8576326"
|
|
234
|
+
d="M 308.61062 422.71082 A 3.8576326 3.8576326 0 1 1 300.89536,422.71082 A 3.8576326 3.8576326 0 1 1 308.61062 422.71082 z"
|
|
235
|
+
transform="matrix(3.1995744,0,0,2.2971646,-442.0504,-459.90229)"
|
|
236
|
+
inkscape:export-filename="/home/sun/path7293.png"
|
|
237
|
+
inkscape:export-xdpi="84.379997"
|
|
238
|
+
inkscape:export-ydpi="84.379997" />
|
|
239
|
+
<path
|
|
240
|
+
sodipodi:type="arc"
|
|
241
|
+
style="fill:#000000"
|
|
242
|
+
id="path2290"
|
|
243
|
+
sodipodi:cx="309.46786"
|
|
244
|
+
sodipodi:cy="411.13791"
|
|
245
|
+
sodipodi:rx="3.4290068"
|
|
246
|
+
sodipodi:ry="3.4290068"
|
|
247
|
+
d="M 312.89687 411.13791 A 3.4290068 3.4290068 0 1 1 306.03886,411.13791 A 3.4290068 3.4290068 0 1 1 312.89687 411.13791 z"
|
|
248
|
+
transform="matrix(2.2971646,0,0,2.2971646,-157.3342,-460.83267)"
|
|
249
|
+
inkscape:export-filename="/home/sun/path7293.png"
|
|
250
|
+
inkscape:export-xdpi="84.379997"
|
|
251
|
+
inkscape:export-ydpi="84.379997" />
|
|
252
|
+
<g
|
|
253
|
+
id="g7300"
|
|
254
|
+
transform="matrix(2.2971646,0,0,2.2971646,-167.03813,-448.06613)"
|
|
255
|
+
inkscape:export-filename="/home/sun/path7293.png"
|
|
256
|
+
inkscape:export-xdpi="84.379997"
|
|
257
|
+
inkscape:export-ydpi="84.379997">
|
|
258
|
+
<path
|
|
259
|
+
sodipodi:nodetypes="cc"
|
|
260
|
+
id="path2310"
|
|
261
|
+
d="M 297.82968,420.50036 C 283.20104,421.58405 283.56895,427.52326 283.56895,427.52326"
|
|
262
|
+
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.77546233px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
|
|
263
|
+
<path
|
|
264
|
+
sodipodi:nodetypes="cc"
|
|
265
|
+
id="path2312"
|
|
266
|
+
d="M 297.4513,420.45157 C 277.03806,421.0992 277.55145,424.64856 277.55145,424.64856"
|
|
267
|
+
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.70815003px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
|
|
268
|
+
<path
|
|
269
|
+
sodipodi:nodetypes="cc"
|
|
270
|
+
id="path2314"
|
|
271
|
+
d="M 297.78763,420.43672 C 288.66511,421.76687 288.89454,429.05683 288.89454,429.05683"
|
|
272
|
+
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.67844433px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
|
|
273
|
+
</g>
|
|
274
|
+
<g
|
|
275
|
+
id="g7295"
|
|
276
|
+
transform="matrix(2.2971646,0,0,2.2971646,-167.03813,-448.06613)"
|
|
277
|
+
inkscape:export-filename="/home/sun/path7293.png"
|
|
278
|
+
inkscape:export-xdpi="84.379997"
|
|
279
|
+
inkscape:export-ydpi="84.379997">
|
|
280
|
+
<path
|
|
281
|
+
sodipodi:nodetypes="cc"
|
|
282
|
+
id="path2316"
|
|
283
|
+
d="M 310.59642,420.92898 C 325.22506,422.01267 324.85715,427.95188 324.85715,427.95188"
|
|
284
|
+
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.77546233px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
|
|
285
|
+
<path
|
|
286
|
+
sodipodi:nodetypes="cc"
|
|
287
|
+
id="path2318"
|
|
288
|
+
d="M 310.9748,420.88019 C 331.38804,421.52782 330.87465,425.07718 330.87465,425.07718"
|
|
289
|
+
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.70815003px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
|
|
290
|
+
<path
|
|
291
|
+
sodipodi:nodetypes="cc"
|
|
292
|
+
id="path2320"
|
|
293
|
+
d="M 310.63847,420.86534 C 319.76099,422.19549 319.53156,429.48545 319.53156,429.48545"
|
|
294
|
+
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.67844433px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
|
|
295
|
+
</g>
|
|
296
|
+
<path
|
|
297
|
+
sodipodi:type="arc"
|
|
298
|
+
style="fill:url(#radialGradient8504);fill-opacity:1"
|
|
299
|
+
id="path2322"
|
|
300
|
+
sodipodi:cx="285.83987"
|
|
301
|
+
sodipodi:cy="395.33234"
|
|
302
|
+
sodipodi:rx="5.6257143"
|
|
303
|
+
sodipodi:ry="7.8759999"
|
|
304
|
+
d="M 291.46559 395.33234 A 5.6257143 7.8759999 0 1 1 280.21416,395.33234 A 5.6257143 7.8759999 0 1 1 291.46559 395.33234 z"
|
|
305
|
+
transform="matrix(2.9534945,0,0,2.7503451,-363.01344,-634.27645)"
|
|
306
|
+
inkscape:export-filename="/home/sun/path7293.png"
|
|
307
|
+
inkscape:export-xdpi="84.379997"
|
|
308
|
+
inkscape:export-ydpi="84.379997" />
|
|
309
|
+
<path
|
|
310
|
+
style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:2.29715872px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
|
|
311
|
+
d="M 529.89372,536.04316 C 547.61683,536.04316 547.2859,526.00189 547.2859,526.00189"
|
|
312
|
+
id="path7293"
|
|
313
|
+
sodipodi:nodetypes="cc"
|
|
314
|
+
inkscape:export-xdpi="84.379997"
|
|
315
|
+
inkscape:export-ydpi="84.379997" />
|
|
316
|
+
<path
|
|
317
|
+
sodipodi:type="arc"
|
|
318
|
+
style="fill:url(#radialGradient8558);fill-opacity:1"
|
|
319
|
+
id="path8556"
|
|
320
|
+
sodipodi:cx="285.83987"
|
|
321
|
+
sodipodi:cy="395.33234"
|
|
322
|
+
sodipodi:rx="5.6257143"
|
|
323
|
+
sodipodi:ry="7.8759999"
|
|
324
|
+
d="M 291.46559 395.33234 A 5.6257143 7.8759999 0 1 1 280.21416,395.33234 A 5.6257143 7.8759999 0 1 1 291.46559 395.33234 z"
|
|
325
|
+
transform="matrix(2.9534945,0,0,2.7503451,-259.30752,-634.27645)"
|
|
326
|
+
inkscape:export-filename="/home/sun/path7293.png"
|
|
327
|
+
inkscape:export-xdpi="84.379997"
|
|
328
|
+
inkscape:export-ydpi="84.379997" />
|
|
329
|
+
</g>
|
|
330
|
+
</svg>
|
data/doc/guide.erb
ADDED
|
@@ -0,0 +1,677 @@
|
|
|
1
|
+
<%
|
|
2
|
+
# local variables for this document
|
|
3
|
+
mailing_list_url = 'http://rubyforge.org/mailman/listinfo/gerbil-talk'
|
|
4
|
+
mailing_list_link = link(mailing_list_url, "project mailing list")
|
|
5
|
+
download_url = 'http://rubyforge.org/frs/?group_id=4905'
|
|
6
|
+
source_repo_url = 'http://gerbil.rubyforge.org/src'
|
|
7
|
+
feed_url = File.join(Gerbil[:website], 'news.xml')
|
|
8
|
+
feed_icon_url = File.join(Gerbil[:website], 'feed-icon-28x28.png')
|
|
9
|
+
|
|
10
|
+
# parameters for the HTML format
|
|
11
|
+
$title = "Gerbil #{Gerbil[:version]} user guide"
|
|
12
|
+
$authors = { 'Suraj N. Kurapati' => 'http://snk.tuxfamily.org' }
|
|
13
|
+
$feeds = { feed_url => :rss }
|
|
14
|
+
$logo = '<img src="gerbil.png" alt="Gerbil logo" title="Gerbil logo"/>'
|
|
15
|
+
|
|
16
|
+
# parameters for Gerbil
|
|
17
|
+
$unindent = ' '
|
|
18
|
+
%>
|
|
19
|
+
|
|
20
|
+
<% chapter "Introduction" do %>
|
|
21
|
+
Gerbil is an *extensible document generator* based on "eRuby":http://www.ruby-doc.org/docs/ProgrammingRuby/html/web.html#S2 that outputs to any format you want: <%= xref 'html', "HTML (web page)" %>, <%= xref 'latex', "LaTeX" %>, <%= xref "man", "UNIX man page" %>, <%= xref 'text', 'plain text' %>, <%= xref "HelloWorld", "your own custom format" %>, and so on.
|
|
22
|
+
|
|
23
|
+
Gerbil is *lighter* and more *flexible* than "DocBook":http://www.docbook.org, "Deplate":http://deplate.sourceforge.net, and "SiSU":http://www.jus.uio.no/sisu/SiSU/ because it is small, fast, and lets you <%= xref "HelloWorld", "define your own custom format" %>. Furthermore, Gerbil is *scriptable* unlike raw text generators such as "AsciiDoc":http://www.methods.co.nz/asciidoc/, "txt2tags":http://txt2tags.sourceforge.net, and "Grutatxt":http://www.triptico.com/software/grutatxt.html because it lets you inject Ruby code directly into your documents for dynamic content generation.
|
|
24
|
+
|
|
25
|
+
Gerbil is *open-source software* (see <%= xref "License" %>) so feel free to contribute your improvements and discuss your ideas in the <%= mailing_list_link %>. You can obtain the source code from Gerbil's "Darcs":http://darcs.net repository by running the following command:
|
|
26
|
+
|
|
27
|
+
darcs get <%= source_repo_url %> gerbil
|
|
28
|
+
|
|
29
|
+
<% note "See the source of this guide" do %>
|
|
30
|
+
Did you know that this user guide was generated by Gerbil? Here is "the source document":guide.erb to prove it!
|
|
31
|
+
<% end %>
|
|
32
|
+
|
|
33
|
+
<% section "Features" do %>
|
|
34
|
+
* Composed of *less than 200 lines* of code!
|
|
35
|
+
* Lets you <%= xref 'HelloWorld', '*define your own* document format' %>.
|
|
36
|
+
* Supports *any text-based output* format.
|
|
37
|
+
* Generates a *table of contents* automatically.
|
|
38
|
+
<% end %>
|
|
39
|
+
|
|
40
|
+
<% section "License" do %>
|
|
41
|
+
<%=h File.read('LICENSE') %>
|
|
42
|
+
<% end %>
|
|
43
|
+
|
|
44
|
+
<% section "Project links" do %>
|
|
45
|
+
* "Announcements":<%= feed_url %> !<%= feed_icon_url %>(RSS icon)! - project news and release announcements.
|
|
46
|
+
* "Download area":<%= download_url %> - place to obtain release packages.
|
|
47
|
+
* "Mailing list":<%= mailing_list_url %> - ask questions, get help, discuss.
|
|
48
|
+
<% end %>
|
|
49
|
+
|
|
50
|
+
<% section "Testimonials" do %>
|
|
51
|
+
bq. I actually felt like printing it [the user guide], because it's just so well-thought typographically... Even if it [Gerbil] weren't great by itself, I'd feel good just looking at the manual. --"_Vitor Peres_ in [ruby-talk:283052]":http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/283052
|
|
52
|
+
<% end %>
|
|
53
|
+
<% end %>
|
|
54
|
+
|
|
55
|
+
<% chapter "Setup" do %>
|
|
56
|
+
<% section "Requirements" do %>
|
|
57
|
+
Your system needs the following software to run Gerbil.
|
|
58
|
+
|
|
59
|
+
|_. Software |_. Notes |
|
|
60
|
+
| "Ruby":http://ruby-lang.org | Version 1.8.x is required. |
|
|
61
|
+
| "RedCloth":http://whytheluckystiff.net/ruby/redcloth/ | Required by the <%= xref 'html', "default HTML format" %>. |
|
|
62
|
+
| "CodeRay":http://coderay.rubychan.de/ | Required by the <%= xref 'html', "default HTML format" %>. |
|
|
63
|
+
|
|
64
|
+
If your system has "RubyGems":http://rubygems.org/, then you can install RedCloth and CodeRay by running the following command:
|
|
65
|
+
|
|
66
|
+
gem install RedCloth coderay
|
|
67
|
+
<% end %>
|
|
68
|
+
|
|
69
|
+
<% section "Installation" do %>
|
|
70
|
+
If your system has "RubyGems":http://rubygems.org/, then you can install Gerbil by running the following commands:
|
|
71
|
+
|
|
72
|
+
gem install gerbil
|
|
73
|
+
gerbil -v
|
|
74
|
+
|
|
75
|
+
Otherwise, follow these instructions:
|
|
76
|
+
# Download the newest release package from "the download area":<%= download_url %>.
|
|
77
|
+
# Extract the release package anywhere you want on your system.
|
|
78
|
+
# Go inside the extracted directory and run the following command:
|
|
79
|
+
<pre>ruby bin/gerbil -v</pre>
|
|
80
|
+
|
|
81
|
+
If the installation was successful, then you will see output like this: <pre><%=h `ruby bin/gerbil -v` %></pre>
|
|
82
|
+
|
|
83
|
+
Otherwise, you can ask for help in the <%= mailing_list_link %>.
|
|
84
|
+
<% end %>
|
|
85
|
+
|
|
86
|
+
<% section "Manifest" do %>
|
|
87
|
+
Now that Gerbil is installed on your system, let us examine its installation directory.
|
|
88
|
+
* If you installed Gerbil manually, then you already know the location of its installation directory.
|
|
89
|
+
* If you installed Gerbil using RubyGems, then run <pre>gerbil -v</pre> and select the right-most item in the output--that is the path of Gerbil's installation directory.
|
|
90
|
+
|
|
91
|
+
Inside Gerbil's installation directory, you will see (among other things) the following items:
|
|
92
|
+
* <tt>bin/</tt> - contains executable programs.
|
|
93
|
+
** <tt>gerbil</tt> - the main source code of Gerbil.
|
|
94
|
+
* <tt>fmt/</tt> - contains the predefined set of format specification files (see <%= xref 'SpecFile' %>). If you ever need to install your custom format specification file globally, put it inside this directory.
|
|
95
|
+
<% Gerbil[:format_files].each do |file| %>
|
|
96
|
+
** <tt><%= File.basename(file) %></tt> - <%= YAML.load_file(file)['desc'] %>
|
|
97
|
+
<% end %>
|
|
98
|
+
* <tt>lib/</tt> - Gerbil automatically adds this directory to Ruby's load path.
|
|
99
|
+
** <tt>gerbil.rb</tt> - project version information.
|
|
100
|
+
** <tt>gerbil/</tt>
|
|
101
|
+
*** <tt>html.rb</tt> - provides the @String#to_html@ method.
|
|
102
|
+
*** <tt>rdoc.rb</tt> - provides RDoc parse trees to Ruby code.
|
|
103
|
+
* <tt>doc/</tt> - contains the user guide and other documentation.
|
|
104
|
+
** <tt>gerbil.svg</tt> - the source file of the Gerbil logo.
|
|
105
|
+
** <tt>guide.erb</tt> - the source file of this user guide.
|
|
106
|
+
* <tt>LICENSE</tt> - the project license and copyright notice.
|
|
107
|
+
<% end %>
|
|
108
|
+
|
|
109
|
+
<% section 'Version numbering system' do %>
|
|
110
|
+
Gerbil uses the "RubyGems rational versioning policy":http://www.rubygems.org/read/chapter/7 to number its releases. This *major.minor.patch* numbering policy "is summarized":http://ablog.apress.com/?p=738 as follows.
|
|
111
|
+
|
|
112
|
+
| Version number components: |_. Major |_. Minor |_. Patch |
|
|
113
|
+
|_. Backwards compatible? | no | yes | yes |
|
|
114
|
+
|_. New features? | yes | yes | no |
|
|
115
|
+
|_. Bug fixes? | yes | yes | yes |
|
|
116
|
+
<% end %>
|
|
117
|
+
<% end %>
|
|
118
|
+
|
|
119
|
+
<% chapter "Theory of operation" do %>
|
|
120
|
+
When you run Gerbil, it operates in the following order:
|
|
121
|
+
# loads the <%= xref "SpecFile", "format specification file" %>
|
|
122
|
+
# creates an *input document* by:
|
|
123
|
+
** reading the input (the content of either the input file or the standard input stream) into memory
|
|
124
|
+
** evaluating <%= xref "include", "include directives" %> in the input
|
|
125
|
+
# transforms the input document into a *processed document* by:
|
|
126
|
+
** building a "document tree" data-structure from <%= xref "Nodes", "nodes" %> present in the input document
|
|
127
|
+
** replacing every node in the input document with the result of its <%= xref "SpecFile.nodes.output", "node output template" %>
|
|
128
|
+
# transforms the processed document into an *output document* according to the <%= xref "SpecFile.output", "document output template" %>
|
|
129
|
+
# prints the output document to the standard output stream
|
|
130
|
+
|
|
131
|
+
Although there is only one document being processed here, we refer to it using three distinct terms (*input*, *processed*, and *output*). This distinction helps us talk about the document in a particular state because the content of the document changes radically with every transformation -- thus it would be ambiguous to say "the input document" all the time.
|
|
132
|
+
|
|
133
|
+
<% section "Nodes" do %>
|
|
134
|
+
A node is a block of text that appears like this:
|
|
135
|
+
|
|
136
|
+
<%% node_type node_argument1, node_argument2, ... do |node_object| %>
|
|
137
|
+
node_content
|
|
138
|
+
<%% end %>
|
|
139
|
+
|
|
140
|
+
Or like this:
|
|
141
|
+
|
|
142
|
+
<%% node_type node_argument1, node_argument2, ... do %>
|
|
143
|
+
node_content
|
|
144
|
+
<%% end %>
|
|
145
|
+
|
|
146
|
+
Or like this:
|
|
147
|
+
|
|
148
|
+
<%%= node_type node_argument1, node_argument2, ... %>
|
|
149
|
+
|
|
150
|
+
Technically, what you see above is really a method invocation made up of the following components:
|
|
151
|
+
|
|
152
|
+
|_. Component |_. Description |
|
|
153
|
+
| node_type | name of the method being invoked |
|
|
154
|
+
| node_argument1, node_argument2, ... | arguments for the method invocation |
|
|
155
|
+
| node_content | a block argument being passed to the method invocation |
|
|
156
|
+
| node_object | a @Node@ object (see <%= xref "Node.class" %>) representing this method invocation |
|
|
157
|
+
|
|
158
|
+
A <%= xref 'SpecFile', 'format specification file' %> defines what types of nodes an input document may use.
|
|
159
|
+
|
|
160
|
+
<% section "The @Node@ class", "Node.class" do %>
|
|
161
|
+
When Gerbil builds a document tree from nodes present in an input document, it stores information about these nodes into @Node@ objects. A @Node@ object has the following properties (methods):
|
|
162
|
+
|
|
163
|
+
|_. Property |_. Type |_. Description |
|
|
164
|
+
| type | String | Name of the type of this node. |
|
|
165
|
+
| args | Array | Arguments passed to this node. |
|
|
166
|
+
| content | String | The block of text passed to this node. |
|
|
167
|
+
| output | String | Result of the node output template for the content of this node. |
|
|
168
|
+
| digest | String | A unique identifier for the content of this node. |
|
|
169
|
+
| trace | Array | A stack trace describing the location of this node in the input document. |
|
|
170
|
+
| index | String | A LaTeX-style section number for this node. This property is only present if the "index" parameter is enabled in the definition of this type of node. |
|
|
171
|
+
| number | Integer | An order-of-occurrence number for this node. This property is only present if the "number" parameter is enabled in the definition of this type of node. |
|
|
172
|
+
| depth | Integer | Distance from the root of the document tree to this node. |
|
|
173
|
+
| parent | @Node@ | The @Node@ object which contains this node. The value of this property will be @nil@ if this node is a root of the document tree. |
|
|
174
|
+
| children | Array of @Node@ | List of child nodes from the document tree. |
|
|
175
|
+
|
|
176
|
+
Furthermore, the @Node@ class is derived from "Ruby's @OpenStruct@ class":http://www.ruby-doc.org/stdlib/libdoc/ostruct/rdoc/classes/OpenStruct.html, so you can define new properties for @Node@ objects dynamically.
|
|
177
|
+
<% end %>
|
|
178
|
+
<% end %>
|
|
179
|
+
|
|
180
|
+
<% section "Format specification file", 'SpecFile' do %>
|
|
181
|
+
A format specification file is a plain-text file marked up in "YAML syntax":http://yaml4r.sourceforge.net/cookbook/. Through the following parameters, it defines (1) what types of nodes an input document may contain, (2) how the content of those nodes is transformed into output, and (3) how the processed document is transformed into the output document.
|
|
182
|
+
|
|
183
|
+
|_. Parameter |_. Type |_. Description |
|
|
184
|
+
| desc | String | A short description of the output format. |
|
|
185
|
+
| code | String | Ruby code that will be loaded before the input document is processed. This source code will be evaluated inside the main Gerbil executable, so any file-system or path-dependent portions of this source code should take appropriate precautions. |
|
|
186
|
+
| nodes | Hash | A listing of <%= xref "SpecFile.nodes", "node definitions" %>. |
|
|
187
|
+
| output | String | An eRuby template for the final output document. See <%= xref "SpecFile.output" %>. |
|
|
188
|
+
|
|
189
|
+
<%
|
|
190
|
+
# XXX: "declare" this local variable here (in the parent
|
|
191
|
+
# scope) because it is initialized and used in two
|
|
192
|
+
# different child scopes that exist at different depths
|
|
193
|
+
common_template_vars = nil
|
|
194
|
+
%>
|
|
195
|
+
|
|
196
|
+
<% section "Node definition", "SpecFile.nodes" do %>
|
|
197
|
+
A node definition is a mapping from a name (the "node type") to the following set of parameters:
|
|
198
|
+
|
|
199
|
+
|_. Parameter |_. Type |_. Description |
|
|
200
|
+
| index | Boolean | Assign a LaTeX-style section number to this node? |
|
|
201
|
+
| number | Boolean | Assign an order-of-occurrence number to this node? |
|
|
202
|
+
| silent | Boolean | Suppress the output of this node? |
|
|
203
|
+
| output | String | An eRuby template for the content of this node. See <%= xref "SpecFile.nodes.output" %>. |
|
|
204
|
+
|
|
205
|
+
You may define additional parameters in a node definition if you want.
|
|
206
|
+
|
|
207
|
+
<% section "Node output template", "SpecFile.nodes.output" do %>
|
|
208
|
+
A node output template (the *output* parameter in a node definition) is an eRuby template that transforms a node's content into output. During the processing stage, Gerbil replaces all nodes in the input document with the result of this template _unless_ the *silent* parameter is enabled in this node's definition.
|
|
209
|
+
|
|
210
|
+
The following variables are available for use in this template:
|
|
211
|
+
|
|
212
|
+
|_. Variable |_. Type |_. Description |
|
|
213
|
+
| @node | @Node@ | the node for which this template is being evaluated |
|
|
214
|
+
<%= common_template_vars = %{
|
|
215
|
+
| @roots | Array of @Node@ | All root nodes in the document tree. |
|
|
216
|
+
| @nodes | Array of @Node@ | All nodes in the document tree. |
|
|
217
|
+
| @types | Hash | Mapping from node type (String) to array of @Node@ objects having that type. |
|
|
218
|
+
| @spec | Hash | Data from the format specification file. |
|
|
219
|
+
|
|
220
|
+
Gerbil also provides the following mappings inside the @@spec@ variable:
|
|
221
|
+
|
|
222
|
+
|_. Expression |_. Type |_. Description |
|
|
223
|
+
| @@spec[:name]@ | String | Short-hand name of the current format. |
|
|
224
|
+
| @@spec[:file]@ | String | Path of the current format specification file. |
|
|
225
|
+
}.lstrip.gsub(/^ +/, '')
|
|
226
|
+
%>
|
|
227
|
+
<% end %>
|
|
228
|
+
<% end %>
|
|
229
|
+
|
|
230
|
+
<% section "Document output template", "SpecFile.output" do %>
|
|
231
|
+
A document output template (the *output* parameter in a format specification file) is an eRuby template that transforms a processed document into the final output document.
|
|
232
|
+
|
|
233
|
+
The following variables are available for use in this template:
|
|
234
|
+
|
|
235
|
+
|_. Variable |_. Type |_. Description |
|
|
236
|
+
| @content | String | Content of the processed document. |
|
|
237
|
+
<%= common_template_vars %>
|
|
238
|
+
<% end %>
|
|
239
|
+
|
|
240
|
+
<% section "Creating your own custom format", "HelloWorld" do %>
|
|
241
|
+
Here is a working example to help you digest all that you've learned so far about format specification files. A few things to notice in this example are:
|
|
242
|
+
* We define a @generate_name()@ method in <%= xref "HelloWorld.spec" %> and make use of it in the <%= xref "HelloWorld.input" %>. This shows how to provide format-specific functionality to an input document.
|
|
243
|
+
* We define a @$style@ variable in <%= xref "HelloWorld.input" %> and make use of it in <%= xref "HelloWorld.spec" %>. This shows how to make your format accept parameters from an input document.
|
|
244
|
+
|
|
245
|
+
To run this example, perform the following steps:
|
|
246
|
+
# Save the code shown in <%= xref "HelloWorld.spec" %> to a file named <tt>HelloWorld.spec</tt>
|
|
247
|
+
# Save the text shown in <%= xref "HelloWorld.input" %> to a file named <tt>HelloWorld.input</tt>
|
|
248
|
+
# Run this command: <pre>gerbil HelloWorld.spec HelloWorld.input > HelloWorld.output</pre>
|
|
249
|
+
# Examine the <tt>HelloWorld.output</tt> file until you are satisfied!
|
|
250
|
+
|
|
251
|
+
<% note "Author's note about documentation quality" do %>
|
|
252
|
+
Please excuse my lack of creativity for this example. I tried different ideas but scrapped most of them because writing documentation is hard and mostly boring. (Although I did have fun reading the wacky names produced by the @generate_name()@ method!)
|
|
253
|
+
|
|
254
|
+
Instead, I just _really_ want to get the first release of Gerbil out the door and continue work on my other programming projects, but I cannot do so until I've written some documentation. Ah, the dilemma of an open-source developer who cares about documentation!
|
|
255
|
+
|
|
256
|
+
On the other hand, if you have ideas on how to improve this example, please speak up in the <%= mailing_list_link %>. Thanks!
|
|
257
|
+
<% end %>
|
|
258
|
+
|
|
259
|
+
<% example "HelloWorld format specification file", "HelloWorld.spec" do |n| %>
|
|
260
|
+
<code lang="rhtml">
|
|
261
|
+
<%= h File.read('doc/HelloWorld.spec').gsub(/^/, $unindent * n.depth.next).lstrip %>
|
|
262
|
+
</code>
|
|
263
|
+
<% end %>
|
|
264
|
+
|
|
265
|
+
<% example "Input document for HelloWorld format", "HelloWorld.input" do |n| %>
|
|
266
|
+
<code lang="rhtml">
|
|
267
|
+
<%= h File.read('doc/HelloWorld.input').gsub(/^/, $unindent * n.depth.next).lstrip %>
|
|
268
|
+
</code>
|
|
269
|
+
<% end %>
|
|
270
|
+
|
|
271
|
+
<% example "Output of HelloWorld format", "HelloWorld.output" do %>
|
|
272
|
+
<%= `ruby bin/gerbil doc/HelloWorld.spec doc/HelloWorld.input` %>
|
|
273
|
+
<% end %>
|
|
274
|
+
<% end %>
|
|
275
|
+
<% end %>
|
|
276
|
+
<% end %>
|
|
277
|
+
|
|
278
|
+
<% chapter "Usage" do %>
|
|
279
|
+
<pre><%=h "\n" << `ruby bin/gerbil -h`.gsub(/^/, $unindent) %></pre>
|
|
280
|
+
|
|
281
|
+
Gerbil requires its _first_ command-line argument to be either (1) the name of a predefined format or (2) the path to a <%= xref 'SpecFile', 'format specification file' %>. Predefined formats are simply short-hand names of format specification files located in the <tt>format/</tt> subdirectory of the Gerbil installation directory (see <%= xref "Manifest" %>).
|
|
282
|
+
|
|
283
|
+
<% section "The *include* directive", "include" do %>
|
|
284
|
+
The *include* directive allows you to insert the content of an arbitrary file at a certain place in the input document. It is written like this:
|
|
285
|
+
|
|
286
|
+
<%%# include _path_ %>
|
|
287
|
+
|
|
288
|
+
Here, _path_ is the path of the file whose content you wish to insert into the input document.
|
|
289
|
+
|
|
290
|
+
You can divide a large document into separate files for easier editing and stitch them together, dynamically, into a single document using the *include* directive.
|
|
291
|
+
<% end %>
|
|
292
|
+
|
|
293
|
+
<% section "The @$unindent@ variable", "unindent" do %>
|
|
294
|
+
The @$unindent@ variable allows you to unindent the content of every node in the input document by a specified amount of whitespace (spaces, tabs, newlines, and so on).
|
|
295
|
+
|
|
296
|
+
Simply define this variable somewhere in your input document, like this (assuming you indent your node content using a TAB and two spaces):
|
|
297
|
+
|
|
298
|
+
<%% $unindent = "\t " %>
|
|
299
|
+
|
|
300
|
+
and let Gerbil do it's magic!
|
|
301
|
+
<% end %>
|
|
302
|
+
<% end %>
|
|
303
|
+
|
|
304
|
+
<% part "Formats" do %>
|
|
305
|
+
This section describes the default formats provided along with Gerbil. The format specification files (see <%= xref "SpecFile" %>) for these formats can be found in the <tt>format/</tt> directory of the Gerbil installation directory (see <%= xref "Manifest" %>).
|
|
306
|
+
|
|
307
|
+
These formats are meant to serve as working examples. If you require more functionality from one of these formats, simply make a copy of the corresponding format specification file and edit the copy to suit your needs. If you would like to contribute or discuss your enhancements to these default formats, you can do so on the <%= mailing_list_link %>.
|
|
308
|
+
|
|
309
|
+
<% chapter "HTML", 'html' do %>
|
|
310
|
+
This format generates a _monolithic_ HTML (technically, it's XHTML 1.0 transitional, but who's counting?) document. A monolithic HTML document allows users to easily search for a particular topic using nothing more than their web browser's built-in text search mechanism. This facilitates offline reading, where an Internet search engine is not available.
|
|
311
|
+
|
|
312
|
+
In the HTML document, you will notice that the numbers of chapters, sections, figures, admonitions, etc. are hyperlinks that take you back to the corresponding place in the table of contents. These links make it easy to navigate the HTML document, especially for users of text-only web browsers.
|
|
313
|
+
|
|
314
|
+
Furthermore, the HTML document comes equipped with a stylesheet that makes it suitable for printing. In particular, users of the "Mozilla":http://mozilla.org and "Opera":http://www.opera.com/ family of web browsers will be pleasantly surprised to notice that all hyperlinks have been expanded to include their target URL next to the link text. So try using the "print preview" function of a graphical web browser to see how the HTML document will appear when printed.
|
|
315
|
+
|
|
316
|
+
<% section "Text to HTML conversion" do %>
|
|
317
|
+
Inside the <tt>format/</tt> subdirectory of the Gerbil installation directory (see <%= xref "Manifest" %>), you will see a <tt>html.rb</tt> file. This file defines a @String.to_html@ method which is used to transform text in an input document into HTML.
|
|
318
|
+
|
|
319
|
+
The default implementation of the @String.to_html@ method is based on the "Textile":http://whytheluckystiff.net/ruby/redcloth/ markup system. If you do not like Textile or wish to use a different markup system for text in your documents, then simply edit the <tt>html.rb</tt> file and adjust the source code of the default @String.to_html@ method accordingly.
|
|
320
|
+
|
|
321
|
+
For example, if you replace the entire <tt>html.rb</tt> file with the following code, then the output of all nodes will appear within red boxes in the final output document.
|
|
322
|
+
|
|
323
|
+
<code>
|
|
324
|
+
class String
|
|
325
|
+
def to_html
|
|
326
|
+
'<p style="border: thin solid red">' + self + '</p>'
|
|
327
|
+
end
|
|
328
|
+
end
|
|
329
|
+
</code>
|
|
330
|
+
|
|
331
|
+
In addition to supporting Textile markup, the default implementation has some additional features which are described in the following subsections.
|
|
332
|
+
|
|
333
|
+
<% section "Syntax coloring for source code" do %>
|
|
334
|
+
Syntax coloring is _automatically added_ to source code found inside the *<code>* and *</code>* HTML tags. Note that in Textile, any text enclosed within a pair of at-signs (@ and @) is also considered to be source code.
|
|
335
|
+
|
|
336
|
+
The following programming languages are currently supported by "CodeRay":http://coderay.rubychan.de:
|
|
337
|
+
* Ruby
|
|
338
|
+
* C
|
|
339
|
+
* Delphi
|
|
340
|
+
* HTML
|
|
341
|
+
* RHTML (Rails)
|
|
342
|
+
* Nitro-XHTML
|
|
343
|
+
|
|
344
|
+
<% section "Specifying the programming language" do %>
|
|
345
|
+
Because different programming languages have different syntax coloring schemes, you can specify the language of your source code using the @lang@ attribute to ensure that only the appropriate coloring scheme is used. Note that unless the @lang@ attribute is specified, _Ruby_ is assumed to be the programming language of all source code by default.
|
|
346
|
+
|
|
347
|
+
<% sampleCode = %q{
|
|
348
|
+
# Ruby ###########################
|
|
349
|
+
def hello
|
|
350
|
+
puts "Hello world!"
|
|
351
|
+
end
|
|
352
|
+
|
|
353
|
+
|
|
354
|
+
/* C ****************************/
|
|
355
|
+
#include <stdio.h>
|
|
356
|
+
int main(int argc, char **argv) {
|
|
357
|
+
printf("Hello world!\n");
|
|
358
|
+
return 0;
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
|
|
362
|
+
<!-- HTML ----------------------->
|
|
363
|
+
<html>
|
|
364
|
+
<body>
|
|
365
|
+
Hello world!
|
|
366
|
+
<body>
|
|
367
|
+
</html>
|
|
368
|
+
} %>
|
|
369
|
+
|
|
370
|
+
For example, here is some source code _without_ the @lang@ attribute:
|
|
371
|
+
|
|
372
|
+
<code><%= sampleCode %></code>
|
|
373
|
+
|
|
374
|
+
And here is the same source code with a @lang="c"@ attribute:
|
|
375
|
+
|
|
376
|
+
<code lang="c"><%= sampleCode %></code>
|
|
377
|
+
|
|
378
|
+
And here is the same source code with a @lang="html"@ attribute:
|
|
379
|
+
|
|
380
|
+
<code lang="html"><%= sampleCode %></code>
|
|
381
|
+
<% end %>
|
|
382
|
+
<% end %>
|
|
383
|
+
|
|
384
|
+
<% section "Smart sizing of source code" do %>
|
|
385
|
+
Source code is _automatically sized_ to be displayed as either a line or paragraph of text, depending on whether it contains line breaks.
|
|
386
|
+
|
|
387
|
+
For example, here is a single line of code:
|
|
388
|
+
|
|
389
|
+
<code>life = true or false</code>
|
|
390
|
+
|
|
391
|
+
And here is a paragraph of code:
|
|
392
|
+
|
|
393
|
+
<code>life =
|
|
394
|
+
true or false</code>
|
|
395
|
+
<% end %>
|
|
396
|
+
|
|
397
|
+
<% section "Protecting verbatim text" do %>
|
|
398
|
+
Sometimes you just need to protect some text from being mangled by the text-to-HTML conversion process . In such cases, you can wrap the text you want to proctect within *<noformat>* and *</noformat>* tags.
|
|
399
|
+
<% end %>
|
|
400
|
+
<% end %>
|
|
401
|
+
|
|
402
|
+
<% section "Parameters" do %>
|
|
403
|
+
The HTML format accepts the following document parameters.
|
|
404
|
+
|
|
405
|
+
|_. Parameter |_. Type |_. Default value |_. Description |
|
|
406
|
+
| @$title@ | String | @"$title"@ | Title of the document. |
|
|
407
|
+
| @$authors@ | Hash | @{"$authors" => nil}@ | A mapping of author name to author URL. You can obfuscate e-mail addresses using the provided @String#to_html_entities@ method like this:<br/>@{ "Y. Matsumoto" => "mailto:matz@ruby.invalid".to_html_entities }@ |
|
|
408
|
+
| @$date@ | String | @Time.now.strftime("%d %B %Y")@ | Date when the document was written. |
|
|
409
|
+
| @$logo@ | String | @nil@ | Arbitrary content that goes above the document title in the default header. |
|
|
410
|
+
| @$feeds@ | Hash | @nil@ | A mapping of feed URL to feed format. Here is an example: <code>$feeds = { "my_rss_feed.xml" => "rss", "my_atom_feed.xml" => "atom" }</code>|
|
|
411
|
+
| @$use_icons@ | Boolean | @true@ | Use "Tango icons":http://tango.freedesktop.org/Tango_Icon_Library in admonitions (see <%= xref "Admonitions" %>)? |
|
|
412
|
+
<% end %>
|
|
413
|
+
|
|
414
|
+
<% section "Methods" do %>
|
|
415
|
+
The HTML format provides the following methods. In the method declarations shown below,
|
|
416
|
+
* a pound sign (#) indicates that the method is an *instance method*, meaning that it can only be invoked on instances of a class, not on the classes themselves.
|
|
417
|
+
* a double colon sign (::) indicates that the method is a *class method*, meaning that it can only be invoked on a class.
|
|
418
|
+
|
|
419
|
+
|_. Method declaration |_. Description |
|
|
420
|
+
<%
|
|
421
|
+
# load library for parsing method documentation
|
|
422
|
+
require 'gerbil/rdoc'
|
|
423
|
+
|
|
424
|
+
spec_tree = RDoc::gen_parse_trees(@spec['code'])
|
|
425
|
+
|
|
426
|
+
html_rb_path = 'lib/gerbil/html.rb'
|
|
427
|
+
html_rb_code = File.read(html_rb_path)
|
|
428
|
+
html_rb_tree = RDoc::gen_parse_trees(html_rb_code, html_rb_path)
|
|
429
|
+
|
|
430
|
+
trees = spec_tree + html_rb_tree
|
|
431
|
+
meths = RDoc::gen_method_infos(*trees)
|
|
432
|
+
|
|
433
|
+
meths.each do |m|
|
|
434
|
+
%>
|
|
435
|
+
| @<%= m[:decl] %>@ | <noformat><%= m[:docs_html] %></noformat> |
|
|
436
|
+
<% end %>
|
|
437
|
+
<% end %>
|
|
438
|
+
|
|
439
|
+
<% chapter "Nodes", "html.nodes" do %>
|
|
440
|
+
Unless otherwise noted, all nodes defined by the HTML format accept two arguments, in this order:
|
|
441
|
+
# a title or name for the node
|
|
442
|
+
# a unique identifier for the node
|
|
443
|
+
|
|
444
|
+
The second argument is used by the cross-referencing nodes (see <%= xref "html.nodes.xref" %> and <%= xref "html.nodes.cite" %>), which allow you to refer to another node in the document by its unique identifier.
|
|
445
|
+
|
|
446
|
+
Furthermore, node definitions in the HTML format have two additional parameters:
|
|
447
|
+
|
|
448
|
+
|_. Parameter |_. Type |_. Description |
|
|
449
|
+
| toc | Boolean | Include this node in the *Table of Contents* (TOC)? |
|
|
450
|
+
| lof | Boolean | Include this node in the *List of Figures* (LOF)? |
|
|
451
|
+
|
|
452
|
+
<% section "Structure" do %>
|
|
453
|
+
The nodes described in this section form the overall structure of the output document.
|
|
454
|
+
|
|
455
|
+
<% section "header", "html.nodes.header" do %>
|
|
456
|
+
This node overrides the logo, title, list of authors, and date when the document was written, all of which are shown at the top of the document.
|
|
457
|
+
<% end %>
|
|
458
|
+
|
|
459
|
+
<% section "footer", "html.nodes.footer" do %>
|
|
460
|
+
This node overrides (1) the date when this document was generated and (2) the hyperlink to the Gerbil website, shown at the bottom of the document. The hyperlink is there as a way of saying thanks for Gerbil, the _wonderful_ little utility you have grown so fond of! ;-)
|
|
461
|
+
<% end %>
|
|
462
|
+
|
|
463
|
+
<% section "abstract", "html.nodes.abstract" do %>
|
|
464
|
+
A summary of the entire document. This is what most readers will _skim_ through, if you are lucky. Alas, nobody reads entire documents these days! :-(
|
|
465
|
+
<% end %>
|
|
466
|
+
|
|
467
|
+
<% section "xref", "html.nodes.xref" do %>
|
|
468
|
+
A cross-reference; a hyperlink that takes you to any node in the document.
|
|
469
|
+
|
|
470
|
+
The first argument of this node is either the unique identifier of the node you wish to cross-reference. If no nodes in the document have the given identifier, then the titles of all nodes in the document are searched. If even that fails, then an error will be raised.
|
|
471
|
+
|
|
472
|
+
The second argument of this node overrides the default link text of the cross-reference.
|
|
473
|
+
|
|
474
|
+
For example, this node in the input document:
|
|
475
|
+
|
|
476
|
+
<%%= xref "SpecFile" %>
|
|
477
|
+
|
|
478
|
+
appears in the output document like this: <%= xref "SpecFile" %>.
|
|
479
|
+
|
|
480
|
+
As another example, this node in the input document:
|
|
481
|
+
|
|
482
|
+
<%%= xref "SpecFile", "custom link text" %>
|
|
483
|
+
|
|
484
|
+
appears in the output document like this: <%= xref "SpecFile", "custom link text" %>.
|
|
485
|
+
<% end %>
|
|
486
|
+
<% end %>
|
|
487
|
+
|
|
488
|
+
<% section "Organization" do %>
|
|
489
|
+
The nodes described in this section are meant to help organize the document's content logically.
|
|
490
|
+
|
|
491
|
+
<% section "part", "html.nodes.part" do %>
|
|
492
|
+
A collection of chapters.
|
|
493
|
+
|
|
494
|
+
<% part "An example" do %>
|
|
495
|
+
This is what a *part* node appears like.
|
|
496
|
+
<% end %>
|
|
497
|
+
<% end %>
|
|
498
|
+
|
|
499
|
+
<% section "chapter", "html.nodes.chapter" do %>
|
|
500
|
+
A collection of sections.
|
|
501
|
+
|
|
502
|
+
<% chapter "An example" do %>
|
|
503
|
+
This is what a *chapter* node appears like.
|
|
504
|
+
<% end %>
|
|
505
|
+
<% end %>
|
|
506
|
+
|
|
507
|
+
<% section "section", "html.nodes.section" do %>
|
|
508
|
+
A collection of paragraphs about a particular topic.
|
|
509
|
+
|
|
510
|
+
<% section "An example" do %>
|
|
511
|
+
This is what a *section* node appears like.
|
|
512
|
+
<% end %>
|
|
513
|
+
<% end %>
|
|
514
|
+
|
|
515
|
+
<% section "paragraph", "html.nodes.paragraph" do %>
|
|
516
|
+
A collection of sentences about a particular idea.
|
|
517
|
+
|
|
518
|
+
<% paragraph "An example" do %>
|
|
519
|
+
This is what a *paragraph* node appears like.
|
|
520
|
+
<% end %>
|
|
521
|
+
<% end %>
|
|
522
|
+
<% end %>
|
|
523
|
+
|
|
524
|
+
<% section "Admonitions" do %>
|
|
525
|
+
An admonition is basically a box that is indented more deeply than the text surrounding it. It is typically used to convey extraneous or pertinent information about the application of ideas discussed in the surrounding text.
|
|
526
|
+
|
|
527
|
+
I like to follow the KDE guidelines<%= cite "KDE.admonitions" %> when determining which admonition to use in my documents.
|
|
528
|
+
|
|
529
|
+
<% reference "KDE.admonitions" do %>
|
|
530
|
+
L. Watts, "Admonitions: Tips, hints, and Warnings", in _The KDE DocBook Authors guide_, Chapter 13, [Online document], 22 September 2004 (Revision 1.00.00), [cited 8 December 2007], Available at <%= link 'http://l10n.kde.org/docs/markup/tips-hints-etc.html' %>
|
|
531
|
+
<% end %>
|
|
532
|
+
|
|
533
|
+
<% section "warning", "html.nodes.warning" do %>
|
|
534
|
+
Use a *warning* node when "data loss could occur if you follow the procedure being described." <%= cite "KDE.admonitions" %>
|
|
535
|
+
|
|
536
|
+
<% warning "An example" do %>
|
|
537
|
+
This is what a *warning* node appears like.
|
|
538
|
+
<% end %>
|
|
539
|
+
<% end %>
|
|
540
|
+
|
|
541
|
+
<% section "caution", "html.nodes.caution" do %>
|
|
542
|
+
bq. A note of caution. Use this for example when the reader may lose easily recovered or replaceable information (e.g. user settings), or when they could cause data loss if they don't correctly follow the procedure being outlined. <%= cite "KDE.admonitions" %>
|
|
543
|
+
|
|
544
|
+
<% caution "An example" do %>
|
|
545
|
+
This is what a *caution* node appears like.
|
|
546
|
+
<% end %>
|
|
547
|
+
<% end %>
|
|
548
|
+
|
|
549
|
+
<% section "important", "html.nodes.important" do %>
|
|
550
|
+
Use an *important* node when:
|
|
551
|
+
|
|
552
|
+
bq. When there is no danger of data loss, but you wish to make clear to the reader a consequence that isn't immediately obvious (e.g. when changing the font for one instance of a program also changes the default setting, and this isn't clear from the GUI.) <%= cite "KDE.admonitions" %>
|
|
553
|
+
|
|
554
|
+
<% important "An example" do %>
|
|
555
|
+
This is what a *important* node appears like.
|
|
556
|
+
<% end %>
|
|
557
|
+
<% end %>
|
|
558
|
+
|
|
559
|
+
<% section "note", "html.nodes.note" do %>
|
|
560
|
+
Use a *note* node to convey:
|
|
561
|
+
|
|
562
|
+
bq. Information the user should be aware of, but is peripheral to the actual task being described. <%= cite "KDE.admonitions" %>
|
|
563
|
+
|
|
564
|
+
<% note "An example" do %>
|
|
565
|
+
This is what a *note* node appears like.
|
|
566
|
+
<% end %>
|
|
567
|
+
<% end %>
|
|
568
|
+
|
|
569
|
+
<% section "tip", "html.nodes.tip" do %>
|
|
570
|
+
Use a *tip* node when:
|
|
571
|
+
|
|
572
|
+
bq. When you're giving a hint to make things easier or more productive for the reader. <%= cite "KDE.admonitions" %>
|
|
573
|
+
|
|
574
|
+
<% tip "An example" do %>
|
|
575
|
+
This is what a *tip* node appears like.
|
|
576
|
+
<% end %>
|
|
577
|
+
<% end %>
|
|
578
|
+
<% end %>
|
|
579
|
+
|
|
580
|
+
<% section "Auxilary materials" do %>
|
|
581
|
+
<% section "figure", "html.nodes.figure" do %>
|
|
582
|
+
A diagram, sketch, image, or illustration; something that visually depicts an idea or thought.
|
|
583
|
+
|
|
584
|
+
<% figure "An example" do %>
|
|
585
|
+
This is what a *figure* node appears like.
|
|
586
|
+
<% end %>
|
|
587
|
+
<% end %>
|
|
588
|
+
|
|
589
|
+
<% section "table", "html.nodes.table" do %>
|
|
590
|
+
Information (typically measurement data) represented in tabular form for easy reading, comparison, and analysis.
|
|
591
|
+
|
|
592
|
+
<% table "An example" do %>
|
|
593
|
+
This is what a *table* node appears like.
|
|
594
|
+
<% end %>
|
|
595
|
+
<% end %>
|
|
596
|
+
|
|
597
|
+
<% section "example", "html.nodes.example" do %>
|
|
598
|
+
A sample application of an idea or thought.
|
|
599
|
+
|
|
600
|
+
<% example "An example" do %>
|
|
601
|
+
This is what a *example* node appears like.
|
|
602
|
+
<% end %>
|
|
603
|
+
<% end %>
|
|
604
|
+
|
|
605
|
+
<% section "equation", "html.nodes.equation" do %>
|
|
606
|
+
A mathematical equation or formula.
|
|
607
|
+
|
|
608
|
+
<% equation "An example" do %>
|
|
609
|
+
This is what a *equation* node appears like.
|
|
610
|
+
<% end %>
|
|
611
|
+
<% end %>
|
|
612
|
+
|
|
613
|
+
<% section "procedure", "html.nodes.procedure" do %>
|
|
614
|
+
An outline; a series of steps outlining some kind of process.
|
|
615
|
+
|
|
616
|
+
<% procedure "An example" do %>
|
|
617
|
+
This is what a *procedure* node appears like.
|
|
618
|
+
<% end %>
|
|
619
|
+
<% end %>
|
|
620
|
+
<% end %>
|
|
621
|
+
|
|
622
|
+
<% section "Bibliography" do %>
|
|
623
|
+
The nodes in this section deal with attribution of ideas -- an important weapon against plagiarism.
|
|
624
|
+
|
|
625
|
+
<% section "reference", "html.nodes.reference" do %>
|
|
626
|
+
This node stores bibliography information about an information source that is relevant to your document.
|
|
627
|
+
|
|
628
|
+
If you wish to cite a certain source in several places in your document, start by creating a *reference* node first and then use a *cite* node (see <%= xref "html.nodes.cite" %>) to perform the citation.
|
|
629
|
+
|
|
630
|
+
<% paragraph "An example" do %>
|
|
631
|
+
See <%= xref 'html.nodes.reference.example' %> for an example of what a *reference* node appears like.
|
|
632
|
+
<% end %>
|
|
633
|
+
|
|
634
|
+
<% reference 'html.nodes.reference.example' do %>
|
|
635
|
+
This is what a *reference* node appears like.
|
|
636
|
+
<% end %>
|
|
637
|
+
<% end %>
|
|
638
|
+
|
|
639
|
+
<% section "cite", "html.nodes.cite" do %>
|
|
640
|
+
A citation to a *reference* node (see <%= xref 'html.nodes.reference' %>) in the document's bibliography.
|
|
641
|
+
|
|
642
|
+
The first argument of this node is the unique identifier of the reference node you wish to cite. You can specify additional arguments to give more detail about the citation.
|
|
643
|
+
|
|
644
|
+
For example, this node in the input document:
|
|
645
|
+
|
|
646
|
+
<%%= cite "html.nodes.reference.example" %>
|
|
647
|
+
|
|
648
|
+
appears in the output document like this: <%= cite "html.nodes.reference.example" %>
|
|
649
|
+
|
|
650
|
+
As another example, this node in the input document:
|
|
651
|
+
|
|
652
|
+
<%%= cite "html.nodes.reference.example", "chapter 10", "page 53", "..." %>
|
|
653
|
+
|
|
654
|
+
appears in the output document like this: <%= cite "html.nodes.reference.example", "chapter 10", "page 53", "..." %>
|
|
655
|
+
<% end %>
|
|
656
|
+
<% end %>
|
|
657
|
+
<% end %>
|
|
658
|
+
<% end %>
|
|
659
|
+
|
|
660
|
+
<% chapter "Plain text", 'text' do %>
|
|
661
|
+
This format is not yet implemented.
|
|
662
|
+
|
|
663
|
+
http://en.wikipedia.org/wiki/Plain_text
|
|
664
|
+
<% end %>
|
|
665
|
+
|
|
666
|
+
<% chapter "LaTeX", 'latex' do %>
|
|
667
|
+
This format is not yet implemented.
|
|
668
|
+
|
|
669
|
+
http://www.latex-project.org
|
|
670
|
+
<% end %>
|
|
671
|
+
|
|
672
|
+
<% chapter "UNIX man page", 'man' do %>
|
|
673
|
+
This format is not yet implemented.
|
|
674
|
+
|
|
675
|
+
http://en.wikipedia.org/wiki/Man_page
|
|
676
|
+
<% end %>
|
|
677
|
+
<% end %>
|