From b1b0b5f2b000d20f9bc6fa32a734a6e8fb52eb9b Mon Sep 17 00:00:00 2001 From: Case Duckworth Date: Tue, 6 Feb 2024 00:11:59 -0600 Subject: Change readme.md to readme.st that build to readme.html --- readme.html | 73 ++++++++++++++++++++++++++++++++++++++++++ readme.md | 20 ------------ readme.st | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 177 insertions(+), 20 deletions(-) create mode 100644 readme.html delete mode 100644 readme.md create mode 100644 readme.st diff --git a/readme.html b/readme.html new file mode 100644 index 0000000..06dc9df --- /dev/null +++ b/readme.html @@ -0,0 +1,73 @@ +

Subtext, a layered document preperation system

+

This repo contains the source of my groff-aesthetic document preparator +subtext. +It's unique in that it's an +awk(1p) +script that compiles a source file to a +shell script that you can pipe to +sh(1p).

+

Doing things in this multi-layered way allows me to +

+so I can truly write-once, run anywhere +(or whatever the kids are saying these days). +Plus, it looks kinda like +roff(1) +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: +

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 +quick start +is not really a good explanation of what's going on. +For that, keep reading.

+ +

The layers of subtext, the subtextual layers

+

There are three main layers of subtext: the +awk +layer, +shell +layer, +and, for lack of something better to call it, the +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.

+ +

Awk layer: %

+

The first thing that happens to any subtext source file is a pass through +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:

+
%
+
Comment the current line. +% +only works at the start of a line for comments.
+
%so FILE
+
Insert FILE verbatim at the line where this directive appears. +FILE is searched in $ST_SOPATH, +which by default is the current directory.
+

I went ahead and reserved %-lines for future directives +that need to be done at awk-time.

+ +

Shell layer: #

+ +todo + +

Text layer: .

+ +todo + +

Contributing

+

Send me an email or whatever :) +This project is licensed under the BSD-3 license. +See COPYING for details.

diff --git a/readme.md b/readme.md deleted file mode 100644 index 46c5943..0000000 --- a/readme.md +++ /dev/null @@ -1,20 +0,0 @@ -# subtext -## a layered roffish markup .. thing - -subtext 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. - -## syntax - -subtext'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. - -### text lines - -### shell substitution - -### dotted lines - -### hashed lines - -## what's a macrofile? - -note: 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 @@ +% SUBTEXT by C. Duckworth +% 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. \ No newline at end of file -- cgit 1.4.1-21-gabe81