maui 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. checksums.yaml +7 -0
  2. data/GPL-3 +674 -0
  3. data/Makefile +17 -0
  4. data/Manifest.txt +9 -0
  5. data/README.fab +222 -0
  6. data/README.html +296 -0
  7. data/bin/maui +200 -0
  8. data/lib/mau/fabricator.rb +2071 -0
  9. data/maui.fab +3576 -0
  10. data/maui.gemspec +24 -0
  11. metadata +59 -0
@@ -0,0 +1,17 @@
1
+ VERSION = $(shell grep -x -A1 '<< VERSION >>:' maui.fab | \
2
+ tail +2 | \
3
+ sed -e 's/^ *//')
4
+
5
+ all: maui-$(VERSION).tar.gz maui-$(VERSION).gem
6
+
7
+ maui-$(VERSION).tar.gz: tangle-everything
8
+ tar czvf $@ `cat Manifest.txt`
9
+
10
+ maui-$(VERSION).gem: tangle-everything
11
+ gem build maui.gemspec
12
+
13
+ .PHONY: tangle-everything
14
+
15
+ tangle-everything:
16
+ ruby -Ilib bin/maui maui.fab
17
+ ruby -Ilib bin/maui README.fab README.html
@@ -0,0 +1,9 @@
1
+ GPL-3
2
+ Makefile
3
+ Manifest.txt
4
+ README.fab
5
+ README.html
6
+ bin/maui
7
+ lib/mau/fabricator.rb
8
+ maui.fab
9
+ maui.gemspec
@@ -0,0 +1,222 @@
1
+ This is Maui, the Mau Independent Fabricator.
2
+
3
+ Fabricator is a literate programming engine with an unobtrusive,
4
+ wiki-like syntax. Modern Fabricator lives normally inside Mau,
5
+ a PIM-oriented wiki engine, but Maui makes it available through
6
+ a command line interface or a Ruby API without requiring a full
7
+ Mau installation.
8
+
9
+
10
+ == Inline markup
11
+
12
+ Fabricator's markup can be viewed as a particular wiki markup
13
+ with literate programming extensions. Here are the inline
14
+ markup elements:
15
+
16
+ - *Bold* text is marked by surrounding stars: [[*foo*]]
17
+
18
+ - /Italic/ text is marked by surrounding slashes: [[/foo/]]
19
+
20
+ - _Underlined_ text is marked by surrounding underscores:
21
+ [[_foo_]]
22
+
23
+ - <Links|http://www.techterms.com/definition/hyperlink> are
24
+ marked by surrounding brokets: [[<link face|URL>]]. Note that
25
+ the order of the aspects of the link matches that commonly
26
+ used in paper encyclopedias rather than that used HTML.
27
+
28
+
29
+ == Narrative structure
30
+
31
+ /Paragraphs/ are separated from each other and other input by
32
+ blank lines.
33
+
34
+
35
+ Two adjacent blank lines separate /sections/.
36
+
37
+
38
+ An indented block of text will be treated as a piece of /sample
39
+ code/, like this:
40
+
41
+ These lines were indented. Note that a block can contain
42
+ blank lines,
43
+
44
+ but only one at a time. Two consecutive blank lines would be
45
+ parsed as a section break, and the new section would contain a
46
+ new block.
47
+
48
+
49
+ Like this.
50
+
51
+
52
+ Items in a /bullet list/ are marked by leading dash and space,
53
+ and can be nested:
54
+
55
+ - 1
56
+ - 1.1
57
+ - 1.2
58
+ - 1.2.1
59
+ - 2
60
+
61
+ will produce:
62
+
63
+ - 1
64
+ - 1.1
65
+ - 1.2
66
+ - 1.2.1
67
+ - 2
68
+
69
+
70
+ A document can be divided into /chapters/, /subchapters/, and
71
+ /subsubchapters/ by /titles/. A title should be separated with
72
+ preceding and following with a blank line and is marked,
73
+ correspondingly, with a leading [[==]], [[===]], or [[====]]
74
+ together with a following separating space.
75
+
76
+ Furthermore, the document structure can be presented with the
77
+ use of /rubrics/, which correspond to Knuth WEB's /starred
78
+ chunks/. A rubric is marked similarly to a title except with a
79
+ leading [[*]] instead of equal signs. The star must be
80
+ separated from the rubric's name with a space lest the parser
81
+ think it's just a bold text marker. Because rubrics are, if a
82
+ paragraph follows, embedded into the paragraph by Fabricator's
83
+ weaving subsystem, it's a good idea to formulate rubric names as
84
+ full sentences, together with a trailing period or other
85
+ punctuation.
86
+
87
+
88
+ == Chunks and transclusion
89
+
90
+ Each section can contain one or more /chunks/, with the
91
+ following notation:
92
+
93
+ << Chunk name >>:
94
+ Chunk content, possibly on many lines,
95
+ including single blank lines.
96
+
97
+ Note that the declaration must be unindented, and the chunk's
98
+ content must be indented.
99
+
100
+ Some programming languages make use of [[<<]] and [[>>]] for
101
+ other purposes. In order to make the plain Fabricator input
102
+ easy to read, no escaping for double brokets is provided.
103
+ You'll have to structure the input in such a way as to avoid
104
+ false transclusion references.
105
+
106
+
107
+ A chunk can be marked as a /root/ chunk by prepending a
108
+ [[.file]] or [[.script]] to directive, like this:
109
+
110
+ << .script hello.rb >>:
111
+ #! /usr/bin/ruby -rubygems
112
+
113
+ puts "<< Friendly, familiar greeting >>"
114
+
115
+
116
+ The (mechanical) power of literate programming comes from
117
+ /transclusion/, which is notated by adding the target chunk's
118
+ name into another chunk, as seen above.
119
+
120
+ << Friendly, familiar greeting >>:
121
+ Hello, world!
122
+
123
+ It is permitted to define multiple chunks with the same name.
124
+ When the name is referred in a transclusion, all these chunks
125
+ will then be processed, separated with a single blank line.
126
+ In cases when the separating blank line is undesirable, it can
127
+ be suppressed by the [[.dense]] directive:
128
+
129
+ @cat_names = qw(
130
+ << The names of cats .dense >>
131
+ )
132
+
133
+
134
+ Normally, Fabricator obeys indentation in a nested manner. In
135
+ certain cases --- most importantly, the 'here-documents' in
136
+ shell scripts and languages borrowing their notation ---, you
137
+ may want to suppress this. This is achieved by the
138
+ [[.clearindent]] directive:
139
+
140
+ << ... >>:
141
+ module Beast
142
+ DATA = {
143
+ :cows => << .clearindent Cows heredoc >>
144
+ }
145
+
146
+ << Cows heredoc >>:
147
+ << 'END-OF-COWS',
148
+ << Cows >>
149
+ END-OF-COWS
150
+
151
+ The extra wrapper, [[<< Cows heredoc >>]], serves two purposes
152
+ in this example:
153
+
154
+ - It ensures that even the first line of the main transcludee,
155
+ [[<< Cows >>]], follows a linebreak within the effect zone of
156
+ [[.clearindent]]. This is necessary because the directive can
157
+ only clear indentations that exist, and without a linebreak
158
+ there is no indentation to suppress.
159
+
160
+ - It also ensures that the terminating [[END-OF-COWS]] is
161
+ flushed left together with the cows' data, for otherwise the
162
+ target language might not recognise it as the here-doc's
163
+ terminator.
164
+
165
+
166
+ It's often useful to intersperse many chunks of the same name
167
+ with a narrative explaining the actions taken. Mau facilitates
168
+ this via /diversions/. The notation for a diversion is a chunk
169
+ header without the chunk; the subsequent indented blocks ---
170
+ which would otherwise be interpreted as example code --- are
171
+ then treated as chunks of this name. A diversion is effect
172
+ until another diversion replaces it or until a title begins a
173
+ new narrative unit of the document. Note that a rubric does not
174
+ cancel a diversion's effect.
175
+
176
+
177
+ == Postprocessing
178
+
179
+ Fabricator provides experimental support for /postprocessing/
180
+ text constructed using the standard LP transclusion mechanism.
181
+ The notation for this is subject to change in future versions,
182
+ and the available postprocessors are environment-dependent.
183
+
184
+ In the current version, Maui defines two postprocessors related
185
+ to <Sass|http://sass-lang.com>, the preprocessor for CSS. These
186
+ are [[|scss->css]] and [[|sass->css]], and they are invoked by
187
+ attaching their names to the transclusion notation like this:
188
+
189
+ << ... >>:
190
+ ...
191
+ puts << EOS
192
+ Content-type: text/css; charset=UTF-8
193
+
194
+ << stylesheet.sass |sass->css >>
195
+ EOS
196
+ ...
197
+
198
+ << stylesheet.sass >>:
199
+ .footer
200
+ font-size: smaller
201
+
202
+ ...
203
+
204
+ == Invocation
205
+
206
+ Last but not least, the way to run [[maui]] goes like this:
207
+
208
+ $ maui foo.fab
209
+
210
+ By default, this outputs warnings about probable problems with
211
+ the input to the standard error stream and both weaves the input
212
+ into [[foo.html]] and [[foo.ctxt]] as well as tangles all the
213
+ defined roots. It's also possible to specify that only some of
214
+ these files are to be written out, like this:
215
+
216
+ $ maui foo.fab hello.c foo.html
217
+
218
+ Note, however, that Fabricator necessarily tangles everything
219
+ (into core memory) defined in the [[fab]] file while processing
220
+ it, so such a command will not take significantly less runtime
221
+ than a general [[maui]] command. It only suppresses writing the
222
+ unwanted results as files.
@@ -0,0 +1,296 @@
1
+ <!doctype html>
2
+ <html>
3
+ <head>
4
+ <meta http-equiv='Content-type' content='text/html; charset=utf-8' />
5
+ <title>README.fab</title>
6
+ <style type='text/css'>
7
+ /**** Fonts ****/
8
+ @import url("http://fonts.googleapis.com/css?family=Roboto");
9
+ @import url("http://fonts.googleapis.com/css?family=Cousine");
10
+ /**** Rules ****/
11
+ body, .maui-transclude {
12
+ font-family: "Roboto", sans-serif; }
13
+
14
+ pre, tt, code {
15
+ font-family: "Cousine", monospace; }
16
+
17
+ body {
18
+ colour: black;
19
+ background: white; }
20
+
21
+ tt, code {
22
+ color: forestgreen; }
23
+
24
+ .maui-inline-warnings {
25
+ color: red; }
26
+
27
+ .maui-warnings tt {
28
+ color: inherit; }
29
+
30
+ .maui-rubric {
31
+ color: crimson; }
32
+
33
+ ul.maui-warnings {
34
+ padding-left: 0; }
35
+ ul.maui-warnings > li {
36
+ list-style: none; }
37
+
38
+ .maui-chunk-body {
39
+ margin-left: 20px;
40
+ border-left: 2px solid #cccccc;
41
+ padding-left: 5px; }
42
+
43
+ .maui-initial-chunk > .maui-chunk-body:before {
44
+ content: "";
45
+ display: block;
46
+ width: 22px;
47
+ border-top: solid 2px #cccccc;
48
+ margin-left: -27px; }
49
+
50
+ .maui-final-chunk > .maui-chunk-body:after {
51
+ content: "";
52
+ display: block;
53
+ margin-left: -7px;
54
+ width: 40px;
55
+ border-bottom: solid 2px #cccccc; }
56
+
57
+ .maui-chunk-body, .maui-chunk > .maui-warnings {
58
+ margin-top: 0;
59
+ margin-bottom: 0; }
60
+
61
+ .maui-chunk {
62
+ margin-top: 16px;
63
+ margin-bottom: 16px; }
64
+
65
+ .maui-chunk-xref {
66
+ font-size: small;
67
+ font-style: italic;
68
+ margin-left: 22px; }
69
+
70
+ /* Backwards compatibility with pre-HTML5 browsers */
71
+ section {
72
+ display: block; }
73
+ </style>
74
+ </head>
75
+ <body>
76
+
77
+ <h1>README.fab</h1>
78
+ <section class='maui-section' id='S.1'>
79
+
80
+ <p><b class='maui-section-number'>§1.</b> This is Maui, the Mau Independent Fabricator.</p>
81
+
82
+ <p>Fabricator is a literate programming engine with an unobtrusive, wiki-like syntax. Modern Fabricator lives normally inside Mau, a PIM-oriented wiki engine, but Maui makes it available through a command line interface or a Ruby API without requiring a full Mau installation.</p>
83
+
84
+ </section>
85
+
86
+ <h2>Contents</h2>
87
+
88
+
89
+ <ul><li>1. <a href='#T.1'>Inline markup</a></li>
90
+ <li>2. <a href='#T.2'>Narrative structure</a></li>
91
+ <li>3. <a href='#T.3'>Chunks and transclusion</a></li>
92
+ <li>4. <a href='#T.4'>Postprocessing</a></li>
93
+ <li>5. <a href='#T.5'>Invocation</a></li></ul>
94
+
95
+ <h2 id='T.1'>1. Inline markup</h2>
96
+
97
+ <section class='maui-section' id='S.2'>
98
+
99
+ <p><b class='maui-section-number'>§2.</b> Fabricator&apos;s markup can be viewed as a particular wiki markup with literate programming extensions. Here are the inline markup elements:</p>
100
+
101
+ <ul>
102
+ <li><b>Bold</b> text is marked by surrounding stars: <code>*foo*</code></li>
103
+ <li><i>Italic</i> text is marked by surrounding slashes: <code>/foo/</code></li>
104
+ <li><u>Underlined</u> text is marked by surrounding underscores: <code>_foo_</code></li>
105
+ <li><a href='http://www.techterms.com/definition/hyperlink'>Links</a> are marked by surrounding brokets: <code>&lt;link face|URL&gt;</code>. Note that the order of the aspects of the link matches that commonly used in paper encyclopedias rather than that used HTML.</li>
106
+ </ul>
107
+
108
+ </section>
109
+
110
+ <h2 id='T.2'>2. Narrative structure</h2>
111
+
112
+ <section class='maui-section' id='S.3'>
113
+
114
+ <p><b class='maui-section-number'>§3.</b> <i>Paragraphs</i> are separated from each other and other input by blank lines.</p>
115
+
116
+ </section>
117
+
118
+ <section class='maui-section' id='S.4'>
119
+
120
+ <p><b class='maui-section-number'>§4.</b> Two adjacent blank lines separate <i>sections</i>.</p>
121
+
122
+ </section>
123
+
124
+ <section class='maui-section' id='S.5'>
125
+
126
+ <p><b class='maui-section-number'>§5.</b> An indented block of text will be treated as a piece of <i>sample code</i>, like this:</p>
127
+
128
+ <pre class='maui-block'>These lines were indented. Note that a block can contain
129
+ blank lines,
130
+
131
+ but only one at a time. Two consecutive blank lines would be
132
+ parsed as a section break, and the new section would contain a
133
+ new block.</pre>
134
+
135
+ </section>
136
+
137
+ <section class='maui-section' id='S.6'>
138
+
139
+ <p><b class='maui-section-number'>§6.</b></p>
140
+
141
+ <pre class='maui-block'>Like this.</pre>
142
+
143
+ </section>
144
+
145
+ <section class='maui-section' id='S.7'>
146
+
147
+ <p><b class='maui-section-number'>§7.</b> Items in a <i>bullet list</i> are marked by leading dash and space, and can be nested:</p>
148
+
149
+ <pre class='maui-block'>- 1
150
+ - 1.1
151
+ - 1.2
152
+ - 1.2.1
153
+ - 2</pre>
154
+
155
+ <p>will produce:</p>
156
+
157
+ <ul>
158
+ <li>1
159
+ <ul>
160
+ <li>1.1</li>
161
+ <li>1.2
162
+ <ul>
163
+ <li>1.2.1</li>
164
+ </ul>
165
+ </li>
166
+ </ul>
167
+ </li>
168
+ <li>2</li>
169
+ </ul>
170
+
171
+ </section>
172
+
173
+ <section class='maui-section' id='S.8'>
174
+
175
+ <p><b class='maui-section-number'>§8.</b> A document can be divided into <i>chapters</i>, <i>subchapters</i>, and <i>subsubchapters</i> by <i>titles</i>. A title should be separated with preceding and following with a blank line and is marked, correspondingly, with a leading <code>==</code>, <code>===</code>, or <code>====</code> together with a following separating space.</p>
176
+
177
+ <p>Furthermore, the document structure can be presented with the use of <i>rubrics</i>, which correspond to Knuth WEB&apos;s <i>starred chunks</i>. A rubric is marked similarly to a title except with a leading <code>*</code> instead of equal signs. The star must be separated from the rubric&apos;s name with a space lest the parser think it&apos;s just a bold text marker. Because rubrics are, if a paragraph follows, embedded into the paragraph by Fabricator&apos;s weaving subsystem, it&apos;s a good idea to formulate rubric names as full sentences, together with a trailing period or other punctuation.</p>
178
+
179
+ </section>
180
+
181
+ <h2 id='T.3'>3. Chunks and transclusion</h2>
182
+
183
+ <section class='maui-section' id='S.9'>
184
+
185
+ <p><b class='maui-section-number'>§9.</b> Each section can contain one or more <i>chunks</i>, with the following notation:</p>
186
+
187
+ <pre class='maui-block'>&lt;&lt; Chunk name &gt;&gt;:
188
+ Chunk content, possibly on many lines,
189
+ including single blank lines.</pre>
190
+
191
+ <p>Note that the declaration must be unindented, and the chunk&apos;s content must be indented.</p>
192
+
193
+ <p>Some programming languages make use of <code>&lt;&lt;</code> and <code>&gt;&gt;</code> for other purposes. In order to make the plain Fabricator input easy to read, no escaping for double brokets is provided. You&apos;ll have to structure the input in such a way as to avoid false transclusion references.</p>
194
+
195
+ </section>
196
+
197
+ <section class='maui-section' id='S.10'>
198
+
199
+ <p><b class='maui-section-number'>§10.</b> A chunk can be marked as a <i>root</i> chunk by prepending a <code>.file</code> or <code>.script</code> to directive, like this:</p>
200
+
201
+ <pre class='maui-block'>&lt;&lt; .script hello.rb &gt;&gt;:
202
+ #! /usr/bin/ruby -rubygems
203
+
204
+ puts &quot;&lt;&lt; Friendly, familiar greeting &gt;&gt;&quot;</pre>
205
+
206
+ </section>
207
+
208
+ <section class='maui-section' id='S.11'>
209
+
210
+ <p><b class='maui-section-number'>§11.</b> The (mechanical) power of literate programming comes from <i>transclusion</i>, which is notated by adding the target chunk&apos;s name into another chunk, as seen above.</p>
211
+
212
+ <pre class='maui-block'>&lt;&lt; Friendly, familiar greeting &gt;&gt;:
213
+ Hello, world!</pre>
214
+
215
+ <p>It is permitted to define multiple chunks with the same name. When the name is referred in a transclusion, all these chunks will then be processed, separated with a single blank line. In cases when the separating blank line is undesirable, it can be suppressed by the <code>.dense</code> directive:</p>
216
+
217
+ <pre class='maui-block'>@cat_names = qw(
218
+ &lt;&lt; The names of cats .dense &gt;&gt;
219
+ )</pre>
220
+
221
+ </section>
222
+
223
+ <section class='maui-section' id='S.12'>
224
+
225
+ <p><b class='maui-section-number'>§12.</b> Normally, Fabricator obeys indentation in a nested manner. In certain cases --- most importantly, the &apos;here-documents&apos; in shell scripts and languages borrowing their notation ---, you may want to suppress this. This is achieved by the <code>.clearindent</code> directive:</p>
226
+
227
+ <pre class='maui-block'>&lt;&lt; ... &gt;&gt;:
228
+ module Beast
229
+ DATA = {
230
+ :cows =&gt; &lt;&lt; .clearindent Cows heredoc &gt;&gt;
231
+ }
232
+
233
+ &lt;&lt; Cows heredoc &gt;&gt;:
234
+ &lt;&lt; &apos;END-OF-COWS&apos;,
235
+ &lt;&lt; Cows &gt;&gt;
236
+ END-OF-COWS</pre>
237
+
238
+ <p>The extra wrapper, <code>&lt;&lt; Cows heredoc &gt;&gt;</code>, serves two purposes in this example:</p>
239
+
240
+ <ul>
241
+ <li>It ensures that even the first line of the main transcludee, <code>&lt;&lt; Cows &gt;&gt;</code>, follows a linebreak within the effect zone of <code>.clearindent</code>. This is necessary because the directive can only clear indentations that exist, and without a linebreak there is no indentation to suppress.</li>
242
+ <li>It also ensures that the terminating <code>END-OF-COWS</code> is flushed left together with the cows&apos; data, for otherwise the target language might not recognise it as the here-doc&apos;s terminator.</li>
243
+ </ul>
244
+
245
+ </section>
246
+
247
+ <section class='maui-section' id='S.13'>
248
+
249
+ <p><b class='maui-section-number'>§13.</b> It&apos;s often useful to intersperse many chunks of the same name with a narrative explaining the actions taken. Mau facilitates this via <i>diversions</i>. The notation for a diversion is a chunk header without the chunk; the subsequent indented blocks --- which would otherwise be interpreted as example code --- are then treated as chunks of this name. A diversion is effect until another diversion replaces it or until a title begins a new narrative unit of the document. Note that a rubric does not cancel a diversion&apos;s effect.</p>
250
+
251
+ </section>
252
+
253
+ <h2 id='T.4'>4. Postprocessing</h2>
254
+
255
+ <section class='maui-section' id='S.14'>
256
+
257
+ <p><b class='maui-section-number'>§14.</b> Fabricator provides experimental support for <i>postprocessing</i> text constructed using the standard LP transclusion mechanism. The notation for this is subject to change in future versions, and the available postprocessors are environment-dependent.</p>
258
+
259
+ <p>In the current version, Maui defines two postprocessors related to <a href='http://sass-lang.com'>Sass</a>, the preprocessor for CSS. These are <code>|scss-&gt;css</code> and <code>|sass-&gt;css</code>, and they are invoked by attaching their names to the transclusion notation like this:</p>
260
+
261
+ <pre class='maui-block'>&lt;&lt; ... &gt;&gt;:
262
+ ...
263
+ puts &lt;&lt; EOS
264
+ Content-type: text/css; charset=UTF-8
265
+
266
+ &lt;&lt; stylesheet.sass |sass-&gt;css &gt;&gt;
267
+ EOS
268
+ ...
269
+
270
+ &lt;&lt; stylesheet.sass &gt;&gt;:
271
+ .footer
272
+ font-size: smaller
273
+
274
+ ...</pre>
275
+
276
+ </section>
277
+
278
+ <h2 id='T.5'>5. Invocation</h2>
279
+
280
+ <section class='maui-section' id='S.15'>
281
+
282
+ <p><b class='maui-section-number'>§15.</b> Last but not least, the way to run <code>maui</code> goes like this:</p>
283
+
284
+ <pre class='maui-block'>$ maui foo.fab</pre>
285
+
286
+ <p>By default, this outputs warnings about probable problems with the input to the standard error stream and both weaves the input into <code>foo.html</code> and <code>foo.ctxt</code> as well as tangles all the defined roots. It&apos;s also possible to specify that only some of these files are to be written out, like this:</p>
287
+
288
+ <pre class='maui-block'>$ maui foo.fab hello.c foo.html</pre>
289
+
290
+ <p>Note, however, that Fabricator necessarily tangles everything (into core memory) defined in the <code>fab</code> file while processing it, so such a command will not take significantly less runtime than a general <code>maui</code> command. It only suppresses writing the unwanted results as files.</p>
291
+
292
+ </section>
293
+
294
+ </html>
295
+ </body>
296
+ </html>