maui 3.1.0

data/Makefile

@@ -0,0 +1,17 @@
+VERSION = $(shell grep -x -A1 '<< VERSION >>:' maui.fab | \
+    tail +2 | \
+    sed -e 's/^ *//')
+
+all: maui-$(VERSION).tar.gz maui-$(VERSION).gem
+
+maui-$(VERSION).tar.gz: tangle-everything
+	tar czvf $@ `cat Manifest.txt`
+
+maui-$(VERSION).gem: tangle-everything
+	gem build maui.gemspec
+
+.PHONY: tangle-everything
+
+tangle-everything:
+	ruby -Ilib bin/maui maui.fab
+	ruby -Ilib bin/maui README.fab README.html

data/Manifest.txt

@@ -0,0 +1,9 @@
+GPL-3
+Makefile
+Manifest.txt
+README.fab
+README.html
+bin/maui
+lib/mau/fabricator.rb
+maui.fab
+maui.gemspec

data/README.fab

@@ -0,0 +1,222 @@
+This is Maui, the Mau Independent Fabricator.
+
+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.
+
+
+== Inline markup
+
+Fabricator's markup can be viewed as a particular wiki markup
+with literate programming extensions.  Here are the inline
+markup elements:
+
+- *Bold* text is marked by surrounding stars: [[*foo*]]
+
+- /Italic/ text is marked by surrounding slashes: [[/foo/]]
+
+- _Underlined_ text is marked by surrounding underscores:
+  [[_foo_]]
+
+- <Links|http://www.techterms.com/definition/hyperlink> are
+  marked by surrounding brokets: [[<link face|URL>]].  Note that
+  the order of the aspects of the link matches that commonly
+  used in paper encyclopedias rather than that used HTML.
+
+
+== Narrative structure
+
+/Paragraphs/ are separated from each other and other input by
+blank lines.
+
+
+Two adjacent blank lines separate /sections/.
+
+
+An indented block of text will be treated as a piece of /sample
+code/, like this:
+
+  These lines were indented.  Note that a block can contain
+  blank lines,
+
+  but only one at a time.  Two consecutive blank lines would be
+  parsed as a section break, and the new section would contain a
+  new block.
+
+
+  Like this.
+
+
+Items in a /bullet list/ are marked by leading dash and space,
+and can be nested:
+
+  - 1
+    - 1.1
+    - 1.2
+      - 1.2.1
+  - 2
+    
+will produce:
+
+- 1
+  - 1.1
+  - 1.2
+    - 1.2.1
+- 2
+  
+
+A document can be divided into /chapters/, /subchapters/, and
+/subsubchapters/ by /titles/.  A title should be separated with
+preceding and following with a blank line and is marked,
+correspondingly, with a leading [[==]], [[===]], or [[====]]
+together with a following separating space.
+
+Furthermore, the document structure can be presented with the
+use of /rubrics/, which correspond to Knuth WEB's /starred
+chunks/.  A rubric is marked similarly to a title except with a
+leading [[*]] 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.
+
+
+== Chunks and transclusion
+
+Each section can contain one or more /chunks/, with the
+following notation:
+
+  << Chunk name >>:
+    Chunk content, possibly on many lines,
+    including single blank lines.
+
+Note that the declaration must be unindented, and the chunk's
+content must be indented.  
+
+Some programming languages make use of [[<<]] and [[>>]] 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.
+
+
+A chunk can be marked as a /root/ chunk by prepending a
+[[.file]] or [[.script]] to directive, like this:
+
+  << .script hello.rb >>:
+    #! /usr/bin/ruby -rubygems
+
+    puts "<< Friendly, familiar greeting >>"
+
+
+The (mechanical) power of literate programming comes from
+/transclusion/, which is notated by adding the target chunk's
+name into another chunk, as seen above.
+
+  << Friendly, familiar greeting >>:
+    Hello, world!
+
+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 [[.dense]] directive:
+
+  @cat_names = qw(
+    << The names of cats .dense >>
+  )
+
+
+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
+[[.clearindent]] directive:
+
+  << ... >>:
+    module Beast
+      DATA = {
+        :cows => << .clearindent Cows heredoc >>
+      }
+
+  << Cows heredoc >>:
+    << 'END-OF-COWS',
+    << Cows >>
+    END-OF-COWS
+
+The extra wrapper, [[<< Cows heredoc >>]], serves two purposes
+in this example:
+
+- It ensures that even the first line of the main transcludee,
+  [[<< Cows >>]], follows a linebreak within the effect zone of
+  [[.clearindent]].  This is necessary because the directive can
+  only clear indentations that exist, and without a linebreak
+  there is no indentation to suppress.
+
+- It also ensures that the terminating [[END-OF-COWS]] is
+  flushed left together with the cows' data, for otherwise the
+  target language might not recognise it as the here-doc's
+  terminator.
+
+
+It's often useful to intersperse many chunks of the same name
+with a narrative explaining the actions taken.  Mau facilitates
+this via /diversions/.  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.
+
+
+== Postprocessing
+
+Fabricator provides experimental support for /postprocessing/
+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.
+
+In the current version, Maui defines two postprocessors related
+to <Sass|http://sass-lang.com>, the preprocessor for CSS.  These
+are [[|scss->css]] and [[|sass->css]], and they are invoked by
+attaching their names to the transclusion notation like this:
+
+  << ... >>:
+    ...
+    puts << EOS
+      Content-type: text/css; charset=UTF-8
+
+      << stylesheet.sass |sass->css >>
+    EOS
+    ...
+
+  << stylesheet.sass >>:
+    .footer
+      font-size: smaller
+
+    ...
+
+== Invocation
+
+Last but not least, the way to run [[maui]] goes like this:
+
+  $ maui foo.fab
+
+By default, this outputs warnings about probable problems with
+the input to the standard error stream and both weaves the input
+into [[foo.html]] and [[foo.ctxt]] 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:
+
+  $ maui foo.fab hello.c foo.html
+
+Note, however, that Fabricator necessarily tangles everything
+(into core memory) defined in the [[fab]] file while processing
+it, so such a command will not take significantly less runtime
+than a general [[maui]] command.  It only suppresses writing the
+unwanted results as files.

