Subtext, a layered document preperation system

This repo contains the source of my groff-aesthetic document preparator subtext. It's unique in that it's an awk(1p) script that compiles a source file to a shell script that you can pipe to sh(1p).

Doing things in this multi-layered way allows me to

so I can truly write-once, run anywhere (or whatever the kids are saying these days). Plus, it looks kinda like roff(1) without having to remember all the arcane two-letter requests and macros.

Quickstart

An easy and quick way to start with subtext is to build this README: 

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 quick start is not really a good explanation of what's going on. For that, keep reading.

The layers of subtext, the subtextual layers

There are three main layers of subtext: the awk layer, shell layer, and, for lack of something better to call it, the 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.

Awk layer: %

The first thing that happens to any subtext source file is a pass through 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:

%
Comment the current line. % only works at the start of a line for comments.
%so FILE
Insert FILE verbatim at the line where this directive appears. FILE is searched in $ST_SOPATH, which by default is the current directory.

I went ahead and reserved %-lines for future directives that need to be done at awk-time.

Shell layer: #

todo

Text layer: .

todo

Contributing

Send me an email or whatever :) This project is licensed under the BSD-3 license. See COPYING for details.