Update readme

2 files changed, 152 insertions, 5 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>
 
@@ -25,7 +25,8 @@ without having to remember all the arcane two-letter requests and macros.
 
 .h2 Quickstart
 
-An easy and quick way to start with $$(code subtext) is to build this README:
+An easy and quick way to start with $$(code subtext) is to build this
+.a href="/subtext/tree/readme.st" README :
 ..code
 make readme
 ..
@@ -91,10 +92,93 @@ that need to be done at awk-time.
 %     filter, and making it parse shell syntax does not seem like a good time.
 .h3 Shell layer: $$(code \#)
 
-.i todo
+So what does $$(subtext) do?
+It takes an input file or stream and converts it to a shell script
+which you can then pipe through $$(code "sh(1)").
+But it doesn't
+.i just
+do that.
+.subtext
+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 \#) puts the rest of the line in the code part,
+enabling you to set a title, say, with $$(code "#title='Some title'") or
+define a function for a commonly-used thing in your file.
+For this README, I've written
+.code #subtext()(code subtext)
+so I save about five characters every time.
 
 .h3 Text layer: $$(code .)
 
+The "text layer" of subtext is actually expanded to a shell here-doc
+so that you can use stuff like
+.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.
+
+In addition, lines beginning with
+.code .
+expand to
+.code \$(...) ,
+and lines beginning with
+.code ..COMMAND&nbsp;[ARGS]
+expand to
+.code \$(COMMAND&nbsp;ARGS&nbsp;<<&nbsp;..
+and close the here-doc with
+.code ..
+on a line by itself.
+
+You can add the
+.code <<&nbsp;END-MARKER
+yourself if you want to specify your own end-marker.
+
+Basically, this means you can write
+..code << /code
+\.h1 My cool article
+.nl
+Here is a cool article.
+It is
+\.i really
+cool.
+.nl
+Here's what someone said about it:
+.nl
+\..blockquote cite="A fan"
+Wow, what a cool article!
+\..
+/code
+
+The above translates to
+
+% NB: I don't have `section' written in html.st.sh, and I don't really
+%     want to bother here ... but I made @ an alias for html_el,
+%     so it all works ^_^
+..@ section 'style="border:1px solid;padding:0.5em"' << //bq
+.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!
+..
+//bq
+
+Since this README was generated from subtext source,
+look at readme.st to get a better feel for the syntax.
+
+.h2 Using $$(subtext)
+
 .i todo
 
 .h2 Contributing