livetext 0.8.1 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 61fc8530a13b32edfcc6701ad7f3b7a439454008
-  data.tar.gz: 6fc9806e07131c1c7ea6e8988c0f14a6695b08b3
+  metadata.gz: fd50a45d248673a1629b46e3f46684f7c505fa35
+  data.tar.gz: 3368732003a8e8b006c5b46a5370dc6b5f71fa1b
 SHA512:
-  metadata.gz: 242cd19f6051338d664968e086ac6d58d9df152e6938592bd7247e5752aa702818ccddf1c820824f6016061f15a3bd1d8a9d3e2e12215f6774f242839bd458df
-  data.tar.gz: a3b5278186da25bfd72beae900569b2df4d1d964ae122ee30f93b5c594554329cd634346350f5d9a22ee41850d5d72626032936423fa42d278d5ff348e952302
+  metadata.gz: 9ae32de005cb4b5339b2efdf8e1c1a346fee048c6431080ffa74d8b6590f8cb5f296ef0fb3878840232e23a232175d5f1a418826656e538d48d2bb7aa7b48e92
+  data.tar.gz: dab5779af0d426f72947c939fbabf6375ada785204a54daa97ee4c102d7765d3c71940bd1a3294f62f259f707a4bd8467defc60335546f7e274894de45179931

data/README.ltx

@@ -1,10 +1,14 @@
-.mixin dsl/tutorial
+.mixin tutorial
+.mixin markdown
+
 .title Livetext: A smart processor for text
 
+*[This README is currently mangled. Fixes coming soon!]
+
 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.  
 
-Why is this special? It's very flexible, very extensible, and it's extensible _(in Ruby).  
+Why is this special? It's very flexible, very extensible, and it's extensible _[in Ruby].  
 
 .section Why Livetext?
 
@@ -12,10 +16,11 @@ Livetext grew out of several motivations. One was a desire for a markup language
 me to write articles (and even books) in my own way and on my own terms. I've done this more
 than once (and I know others who have, as well).   
 
-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.  
+I liked Softcover, but I found it to be very complex. I never liked Markdown much -- I find it very
+dumb, and it's not extensible at all. (In fairness to Markdown, it does serve a different purpose
+in everyday life.)
 
-I wanted something that had the basic functionality of all my ad hoc solutions but allowed 
+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.  
 
@@ -52,33 +57,34 @@ you could even emit PDF, PNG, or SVG formats.
 
 . Idea: Make an RMagick DSL as an example.
 
-It's possible to embed comments in the text, or even to pass them through to the output 
-in commented form.  
+It's possible to embed comments in the text. Later it will be possible  to pass 
+them through to the output in commented form.  
 
 The command `.end 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 `.end command.
 
 The file extension I've chosen is `.ltx (though this may change). *Note: The source for this 
-README is a `.ltx file which uses its own little _(ad hoc) library (called `(readme.rb)). Refer to
+README is a `.ltx file which uses its own little _[ad hoc] library (called ``tutorial.rb). Refer to
 the repo to see these.
 
 .section Syntax, comments, and more
 
 At first, my idea was to provide predefined commands and allow user-defined commands (to be 
-distinguished by a leading `. or `.. markers). So the single and double dots are both legal. 
+distinguished by a leading `. or `.. marker). So the single and double dots were both legal. 
 
-However, my concept at present is that the double dots (currently unused) will be used for 
+However, my concept at present is that the double dots (currently unused) may be used for 
 subcommmands.
 
-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.
+User-defined commands may be added to the standard namespace. There are plans to 
+permit commands beginning with a specified character other than the period (to 
+be stored in their own namespace.
 
-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 `.end tag.
+When a leading 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 a text block (multiple lines of text terminated by 
+a `.end tag).
 
 .section Boldface and italics
 
@@ -93,17 +99,25 @@ need a workaround for that.
 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 "code font." 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.)
+kind of suffixed character. 
+
+I also find it's common to want to terminate such a string with some kind of 
+naturally-occurring punctuation mark. If we double the initial delimiter, it 
+will be understood to terminate at the first period, comma, or right parenthesis.
 
 Of course, there are cases where this won'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.
+may exclude characters before the blank space. In this case, we can use an opening bracket
+after the prefix and a closing bracket at the end of the string.
+
+This means that it can be difficult to include brackets inside a formatted token. The solution
+is simply to escape with a backslash.
 
-This means that it can be difficult to include a left paren inside a formatted token. I'm thinking
-about that. It also means that a "literal" prefix character must be escaped.
+A delimiter character sitting by itself need not be escaped. It will be output as a literal.
 
-This is all summarized in this example (taken from one of the testcases):
+A delimiter character that is already inside another string need not be escaped. These cannot
+be nested (though there is a way to accomplish this using functions).
+
+Most of this is summarized in this example (taken from one of the testcases):
 
 .testcase basic_formatting
 
@@ -111,28 +125,28 @@ This is all summarized in this example (taken from one of the testcases):
 
 The module `Livetext::Standard 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 `def as a method name, so we use `_def instead.)
