about summary refs log tree commit diff stats
path: root/readme.st
diff options
context:
space:
mode:
Diffstat (limited to 'readme.st')
-rw-r--r--readme.st88
1 files changed, 86 insertions, 2 deletions
diff --git a/readme.st b/readme.st index 1344818..2315ad3 100644 --- a/readme.st +++ b/readme.st
@@ -25,7 +25,8 @@ without having to remember all the arcane two-letter requests and macros.
25 25
26.h2 Quickstart 26.h2 Quickstart
27 27
28An easy and quick way to start with $$(code subtext) is to build this README: 28An easy and quick way to start with $$(code subtext) is to build this
29.a href="/subtext/tree/readme.st" README :
29..code 30..code
30make readme 31make readme
31.. 32..
@@ -91,10 +92,93 @@ that need to be done at awk-time.
91% filter, and making it parse shell syntax does not seem like a good time. 92% filter, and making it parse shell syntax does not seem like a good time.
92.h3 Shell layer: $$(code \#) 93.h3 Shell layer: $$(code \#)
93 94
94.i todo 95So what does $$(subtext) do?
96It takes an input file or stream and converts it to a shell script
97which you can then pipe through $$(code "sh(1)").
98But it doesn't
99.i just
100do that.
101.subtext
102also outputs various functions and variables and what-not
103to set up the environment in which the source document is expanded.
104Starting a line with $$(code \#) puts the rest of the line in the code part,
105enabling you to set a title, say, with $$(code "#title='Some title'") or
106define a function for a commonly-used thing in your file.
107For this README, I've written
108.code #subtext()(code subtext)
109so I save about five characters every time.
95 110
96.h3 Text layer: $$(code .) 111.h3 Text layer: $$(code .)
97 112
113The "text layer" of subtext is actually expanded to a shell here-doc
114so that you can use stuff like
115.code \$(...)
116to call shell functions.
117But don't worry – I've made it easier to not shoot yourself in the foot.
118One $ is changed to \\$ in the expansion,
119and more than one $ is changed to one less.
120So \$\$$ becomes \$$, etc.
121if you really want to put the process number in your output.
122Oh, and ` are all escaped.
123Those were a bad idea from go.
124
125In addition, lines beginning with
126.code .
127expand to
128.code \$(...) ,
129and lines beginning with
130.code ..COMMAND [ARGS]
131expand to
132.code \$(COMMAND&nbsp;ARGS&nbsp;<<&nbsp;..
133and close the here-doc with
134.code ..
135on a line by itself.
136
137You can add the
138.code <<&nbsp;END-MARKER
139yourself if you want to specify your own end-marker.
140
141Basically, this means you can write
142..code << /code
143\.h1 My cool article
144.nl
145Here is a cool article.
146It is
147\.i really
148cool.
149.nl
150Here's what someone said about it:
151.nl
152\..blockquote cite="A fan"
153Wow, what a cool article!
154\..
155/code
156
157The above translates to
158
159% NB: I don't have `section' written in html.st.sh, and I don't really
160% want to bother here ... but I made @ an alias for html_el,
161% so it all works ^_^
162..@ section 'style="border:1px solid;padding:0.5em"' << //bq
163.h1 My cool article
164
165Here is a cool article.
166It is
167.i really
168cool.
169
170Here's what someone said about it:
171
172..blockquote cite="A fan"
173Wow, what a cool article!
174..
175//bq
176
177Since this README was generated from subtext source,
178look at readme.st to get a better feel for the syntax.
179
180.h2 Using $$(subtext)
181
98.i todo 182.i todo
99 183
100.h2 Contributing 184.h2 Contributing