livetext 0.8.2 → 0.8.3

data/README.html

@@ -1,960 +0,0 @@
-<p><center><h2>Livetext: A smart processor for text</h2></center></p>
-
-<p>Livetext is simply a tool for transforming text from one format into another. The source file
-has commands embedded in it, and the output is dependent on those commands.  </p>
-
-<p>Why is this special? It&#39;s very flexible, very extensible, and it&#39;s extensible <i>in Ruby</i>.  </p>
-
-<p><br><br><b><font size=+1>Why Livetext?</font></b><br></p>
-
-<p>Livetext grew out of several motivations. One was a desire for a markup language that would permit
-me to write articles (and even books) in my own way and on my own terms. I&#39;ve done this more
-than once (and I know others who have, as well).   </p>
-
-<p>I liked Softcover, but I found it to be very complex. I never liked Markdown much -- it is very
-dumb and not extensible at all.  </p>
-
-<p>I wanted something that had the basic functionality of all my ad hoc solutions but allowed 
-extensions. Then my old solutions would be like subsets of the new format. This was a generalization
-similar to the way we began several years ago to view HTML as a subset of XML.  </p>
-
-<p><br><br><b><font size=+1>What is Livetext really?</font></b><br></p>
-
-<p>Here goes:
-<ul>
-<li>It&#39;s a text transformer
-</li>
-<li>It&#39;s Ruby-based (later on, more language agnostic)
-</li>
-<li>It&#39;s (potentially) agnostic about output format
-</li>
-<li>It&#39;s designed to be flexible, extensible, and easy
-</li>
-<li>It&#39;s designed to be &quot;plugin&quot; oriented
-</li>
-<li>It&#39;s like an old-fashioned text formatter (but extensible)
-</li>
-<li>It&#39;s like a macro processor (but not)
-</li>
-<li>It&#39;s like markdown and others (but not)
-</li>
-<li>It&#39;s like erb or HAML (but not)
-</li>
-<li>It&#39;s powerful but not too dangerous
-</li>
-<li>It&#39;s not necesarily a markdown replacement
-</li>
-<li>It&#39;s definitely not a softcover replacement
-</li>
-<li>It could possibly augment markdown, softcover, others
-</li>
-</ul></p>
-
-<p><br><br><b><font size=+1>How does it work?</font></b><br></p>
-
-<p>A Livetext file is simply a text file which may have commands interspersed. A command is
-simply a period followed by a name and optional parameters (at the beginning of a line).  </p>
-
-<p>The period is configurable if you want to use another character. The names are (for now)
-actual Ruby method names, so names such as <tt>to_s</tt> and <tt>inspect</tt> are currently not allowed.  </p>
-
-<p>Currently I am mostly emitting &quot;dumb HTML&quot; or Markdown as output. In theory, you can write
-code (or use someone else&#39;s) to manipulate text in any way and output any format. Technically,
-you could even emit PDF, PNG, or SVG formats.</p>
-
-<p>It&#39;s possible to embed comments in the text, or even to pass them through to the output 
-in commented form.  </p>
-
-<p>The command <tt>.end</tt> is special, marking the end of a body of text. Some commands may operate on
-a block of lines rather than just a few parameters. (A text block is like a here-document.)
-There is no method name corresponding to the <tt>.end</tt> command.</p>
-
-<p>The file extension I&#39;ve chosen is <tt>.lt</tt> (though this may change). <b>Note:</b> The source for this 
-README is a <tt>.lt</tt> file which uses its own little <i>ad hoc</i> library (called <tt>readme.rb</tt>). Refer to
-the repo to see these.</p>
-
-<p><br><br><b><font size=+1>Syntax, comments, and more</font></b><br></p>
-
-<p>At first, my idea was to provide predefined commands and allow user-defined commands (to be 
-distinguished by a leading <tt>.</tt> or <tt>..</tt> markers). So the single and double dots are both legal. </p>
-
-<p>However, my concept at present is that the double dots (currently unused) will be used for 
-subcommmands.</p>
-
-<p>User-defined commands may be added to the standard namespace marked with a period. They may
-also be preceded by a specified character other than the period and thus stored in their own
-namespace. More on that later.</p>
-
-<p>When a leading period (or double period) is followed by a space, that line is a comment.
-When it is follwed by a name, that name is typically understood to be a method name. Any 
-remaining text on the line is treated as a parameter list to be accessed by that method.
-Some methods accept multiple lines of text, terminated by a <tt>.end</tt> tag.</p>
-
-<p><br><br><b><font size=+1>Boldface and italics</font></b><br></p>
-
-<p>Very commonly we want to format short words or phrases in italics, boldface, or a monospaced
-(fixed width) font. The Markdown spec provides ways to do this that are fairly intuitive; but I
-personally don&#39;t like them. My own notation works a different way.</p>
-
-<p>First of all, note that these don&#39;t work across source lines; they&#39;re strictly intra-line.
-You may need (for example) an italicized phrase that spans across a newline; at present, you&#39;ll
-need a workaround for that.</p>
-
-<p>I find that most short items I want to format are single tokens. Therefore I use a prefixed
-character in front of such a token: Underscore for italics, asterisk for boldface, and backtick
-for &quot;code font.&quot; The formatting ends when the first blank space is encountered, without any 
-kind of suffixed character. (This behavior may change to include certain punctuation marks as
-terminators.)</p>
-
-<p>Of course, there are cases where this won&#39;t work; a formatted string may contain spaces, or it
-may exclude characters before the blank space. In this case, we can use an opening parenthesis 
-after the prefix and a closing parenthesis at the end of the string.</p>
-
-<p>This means that it can be difficult to include a left paren inside a formatted token. I&#39;m thinking
-about that. It also means that a &quot;literal&quot; prefix character must be escaped.</p>
-
-<p>This is all summarized in this example (taken from one of the testcases):</p>
-
-<p><b>Test: <tt>015_basic_formatting</tt></b><br>
-    <center>
-    <table width=80% cellpadding=4>
-    <tr>
-      <td width=50%><b>Input</b></td>
-      <td width=50%><b>Output</b></td>
-    </tr>
-    <tr>
-      <td width=50% bgcolor=#fec0fe valign=top>
-        <pre> Here are examples of *boldface and _italics and <code>code
- as well as *(more complex) examples of \_(italicized text)
- and</code>(code font).</p>
-
-<p>Here are some random punctuation marks:
- # . @ * _ ` : ; % ^ &amp; $</p>
-
-<p>Oops, forgot to escape these:  * \_ `
-</pre>
-      </td>
-      <td width=50% bgcolor=lightgray valign=top>
-        <pre> Here are examples of <b>boldface</b> and <i>italics</i> and <tt>code</tt>
- as well as <b>more complex</b> examples of <i>italicized text</i>
- and <tt>code font</tt>.</p>
-
-<p>Here are some random punctuation marks:
- # . @ * _ ` : ; % ^ &amp; $</p>
-
-<p>Oops, forgot to escape these:  * _ `
-</pre>
-      </td>
-    </tr>
-    </table>
-    </center></p>
-
-<p><br><br><b><font size=+1>Standard methods</font></b><br></p>
-
-<p>The module <tt>Livetext::Standard</tt> contains the set of standard or predefined methods. Their 
-names are essentially the same as the names of the dot-commands, with occasional exceptions.
-(For example, it is impractical to use the name <tt>def</tt> as a method name, so we use <tt>_def</tt> instead.)
-Here is the current list:</p>
-
-<table>
-<tr>
-<td width=3%><td width=10%> <tt>comment</tt> </td><td> Start a comment block
-</td>
-</tr>
-<tr>
-<td width=3%><td width=10%> <tt>errout</tt> </td><td> Write an error message to STDERR
-</td>
-</tr>
-<tr>
-<td width=3%><td width=10%> <tt>sigil</tt> </td><td> Change the default sigil from <tt>.</tt> to some other character
-</td>
-</tr>
-<tr>
-<td width=3%><td width=10%> <tt>_def</tt> </td><td> Define a new method inline
-</td>
-</tr>
-<tr>
-<td width=3%><td width=10%> <tt>set</tt> </td><td> Assign values to variables for later interpolation
-</td>
-</tr>
-<tr>
-<td width=3%><td width=10%> <tt>include</tt> </td><td> Include an outside text file (to be interpreted as Livetext)
-</td>
-</tr>
-<tr>
-<td width=3%><td width=10%> <tt>mixin</tt> </td><td> Mix this file of Ruby methods into the standard namespace
-</td>
-</tr>
-<tr>
-<td width=3%><td width=10%> <tt>copy</tt> </td><td> Copy this input file verbatim (no interpretation)
-</td>
-</tr>
-<tr>
-<td width=3%><td width=10%> <tt>r</tt> </td><td> Pass a single line through without processing
-</td>
-</tr>
-<tr>
-<td width=3%><td width=10%> <tt>raw</tt> </td><td> Pass this special text block (terminated with <tt>__EOF__</tt>) directly into output without processing 
-</td>
-</tr>
-</table>
-
-<p><br><br><b><font size=+1>Examples from the tests</font></b><br></p>
-
-<p>Here are some tests from the suite. The file name reflects the general purpose of the test.</p>
-
-<p><b>Test: <tt>001_hello_world</tt></b><br>
-    <center>
-    <table width=80% cellpadding=4>
-    <tr>
-      <td width=50%><b>Input</b></td>
-      <td width=50%><b>Output</b></td>
-    </tr>
-    <tr>
-      <td width=50% bgcolor=#fec0fe valign=top>
-        <pre> Hello,
- world!
-</pre>
-      </td>
-      <td width=50% bgcolor=lightgray valign=top>
-        <pre> Hello,
- world!
-</pre>
-      </td>
-    </tr>
-    </table>
-    </center></p>
-
-<p><b>Test: <tt>002_comments_ignored_1</tt></b><br>
-    <center>
-    <table width=80% cellpadding=4>
-    <tr>
-      <td width=50%><b>Input</b></td>
-      <td width=50%><b>Output</b></td>
-    </tr>
-    <tr>
-      <td width=50% bgcolor=#fec0fe valign=top>
-        <pre> . Comments are ignored
- abc 123
- this is a test
- . whether at beginning, middle, or
- more stuff
- still more stuff
- . end of the file
-</pre>
-      </td>
-      <td width=50% bgcolor=lightgray valign=top>
-        <pre> abc 123
- this is a test
- more stuff
- still more stuff
-</pre>
-      </td>
-    </tr>
-    </table>
-    </center></p>
-
-<p><b>Test: <tt>003_comments_ignored_2</tt></b><br>
-    <center>
-    <table width=80% cellpadding=4>
-    <tr>
-      <td width=50%><b>Input</b></td>
-      <td width=50%><b>Output</b></td>
-    </tr>
-    <tr>
-      <td width=50% bgcolor=#fec0fe valign=top>
-        <pre> .. Comments (with a double-dot) are ignored
- abc 123
- this is a test
- .. whether at beginning, middle, or
- more stuff
- still more stuff
- .. end of the file
-</pre>
-      </td>
-      <td width=50% bgcolor=lightgray valign=top>
-        <pre> abc 123
- this is a test
- more stuff
- still more stuff
-</pre>
-      </td>
-    </tr>
-    </table>
-    </center></p>
-
-<p><b>Test: <tt>004_sigil_can_change</tt></b><br>
-    <center>
-    <table width=80% cellpadding=4>
-    <tr>
-      <td width=50%><b>Input</b></td>
-      <td width=50%><b>Output</b></td>
-    </tr>
-    <tr>
-      <td width=50% bgcolor=#fec0fe valign=top>
-        <pre> . This is a comment
- .sigil #
- # Comments are ignored
- abc 123
- this is a test
- . this is not a comment
- # whether at beginning, middle, or
- more stuff
- .this means nothing
- still more stuff
- # end of the file
-</pre>
-      </td>
-      <td width=50% bgcolor=lightgray valign=top>
-        <pre> abc 123
- this is a test
- . this is not a comment
- more stuff
- .this means nothing
- still more stuff
-</pre>
-      </td>
-    </tr>
-    </table>
-    </center></p>
-
-<p><b>Test: <tt>005_block_comment</tt></b><br>
-    <center>
-    <table width=80% cellpadding=4>
-    <tr>
-      <td width=50%><b>Input</b></td>
-      <td width=50%><b>Output</b></td>
-    </tr>
-    <tr>
-      <td width=50% bgcolor=#fec0fe valign=top>
-        <pre> .comment
- This is
- a comment
- .end
- abc 123
- xyz
- .comment
- And so is this.
- .end</p>
-
-<p>one
- more
- time
- .comment
- And so
- is
- this
- .end
-</pre>
-      </td>
-      <td width=50% bgcolor=lightgray valign=top>
-        <pre> abc 123
- xyz</p>
-
-<p>one
- more
- time
-</pre>
-      </td>
-    </tr>
-    </table>
-    </center></p>
-
-<p><b>Test: <tt>006_def_method</tt></b><br>
-    <center>
-    <table width=80% cellpadding=4>
-    <tr>
-      <td width=50%><b>Input</b></td>
-      <td width=50%><b>Output</b></td>
-    </tr>
-    <tr>
-      <td width=50% bgcolor=#fec0fe valign=top>
-        <pre> abc
- 123
- .def foobar
- ::STDERR.puts &quot;This is the&quot;
- ::STDERR.puts &quot;foobar method&quot;
- .end
- xyz
- .foobar
- xyzzy
- 123
-</pre>
-      </td>
-      <td width=50% bgcolor=lightgray valign=top>
-        <pre> abc
- 123
- xyz
- xyzzy
- 123
-</pre>
-      </td>
-    </tr>
-    </table>
-    </center></p>
-
-<p><b>Test: <tt>007_simple_vars</tt></b><br>
-    <center>
-    <table width=80% cellpadding=4>
-    <tr>
-      <td width=50%><b>Input</b></td>
-      <td width=50%><b>Output</b></td>
-    </tr>
-    <tr>
-      <td width=50% bgcolor=#fec0fe valign=top>
-        <pre> Just
- some text.
- .set name=GulliverFoyle,nation=Terra
- Hi, there.
- $name is my name, and $nation is my nation.
- I&#39;m $name, from $nation.
- That&#39;s all.
-</pre>
-      </td>
-      <td width=50% bgcolor=lightgray valign=top>
-        <pre> Just
- some text.
- Hi, there.
- GulliverFoyle is my name, and Terra is my nation.
- I&#39;m GulliverFoyle, from Terra.
- That&#39;s all.
-</pre>
-      </td>
-    </tr>
-    </table>
-    </center></p>
-
-<p><b>Test: <tt>008_simple_include</tt></b><br>
-    <center>
-    <table width=80% cellpadding=4>
-    <tr>
-      <td width=50%><b>Input</b></td>
-      <td width=50%><b>Output</b></td>
-    </tr>
-    <tr>
-      <td width=50% bgcolor=#fec0fe valign=top>
-        <pre> Here I am
- trying to
- include
- .include simplefile.inc
- I hope that
- worked.
-</pre>
-      </td>
-      <td width=50% bgcolor=lightgray valign=top>
-        <pre> Here I am
- trying to
- include
- a simple
- include file.
- I hope that
- worked.
-</pre>
-      </td>
-    </tr>
-    </table>
-    </center></p>
-
-<p><b>Test: <tt>009_simple_mixin</tt></b><br>
-    <center>
-    <table width=80% cellpadding=4>
-    <tr>
-      <td width=50%><b>Input</b></td>
-      <td width=50%><b>Output</b></td>
-    </tr>
-    <tr>
-      <td width=50% bgcolor=#fec0fe valign=top>
-        <pre> Here I am
- testing a simple mixin
- .mixin simple_mixin
- Now call it:
- .hello_world
- That&#39;s all.
-</pre>
-      </td>
-      <td width=50% bgcolor=lightgray valign=top>
-        <pre> Here I am
- testing a simple mixin
- Now call it:
- Hello, world.
- That&#39;s all.
-</pre>
-      </td>
-    </tr>
-    </table>
-    </center></p>
-
-<p><b>Test: <tt>010_simple_copy</tt></b><br>
-    <center>
-    <table width=80% cellpadding=4>
-    <tr>
-      <td width=50%><b>Input</b></td>
-      <td width=50%><b>Output</b></td>
-    </tr>
-    <tr>
-      <td width=50% bgcolor=#fec0fe valign=top>
-        <pre> The copy command
- copies any file
- without interpretation,
- such as:
- .copy simplefile.inc
- That is all.
-</pre>
-      </td>
-      <td width=50% bgcolor=lightgray valign=top>
-        <pre> The copy command
- copies any file
- without interpretation,
- such as:
- a simple
- include file.
- That is all.
-</pre>
-      </td>
-    </tr>
-    </table>
-    </center></p>
-
-<p><b>Test: <tt>011_copy_is_raw</tt></b><br>
-    <center>
-    <table width=80% cellpadding=4>
-    <tr>
-      <td width=50%><b>Input</b></td>
-      <td width=50%><b>Output</b></td>
-    </tr>
-    <tr>
-      <td width=50% bgcolor=#fec0fe valign=top>
-        <pre> A copy command
- does not interpret its input:
- .copy rawtext.inc
- That&#39;s all.
-</pre>
-      </td>
-      <td width=50% bgcolor=lightgray valign=top>
-        <pre> A copy command
- does not interpret its input:
- This is not a comment:
- .comment woohoo!
- This is not a method:
- .no_such_method
- That&#39;s all.
-</pre>
-      </td>
-    </tr>
-    </table>
-    </center></p>
-
-<p><b>Test: <tt>012_raw_text_block</tt></b><br>
-    <center>
-    <table width=80% cellpadding=4>
-    <tr>
-      <td width=50%><b>Input</b></td>
-      <td width=50%><b>Output</b></td>
-    </tr>
-    <tr>
-      <td width=50% bgcolor=#fec0fe valign=top>
-        <pre> This text block will be passed thru
- with no interpretation or processing:
- .raw
- .comment
- This isn&#39;t a
- real comment.
- .end  This isn&#39;t picked up.</p>
-
-<p>.not_a_method</p>
-
-<p>And this stuff won&#39;t be munged: <code>alpha \_beta *gamma
- Or this:</code>(alpha male) _(beta max) *(gamma rays)
- __EOF__</p>
-
-<p>I hope that worked.
-</pre>
-      </td>
-      <td width=50% bgcolor=lightgray valign=top>
-        <pre> This text block will be passed thru
- with no interpretation or processing:
- .comment
- This isn&#39;t a
- real comment.
- .end  This isn&#39;t picked up.</p>
-
-<p>.not_a_method</p>
-
-<p>And this stuff won&#39;t be munged: <code>alpha \_beta *gamma
- Or this:</code>(alpha male) _(beta max) *(gamma rays)</p>
-
-<p>I hope that worked.
-</pre>
-      </td>
-    </tr>
-    </table>
-    </center></p>
-
-<p><br><br><b><font size=+1>Writing custom methods</font></b><br></p>
-
-<p>Suppose you wanted to write a method called <tt>chapter</tt> that would simply
-output a chapter number and title with certain heading tags and a
-horizontal rule following. There is more than one way to do this.</p>
-
-<p>The simplest way is just to define a method inline with the rest of 
-the text. Here&#39;s an example.</p>
-
-<pre>
-     .comment
-     This example shows how to define
-     a simple method &quot;chapter&quot; inline
-     .end
-   
-     . This is also a comment, by the way.
-     .def chapter
-        params = _args
-        raise &quot;chapter: expecting at least two args&quot; unless params.size &gt; 1
-        num, *title = params     # Chapter number + title
-        title = title.join(&quot; &quot;)  # Join all words into one string
-        text = &lt;&lt;-HTML
-        &lt;h3&gt;Chapter #{num}&lt;/h3&gt;
-        &lt;h2&gt;#{title}&lt;/h2&gt;
-        &lt;hr&gt;
-        HTML
-        _puts text
-     .end
-     . Now let&#39;s invoke it...
-     .chapter 1 Why I Went to the Woods
-     It was the best of times, and you can call me Ishmael. The clocks
-     were striking thirteen.
-</pre>
-
-<p>What can we see from this example? First of all, notice that the part
-between <tt>.def</tt> and <tt>.end</tt> (the body of the method) really is just Ruby
-code. The method takes no parameters because parameter passing is 
-handled inside the Livetext engine and the instance variable <tt>@<em>args</tt> is
-initialized to the contents of this array. We usually refer to the
-<tt>@</em>args</tt> array only through the method <tt>_args</tt> which returns it.</p>
-
-<p>The <tt>_args</tt> method is also an iterator. If a block is attached, that block
-will be called for every argument.</p>
-
-<p>We then create a string using these parameters and call it using the
-<tt>_puts</tt> method. This really does do a <tt>puts</tt> call, but it applies it to
-wherever the output is currently being sent (defaulting to STDOUT).</p>
-
-<p>All the &quot;helper&quot; methods start with an underscore so as to avoid name
-collisions. These are all stored in the <tt>Livetext::Helpers</tt> module
-(which also has some methods you will never use).</p>
-
-<p>Here is the HTML output of the previous example:</p>
-
-<pre>
-     &lt;h3&gt;Chapter 1&lt;/h3&gt;
-     &lt;h2&gt;Why I Went to the Woods&lt;/h2&gt;
-     &lt;hr&gt;
-     It was the best of times, and you can call me Ishmael. The clocks
-     were striking thirteen.
-</pre>
-
-<p>What are some other helper methods? Here&#39;s a list.</p>
-
-<table>
-<tr>
-<td width=3%><td width=10%><tt>_args</tt> </td><td> Returns an array of arguments for the method (or an enumerator for that array)
-</td>
-</tr>
-<tr>
-<td width=3%><td width=10%><tt>_data</tt> </td><td> A single "unsplit" string of all arguments in raw form
-</td>
-</tr>
-<tr>
-<td width=3%><td width=10%><tt>_body</tt> </td><td> Returns a string (or enumerator) giving access to the text block (preceding <tt>.end</tt>)
-</td>
-</tr>
-<tr>
-<td width=3%><td width=10%><tt>_puts</tt> </td><td> Write a line to output (STDOUT or wherever)
-</td>
-</tr>
-<tr>
-<td width=3%><td width=10%><tt>_print</tt> </td><td> Write a line to output (STDOUT or wherever) without a newline
-</td>
-</tr>
-<tr>
-<td width=3%><td width=10%><tt>_formatting</tt> </td><td> A function transforming boldface, italics, and monospace (Livetext conventions)
-</td>
-</tr>
-<tr>
-<td width=3%><td width=10%><tt>_var_substitution</tt> </td><td> Substitute variables into a string
-</td>
-</tr>
-<tr>
-<td width=3%><td width=10%><tt>_passthru</tt> </td><td> Feed a line directly into output after transforming and substituting
-</td>
-</tr>
-</table>
-
-<p>Note that the last three methods are typically <i>not</i> called in your own code. They could be,
-but it remains to be seen whether something that advanced is useful.</p>
-
-<p><br><br><b><font size=+1>More examples</font></b><br></p>
-
-<p>Suppose you wanted to take a list of words, more than one per line, and alphabetize them.
-Let&#39;s write a method called <tt>alpha</tt> for that. This exercise and the next one are implemented 
-in the test suite.</p>
-
-<p><b>Test: <tt>013_example_alpha</tt></b><br>
-    <center>
-    <table width=80% cellpadding=4>
-    <tr>
-      <td width=50%><b>Input</b></td>
-      <td width=50%><b>Output</b></td>
-    </tr>
-    <tr>
-      <td width=50% bgcolor=#fec0fe valign=top>
-        <pre> .def alpha
-    text = _body.join
-    text.gsub!(/\n/, &quot; &quot;)
-    words = text.split.sort
-    words.each {|w| _puts &quot;    #{w}&quot; }
- .end
- Here is an alphabetized list:</p>
-
-<p>.alpha
- fishmonger anarchist aardvark glyph gryphon
- halcyon zymurgy mataeotechny zootrope
- pareidolia manicotti quark bellicose anamorphic
- cytology fusillade ectomorph
- .end</p>
-
-<p>I hope that worked.
-</pre>
-      </td>
-      <td width=50% bgcolor=lightgray valign=top>
-        <pre> Here is an alphabetized list:</p>
-
-<pre><code> aardvark
- anamorphic
- anarchist
- bellicose
- cytology
- ectomorph
- fishmonger
- fusillade
- glyph
- gryphon
- halcyon
- manicotti
- mataeotechny
- pareidolia
- quark
- zootrope
- zymurgy
-</code></pre>
-
-<p>I hope that worked.
-</pre>
-      </td>
-    </tr>
-    </table>
-    </center></p>
-
-<p>I&#39;ll let that code stand on its own. Now suppose you wanted to allow columnar output. Let&#39;s
-have the user specify a number of columns (from 1 to 5, defaulting to 1).</p>
-
-<p><b>Test: <tt>014_example_alpha2</tt></b><br>
-    <center>
-    <table width=80% cellpadding=4>
-    <tr>
-      <td width=50%><b>Input</b></td>
-      <td width=50%><b>Output</b></td>
-    </tr>
-    <tr>
-      <td width=50% bgcolor=#fec0fe valign=top>
-        <pre> .def alpha
-    cols = _args.first
-    cols = &quot;1&quot; if cols == &quot;&quot;
-    cols = cols.to_i
-    raise &quot;Columns must be 1-5&quot; unless cols.between?(1,5)
-    text = _body.join
-    text.gsub!(/\n/, &quot; &quot;)
-    words = text.split.sort
-    words.each_slice(cols) do |row|
-      row.each {|w| _print &#39;%-15s&#39; % w }
-      _puts
-    end
- .end
- Here is an alphabetized list:</p>
-
-<p>.alpha 3
- fishmonger anarchist aardvark glyph gryphon
- halcyon zymurgy mataeotechny zootrope
- pareidolia manicotti quark bellicose anamorphic
- cytology fusillade ectomorph
- .end</p>
-
-<p>I hope that worked a second time.
-</pre>
-      </td>
-      <td width=50% bgcolor=lightgray valign=top>
-        <pre> Here is an alphabetized list:</p>
-
-<p>aardvark       anamorphic     anarchist
- bellicose      cytology       ectomorph
- fishmonger     fusillade      glyph
- gryphon        halcyon        manicotti
- mataeotechny   pareidolia     quark
- zootrope       zymurgy</p>
-
-<p>I hope that worked a second time.
-</pre>
-      </td>
-    </tr>
-    </table>
-    </center></p>
-
-<p>What if we wanted to store the code outside the text file? There is more than one way to 
-do this.</p>
-
-<p>Let&#39;s assume we have a file called <tt>mylib.rb</tt> in the same directory as the file we&#39;re processing.
-(Issues such as paths and security have not been addressed yet.) We&#39;ll stick the actual Ruby code
-in here (and nothing else).</p>
-
-<pre>
-   # File: mylib.rb
-   
-   def alpha
-     cols = _args.first
-     cols = &quot;1&quot; if cols == &quot;&quot;
-     cols = cols.to_i
-     raise &quot;Columns must be 1-5&quot; unless cols.between?(1,5)
-     text = _body.join
-     text.gsub!(/\n/, &quot; &quot;)
-     words = text.split.sort
-     words.each_slice(cols) do |row| 
-       row.each {|w| _print &#39;%-15s&#39; % w }
-       _puts 
-     end
-   end
-</pre>
-
-<p>Now the <tt>.lt</tt> file can be written this way:</p>
-
-<pre>
-    .mixin mylib
-    Here is an alphabetized list:
-   
-    .alpha 3
-    fishmonger anarchist aardvark glyph gryphon
-    halcyon zymurgy mataeotechny zootrope
-    pareidolia manicotti quark bellicose anamorphic
-    cytology fusillade ectomorph
-    .end
-   
-    I hope that worked a second time.
-</pre>
-
-<p>The output, of course, is the same.</p>
-
-<p>There is an important feature that has not yet been implemented (the
-<tt>require</tt> method). Like Ruby&#39;s <tt>require</tt>, it will grab Ruby code and 
-load it; however, unlike <tt>mixin</tt>, it will load it into a customized
-object and associate a new sigil with it. So for example, the command
-<tt>.foobar</tt> would refer to a method in the <tt>Livetext::Standard</tt> class 
-(whether predefined or user-defined). If we did a <tt>require</tt> on a file
-and associated the sigil <tt>#</tt> with it, then <tt>#foobar</tt> would be a method
-on that new custom object. I will implement this soon.</p>
-
-<p><br><br><b><font size=+1>Issues, open questions, and to-do items</font></b><br></p>
-
-<p>This list is not prioritized yet.</p>
-
-<ol>
-<li>Add versioning information 
-</li>
-<li>Clean up code structure
-</li>
-<li>Add RDoc
-</li>
-<li>Think about command line executable
-</li>
-<li>Write as pure library in addition to executable
-</li>
-<li>Package as gem
-</li>
-<li>Document: <tt>require</tt> `include <tt>copy</tt> `mixin <tt>errout</tt> and others
-</li>
-<li>Need much better error checking and corresponding tests
-</li>
-<li>Worry about nesting of elements (probably mostly disallow)
-</li>
-<li>Think about UTF-8
-</li>
-<li>Document API fully
-</li>
-<li>Add <tt>_raw_args</tt> and let <tt>_args</tt> honor quotes
-</li>
-<li>Support quotes in <tt>.set</tt> values
-</li>
-<li>Support "namespaced" variables  (`(.set code.font="whatever"))
-</li>
-<li>Support functions (`($$func)) including namespacing
-</li>
-<li>Create predefined variables and functions (e.g., <tt>$_source_file</tt>, <tt>$(_line),</tt> <tt>$$_today</tt>)
-</li>
-<li>Support markdown-style bold/italics? (`_markdown replaces <tt>_formatting</tt> method)
-</li>
-<li>Allow turning on/off: formatting, variable interpolation, function interpolation?
-</li>
-<li><tt>.require</tt> with file and sigil parameters
-</li>
-<li>Comments passed through (e.g. as HTML comments)
-</li>
-<li><tt>.run</tt> to execute arbitrary Ruby code inline?
-</li>
-<li>Concept of <tt>.proc</tt> (guaranteed to return no value, produce no output)?
-</li>
-<li>Exceptions??
-</li>
-<li>Ruby <tt>$SAFE</tt> levels?
-</li>
-<li>Warn when overriding existing names?
-</li>
-<li>Think about passing data in (erb replacement)
-</li>
-<li>Allow custom ending tag on <tt>raw</tt> method
-</li>
-<li>Ignore first blank line after <tt>.end</tt>? (and after raw-tag?)
-</li>
-<li>Allow/encourage custom <tt>passthru</tt> method?
-</li>
-<li>Must have sane support for CSS
-</li>
-<li>Support for Pygments and/or other code processors
-</li>
-<li>Support for gists? arbitrary links? other remote resouces?
-</li>
-<li>Small libraries for special purposes (books? special Softcover support? blogs? PDF? RMagick?)
-</li>
-<li>Experiment with idea of special libraries having pluggable output formats (via Ruby mixin?)
-</li>
-<li>Imagining a lib that can run/test code fragments as part of document generation
-</li>
-<li>Create vim (emacs?) syntax files
-</li>
-<li>Someday: Support other languages (Elixir, Python, ...)
-</li>
-<li><tt>.pry</tt> method?
-</li>
-<li><tt>.irb</tt> method?
-</li>
-<li>Other debugging features
-</li>
-<li>Feature to "break" to EOF?
-</li>
-<li><tt>.meth?</tt> method ending in <tt>?</tt> takes a block that may be processed or thrown away (`(.else) perhaps?)
-</li>
-<li><tt>.dump</tt> to dump all variables and their values
-</li>
-<li><tt>.if</tt> and <tt>.else</tt>?
-</li>
-<li>Make any/all delimiters configurable
-</li>
-<li>HTML helper? (in their own library?)
-</li>
-</ol>