Change readme.md to readme.st that build to readme.html

1 files changed, 73 insertions, 0 deletions

@@ -0,0 +1,73 @@
+<h1>Subtext, a layered document preperation system</h1>
+<p>This repo contains the source of my groff-aesthetic document preparator
+<code>subtext</code>.
+It's unique in that it's an
+<code>awk(1p)</code>
+script that compiles a source file to a
+shell script that you can pipe to
+<code>sh(1p)</code>.</p>
+<p>Doing things in this multi-layered way allows me to
+<ul><li>Build a rich writing environment using only off-the-shelf POSIX tools</li>
+<li>Use the same input to generate multiple outputs</li>
+<li>A cool third thing</li></ul>
+so I can truly write-once, run anywhere
+(or whatever the kids are saying these days).
+Plus, it looks kinda like
+<code>roff(1)</code>
+without having to remember all the arcane two-letter requests and macros.</p>
+
+<h2>Quickstart</h2>
+<p>An easy and quick way to start with <code>subtext</code> is to build this README:
+<pre><code>make readme</code></pre>
+Of course, I'd recommend reading readme.st in this repo
+to get a feel for the syntax as well.
+I've tried to use all the ways to inject control codes to illustrate it.</p>
+<p>However, this
+<em>quick start</em>
+is not really a good explanation of what's going on.
+For that, keep reading.</p>
+
+<h2>The layers of subtext, the subtextual layers</h2>
+<p>There are three main layers of <code>subtext</code>: the
+<b>awk</b>
+layer,
+<b>shell</b>
+layer,
+and, for lack of something better to call it, the
+<b>text</b>
+layer.
+These layers don't really reflect the order of expansions,
+but rather how I think they feel to the user
+and how they're reflected in syntax.
+<code>subtext</code>
+is inherently a line-based markup language,
+and each of these layers has its own line marker.</p>
+
+<h3>Awk layer: <code>%</code></h3>
+<p>The first thing that happens to any <code>subtext</code> source file is a pass through
+<code>subtext.awk</code>.
+While this awk script passes most things through to the next layers,
+there are two special directives at this layer you can use:</p>
+<dl><dt><code>%</code></dt>
+<dd>Comment the current line.
+<code>%</code>
+only works at the start of a line for comments.</dd>
+<dt><code>%so FILE</code></dt>
+<dd>Insert FILE verbatim at the line where this directive appears.
+FILE is searched in <code>$ST_SOPATH</code>,
+which by default is the current directory.</dd></dl>
+<p>I went ahead and reserved <code>%</code>-lines for future directives
+that need to be done at awk-time.</p>
+
+<h3>Shell layer: <code>#</code></h3>
+
+<i>todo</i>
+
+<h3>Text layer: <code>.</code></h3>
+
+<i>todo</i>
+
+<h2>Contributing</h2>
+<p>Send me an email or whatever :)
+This project is licensed under the BSD-3 license.
+See COPYING for details.</p>