Update readme

1 files changed, 66 insertions, 3 deletions

@@ -18,7 +18,7 @@ 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
-<a href="/subtext/tree/readme.st">README</a>:
+<a href=/subtext/tree/readme.st>README</a>:
 <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.
@@ -61,10 +61,73 @@ which by default is the current directory.</dd></dl>
 that need to be done at awk-time.</p>
 
 <h3>Shell layer: <code>#</code></h3>
-
-<i>todo</i>
+<p>So what does <code>subtext</code> do?
+It takes an input file or stream and converts it to a shell script
+which you can then pipe through <code>sh(1)</code>.
+But it doesn't
+<i>just</i>
+do that.
+<code>subtext</code>
+also outputs various functions and variables and what-not
+to set up the environment in which the source document is expanded.
+Starting a line with <code>#</code> puts the rest of the line in the code part,
+enabling you to set a title, say, with <code #title='Some title'></code> or
+define a function for a commonly-used thing in your file.
+For this README, I've written
+<code>#subtext()(code subtext)</code>
+so I save about five characters every time.</p>
 
 <h3>Text layer: <code>.</code></h3>
+<p>The "text layer" of subtext is actually expanded to a shell here-doc
+so that you can use stuff like
+<code>$(...)</code>
+to call shell functions.
+But don't worry &ndash; I've made it easier to not shoot yourself in the foot.
+One $ is changed to \$ in the expansion,
+and more than one $ is changed to one less.
+So $$$ becomes $$, etc.
+if you really want to put the process number in your output.
+Oh, and ` are all escaped.
+Those were a bad idea from go.</p>
+<p>In addition, lines beginning with
+<code>.</code>
+expand to
+<code>$(...)</code>,
+and lines beginning with
+<code>..COMMAND&nbsp;[ARGS]</code>
+expand to
+<code>$(COMMAND&nbsp;ARGS&nbsp;<<&nbsp;..</code>
+and close the here-doc with
+<code>..</code>
+on a line by itself.</p>
+<p>You can add the
+<code><<&nbsp;END-MARKER</code>
+yourself if you want to specify your own end-marker.</p>
+<p>Basically, this means you can write
+<pre><code>.h1 My cool article
+
+Here is a cool article.
+It is
+.i really
+cool.
+
+Here's what someone said about it:
+
+..blockquote cite="A fan"
+Wow, what a cool article!
+..</code></pre></p>
+<p>The above translates to</p>
+<section style="border:1px solid;padding:0.5em"><h1>My cool article</h1>
+<p>Here is a cool article.
+It is
+<i>really</i>
+cool.</p>
+<p>Here's what someone said about it:</p>
+<blockquote cite=A fan>Wow, what a cool article!</blockquote></section>
+<p>Since this README was generated from subtext source,
+look at readme.st to get a better feel for the syntax.</p>
+
+<h2>Using <code>subtext</code></h2>
 
 <i>todo</i>