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
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
<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>
<p>So what does <code>subtext</code> do?
It takes an input file or stream and converts it to a shell script
which you can then pipe through <code>sh(1)</code>.
But it doesn't
<i>just</i>
do that.
<code>subtext</code>
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>#</code> puts the rest of the line in the code part,
enabling you to set a title, say, with <code #title='Some title'></code> or
define a function for a commonly-used thing in your file.
For this README, I've written
<code>#subtext()(code subtext)</code>
so I save about five characters every time.</p>
<h3>Text layer: <code>.</code></h3>
<p>The "text layer" of subtext is actually expanded to a shell here-doc
so that you can use stuff like
<code>$(...)</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.</p>
<p>In addition, lines beginning with
<code>.</code>
expand to
<code>$(...)</code>,
and lines beginning with
<code>..COMMAND [ARGS]</code>
expand to
<code>$(COMMAND ARGS << ..</code>
and close the here-doc with
<code>..</code>
on a line by itself.</p>
<p>You can add the
<code><< END-MARKER</code>
yourself if you want to specify your own end-marker.</p>
<p>Basically, this means you can write
<pre><code>.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!
..</code></pre></p>
<p>The above translates to</p>
<section style="border:1px solid;padding:0.5em"><h1>My cool article</h1>
<p>Here is a cool article.
It is
<i>really</i>
cool.</p>
<p>Here's what someone said about it:</p>
<blockquote cite=A fan>Wow, what a cool article!</blockquote></section>
<p>Since this README was generated from subtext source,
look at readme.st to get a better feel for the syntax.</p>
<h2>Using <code>subtext</code></h2>
<i>todo</i>
<h2>Issues</h2>
<h3>Debugging</h3>
<p>Because shell's debugging tools are pretty bad,
and because of the multiple layers involved with
<code>subtext</code>
it can be pretty hard to debug.
It would be nice to figure out a way around this.</p>
<h3>Shell quoting issues</h3>
<p>If you've programmed in shell at all,
you'll know that quoting is ... difficult,
to say the least.
Because
<code>subtext</code>
expands to shell forms, it's vulnerable to similar issues
– especially on
<code>.</code>
lines.</p>
<h2>Contributing</h2>
<p>Send me an email or whatever :)
This project is licensed under the BSD-3 license.
See COPYING for details.</p>
|
