1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
|
<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
<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.
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>
|