-Here is the current list:
-
-.dlist
- `comment ~~ Start a comment block
- `errout ~~ Write an error message to STDERR
- `def ~~ Define a new method inline
- `set ~~ Assign values to variables for later interpolation
- `include ~~ Include an outside text file (to be interpreted as Livetext)
- `mixin ~~ Mix this file of Ruby methods into the standard namespace
- `copy ~~ Copy this input file verbatim (no interpretation)
- `r ~~ Pass a single line through without processing
- `raw ~~ Pass this special text block (terminated with `(__EOF__)) directly into output without processing 
-`func ~~ Define a function to be invoked inline
-`say ~~ Print a message to the screen
-`banner ~~ Print a "noticeable" message to the screen
-`quit ~~ End processing and exit
-`nopass ~~ Don't pass lines through (just honor commands)
-`include ~~ Read and process another file (typically a `.ltx file)
-`debug ~~ Turn on debugging
-`nopara ~~ Turn off the "blank line implies new paragraph" switch
-`newpage ~~ Start a new output page
+(For example, it is impractical to use the name `def as a method name, so the module has a
+`_def method instead.) Here is the current list:
+
+.dlist %%
+ `comment   %% Start a comment block
+ `errout    %% Write an error message to STDERR
+ `def       %% Define a new method inline
+ `set       %% Assign values to variables for later interpolation
+ `include   %% Include an outside text file (to be interpreted as Livetext)
+ `mixin     %% Mix this file of Ruby methods into the standard namespace
+ `copy      %% Copy this input file verbatim (no interpretation)
+ `r         %% Pass a single line through without processing
+ `raw       %% Pass this special text block (terminated with ``__EOF__) directly into output without processing 
+`func       %% Define a function to be invoked inline
+`say        %% Print a message to the screen
+`banner     %% Print a "noticeable" message to the screen
+`quit       %% End processing and exit
+`nopass     %% Don't pass lines through (just honor commands)
+`include    %% Read and process another file (typically a `.ltx file)
+`debug      %% Turn on debugging
+`nopara     %% Turn off the "blank line implies new paragraph" switch
+`newpage    %% Start a new output page
 .end
 
 .section Examples from the tests
@@ -199,7 +213,7 @@ We then create a string using these parameters and call it using the
 wherever the output is currently being sent (defaulting to STDOUT).
 
 All the "helper" methods start with an underscore so as to avoid name
-collisions. These are all stored in the `Livetext::Helpers module
+collisions. These are all stored in the `Livetext::UserAPI module
 (which also has some methods you will never use).
 
 Here is the HTML output of the previous example:
@@ -215,14 +229,13 @@ Here is the HTML output of the previous example:
 What are some other helper methods? Here's a list.
 
 .dlist
-`_args ~~ Returns an array of arguments for the method (or an enumerator for that array)
-`_data ~~ A single "unsplit" string of all arguments in raw form
-`_body ~~ Returns a string (or enumerator) giving access to the text block (preceding `(.end))
-`_puts ~~ Write a line to output (STDOUT or wherever)
-`_print ~~ Write a line to output (STDOUT or wherever) without a newline
-`_formatting ~~ A function transforming boldface, italics, and monospace (Livetext conventions)
-`_var_substitution ~~ Substitute variables into a string
-`_passthru ~~ Feed a line directly into output after transforming and substituting
+`_args       %% Returns an array of arguments for the method (or an enumerator for that array)
+`_data       %% A single "unsplit" string of all arguments in raw form
+`_body       %% Returns a string (or enumerator) giving access to the text block (preceding ``.end)
+`_puts       %% Write a line to output (STDOUT or wherever)
+`_print      %% Write a line to output (STDOUT or wherever) without a newline
+`_formatting %% A function transforming boldface, italics, and monospace (Livetext conventions)
+`_passthru   %% Feed a line directly into output after transforming and substituting
 .end
 
 Note that the last three methods are typically _not called in your own code. They could be,
@@ -285,36 +298,38 @@ Now the `.ltx file can be written this way:
 The output, of course, is the same.
 
 There is an important feature that has not yet been implemented (the
-`require method). Like Ruby's `(require), it will grab Ruby code and 
-load it; however, unlike `(mixin), it will load it into a customized
+`require method). Like Ruby's ``require, it will grab Ruby code and 
+load it; however, unlike ``mixin, it will load it into a customized
 object and associate a new sigil with it. So for example, the command
 `.foobar would refer to a method in the `Livetext::Standard class 
 (whether predefined or user-defined). If we did a `require on a file
 and associated the sigil `# with it, then `#foobar would be a method
-on that new custom object. I will implement this soon.
+on that new custom object. I plan to implement this later.
 
 .section Issues, open questions, and to-do items
 
 This list is not prioritized yet.
 
 .nlist
-Add versioning information 
-Clean up code structure
+~[Add versioning information 
+~[Clean up code structure
 Add RDoc
-Think about command line executable
-Write as pure library in addition to executable
-Package as gem
+~[Think about command line executable
+~[Write as pure library in addition to executable
+~[Package as gem
 Document: `require `include `copy `mixin `errout and others
-Need much better error checking and corresponding tests
+Need ~much better error checking and corresponding tests
 Worry about nesting of elements (probably mostly disallow)
 Think about UTF-8
 Document API fully
 Add `_raw_args and let `_args honor quotes
 Support quotes in `.set values
-Support "namespaced" variables  (`(.set code.font="whatever"))
-Support functions (`($$func)) including namespacing
-Create predefined variables and functions (e.g., `($_source_file), `$(_line), `($$_today))
-Support markdown-style bold/italics? (`_markdown replaces `_formatting method)
+Support "namespaced" variables  (`[.set code.font="whatever"])
+~[Support functions (``$$func) 
+Support function namespacing
+Create predefined variables (e.g., `[$_source_file], `$[_line])
+Create predefined functions (e.g., `[$$_date])
+More support for markdown
 Allow turning on/off: formatting, variable interpolation, function interpolation?
 `.require with file and sigil parameters
 Investigate "common intermediate format" - output renderers all read it
@@ -325,8 +340,8 @@ Exceptions??
 Ruby `$SAFE levels?
 Warn when overriding existing names?
 Think about passing data in (erb replacement)
-Allow custom ending tag on `raw method
-Ignore first blank line after `(.end)? (and after raw-tag?)
+~]Allow custom ending tag on `raw method
+~[Ignore first blank line after `[.end]? (and after raw-tag?)
 Allow/encourage custom `passthru method?
 Must have sane support for CSS
 Support for Pygments and/or other code processors
@@ -340,9 +355,9 @@ Someday: Support other languages (Elixir, Python, ...)
 `.irb method?
 Other debugging features
 Feature to "break" to EOF?
-`.meth? method ending in `? takes a block that may be processed or thrown away (`(.else) perhaps?)
+`.meth? method ending in `? takes a block that may be processed or thrown away (`.else perhaps?)
 `.dump to dump all variables and their values
-`.if and `(.else)?
+`.if and `[.else]?
 Make any/all delimiters configurable
 HTML helper? (in their own library?)
 .end

data/README.md

@@ -1,123 +1,151 @@
-<center><h2>Livetext: A smart processor for text</h2></center>
+# Livetext: A smart processor for text
+<p>
+
+<b>This README is currently mangled. Fixes coming soon!</b>
+<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>
 
 Why is this special? It's very flexible, very extensible, and it's extensible <i>in Ruby</i>.  
+<p>
 
-<br><br><b><font size=+1>Why Livetext?</font></b><br>
+### Why Livetext?
+<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've done this more
 than once (and I know others who have, as well).   
+<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.  
+I liked Softcover, but I found it to be very complex. I never liked Markdown much -- I find it very
+dumb, and it's not extensible at all. (In fairness to Markdown, it does serve a different purpose
+in everyday life.)
+<p>
 
-I wanted something that had the basic functionality of all my ad hoc solutions but allowed 
+I wanted something that had the basic functionality of all my <i>ad hoc</i> 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>
 
-<br><br><b><font size=+1>What is Livetext really?</font></b><br>
+### What is Livetext really?
+<p>
 
 Here goes:
-<ul>
-<li>It's a text transformer
-</li>
-<li>It's Ruby-based (later on, more language agnostic)
-</li>
-<li>It's (potentially) agnostic about output format
-</li>
-<li>It's designed to be flexible, extensible, and easy
-</li>
-<li>It's designed to be "plugin" oriented
-</li>
-<li>It's like an old-fashioned text formatter (but extensible)
-</li>
-<li>It's like a macro processor (but not)
-</li>
-<li>It's like markdown and others (but not)
-</li>
-<li>It's like erb or HAML (but not)
-</li>
-<li>It's powerful but not too dangerous
-</li>
-<li>It's not necesarily a markdown replacement
-</li>
-<li>It's definitely not a softcover replacement
-</li>
-<li>It could possibly augment markdown, softcover, others
-</li>
-</ul>
-
-<br><br><b><font size=+1>How does it work?</font></b><br>
+ * It's a text transformer
+ * It's Ruby-based (later on, more language agnostic)
+ * It's (potentially) agnostic about output format
+ * It's designed to be flexible, extensible, and easy
+ * It's designed to be "plugin" oriented
+ * It's like an old-fashioned text formatter (but extensible)
+ * It's like a macro processor (but not)
+ * It's like markdown and others (but not)
+ * It's like erb or HAML (but not)
+ * It's powerful but not too dangerous
+ * It's not necesarily a markdown replacement
+ * It's definitely not a softcover replacement
+ * It could possibly augment markdown, softcover, others
+### How does it work?
+<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>
 
-The period is configurable if you want to use another character. The names are (for now)
+The period will be configurable later 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>
 
-Currently I am mostly emitting "dumb HTML" or Markdown as output. In theory, you can write
+At present, I am mostly emitting "dumb HTML" or Markdown as output. In theory, you can write
 code (or use someone else's) to manipulate text in any way and output any format. Technically,
 you could even emit PDF, PNG, or SVG formats.
+<p>
 
+<p>
 
-It's possible to embed comments in the text, or even to pass them through to the output 
-in commented form.  
+It's possible to embed comments in the text. Later it will be possible  to pass 
+them through to the output in commented form.  
+<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>
 
-The file extension I'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 file extension I've chosen is <tt>.ltx</tt> (though this may change). <b>Note:</b> The source for this 
+README is a <tt>.ltx</tt> file which uses its own little <i>ad hoc</i> library (called <tt>tutorial</tt>.rb). Refer to
 the repo to see these.
+<p>
 
-<br><br><b><font size=+1>Syntax, comments, and more</font></b><br>
+### Syntax, comments, and more
+<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. 
+distinguished by a leading <tt>.</tt> or <tt>..</tt> marker). So the single and double dots were both legal. 
+<p>
 
-However, my concept at present is that the double dots (currently unused) will be used for 
+However, my concept at present is that the double dots (currently unused) may be used for 
 subcommmands.
+<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.
+User-defined commands may be added to the standard namespace. There are plans to 
+permit commands beginning with a specified character other than the period (to 
+be stored in their own namespace.
+<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.
+When a leading 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 a text block (multiple lines of text terminated by 
+a <tt>.end</tt> tag).
+<p>
 
-<br><br><b><font size=+1>Boldface and italics</font></b><br>
+### Boldface and italics
+<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't like them. My own notation works a different way.
+<p>
 
 First of all, note that these don't work across source lines; they're strictly intra-line.
 You may need (for example) an italicized phrase that spans across a newline; at present, you'll
 need a workaround for that.
+<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 "code font." 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.)
+kind of suffixed character. 
+<p>
+
+I also find it's common to want to terminate such a string with some kind of 
+naturally-occurring punctuation mark. If we double the initial delimiter, it 
+will be understood to terminate at the first period, comma, or right parenthesis.
+<p>
 
 Of course, there are cases where this won'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.
+may exclude characters before the blank space. In this case, we can use an opening bracket
+after the prefix and a closing bracket at the end of the string.
+<p>
+
+This means that it can be difficult to include brackets inside a formatted token. The solution
+is simply to escape with a backslash.
+<p>
 
-This means that it can be difficult to include a left paren inside a formatted token. I'm thinking
-about that. It also means that a "literal" prefix character must be escaped.
+A delimiter character sitting by itself need not be escaped. It will be output as a literal.
+<p>
 
-This is all summarized in this example (taken from one of the testcases):
+A delimiter character that is already inside another string need not be escaped. These cannot
+be nested (though there is a way to accomplish this using functions).
+<p>
 
+Most of this is summarized in this example (taken from one of the testcases):
+<p>
 
-<b>Test: <tt>015\_basic\_formatting</tt></b><br>
+
+<font size=+1><b>Test: </font><font size=+2><tt>basic_formatting</tt></font></b></h3><br>
     <center>
     <table width=80% cellpadding=4>
     <tr>
@@ -127,86 +155,107 @@ This is all summarized in this example (taken from one of the testcases):
     <tr>
       <td width=50% bgcolor=#fec0fe valign=top>
         <pre> Here are examples of *boldface and \_italics and `code
- as well as *(more complex) examples of \_(italicized text)
- and `(code font).
+ as well as *[more complex] examples of \_[italicized text]
+ and `[code font].
  
  Here are some random punctuation marks:
  # . @ * \_ ` : ; % ^ & $
  
- Oops, forgot to escape these:  \* \\_ \`
+ No need 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>
  
  Here are some random punctuation marks:
  # . @ * \_ ` : ; % ^ & $
+ <p>
  
- Oops, forgot to escape these:  * \_ `
+ No need to escape these:  * \_ `
 </pre>
       </td>
     </tr>
     </table>
     </center>
+<br>
+<p>
 
-<br><br><b><font size=+1>Standard methods</font></b><br>
+### Standard methods
+<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:
+(For example, it is impractical to use the name <tt>def</tt> as a method name, so the module has a
+<tt>_def</tt> method 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>
+<td width=3%><td width=10%> <tt>comment</tt>   %% Start a comment block</td><td></td>
+</tr>
+<tr>
+<td width=3%><td width=10%> <tt>errout</tt>    %% Write an error message to STDERR</td><td></td>
+</tr>
+<tr>
+<td width=3%><td width=10%> <tt>def</tt>       %% Define a new method inline</td><td></td>
+</tr>
+<tr>
+<td width=3%><td width=10%> <tt>set</tt>       %% Assign values to variables for later interpolation</td><td></td>
+</tr>
+<tr>
+<td width=3%><td width=10%> <tt>include</tt>   %% Include an outside text file (to be interpreted as Livetext)</td><td></td>
+</tr>
+<tr>
+<td width=3%><td width=10%> <tt>mixin</tt>     %% Mix this file of Ruby methods into the standard namespace</td><td></td>
 </tr>
 <tr>
-<td width=3%><td width=10%> <tt>errout</tt> </td><td> Write an error message to STDERR
-</td>
+<td width=3%><td width=10%> <tt>copy</tt>      %% Copy this input file verbatim (no interpretation)</td><td></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>
+<td width=3%><td width=10%> <tt>r</tt>         %% Pass a single line through without processing</td><td></td>
 </tr>
 <tr>
-<td width=3%><td width=10%> <tt>_def</tt> </td><td> Define a new method inline
-</td>
+<td width=3%><td width=10%> <tt>raw</tt>       %% Pass this special text block (terminated with <tt>__EOF__</tt>) directly into output without processing </td><td></td>
 </tr>
 <tr>
-<td width=3%><td width=10%> <tt>set</tt> </td><td> Assign values to variables for later interpolation
-</td>
+<td width=3%><td width=10%><tt>func</tt>       %% Define a function to be invoked inline</td><td></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>
+<td width=3%><td width=10%><tt>say</tt>        %% Print a message to the screen</td><td></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>
+<td width=3%><td width=10%><tt>banner</tt>     %% Print a "noticeable" message to the screen</td><td></td>
 </tr>
 <tr>
-<td width=3%><td width=10%> <tt>copy</tt> </td><td> Copy this input file verbatim (no interpretation)
-</td>
+<td width=3%><td width=10%><tt>quit</tt>       %% End processing and exit</td><td></td>
 </tr>
 <tr>
-<td width=3%><td width=10%> <tt>r</tt> </td><td> Pass a single line through without processing
-</td>
+<td width=3%><td width=10%><tt>nopass</tt>     %% Don't pass lines through (just honor commands)</td><td></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>
+<td width=3%><td width=10%><tt>include</tt>    %% Read and process another file (typically a <tt>.ltx</tt> file)</td><td></td>
+</tr>
+<tr>
+<td width=3%><td width=10%><tt>debug</tt>      %% Turn on debugging</td><td></td>
+</tr>
+<tr>
+<td width=3%><td width=10%><tt>nopara</tt>     %% Turn off the "blank line implies new paragraph" switch</td><td></td>
+</tr>
+<tr>
+<td width=3%><td width=10%><tt>newpage</tt>    %% Start a new output page</td><td></td>
 </tr>
 </table>
-
-<br><br><b><font size=+1>Examples from the tests</font></b><br>
+### Examples from the tests
+<p>
 
 Here are some tests from the suite. The file name reflects the general purpose of the test.
+<p>
 
 
-<b>Test: <tt>001\_hello\_world</tt></b><br>
+<font size=+1><b>Test: </font><font size=+2><tt>hello_world</tt></font></b></h3><br>
     <center>
     <table width=80% cellpadding=4>
     <tr>
@@ -227,8 +276,9 @@ Here are some tests from the suite. The file name reflects the general purpose o
     </tr>
     </table>
     </center>
+<br>
 
-<b>Test: <tt>002\_comments\_ignored\_1</tt></b><br>
+<font size=+1><b>Test: </font><font size=+2><tt>comments_ignored_1</tt></font></b></h3><br>
     <center>
     <table width=80% cellpadding=4>
     <tr>
@@ -256,72 +306,9 @@ Here are some tests from the suite. The file name reflects the general purpose o
     </tr>
     </table>
     </center>
+<br>
 
-<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>
-
-<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>
-
-<b>Test: <tt>005\_block\_comment</tt></b><br>
+<font size=+1><b>Test: </font><font size=+2><tt>block_comment</tt></font></b></h3><br>
     <center>
     <table width=80% cellpadding=4>
     <tr>
@@ -348,12 +335,12 @@ Here are some tests from the suite. The file name reflects the general purpose o
  is
  this
  .end
+ 
 </pre>
       </td>
       <td width=50% bgcolor=lightgray valign=top>
         <pre> abc 123
  xyz
- 
  one
  more
  time
@@ -362,8 +349,9 @@ Here are some tests from the suite. The file name reflects the general purpose o
     </tr>
     </table>
     </center>
+<br>
 
-<b>Test: <tt>006\_def\_method</tt></b><br>
+<font size=+1><b>Test: </font><font size=+2><tt>def_method</tt></font></b></h3><br>
     <center>
     <table width=80% cellpadding=4>
     <tr>
@@ -395,8 +383,9 @@ Here are some tests from the suite. The file name reflects the general purpose o
     </tr>
     </table>
     </center>
+<br>
 
-<b>Test: <tt>007\_simple\_vars</tt></b><br>
+<font size=+1><b>Test: </font><font size=+2><tt>simple_vars</tt></font></b></h3><br>
     <center>
     <table width=80% cellpadding=4>
     <tr>
@@ -426,8 +415,9 @@ Here are some tests from the suite. The file name reflects the general purpose o
     </tr>
     </table>
     </center>
+<br>
 
-<b>Test: <tt>008\_simple\_include</tt></b><br>
+<font size=+1><b>Test: </font><font size=+2><tt>simple_include</tt></font></b></h3><br>
     <center>
     <table width=80% cellpadding=4>
     <tr>
@@ -437,6 +427,7 @@ Here are some tests from the suite. The file name reflects the general purpose o
     <tr>
       <td width=50% bgcolor=#fec0fe valign=top>
         <pre> Here I am
+ .debug
  trying to
  include
  .include simplefile.inc
@@ -457,8 +448,9 @@ Here are some tests from the suite. The file name reflects the general purpose o
     </tr>
     </table>
     </center>
+<br>
 
-<b>Test: <tt>009\_simple\_mixin</tt></b><br>
+<font size=+1><b>Test: </font><font size=+2><tt>simple_mixin</tt></font></b></h3><br>
     <center>
     <table width=80% cellpadding=4>
     <tr>
@@ -486,8 +478,9 @@ Here are some tests from the suite. The file name reflects the general purpose o
     </tr>
     </table>
     </center>
+<br>
 
-<b>Test: <tt>010\_simple\_copy</tt></b><br>
+<font size=+1><b>Test: </font><font size=+2><tt>simple_copy</tt></font></b></h3><br>
     <center>
     <table width=80% cellpadding=4>
     <tr>
@@ -517,8 +510,9 @@ Here are some tests from the suite. The file name reflects the general purpose o
     </tr>
     </table>
     </center>
+<br>
 
-<b>Test: <tt>011\_copy\_is\_raw</tt></b><br>
+<font size=+1><b>Test: </font><font size=+2><tt>copy_is_raw</tt></font></b></h3><br>
     <center>
     <table width=80% cellpadding=4>
     <tr>
@@ -546,8 +540,9 @@ Here are some tests from the suite. The file name reflects the general purpose o
     </tr>
     </table>
     </center>
+<br>
 
-<b>Test: <tt>012\_raw\_text\_block</tt></b><br>
+<font size=+1><b>Test: </font><font size=+2><tt>raw_text_block</tt></font></b></h3><br>
     <center>
     <table width=80% cellpadding=4>
     <tr>
@@ -570,6 +565,7 @@ Here are some tests from the suite. The file name reflects the general purpose o
  Or this: `(alpha male) \_(beta max) *(gamma rays)
  \_\_EOF\_\_
  
+ 
  I hope that worked.
 </pre>
       </td>
@@ -585,6 +581,7 @@ Here are some tests from the suite. The file name reflects the general purpose o
  
  And this stuff won't be munged: `alpha \_beta *gamma
  Or this: `(alpha male) \_(beta max) *(gamma rays)
+ <p>
  
  I hope that worked.
 </pre>
@@ -592,15 +589,20 @@ Here are some tests from the suite. The file name reflects the general purpose o
     </tr>
     </table>
     </center>
+<br>
+<p>
 
-<br><br><b><font size=+1>Writing custom methods</font></b><br>
+### Writing custom methods
+<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>
 
 The simplest way is just to define a method inline with the rest of 
 the text. Here's an example.
+<p>
 
 <pre>
      .comment
@@ -626,26 +628,30 @@ the text. Here's an example.
      It was the best of times, and you can call me Ishmael. The clocks
      were striking thirteen.
 </pre>
-
 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>@_args</tt> is
 initialized to the contents of this array. We usually refer to the
 <tt>@_args</tt> array only through the method <tt>_args</tt> which returns it.
+<p>
 
 The <tt>_args</tt> method is also an iterator. If a block is attached, that block
 will be called for every argument.
+<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>
 
 All the "helper" methods start with an underscore so as to avoid name
-collisions. These are all stored in the <tt>Livetext::Helpers</tt> module
+collisions. These are all stored in the <tt>Livetext::UserAPI</tt> module
 (which also has some methods you will never use).
+<p>
 
 Here is the HTML output of the previous example:
+<p>
 
 <pre>
      &lt;h3&gt;Chapter 1&lt;/h3&gt;
@@ -654,55 +660,46 @@ Here is the HTML output of the previous example:
      It was the best of times, and you can call me Ishmael. The clocks
      were striking thirteen.
 </pre>
-
 What are some other helper methods? Here'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>
+<td width=3%><td width=10%><tt>_args</tt>       %% Returns an array of arguments for the method (or an enumerator for that array)</td><td></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>
+<td width=3%><td width=10%><tt>_data</tt>       %% A single "unsplit" string of all arguments in raw form</td><td></td>
 </tr>
 <tr>
-<td width=3%><td width=10%><tt>_puts</tt> </td><td> Write a line to output (STDOUT or wherever)
-</td>
+<td width=3%><td width=10%><tt>_body</tt>       %% Returns a string (or enumerator) giving access to the text block (preceding <tt></tt>.end)</td><td></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>
+<td width=3%><td width=10%><tt>_puts</tt>       %% Write a line to output (STDOUT or wherever)</td><td></td>
 </tr>
 <tr>
-<td width=3%><td width=10%><tt>_formatting</tt> </td><td> A function transforming boldface, italics, and monospace (Livetext conventions)
-</td>
+<td width=3%><td width=10%><tt>_print</tt>      %% Write a line to output (STDOUT or wherever) without a newline</td><td></td>
 </tr>
 <tr>
-<td width=3%><td width=10%><tt>_var_substitution</tt> </td><td> Substitute variables into a string
-</td>
+<td width=3%><td width=10%><tt>_formatting</tt> %% A function transforming boldface, italics, and monospace (Livetext conventions)</td><td></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>
+<td width=3%><td width=10%><tt>_passthru</tt>   %% Feed a line directly into output after transforming and substituting</td><td></td>
 </tr>
 </table>
-
 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>
 
-<br><br><b><font size=+1>More examples</font></b><br>
+### More examples
+<p>
 
 Suppose you wanted to take a list of words, more than one per line, and alphabetize them.
 Let's write a method called <tt>alpha</tt> for that. This exercise and the next one are implemented 
 in the test suite.
+<p>
 
 
-<b>Test: <tt>013\_example\_alpha</tt></b><br>
+<font size=+1><b>Test: </font><font size=+2><tt>example_alpha</tt></font></b></h3><br>
     <center>
     <table width=80% cellpadding=4>
     <tr>
@@ -726,11 +723,13 @@ in the test suite.
  cytology fusillade ectomorph
  .end
  
+ 
  I hope that worked.
 </pre>
       </td>
       <td width=50% bgcolor=lightgray valign=top>
         <pre> Here is an alphabetized list:
+ <p>
  
      aardvark
      anamorphic
@@ -749,6 +748,7 @@ in the test suite.
      quark
      zootrope
      zymurgy
+ <p>
  
  I hope that worked.
 </pre>
@@ -756,12 +756,15 @@ in the test suite.
     </tr>
     </table>
     </center>
+<br>
+<p>
 
 I'll let that code stand on its own. Now suppose you wanted to allow columnar output. Let's
 have the user specify a number of columns (from 1 to 5, defaulting to 1).
+<p>
 
 
-<b>Test: <tt>014\_example\_alpha2</tt></b><br>
+<font size=+1><b>Test: </font><font size=+2><tt>example_alpha2</tt></font></b></h3><br>
     <center>
     <table width=80% cellpadding=4>
     <tr>
@@ -792,11 +795,13 @@ have the user specify a number of columns (from 1 to 5, defaulting to 1).
  cytology fusillade ectomorph
  .end
  
+ 
  I hope that worked a second time.
 </pre>
       </td>
       <td width=50% bgcolor=lightgray valign=top>
         <pre> Here is an alphabetized list:
+ <p>
  
  aardvark       anamorphic     anarchist
  bellicose      cytology       ectomorph
@@ -804,6 +809,7 @@ have the user specify a number of columns (from 1 to 5, defaulting to 1).
  gryphon        halcyon        manicotti
  mataeotechny   pareidolia     quark
  zootrope       zymurgy
+ <p>
  
  I hope that worked a second time.
 </pre>
@@ -811,13 +817,17 @@ have the user specify a number of columns (from 1 to 5, defaulting to 1).
     </tr>
     </table>
     </center>
+<br>
+<p>
 
 What if we wanted to store the code outside the text file? There is more than one way to 
 do this.
+<p>
 
 Let's assume we have a file called <tt>mylib.rb</tt> in the same directory as the file we're processing.
 (Issues such as paths and security have not been addressed yet.) We'll stick the actual Ruby code
 in here (and nothing else).
+<p>
 
 <pre>
    # File: mylib.rb
@@ -836,8 +846,8 @@ in here (and nothing else).
      end
    end
 </pre>
-
-Now the <tt>.lt</tt> file can be written this way:
+Now the <tt>.ltx</tt> file can be written this way:
+<p>
 
 <pre>
     .mixin mylib
@@ -852,8 +862,8 @@ Now the <tt>.lt</tt> file can be written this way:
    
     I hope that worked a second time.
 </pre>
-
 The output, of course, is the same.
+<p>
 
 There is an important feature that has not yet been implemented (the
 <tt>require</tt> method). Like Ruby's <tt>require</tt>, it will grab Ruby code and 
@@ -862,104 +872,61 @@ 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.
+on that new custom object. I plan to implement this later.
+<p>
 
-<br><br><b><font size=+1>Issues, open questions, and to-do items</font></b><br>
+### Issues, open questions, and to-do items
+<p>
 
 This list is not prioritized yet.
-
-<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>
-
+<p>
+
+1. <strike>Add versioning information </strike>
+2. <strike>Clean up code structure</strike>
+3. Add RDoc
+4. <strike>Think about command line executable</strike>
+5. <strike>Write as pure library in addition to executable</strike>
+6. <strike>Package as gem</strike>
+7. Document: <tt>require</tt> <tt>include</tt> <tt>copy</tt> <tt>mixin</tt> <tt>errout</tt> and others
+8. Need <strike>much</strike> better error checking and corresponding tests
+9. Worry about nesting of elements (probably mostly disallow)
+10. Think about UTF-8
+11. Document API fully
+12. Add <tt>_raw_args</tt> and let <tt>_args</tt> honor quotes
+13. Support quotes in <tt>.set</tt> values
+14. Support "namespaced" variables  (<tt>.set code.font="whatever"</tt>)
+15. <strike>Support functions (``$$func) </strike>
+16. Support function namespacing
+17. Create predefined variables (e.g., <tt>$_source_file</tt>, <tt>$[_line])</tt>
+18. Create predefined functions (e.g., <tt>$$_date</tt>)
+19. More support for markdown
+20. Allow turning on/off: formatting, variable interpolation, function interpolation?
+21. <tt>.require</tt> with file and sigil parameters
+22. Investigate "common intermediate format" - output renderers all read it
+23. Comments passed through (e.g. as HTML comments)
+24. <tt>.run</tt> to execute arbitrary Ruby code inline?
+25. Concept of <tt>.proc</tt> (guaranteed to return no value, produce no output)?
+26. Exceptions??
+27. Ruby <tt>$SAFE</tt> levels?
+28. Warn when overriding existing names?
+29. Think about passing data in (erb replacement)
+30. <strike>]Allow</strike> custom ending tag on <tt>raw</tt> method
+31. <strike>Ignore first blank line after `[.end</strike>? (and after raw-tag?)
+32. Allow/encourage custom <tt>passthru</tt> method?
+33. Must have sane support for CSS
+34. Support for Pygments and/or other code processors
+35. Support for gists? arbitrary links? other remote resouces?
+36. Small libraries for special purposes (books? special Softcover support? blogs? PDF? RMagick?)
+37. Experiment with idea of special libraries having pluggable output formats (via Ruby mixin?)
+38. Imagining a lib that can run/test code fragments as part of document generation
+39. Create vim (emacs?) syntax files
+40. Someday: Support other languages (Elixir, Python, ...)
+41. <tt>.pry</tt> method?
+42. <tt>.irb</tt> method?
+43. Other debugging features
+44. Feature to "break" to EOF?
+45. <tt>.meth?</tt> method ending in <tt>?</tt> takes a block that may be processed or thrown away (<tt>.else</tt> perhaps?)
+46. <tt>.dump</tt> to dump all variables and their values
+47. <tt>.if</tt> and <tt>.else</tt>?
+48. Make any/all delimiters configurable
+49. HTML helper? (in their own library?)