data/README.html

@@ -0,0 +1,296 @@
+<!doctype html>
+<html>
+<head>
+<meta http-equiv='Content-type' content='text/html; charset=utf-8' />
+<title>README.fab</title>
+<style type='text/css'>
+/**** Fonts ****/
+@import url("http://fonts.googleapis.com/css?family=Roboto");
+@import url("http://fonts.googleapis.com/css?family=Cousine");
+/**** Rules ****/
+body, .maui-transclude {
+  font-family: "Roboto", sans-serif; }
+
+pre, tt, code {
+  font-family: "Cousine", monospace; }
+
+body {
+  colour: black;
+  background: white; }
+
+tt, code {
+  color: forestgreen; }
+
+.maui-inline-warnings {
+  color: red; }
+
+.maui-warnings tt {
+  color: inherit; }
+
+.maui-rubric {
+  color: crimson; }
+
+ul.maui-warnings {
+  padding-left: 0; }
+  ul.maui-warnings > li {
+    list-style: none; }
+
+.maui-chunk-body {
+  margin-left: 20px;
+  border-left: 2px solid #cccccc;
+  padding-left: 5px; }
+
+.maui-initial-chunk > .maui-chunk-body:before {
+  content: "";
+  display: block;
+  width: 22px;
+  border-top: solid 2px #cccccc;
+  margin-left: -27px; }
+
+.maui-final-chunk > .maui-chunk-body:after {
+  content: "";
+  display: block;
+  margin-left: -7px;
+  width: 40px;
+  border-bottom: solid 2px #cccccc; }
+
+.maui-chunk-body, .maui-chunk > .maui-warnings {
+  margin-top: 0;
+  margin-bottom: 0; }
+
+.maui-chunk {
+  margin-top: 16px;
+  margin-bottom: 16px; }
+
+.maui-chunk-xref {
+  font-size: small;
+  font-style: italic;
+  margin-left: 22px; }
+
+/* Backwards compatibility with pre-HTML5 browsers */
+section {
+  display: block; }
+</style>
+</head>
+<body>
+
+<h1>README.fab</h1>
+<section class='maui-section' id='S.1'>
+
+<p><b class='maui-section-number'>§1.</b> This is Maui, the Mau Independent Fabricator.</p>
+
+<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>
+
+</section>
+
+<h2>Contents</h2>
+
+
+<ul><li>1. <a href='#T.1'>Inline markup</a></li>
+<li>2. <a href='#T.2'>Narrative structure</a></li>
+<li>3. <a href='#T.3'>Chunks and transclusion</a></li>
+<li>4. <a href='#T.4'>Postprocessing</a></li>
+<li>5. <a href='#T.5'>Invocation</a></li></ul>
+
+<h2 id='T.1'>1. Inline markup</h2>
+
+<section class='maui-section' id='S.2'>
+
+<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>
+
+<ul>
+<li><b>Bold</b> text is marked by surrounding stars: <code>*foo*</code></li>
+<li><i>Italic</i> text is marked by surrounding slashes: <code>/foo/</code></li>
+<li><u>Underlined</u> text is marked by surrounding underscores: <code>_foo_</code></li>
+<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>
+</ul>
+
+</section>
+
+<h2 id='T.2'>2. Narrative structure</h2>
+
+<section class='maui-section' id='S.3'>
+
+<p><b class='maui-section-number'>§3.</b> <i>Paragraphs</i> are separated from each other and other input by blank lines.</p>
+
+</section>
+
+<section class='maui-section' id='S.4'>
+
+<p><b class='maui-section-number'>§4.</b> Two adjacent blank lines separate <i>sections</i>.</p>
+
+</section>
+
+<section class='maui-section' id='S.5'>
+
+<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>
+
+<pre class='maui-block'>These lines were indented.  Note that a block can contain
+blank lines,
+
+but only one at a time.  Two consecutive blank lines would be
+parsed as a section break, and the new section would contain a
+new block.</pre>
+
+</section>
+
+<section class='maui-section' id='S.6'>
+
+<p><b class='maui-section-number'>§6.</b></p>
+
+<pre class='maui-block'>Like this.</pre>
+
+</section>
+
+<section class='maui-section' id='S.7'>
+
+<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>
+
+<pre class='maui-block'>- 1
+  - 1.1
+  - 1.2
+    - 1.2.1
+- 2</pre>
+
+<p>will produce:</p>
+
+<ul>
+<li>1
+<ul>
+<li>1.1</li>
+<li>1.2
+<ul>
+<li>1.2.1</li>
+</ul>
+</li>
+</ul>
+</li>
+<li>2</li>
+</ul>
+
+</section>
+
+<section class='maui-section' id='S.8'>
+
+<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>
+
+<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>
+
+</section>
+
+<h2 id='T.3'>3. Chunks and transclusion</h2>
+
+<section class='maui-section' id='S.9'>
+
+<p><b class='maui-section-number'>§9.</b> Each section can contain one or more <i>chunks</i>, with the following notation:</p>
+
+<pre class='maui-block'>&lt;&lt; Chunk name &gt;&gt;:
+  Chunk content, possibly on many lines,
+  including single blank lines.</pre>
+
+<p>Note that the declaration must be unindented, and the chunk&apos;s content must be indented.</p>
+
+<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>
+
+</section>
+
+<section class='maui-section' id='S.10'>
+
+<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>
+
+<pre class='maui-block'>&lt;&lt; .script hello.rb &gt;&gt;:
+  #! /usr/bin/ruby -rubygems
+
+  puts &quot;&lt;&lt; Friendly, familiar greeting &gt;&gt;&quot;</pre>
+
+</section>
+
+<section class='maui-section' id='S.11'>
+
+<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>
+
+<pre class='maui-block'>&lt;&lt; Friendly, familiar greeting &gt;&gt;:
+  Hello, world!</pre>
+
+<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>
+
+<pre class='maui-block'>@cat_names = qw(
+  &lt;&lt; The names of cats .dense &gt;&gt;
+)</pre>
+
+</section>
+
+<section class='maui-section' id='S.12'>
+
+<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>
+
+<pre class='maui-block'>&lt;&lt; ... &gt;&gt;:
+  module Beast
+    DATA = {
+      :cows =&gt; &lt;&lt; .clearindent Cows heredoc &gt;&gt;
+    }
+
+&lt;&lt; Cows heredoc &gt;&gt;:
+  &lt;&lt; &apos;END-OF-COWS&apos;,
+  &lt;&lt; Cows &gt;&gt;
+  END-OF-COWS</pre>
+
+<p>The extra wrapper, <code>&lt;&lt; Cows heredoc &gt;&gt;</code>, serves two purposes in this example:</p>
+
+<ul>
+<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>
+<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>
+</ul>
+
+</section>
+
+<section class='maui-section' id='S.13'>
+
+<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>
+
+</section>
+
+<h2 id='T.4'>4. Postprocessing</h2>
+
+<section class='maui-section' id='S.14'>
+
+<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>
+
+<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>
+
+<pre class='maui-block'>&lt;&lt; ... &gt;&gt;:
+  ...
+  puts &lt;&lt; EOS
+    Content-type: text/css; charset=UTF-8
+
+    &lt;&lt; stylesheet.sass |sass-&gt;css &gt;&gt;
+  EOS
+  ...
+
+&lt;&lt; stylesheet.sass &gt;&gt;:
+  .footer
+    font-size: smaller
+
+  ...</pre>
+
+</section>
+
+<h2 id='T.5'>5. Invocation</h2>
+
+<section class='maui-section' id='S.15'>
+
+<p><b class='maui-section-number'>§15.</b> Last but not least, the way to run <code>maui</code> goes like this:</p>
+
+<pre class='maui-block'>$ maui foo.fab</pre>
+
+<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>
+
+<pre class='maui-block'>$ maui foo.fab hello.c foo.html</pre>
+
+<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>
+
+</section>
+
+</html>
+</body>
+</html>