3 files changed, 177 insertions, 20 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>
@@ -1,20 +0,0 @@
-# subtext
-## a layered roffish markup .. thing
-
-subtext is a way to write text using shell templating and roff-like aesthetics for fun.  confused?  I don't know how to describe it really. just look at the syntax, i guess.
-
-## syntax
-
-subtext's syntax is inspired by roff mostly, with some other line-oriented markups in there as well.  its semantics are mostly inspired by this one program i read about reading files as shell here-docs.  i kinda combined those ideas together to make an awk script that generates a shell script that you can execute to generate markup.  i will *eventually* have html and gemtext macrofiles in this repo, so you can generate html and gemtext from the same source file.
-
-### text lines
-
-### shell substitution
-
-### dotted lines
-
-### hashed lines
-
-## what's a macrofile?
-
-note: i should probably change this name
@@ -0,0 +1,104 @@
+% SUBTEXT by C. Duckworth <acdw@acdw.net>
+% This file generates README.md when you run `make readme'.
+
+.h1 Subtext, a layered document preperation system
+
+This repo contains the source of my groff-aesthetic document preparator
+.code subtext .
+It's unique in that it's an
+.code awk(1p)
+script that compiles a source file to a
+shell script that you can pipe to
+.code sh(1p) .
+
+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 Use the same input to generate multiple outputs
+.li A cool third thing
+..
+so I can truly write-once, run anywhere
+(or whatever the kids are saying these days).
+Plus, it looks kinda like
+.code roff(1)
+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:
+..code
+make readme
+..
+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.
+
+However, this
+.em quick start
+is not really a good explanation of what's going on.
+For that, keep reading.
+
+.h2 The layers of subtext, the subtextual layers
+
+% I keep writing "subtext", so I'm going to define it here
+#subtext(){ code subtext; }
+
+There are three main layers of $$(subtext): the
+.b awk
+layer,
+.b shell
+layer,
+and, for lack of something better to call it, the
+.b text
+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.
+.subtext
+is inherently a line-based markup language,
+and each of these layers has its own line marker.
+
+.h3 Awk layer: $$(code %)
+
+The first thing that happens to any $$(subtext) source file is a pass through
+.code subtext.awk .
+While this awk script passes most things through to the next layers,
+there are two special directives at this layer you can use:
+
+..dl
+.dt $$(code %)
+..dd << /dd
+Comment the current line.
+.code %
+only works at the start of a line for comments.
+/dd
+.
+.dt $$(code %so FILE)
+..dd << /dd
+Insert FILE verbatim at the line where this directive appears.
+FILE is searched in $$(code $ST_SOPATH),
+which by default is the current directory.
+/dd
+..
+
+I went ahead and reserved $$(code %)-lines for future directives
+that need to be done at awk-time.
+
+% NB: The octothorpe on the line below this comment must be escaped or quoted.
+%     I'm thinking about escaping #'s as well .. but I think doing that would
+%     take extra code I'm not sure I want to bother with, namely working with
+%     a character's context.  I like the idea that subtext.awk is a pretty-dumb
+%     filter, and making it parse shell syntax does not seem like a good time.
+.h3 Shell layer: $$(code \#)
+
+.i todo
+
+.h3 Text layer: $$(code .)
+
+.i todo
+
+.h2 Contributing
+
+Send me an email or whatever :)
+This project is licensed under the BSD-3 license.
+See COPYING for details.
\ No newline at end of file