about summary refs log tree commit diff stats
diff options
context:
space:
mode:
-rw-r--r--readme.html73
-rw-r--r--readme.md20
-rw-r--r--readme.st104
3 files changed, 177 insertions, 20 deletions
diff --git a/readme.html b/readme.html new file mode 100644 index 0000000..06dc9df --- /dev/null +++ b/readme.html
@@ -0,0 +1,73 @@
1<h1>Subtext, a layered document preperation system</h1>
2<p>This repo contains the source of my groff-aesthetic document preparator
3<code>subtext</code>.
4It's unique in that it's an
5<code>awk(1p)</code>
6script that compiles a source file to a
7shell script that you can pipe to
8<code>sh(1p)</code>.</p>
9<p>Doing things in this multi-layered way allows me to
10<ul><li>Build a rich writing environment using only off-the-shelf POSIX tools</li>
11<li>Use the same input to generate multiple outputs</li>
12<li>A cool third thing</li></ul>
13so I can truly write-once, run anywhere
14(or whatever the kids are saying these days).
15Plus, it looks kinda like
16<code>roff(1)</code>
17without having to remember all the arcane two-letter requests and macros.</p>
18
19<h2>Quickstart</h2>
20<p>An easy and quick way to start with <code>subtext</code> is to build this README:
21<pre><code>make readme</code></pre>
22Of course, I'd recommend reading readme.st in this repo
23to get a feel for the syntax as well.
24I've tried to use all the ways to inject control codes to illustrate it.</p>
25<p>However, this
26<em>quick start</em>
27is not really a good explanation of what's going on.
28For that, keep reading.</p>
29
30<h2>The layers of subtext, the subtextual layers</h2>
31<p>There are three main layers of <code>subtext</code>: the
32<b>awk</b>
33layer,
34<b>shell</b>
35layer,
36and, for lack of something better to call it, the
37<b>text</b>
38layer.
39These layers don't really reflect the order of expansions,
40but rather how I think they feel to the user
41and how they're reflected in syntax.
42<code>subtext</code>
43is inherently a line-based markup language,
44and each of these layers has its own line marker.</p>
45
46<h3>Awk layer: <code>%</code></h3>
47<p>The first thing that happens to any <code>subtext</code> source file is a pass through
48<code>subtext.awk</code>.
49While this awk script passes most things through to the next layers,
50there are two special directives at this layer you can use:</p>
51<dl><dt><code>%</code></dt>
52<dd>Comment the current line.
53<code>%</code>
54only works at the start of a line for comments.</dd>
55<dt><code>%so FILE</code></dt>
56<dd>Insert FILE verbatim at the line where this directive appears.
57FILE is searched in <code>$ST_SOPATH</code>,
58which by default is the current directory.</dd></dl>
59<p>I went ahead and reserved <code>%</code>-lines for future directives
60that need to be done at awk-time.</p>
61
62<h3>Shell layer: <code>#</code></h3>
63
64<i>todo</i>
65
66<h3>Text layer: <code>.</code></h3>
67
68<i>todo</i>
69
70<h2>Contributing</h2>
71<p>Send me an email or whatever :)
72This project is licensed under the BSD-3 license.
73See COPYING for details.</p>
diff --git a/readme.md b/readme.md deleted file mode 100644 index 46c5943..0000000 --- a/readme.md +++ /dev/null
@@ -1,20 +0,0 @@
1# subtext
2## a layered roffish markup .. thing
3
4subtext is a way to write text using shell templating and roff-like aesthetics for fun. confused? I don't know how to describe it really. just look at the syntax, i guess.
5
6## syntax
7
8subtext's syntax is inspired by roff mostly, with some other line-oriented markups in there as well. its semantics are mostly inspired by this one program i read about reading files as shell here-docs. i kinda combined those ideas together to make an awk script that generates a shell script that you can execute to generate markup. i will *eventually* have html and gemtext macrofiles in this repo, so you can generate html and gemtext from the same source file.
9
10### text lines
11
12### shell substitution
13
14### dotted lines
15
16### hashed lines
17
18## what's a macrofile?
19
20note: i should probably change this name
diff --git a/readme.st b/readme.st new file mode 100644 index 0000000..1344818 --- /dev/null +++ b/readme.st
@@ -0,0 +1,104 @@
1% SUBTEXT by C. Duckworth <acdw@acdw.net>
2% This file generates README.md when you run `make readme'.
3
4.h1 Subtext, a layered document preperation system
5
6This repo contains the source of my groff-aesthetic document preparator
7.code subtext .
8It's unique in that it's an
9.code awk(1p)
10script that compiles a source file to a
11shell script that you can pipe to
12.code sh(1p) .
13
14Doing things in this multi-layered way allows me to
15..ul
16.li Build a rich writing environment using only off-the-shelf POSIX tools
17.li Use the same input to generate multiple outputs
18.li A cool third thing
19..
20so I can truly write-once, run anywhere
21(or whatever the kids are saying these days).
22Plus, it looks kinda like
23.code roff(1)
24without having to remember all the arcane two-letter requests and macros.
25
26.h2 Quickstart
27
28An easy and quick way to start with $$(code subtext) is to build this README:
29..code
30make readme
31..
32Of course, I'd recommend reading readme.st in this repo
33to get a feel for the syntax as well.
34I've tried to use all the ways to inject control codes to illustrate it.
35
36However, this
37.em quick start
38is not really a good explanation of what's going on.
39For that, keep reading.
40
41.h2 The layers of subtext, the subtextual layers
42
43% I keep writing "subtext", so I'm going to define it here
44#subtext(){ code subtext; }
45
46There are three main layers of $$(subtext): the
47.b awk
48layer,
49.b shell
50layer,
51and, for lack of something better to call it, the
52.b text
53layer.
54These layers don't really reflect the order of expansions,
55but rather how I think they feel to the user
56and how they're reflected in syntax.
57.subtext
58is inherently a line-based markup language,
59and each of these layers has its own line marker.
60
61.h3 Awk layer: $$(code %)
62
63The first thing that happens to any $$(subtext) source file is a pass through
64.code subtext.awk .
65While this awk script passes most things through to the next layers,
66there are two special directives at this layer you can use:
67
68..dl
69.dt $$(code %)
70..dd << /dd
71Comment the current line.
72.code %
73only works at the start of a line for comments.
74/dd
75.
76.dt $$(code %so FILE)
77..dd << /dd
78Insert FILE verbatim at the line where this directive appears.
79FILE is searched in $$(code $ST_SOPATH),
80which by default is the current directory.
81/dd
82..
83
84I went ahead and reserved $$(code %)-lines for future directives
85that need to be done at awk-time.
86
87% NB: The octothorpe on the line below this comment must be escaped or quoted.
88% I'm thinking about escaping #'s as well .. but I think doing that would
89% take extra code I'm not sure I want to bother with, namely working with
90% a character's context. I like the idea that subtext.awk is a pretty-dumb
91% filter, and making it parse shell syntax does not seem like a good time.
92.h3 Shell layer: $$(code \#)
93
94.i todo
95
96.h3 Text layer: $$(code .)
97
98.i todo
99
100.h2 Contributing
101
102Send me an email or whatever :)
103This project is licensed under the BSD-3 license.
104See COPYING for details. \ No newline at end of file