1 files changed, 104 insertions, 0 deletions

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