erbook 7.3.0 → 8.0.0
Sign up to get free protection for your applications and to get access to all the features.
- data/doc/HelloWorld.spec +9 -10
- data/doc/api/classes/ERBook/Document.html +50 -38
- data/doc/api/classes/ERBook/Document/Node.html +185 -8
- data/doc/api/classes/ERBook/Template.html +20 -20
- data/doc/api/classes/ERBook/Template/Sandbox.html +5 -5
- data/doc/api/classes/RDoc/AnyMethod.html +20 -20
- data/doc/api/classes/RDoc/TopLevel.html +30 -30
- data/doc/api/classes/String.html +10 -10
- data/doc/api/created.rid +1 -1
- data/doc/api/files/lib/erbook/document_rb.html +1 -1
- data/doc/api/files/lib/erbook/to_xhtml_rb.html +2 -2
- data/doc/api/files/lib/erbook_rb.html +1 -1
- data/doc/api/panel/search_index.js +1 -1
- data/doc/formats.erb +196 -61
- data/doc/history.erb +45 -0
- data/doc/index.html +608 -537
- data/doc/intro.erb +1 -1
- data/doc/setup.erb +66 -38
- data/doc/theory.erb +292 -61
- data/doc/usage.erb +1 -1
- data/fmt/xhtml.yaml +139 -150
- data/lib/erbook.rb +2 -2
- data/lib/erbook/document.rb +62 -26
- metadata +5 -5
data/doc/intro.erb
CHANGED
|
@@ -35,7 +35,7 @@
|
|
|
35
35
|
* It consists of a mere <%= `sloccount .`[/^Total.+=\s*(\d+)$/, 1] %> lines of code.
|
|
36
36
|
|
|
37
37
|
|
|
38
|
-
%|note "More document formats are planned"
|
|
38
|
+
%|note! "More document formats are planned"
|
|
39
39
|
|
|
40
40
|
<%= xref "latex", "LaTeX (PDF)" %>, <%= xref "man", "UNIX manual page" %>, and <%= xref "text", "plain text" %> document formats are planned for future releases... <%= xref "License", "patches are welcome" %>!
|
|
41
41
|
|
data/doc/setup.erb
CHANGED
|
@@ -10,10 +10,30 @@
|
|
|
10
10
|
|
|
11
11
|
Your system needs the following software to run <%= $project %>.
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
13
|
+
%|table
|
|
14
|
+
%|thead
|
|
15
|
+
%|tr
|
|
16
|
+
%|th
|
|
17
|
+
Software
|
|
18
|
+
%|th
|
|
19
|
+
Description
|
|
20
|
+
%|th
|
|
21
|
+
Notes
|
|
22
|
+
%|tbody
|
|
23
|
+
%|tr
|
|
24
|
+
%|td
|
|
25
|
+
[Ruby](http://ruby-lang.org)
|
|
26
|
+
%|td
|
|
27
|
+
Ruby language interpreter
|
|
28
|
+
%|td
|
|
29
|
+
Version 1.8.7 or newer is required.
|
|
30
|
+
%|tr
|
|
31
|
+
%|td
|
|
32
|
+
[RubyGems](http://rubygems.org)
|
|
33
|
+
%|td
|
|
34
|
+
Ruby packaging system
|
|
35
|
+
%|td
|
|
36
|
+
Version 1.0.0 or newer is required.
|
|
17
37
|
|
|
18
38
|
|
|
19
39
|
%|section "Installation"
|
|
@@ -76,37 +96,45 @@
|
|
|
76
96
|
policy](http://www.rubygems.org/read/chapter/7), which
|
|
77
97
|
can be summarized as follows:
|
|
78
98
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
99
|
+
%|table
|
|
100
|
+
%|thead
|
|
101
|
+
%|tr
|
|
102
|
+
%|td :rowspan => 2
|
|
103
|
+
What increased in the version number?
|
|
104
|
+
%|td :colspan => 3
|
|
105
|
+
The increase indicates that the release:
|
|
106
|
+
%|tr
|
|
107
|
+
%|th
|
|
108
|
+
Is backward compatible?
|
|
109
|
+
%|th
|
|
110
|
+
Has new features?
|
|
111
|
+
%|th
|
|
112
|
+
Has bug fixes?
|
|
113
|
+
%|tbody
|
|
114
|
+
%|tr
|
|
115
|
+
%|th
|
|
116
|
+
major
|
|
117
|
+
%|td :style => "background-color: #FFE4E1;"
|
|
118
|
+
No
|
|
119
|
+
%|td
|
|
120
|
+
Yes
|
|
121
|
+
%|td
|
|
122
|
+
Yes
|
|
123
|
+
%|tr
|
|
124
|
+
%|th
|
|
125
|
+
minor
|
|
126
|
+
%|td
|
|
127
|
+
Yes
|
|
128
|
+
%|td
|
|
129
|
+
Yes
|
|
130
|
+
%|td
|
|
131
|
+
Yes
|
|
132
|
+
%|tr
|
|
133
|
+
%|th
|
|
134
|
+
patch
|
|
135
|
+
%|td
|
|
136
|
+
Yes
|
|
137
|
+
%|td :style => "background-color: #FFE4E1;"
|
|
138
|
+
No
|
|
139
|
+
%|td
|
|
140
|
+
Yes
|
data/doc/theory.erb
CHANGED
|
@@ -62,12 +62,34 @@
|
|
|
62
62
|
|
|
63
63
|
Technically, nodes are Ruby method invocations composed of the following:
|
|
64
64
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
65
|
+
%|table
|
|
66
|
+
%|thead
|
|
67
|
+
%|tr
|
|
68
|
+
%|th
|
|
69
|
+
Component
|
|
70
|
+
%|th
|
|
71
|
+
Description
|
|
72
|
+
%|tbody
|
|
73
|
+
%|tr
|
|
74
|
+
%|td
|
|
75
|
+
`node_type`
|
|
76
|
+
%|td
|
|
77
|
+
Name of the method being invoked.
|
|
78
|
+
%|tr
|
|
79
|
+
%|td
|
|
80
|
+
`node_argument1, node_argument2, ...`
|
|
81
|
+
%|td
|
|
82
|
+
Arguments for the method invocation.
|
|
83
|
+
%|tr
|
|
84
|
+
%|td
|
|
85
|
+
`node_content`
|
|
86
|
+
%|td
|
|
87
|
+
A block argument being passed to the method invocation.
|
|
88
|
+
%|tr
|
|
89
|
+
%|td
|
|
90
|
+
`node_object`
|
|
91
|
+
%|td
|
|
92
|
+
A `ERBook::Document::Node` object (see <%= xref "Node.class" %>) representing this method invocation.
|
|
71
93
|
|
|
72
94
|
A <%= xref "SpecFile", "format specification file" %> defines what types of nodes an input document may use.
|
|
73
95
|
|
|
@@ -76,39 +98,146 @@
|
|
|
76
98
|
|
|
77
99
|
When <%= $project %> builds a document tree from the nodes in an input document, it stores information about these nodes into `ERBook::Document::Node` objects. A `ERBook::Document::Node` object has the following properties (methods):
|
|
78
100
|
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
101
|
+
%|table
|
|
102
|
+
%|thead
|
|
103
|
+
%|tr
|
|
104
|
+
%|th
|
|
105
|
+
Property
|
|
106
|
+
%|th
|
|
107
|
+
Type
|
|
108
|
+
%|th
|
|
109
|
+
Description
|
|
110
|
+
%|tbody
|
|
111
|
+
%|tr
|
|
112
|
+
%|td
|
|
113
|
+
type
|
|
114
|
+
%|td
|
|
115
|
+
`String`
|
|
116
|
+
%|td
|
|
117
|
+
Name of the type of this node.
|
|
118
|
+
%|tr
|
|
119
|
+
%|td
|
|
120
|
+
definition
|
|
121
|
+
%|td
|
|
122
|
+
`Hash`
|
|
123
|
+
%|td
|
|
124
|
+
The definition of this type of node, taken directly from the <%= xref "SpecFile", "format specification file" %>.
|
|
125
|
+
%|tr
|
|
126
|
+
%|td
|
|
127
|
+
arguments
|
|
128
|
+
%|td
|
|
129
|
+
`Array`
|
|
130
|
+
%|td
|
|
131
|
+
Arguments passed to this node.
|
|
132
|
+
%|tr
|
|
133
|
+
%|td
|
|
134
|
+
backtrace
|
|
135
|
+
%|td
|
|
136
|
+
`Array`
|
|
137
|
+
%|td
|
|
138
|
+
A stack trace describing the location of this node in the input document.
|
|
139
|
+
%|tr
|
|
140
|
+
%|td
|
|
141
|
+
parent
|
|
142
|
+
%|td
|
|
143
|
+
`ERBook::Document::Node`
|
|
144
|
+
%|td
|
|
145
|
+
The `ERBook::Document::Node` object which contains this node. The value of this property will be `nil` if this node is a root of the document tree.
|
|
146
|
+
%|tr
|
|
147
|
+
%|td
|
|
148
|
+
children
|
|
149
|
+
%|td
|
|
150
|
+
`Array` of `ERBook::Document::Node`
|
|
151
|
+
%|td
|
|
152
|
+
List of child nodes from the document tree.
|
|
153
|
+
%|tr
|
|
154
|
+
%|td
|
|
155
|
+
depth
|
|
156
|
+
%|td
|
|
157
|
+
`Integer`
|
|
158
|
+
%|td
|
|
159
|
+
Distance from the root of the document tree to this node.
|
|
160
|
+
%|tr
|
|
161
|
+
%|td
|
|
162
|
+
section_number
|
|
163
|
+
%|td
|
|
164
|
+
`String`
|
|
165
|
+
%|td
|
|
166
|
+
A LaTeX-style section number for this node. This property is only present if enabled in the **number** parameter in the definition of this type of node.
|
|
167
|
+
%|tr
|
|
168
|
+
%|td
|
|
169
|
+
ordinal_number
|
|
170
|
+
%|td
|
|
171
|
+
`Integer`
|
|
172
|
+
%|td
|
|
173
|
+
An order-of-occurrence number for this node. This property is only present if enabled in the **number** parameter in the definition of this type of node.
|
|
174
|
+
%|tr
|
|
175
|
+
%|td
|
|
176
|
+
content
|
|
177
|
+
%|td
|
|
178
|
+
`String`
|
|
179
|
+
%|td
|
|
180
|
+
The block of text passed to this node.
|
|
181
|
+
%|tr
|
|
182
|
+
%|td
|
|
183
|
+
output
|
|
184
|
+
%|td
|
|
185
|
+
`String`
|
|
186
|
+
%|td
|
|
187
|
+
Result of the node output template for the content of this node.
|
|
188
|
+
|
|
189
|
+
Furthermore, the `ERBook::Document::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 _additional_ properties for `ERBook::Document::Node` objects dynamically.
|
|
94
190
|
|
|
95
191
|
|
|
96
192
|
%|section "Format specification file", "SpecFile"
|
|
97
193
|
|
|
98
194
|
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.
|
|
99
195
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
196
|
+
%|table
|
|
197
|
+
%|thead
|
|
198
|
+
%|tr
|
|
199
|
+
%|th
|
|
200
|
+
Parameter
|
|
201
|
+
%|th
|
|
202
|
+
Type
|
|
203
|
+
%|th
|
|
204
|
+
Description
|
|
205
|
+
%|tbody
|
|
206
|
+
%|tr
|
|
207
|
+
%|td
|
|
208
|
+
desc
|
|
209
|
+
%|td
|
|
210
|
+
`String`
|
|
211
|
+
%|td
|
|
212
|
+
A short description of the output format.
|
|
213
|
+
%|tr
|
|
214
|
+
%|td
|
|
215
|
+
code
|
|
216
|
+
%|td
|
|
217
|
+
`String`
|
|
218
|
+
%|td
|
|
219
|
+
Ruby code that will be loaded before the input document is processed. This source code will be evaluated inside the main <%= $project %> executable, so any file-system or path-dependent portions of this source code should take appropriate precautions.
|
|
220
|
+
%|tr
|
|
221
|
+
%|td
|
|
222
|
+
nodes
|
|
223
|
+
%|td
|
|
224
|
+
Hash
|
|
225
|
+
%|td
|
|
226
|
+
A listing of <%= xref "SpecFile.nodes", "node definitions" %>.
|
|
227
|
+
%|tr
|
|
228
|
+
%|td
|
|
229
|
+
output
|
|
230
|
+
%|td
|
|
231
|
+
`String`
|
|
232
|
+
%|td
|
|
233
|
+
An eRuby template for the final output document. See <%= xref "SpecFile.output" %>.
|
|
234
|
+
|
|
106
235
|
|
|
107
236
|
<%
|
|
108
237
|
# XXX: "declare" this local variable here (in the parent
|
|
109
238
|
# scope) because it is initialized and used in two
|
|
110
239
|
# different child scopes that exist at different depths
|
|
111
|
-
|
|
240
|
+
output_template_table_builder = nil
|
|
112
241
|
%>
|
|
113
242
|
|
|
114
243
|
|
|
@@ -116,14 +245,51 @@
|
|
|
116
245
|
|
|
117
246
|
A node definition is a mapping from a name (the "node type") to the following set of parameters:
|
|
118
247
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
248
|
+
%|table
|
|
249
|
+
%|thead
|
|
250
|
+
%|tr
|
|
251
|
+
%|th
|
|
252
|
+
Parameter
|
|
253
|
+
%|th
|
|
254
|
+
Type
|
|
255
|
+
%|th
|
|
256
|
+
Description
|
|
257
|
+
%|tbody
|
|
258
|
+
%|tr
|
|
259
|
+
%|td
|
|
260
|
+
params
|
|
261
|
+
%|td
|
|
262
|
+
`String` or `Array` thereof
|
|
263
|
+
%|td
|
|
264
|
+
List of parameters that are expected to be specified during an instantiation of node. Any additional arguments passed during instantiation are stored in the `arguments` attribute of the resulting `ERBook::Document::Node` object.
|
|
265
|
+
%|tr
|
|
266
|
+
%|td
|
|
267
|
+
number
|
|
268
|
+
%|td
|
|
269
|
+
`String` or `Array` thereof
|
|
270
|
+
%|td
|
|
271
|
+
When "ordinal", assign an order of occurrence number to this node. When "section", assign a LaTeX-style section number to this node. Both choices can be specified simultaneously.
|
|
272
|
+
%|tr
|
|
273
|
+
%|td
|
|
274
|
+
inline
|
|
275
|
+
%|td
|
|
276
|
+
Boolean
|
|
277
|
+
%|td
|
|
278
|
+
Is node's output an in-line string of text that can be embedded anywhere in the document?
|
|
279
|
+
%|tr
|
|
280
|
+
%|td
|
|
281
|
+
silent
|
|
282
|
+
%|td
|
|
283
|
+
Boolean
|
|
284
|
+
%|td
|
|
285
|
+
Suppress the output of this node at the location it is instantiated?
|
|
286
|
+
%|tr
|
|
287
|
+
%|td
|
|
288
|
+
output
|
|
289
|
+
%|td
|
|
290
|
+
`String`
|
|
291
|
+
%|td
|
|
292
|
+
An eRuby template for the content of this node. See <%= xref "SpecFile.nodes.output" %>.
|
|
127
293
|
|
|
128
294
|
You may define additional parameters in a node definition if you want.
|
|
129
295
|
|
|
@@ -134,24 +300,84 @@
|
|
|
134
300
|
|
|
135
301
|
The following variables are available for use in this template:
|
|
136
302
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
303
|
+
%|output_template_table_builder = lambda do |additional_rows|
|
|
304
|
+
%|table
|
|
305
|
+
%|thead
|
|
306
|
+
%|tr
|
|
307
|
+
%|th
|
|
308
|
+
Variable
|
|
309
|
+
%|th
|
|
310
|
+
Type
|
|
311
|
+
%|th
|
|
312
|
+
Description
|
|
313
|
+
%|tbody
|
|
314
|
+
% additional_rows.call
|
|
315
|
+
%|tr
|
|
316
|
+
%|td
|
|
317
|
+
`@roots`
|
|
318
|
+
%|td
|
|
319
|
+
`Array` of `ERBook::Document::Node`
|
|
320
|
+
%|td
|
|
321
|
+
All root nodes in the document tree.
|
|
322
|
+
%|tr
|
|
323
|
+
%|td
|
|
324
|
+
`@nodes`
|
|
325
|
+
%|td
|
|
326
|
+
`Array` of `ERBook::Document::Node`
|
|
327
|
+
%|td
|
|
328
|
+
All nodes in the document tree.
|
|
329
|
+
%|tr
|
|
330
|
+
%|td
|
|
331
|
+
`@nodes_by_type`
|
|
332
|
+
%|td
|
|
333
|
+
`Hash`
|
|
334
|
+
%|td
|
|
335
|
+
Mapping from node type (`String`) to array of `ERBook::Document::Node` objects having that type.
|
|
336
|
+
%|tr
|
|
337
|
+
%|td
|
|
338
|
+
`@format`
|
|
339
|
+
%|td
|
|
340
|
+
`Hash`
|
|
341
|
+
%|td
|
|
342
|
+
Data from the format specification file.
|
|
343
|
+
|
|
344
|
+
<%= PROJECT %> also provides the following mappings inside the `@format` variable:
|
|
345
|
+
|
|
346
|
+
%|table
|
|
347
|
+
%|thead
|
|
348
|
+
%|tr
|
|
349
|
+
%|th
|
|
350
|
+
Expression
|
|
351
|
+
%|th
|
|
352
|
+
Type
|
|
353
|
+
%|th
|
|
354
|
+
Description
|
|
355
|
+
%|tbody
|
|
356
|
+
%|tr
|
|
357
|
+
%|td
|
|
358
|
+
`@format[:name]`
|
|
359
|
+
%|td
|
|
360
|
+
`String`
|
|
361
|
+
%|td
|
|
362
|
+
Short-hand name of the current format.
|
|
363
|
+
%|tr
|
|
364
|
+
%|td
|
|
365
|
+
`@format[:file]`
|
|
366
|
+
%|td
|
|
367
|
+
`String`
|
|
368
|
+
%|td
|
|
369
|
+
Path of the current format specification file.
|
|
370
|
+
%|tr
|
|
371
|
+
|
|
372
|
+
% output_template_table_builder.call lambda {
|
|
373
|
+
%|tr
|
|
374
|
+
%|td
|
|
375
|
+
`@node`
|
|
376
|
+
%|td
|
|
377
|
+
`ERBook::Document::Node`
|
|
378
|
+
%|td
|
|
379
|
+
The node for which this template is being evaluated.
|
|
380
|
+
% }
|
|
155
381
|
|
|
156
382
|
%|section "Document output template", "SpecFile.output"
|
|
157
383
|
|
|
@@ -159,10 +385,15 @@
|
|
|
159
385
|
|
|
160
386
|
The following variables are available for use in this template:
|
|
161
387
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
388
|
+
% output_template_table_builder.call lambda {
|
|
389
|
+
%|tr
|
|
390
|
+
%|td
|
|
391
|
+
`@content`
|
|
392
|
+
%|td
|
|
393
|
+
`String`
|
|
394
|
+
%|td
|
|
395
|
+
Content of the processed document.
|
|
396
|
+
% }
|
|
166
397
|
|
|
167
398
|
|
|
168
399
|
%|section "Creating your own document format", "HelloWorld"
|
|
@@ -186,18 +417,18 @@
|
|
|
186
417
|
4. Examine the <tt>HelloWorld.output</tt> file to your satisfaction!
|
|
187
418
|
|
|
188
419
|
|
|
189
|
-
%|example "HelloWorld format specification file", "HelloWorld.spec"
|
|
420
|
+
%|example! "HelloWorld format specification file", "HelloWorld.spec"
|
|
190
421
|
|
|
191
422
|
<code lang="rhtml"><%= verbatim File.read('doc/HelloWorld.spec') %></code>
|
|
192
423
|
|
|
193
424
|
|
|
194
|
-
%|example "Input document for HelloWorld format", "HelloWorld.input"
|
|
425
|
+
%|example! "Input document for HelloWorld format", "HelloWorld.input"
|
|
195
426
|
|
|
196
427
|
Note that this input document uses the [*shorthand* eRuby directive syntax](<%= Ember::WEBSITE %>#Directives) and the [implicit <tt><%% end %></tt> inference](<%= Ember::WEBSITE %>#Infer-block-endings) features of the [<%= Ember::PROJECT %>](<%= Ember::WEBSITE %>) <%= Ember::TAGLINE %>.
|
|
197
428
|
|
|
198
429
|
<code lang="rhtml"><%= verbatim File.read('doc/HelloWorld.input') %></code>
|
|
199
430
|
|
|
200
431
|
|
|
201
|
-
%|example "Output of HelloWorld format", "HelloWorld.output"
|
|
432
|
+
%|example! "Output of HelloWorld format", "HelloWorld.output"
|
|
202
433
|
|
|
203
434
|
%= `ruby bin/#{PROGRAM} -u doc/HelloWorld.spec doc/HelloWorld.input`
|