From 3ca15b7de0d147c400199c5040a7f87ea92b0c32 Mon Sep 17 00:00:00 2001 From: Case Duckworth Date: Tue, 6 Feb 2024 22:12:47 -0600 Subject: Update readme --- readme.html | 69 +++++++++++++++++++++++++++++++++++++++++++++--- readme.st | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 152 insertions(+), 5 deletions(-) diff --git a/readme.html b/readme.html index b6e2ec2..a42f9a9 100644 --- a/readme.html +++ b/readme.html @@ -18,7 +18,7 @@ without having to remember all the arcane two-letter requests and macros.

Quickstart

An easy and quick way to start with subtext is to build this -README: +README: 

make readme
Of course, I'd recommend reading readme.st in this repo to get a feel for the syntax as well. @@ -61,10 +61,73 @@ which by default is the current directory. that need to be done at awk-time.

Shell layer: #

- -todo +

So what does subtext do? +It takes an input file or stream and converts it to a shell script +which you can then pipe through sh(1). +But it doesn't +just +do that. +subtext +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 # puts the rest of the line in the code part, +enabling you to set a title, say, with or +define a function for a commonly-used thing in your file. +For this README, I've written +#subtext()(code subtext) +so I save about five characters every time.

Text layer: .

+

The "text layer" of subtext is actually expanded to a shell here-doc +so that you can use stuff like +$(...) +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.

+

In addition, lines beginning with +. +expand to +$(...), +and lines beginning with +..COMMAND [ARGS] +expand to +$(COMMAND ARGS << .. +and close the here-doc with +.. +on a line by itself.

+

You can add the +<< END-MARKER +yourself if you want to specify your own end-marker.

+

Basically, this means you can write +

.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!
+..

+

The above translates to

+

My cool article

+

Here is a cool article. +It is +really +cool.

+

Here's what someone said about it:

+
Wow, what a cool article!
+

Since this README was generated from subtext source, +look at readme.st to get a better feel for the syntax.

+ +

Using subtext

todo 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. .h2 Quickstart -An easy and quick way to start with $$(code subtext) is to build this README: +An easy and quick way to start with $$(code subtext) is to build this +.a href="/subtext/tree/readme.st" README : ..code make readme .. @@ -91,10 +92,93 @@ that need to be done at awk-time. % filter, and making it parse shell syntax does not seem like a good time. .h3 Shell layer: $$(code \#) -.i todo +So what does $$(subtext) do? +It takes an input file or stream and converts it to a shell script +which you can then pipe through $$(code "sh(1)"). +But it doesn't +.i just +do that. +.subtext +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 \#) puts the rest of the line in the code part, +enabling you to set a title, say, with $$(code "#title='Some title'") or +define a function for a commonly-used thing in your file. +For this README, I've written +.code #subtext()(code subtext) +so I save about five characters every time. .h3 Text layer: $$(code .) +The "text layer" of subtext is actually expanded to a shell here-doc +so that you can use stuff like +.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. + +In addition, lines beginning with +.code . +expand to +.code \$(...) , +and lines beginning with +.code ..COMMAND [ARGS] +expand to +.code \$(COMMAND ARGS << .. +and close the here-doc with +.code .. +on a line by itself. + +You can add the +.code << END-MARKER +yourself if you want to specify your own end-marker. + +Basically, this means you can write +..code << /code +\.h1 My cool article +.nl +Here is a cool article. +It is +\.i really +cool. +.nl +Here's what someone said about it: +.nl +\..blockquote cite="A fan" +Wow, what a cool article! +\.. +/code + +The above translates to + +% NB: I don't have `section' written in html.st.sh, and I don't really +% want to bother here ... but I made @ an alias for html_el, +% so it all works ^_^ +..@ section 'style="border:1px solid;padding:0.5em"' << //bq +.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! +.. +//bq + +Since this README was generated from subtext source, +look at readme.st to get a better feel for the syntax. + +.h2 Using $$(subtext) + .i todo .h2 Contributing -- cgit 1.4.1-21-gabe81