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.
- checksums.yaml +7 -0
- data/GPL-3 +674 -0
- data/Makefile +17 -0
- data/Manifest.txt +9 -0
- data/README.fab +222 -0
- data/README.html +296 -0
- data/bin/maui +200 -0
- data/lib/mau/fabricator.rb +2071 -0
- data/maui.fab +3576 -0
- data/maui.gemspec +24 -0
- metadata +59 -0
data/Makefile
ADDED
@@ -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
|
data/Manifest.txt
ADDED
data/README.fab
ADDED
@@ -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.
|
data/README.html
ADDED
@@ -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'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><link face|URL></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'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's name with a space lest the parser think it's just a bold text marker. Because rubrics are, if a paragraph follows, embedded into the paragraph by Fabricator's weaving subsystem, it'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'><< Chunk name >>:
|
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's content must be indented.</p>
|
192
|
+
|
193
|
+
<p>Some programming languages make use of <code><<</code> and <code>>></code> for other purposes. In order to make the plain Fabricator input easy to read, no escaping for double brokets is provided. You'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'><< .script hello.rb >>:
|
202
|
+
#! /usr/bin/ruby -rubygems
|
203
|
+
|
204
|
+
puts "<< Friendly, familiar greeting >>"</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's name into another chunk, as seen above.</p>
|
211
|
+
|
212
|
+
<pre class='maui-block'><< Friendly, familiar greeting >>:
|
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
|
+
<< The names of cats .dense >>
|
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 'here-documents' 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'><< ... >>:
|
228
|
+
module Beast
|
229
|
+
DATA = {
|
230
|
+
:cows => << .clearindent Cows heredoc >>
|
231
|
+
}
|
232
|
+
|
233
|
+
<< Cows heredoc >>:
|
234
|
+
<< 'END-OF-COWS',
|
235
|
+
<< Cows >>
|
236
|
+
END-OF-COWS</pre>
|
237
|
+
|
238
|
+
<p>The extra wrapper, <code><< Cows heredoc >></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><< Cows >></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' data, for otherwise the target language might not recognise it as the here-doc'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'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'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->css</code> and <code>|sass->css</code>, and they are invoked by attaching their names to the transclusion notation like this:</p>
|
260
|
+
|
261
|
+
<pre class='maui-block'><< ... >>:
|
262
|
+
...
|
263
|
+
puts << EOS
|
264
|
+
Content-type: text/css; charset=UTF-8
|
265
|
+
|
266
|
+
<< stylesheet.sass |sass->css >>
|
267
|
+
EOS
|
268
|
+
...
|
269
|
+
|
270
|
+
<< stylesheet.sass >>:
|
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'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>
|