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
|
% 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.
|
