1 files changed, 86 insertions, 2 deletions

@@ -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 – 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 [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