Index: cortav.ct
==================================================================
--- cortav.ct
+++ cortav.ct
@@ -1,24 +1,26 @@
-# cortav
+# cortav specification
 [*cortav] is a markup language designed to be a simpler, but more capable alternative to markdown. its name derives from the [>dict Ranuir words] [!cor] "writing" and [!tav] "document", translating to something like "(plain) text document".
 
 	dict: http://ʞ.cc/fic/spirals/glossary
 
+the cortav [!format] can be called [!cortavgil], or [!gil cortavi], to differentiate it from the reference implementation [!cortavsir] or [!sir cortavi].
+
 %toc
 
 ## cortav vs. markdown
-the most important difference between cortav and markdown is that cortav is strictly line-oriented. this choice was made to ensure that cortav was relatively easy to parse. so while a simple [$.ct] file may look a bit like a [$.md] file, in reality it's a lot closer to Gemini structured text than any flavor of markdown.
+the most important difference between cortav and markdown is that cortav is strictly line-oriented. this choice was made to ensure that cortav was relatively easy to parse. so while a simple [$.ct] file may look a bit like a [$.md] file, in reality it's a lot closer to gemtext than any flavor of markdown.
 
 ## encoding
 a cortav document is made up of a sequence of codepoints. UTF-8 must be supported, but other encodings (such as UTF-32 or C6B) may be supported as well. lines will be derived by splitting the codepoints at the linefeed character or equivalent. note that unearthly encodings like C6B or EBCDIC will need to select their own control sequences.
 
 ## structure
 cortav is based on an HTML-like block model, where a document consists of sections, which are made up of blocks, which may contain a sequence of spans. flows of text are automatically conjoined into spans, and blocks are separated by one or more newlines. this means that, unlike in markdown, a single logical paragraph [*cannot] span multiple ASCII lines. the primary purpose of this was to ensure ease of parsing, but also, both markdown and cortav are supposed to be readable from within a plain text editor. this is the 21st century. every reasonable text editor supports soft word wrap, and if yours doesn't, that's entirely your own damn fault.
 
 the first character(s) of every line (the "control sequence") indicates the role of that line. if no control sequence is recognized, the sequence [$.] is implied instead. the standard line classes and their associated control sequences are listed below. some control sequences have alternate forms, in order to support modern, readable unicode characters as well as plain ascii text.
 
-* paragraphs (. ¶ ❡): a paragraph is a simple block of text. the backslash control sequence is only necessary if the paragraph text begins with something that would otherwise be interpreted as a control sequence.
+* paragraphs (. ¶ ❡): a paragraph is a simple block of text. the period control sequence is only necessary if the paragraph text begins with something that would otherwise be interpreted as a control sequence.
 * newlines (\): inserts a line break into previous paragraph and attaches the following text. mostly useful for poetry or lyrics.
 * section starts (# §): starts a new section. all sections have an associated depth, determined by the number of sequence repetitions (e.g. "###" indicates depth-three"). sections may have headers and IDs; both are optional. IDs, if present, are a sequence of raw-text immediately following the hash marks. if the line has one or more space character followed by styled-text, a header will be attached. the character immediately following the hashes can specify a particular type of section. e.g.:
 ** [$#] is a simple section break.
 ** [$#anchor] opens a new section with the ID [$anchor].
 ** [$# header] opens a new section with the title "header".
@@ -54,53 +56,56 @@
 most blocks contain a sequence of spans. these spans are produced by interpreting a stream of [*styled-text] following the control sequence. styled-text is a sequence of codepoints potentially interspersed with escapes. an escape is formed by an open square bracket [$\[] followed by a [*span control sequence], and arguments for that sequence like more styled-text. escapes can be nested.
 
 * strong \[*[!styled-text]\]: causes its text to stand out from the narrative, generally rendered as bold or a brighter color.
 * emphatic \[![!styled-text]\]: indicates that its text should be spoken with emphasis, generally rendered as italics
 * literal \[$[!styled-text]\]: indicates that its text is a reference to a literal sequence of characters, variable name, or other discrete token. generally rendered in monospace
-* link \[>[!ref] [!styled-text]\]: produces a hyperlink or cross-reference denoted by [$ref], which may be either a URL specified with a reference or the name of an object like an image or section elsewhere in the document.
+* link \[>[!ref] [!styled-text]\]: produces a hyperlink or cross-reference denoted by [$ref], which may be either a URL specified with a reference or the name of an object like an image or section elsewhere in the document. the unicode characters [$→] and [$🔗] can also be used instead of [$>] to denote a link.
 * footnote \[^[!ref] [!styled-text]\]: annotates the text with a defined footnote
 * raw \[\\[!raw-text]\]: causes all characters within to be interpreted literally, without expansion. the only special characters are square brackets, which must have a matching closing bracket
 * raw literal \[$\\[!raw-text]\]: shorthand for [\[$[\…]]]
 * macro \{[!name] [!arguments]}: invokes a [>ex.mac macro], specified with a reference
 * argument \[#[!var]\]: in macros only, inserts the [$var]-th argument. otherwise, inserts a context variable provided by the renderer.
 * raw argument \[##[!var]\]: like above, but does not evaluate [$var].
 * term \[&[!name] ([!label])\]: quotes a defined term with a link to its definition
-* inline image \[&@[!name]\]: shows a small image or other object inline
+* inline image \[&@[!name]\]: shows a small image or other object inline. the unicode character [$🖼] can also be used instead of [$&@].
 
 ## identifiers
 any identifier (including a reference) that is defined within a named section must be referred to from outside that section as [$[!sec].[!obj]], where [$sec] is the ID of the containing section and [$obj] is the ID of the object one wishes to reference.
 
 ## context variables
-context variables are provided so that cortav renderers can process templates. certain context variables are provided for by the standard. you can test for the presence of a context variable with the directive [$when ctx [!var]].
+context variables are provided so that cortav renderers can process templates. certain context variables are provided for by the standard. you can test for the presence of a context variable with the directive [$%[*when] ctx [!var]].
 
-* cortav.file: the name of the file currently being rendered
-* cortav.path: the absolute path of the file currently being rendered
-* cortav.time: the current system time
-* cortav.date: the current system date
-* cortav.page: the number of the page currently being rendered
-* cortav.id: the identifier of the renderer
-* cortav.hash: the SHA3 hash of the source file being rendered
+* {def cortav.file} the name of the file currently being rendered
+* {def cortav.path} the absolute path of the file currently being rendered
+* {def cortav.time} the current system time in the form [$[#cortav.time]]
+* {def cortav.date} the current system date in the form [$[#cortav.date]]
+* {def cortav.datetime} the current system date and time represented in the locale or system-standard manner (e.g. [$[#cortav.datetime]])
+* {def cortav.page} the number of the page currently being rendered
+* {def cortav.id} the identifier of the renderer
+* {def cortav.hash} the SHA3 hash of the source file being rendered
+	def: [*[#1]]:
 
 on systems with environment variables, these may be accessed as context variables by prefixing their name with [$env.].
 
 different renderers may provide context in different ways, such as from command line options or a context file. any predefined variables should carry an appropriate prefix to prevent conflation. 
 
 ## directives
-* format: gives a hint on how the document should be formatted. the first hint that is understood will be applied; all others will be discarded. standard hints include
+	d: [$%[*[##1]]]
+* {d format} gives a hint on how the document should be formatted. the first hint that is understood will be applied; all others will be discarded. standard hints include:
 ** essay
 ** narrative
 ** screenplay: uses asides to denote actions, quotes for dialogue
 ** stageplay: uses asides to denote actions, quotes for dialogue
 ** manual
 ** glossary
 ** news
-* author: encodes document authorship
-* cols: specifies the number of columns the next object should be rendered with
-* include: transcludes another file
-* quote: transcludes another file, without expanding the text except for paragraphs 
-* embed: where possible, embeds another file as an object within the current one. in HTML this could be accomplished with e.g. an iframe.
-* expand: causes the next object (usually a code block) to be fully expanded when it would otherwise not be
+* {d author} encodes document authorship
+* {d cols} specifies the number of columns the next object should be rendered with
+* {d include} transcludes another file
+* {d quote} transcludes another file, without expanding the text except for paragraphs 
+* {d embed}, where possible, embeds another file as an object within the current one. in HTML this could be accomplished with e.g. an iframe.
+* {d expand} causes the next object (usually a code block) to be fully expanded when it would otherwise not be
 
 ##ex examples
 
 ~~~ blockquotes #bq [cortav] ~~~
 the following excerpts of text were recovered from a partially erased hard drive found in the Hawthorne manor in the weeks after the Incident. context is unknown.
@@ -175,11 +180,11 @@
 
 used files should return a table with the following members
 * macros: an array of functions that return strings or arrays of strings when invoked. these will be injected into the global macro namespace.
 
 ### ts
-the [*ts] extension allows documents to be marked up for basic classification constraints and automatically redacted. if you are seriously relying on ts for confidentiality, make damn sure you start the file with [$\[requires ts\]], so that rendering will fail with an error if the extension isn't supported.
+the [*ts] extension allows documents to be marked up for basic classification constraints and automatically redacted. if you are seriously relying on ts for confidentiality, make damn sure you start the file with [$%[*requires] ts], so that rendering will fail with an error if the extension isn't supported.
 
 ts enables the directives:
 * [$ts class [!scope] [!level] (styled-text)]: indicates a classification level for either the while document (scope [!doc]) or the next section (scope [!sec]). if the ts level is below [$level], the section will be redacted or rendering will fail with an error, as appropriate. if styled-text is included, this will be treated as the name of the classification level.
 * [$ts word [!scope] [!word] (styled-text)]: indicates a codeword clearance that must be present for the text to render. if styled-text is present, this will be used to render the name of the codeword instead of [$word].
 * [$when ts level [!level]]
@@ -212,6 +217,72 @@
 <A, shouting> god DAMMIT woman I am trying to SAVE your worthless skin
 <B> Hyacinth! your Godforsaken scrambler!
 <A> …oh, [!fuck].
 (signal lost)
 ~~~
+
+# reference implementation
+the cortav standard is implemented in [$cortav.lua], found in this repository. only the way [$cortav.lua] interprets the cortav language is defined as a reference implementation; other behaviors are simply how [$cortav.lua] implements the specification and may be copied, ignored, tweaked, violently assaulted, or used as inspiration by a compliant parser.
+
+## invocation
+[$cortav.lua] is operated from the command line, either with the command [$lua cortav.lua] or by first compiling it to bytecode; a makefile for producing a "bytecode binary" that can be executed like a normal executable is included in the repository. henceforth it will be assumed you are using the compiled form; if you are instead running [$cortav.lua] directly as an interpreted script, just replace [$$ cortav] with [$$ lua cortav.lua] in incantations.
+
+when run without commands, [$cortav.lua] will read input from standard input and write to standard output. alternately, a source file can be given as an argument. to write to a specific file instead of the standard output stream, use the [$-o [!file]] flag.
+
+~~~
+$ cortav readme.ct -o readme.html
+	# reads from readme.ct, writes to readme.html
+$ cortav -o readme.html
+	# reads from standard input, writes to readme.html
+$ cortav readme.ct
+	# reads from readme.ct, writes to standard output
+~~~
+
+### switches
+[$cortav.lua] offers various switches to control its behavior.
++ long                      + short + function                                    +
+| [$--out [!file]]         :|:[$-o]:| sets the output file (default stdout)       |
+| [$--log [!file]]         :|:[$-l]:| sets the log file (default stderr)          |
+| [$--define [!var] [!val]]:|:[$-d]:| sets the context variable [$var] to [$val]  |
+| [$--mode-set [!mode]]    :|:[$-y]:| activates the [>refimpl-mode mode] with ID [!mode]
+| [$--mode-clear [!mode]]  :|:[$-n]:| disables the mode with ID [!mode]           |
+| [$--mode [!id] [!val]]   :|:[$-m]:| configures mode [!id] with the value [!val] |
+| [$--help]                :|:[$-h]:| display online help                         |
+| [$--version]             :|:[$-V]:| display the interpreter version             |
+
+###refimpl-mode modes
+most of [$cortav.lua]'s implementation-specific behavior is controlled by use of [!modes]. these are namespaced options which may have a boolean, string, or numeric value. boolean modes are set with the [$-y] [$-n] flags; other modes use the [$-m] flags.
+
+most modes are defined by the renderer backend. the following modes affect the behavior of the frontend:
+
++ ID              + type   + effect
+|   [$render:format]:| string | selects the [>refimpl-rend renderer] (default [$html])
+| [$parse:show-tree]:| flag   | dumps the parse tree to the log after parsing completes
+
+##refimpl-rend renderers
+[$cortav.lua] implements a frontend-backend architecture, separating the parsing stage from the rendering stage. this means new renderers can be added to [$cortav.lua] relatively easily. currently, only an [>refimpl-rend-html HTML renderer] is included; however, a [$groff] backend is planned at some point in the future, so that PDFs and manpages can be generated from cortav files.
+
+###refimpl-rend-html html
+the HTML renderer is activated with the incantation [$-m render:format html]. it is currently the default backend. it produces a single HTML file, optionally with CSS styling data, from a [$.ct] input file.
+
+it supports the following modes:
+
+* string (css length) [$html:width] sets a maximum width for the body content in order to make the page more readable on large displays
+* number [$html:accent] applies an accent hue to the generated webpage. the hue is specified in degrees, e.g. [$-m html:accent 0] applies a red accent.
+* flag [$html:dark-on-light] uses dark-on-light styling, instead of the default light-on-dark
+* flag [$html:fossil-uv] outputs an HTML snippet suitable for use with the Fossil VCS webserver. this is intended to be used with the unversioned content mechanism to host rendered versions of documentation written in cortav that's stored in a Fossil repository.
+* number [$html:hue-spread] generates a color palette based on the supplied accent hue. the larger the value, the more the other colors diverge from the accent hue.
+* string [$html:link-css] generates a document linking to the named stylesheet
+* flag [$html:gen-styles] embeds appropriate CSS styles in the document (default on)
+* flag [$html:snippet] produces a snippet of html instead of an entire web page. note that proper CSS scoping is not yet implemented (and can't be implemented hygienically since [$scoped] was removed 😢)
+* string [$html:title] specifies the webpage titlebar contents (normally autodetected from the document based on headings or directives)
+
+~~~
+$ cortav readme.ct --out readme.html \
+	-m render:format html \
+	-m html:width 40em \
+	-m html:accent 80 \
+	-m html:hue-spread 35 \
+	-y html:dark-on-light # could also be written as:
+$ cortav readme.ct -ommmmy readme.html render:format html html:width 40em html:accent 80 html:hue-spread 35 html:dark-on-light
+~~~
 

Index: cortav.lua
==================================================================
--- cortav.lua
+++ cortav.lua
@@ -1,9 +1,9 @@
 -- [ʞ] cortav.lua
 --  ~ lexi hale <lexi@hale.su>
 --  © AGPLv3
---  ? renderer
+--  ? reference implementation of the cortav document language
 
 local ct = { render = {} }
 
 local function hexdump(s)
 	local hexlines, charlines = {},{}
@@ -68,10 +68,20 @@
 		return string.format('“%s”', o)
 	else
 		return tostring(o)
 	end
 end
+
+local function
+lerp(t, a, b)
+	return (1-t)*a + (t*b)
+end
+
+local function
+startswith(str, pfx)
+	return string.sub(str, 1, #pfx) == pfx
+end
 
 local function declare(c)
 	local cls = setmetatable({
 		__name = c.ident;
 	}, {
@@ -175,10 +185,11 @@
 	end);
 	cli = ct.exnkind 'command line parse error';
 	mode = ct.exnkind('bad mode', function(msg, ...)
 		return string.format("mode “%s” "..msg, ...)
 	end);
+	unimpl = ct.exnkind 'feature not implemented';
 }
 
 ct.ctx = declare {
 	mk = function(src) return {src = src} end;
 	ident = 'context';
@@ -197,10 +208,14 @@
 	end;
 	fns = {
 		fail = function(self, msg, ...)
 			ct.exns.tx(msg, self.src.file, self.line or 0, ...):throw()
 		end;
+		insert = function(self, block)
+			block.origin = self:clone()
+			table.insert(self.sec.blocks,block)
+		end;
 		ref = function(self,id)
 			if not id:find'%.' then
 				local rid = self.sec.refs[id]
 				if self.sec.refs[id] then
 					return self.sec.refs[id]
@@ -239,16 +254,61 @@
 			local o = ct.sec(id, depth)
 			if id then self.sections[id] = o end
 			table.insert(self.secorder, o)
 			return o
 		end;
+		context_var = function(self, var, ctx, test)
+			local fail = function(...)
+				if test then return false end
+				ctx:fail(...)
+			end
+			if startswith(var, 'cortav.') then
+				local v = var:sub(8)
+				if v == 'page' then
+					if ctx.page then return tostring(ctx.page)
+						else return '(unpaged)' end
+				elseif v == 'renderer' then
+					if not self.stage then
+						return fail 'document is not being rendererd'
+					end
+					return self.stage.format
+				elseif v == 'datetime' then
+					return os.date()
+				elseif v == 'time' then
+					return os.date '%H:%M:%S'
+				elseif v == 'date' then
+					return os.date '%A %d %B %Y'
+				elseif v == 'id' then
+					return 'cortav.lua (reference implementation)'
+				elseif v == 'file' then
+					return self.src.file
+				else
+					return fail('unimplemented predefined variable %s', var)
+				end
+			elseif startswith(var, 'env.') then
+				local v = var:sub(5)
+				local val = os.getenv(v)
+				if not val then
+					return fail('undefined environment variable %s', v)
+				end
+			elseif self.stage.kind == 'render' and startswith(var, self.stage.format..'.') then
+				-- TODO query the renderer somehow
+				return fail('renderer %s does not implement variable %s', self.stage.format, var)
+			elseif self.vars[var] then
+				return self.vars[var]
+			else
+				if test then return false end
+				return '' -- is this desirable behavior?
+			end
+		end;
 	};
 	mk = function() return {
 		sections = {};
 		secorder = {};
 		embed = {};
 		meta = {};
+		vars = {};
 	} end;
 }
 
 local function map(fn, lst)
 	local new = {}
@@ -268,10 +328,11 @@
 		return string.format(str, ...)
 	end
 end
 
 function ct.render.html(doc, opts)
+	local doctitle = opts['title']
 	local f = string.format
 	local ids = {}
 	local canonicalID = {}
 	local function getSafeID(obj)
 		if canonicalID[obj] then
@@ -309,14 +370,29 @@
 		python = { color = 0xffd277 };
 		python = { color = 0xcdd6ff };
 	}
 
 	local stylesets = {
+		accent = [[
+			body { background: @bg; color: @fg }
+			a[href] {
+				color: @tone(0.7 30);
+				text-decoration-color: @tone/0.4(0.7 30);
+			}
+			a[href]:hover {
+				color: @tone(0.9 30);
+				text-decoration-color: @tone/0.7(0.7 30);
+			}
+			h1,h2,h3,h4,h5,h6 {
+				color: @tone(2);
+				border-bottom: 1px solid @tone(0.7);
+			}
+		]];
 		code = [[
 			code {
-				background: #000;
-				color: #fff;
+				background: @fg;
+				color: @bg;
 				font-family: monospace;
 				font-size: 90%;
 				padding: 3px 5px;
 			}
 		]];
@@ -325,16 +401,17 @@
 		]];
 		editors_markup = [[]];
 		block_code_listing = [[
 			section > figure.listing {
 				font-family: monospace;
-				background: #000;
-				color: #fff;
+				background: @tone(0.05);
+				color: @fg;
 				padding: 0;
 				margin: 0.3em 0;
 				counter-reset: line-number;
 				position: relative;
+				border: 1px solid @fg;
 			}
 			section > figure.listing>div {
 				white-space: pre-wrap;
 				counter-increment: line-number;
 				text-indent: -2.3em;
@@ -343,29 +420,29 @@
 			section > figure.listing>:is(div,hr)::before {
 				width: 1.0em;
 				padding: 0.2em 0.4em;
 				text-align: right;
 				display: inline-block;
-				background-color: #333;
-				border-right: 1px solid #fff;
+				background-color: @tone(0.2);
+				border-right: 1px solid @fg;
 				content: counter(line-number);
 				margin-right: 0.3em;
 			}
 			section > figure.listing>hr::before {
-				color: #333;
+				color: transparent;
 				padding-top: 0;
 				padding-bottom: 0;
 			}
 			section > figure.listing>div::before {
-				color: #fff;
+				color: @fg;
 			}
 			section > figure.listing>div:last-child::before {
 				padding-bottom: 0.5em;
 			}
 			section > figure.listing>figcaption:first-child {
 				border: none;
-				border-bottom: 1px solid #fff;
+				border-bottom: 1px solid @fg;
 			}
 			section > figure.listing>figcaption::after {
 				display: block;
 				float: right;
 				font-weight: normal;
@@ -373,14 +450,14 @@
 				font-size: 70%;
 				padding-top: 0.3em;
 			}
 			section > figure.listing>figcaption {
 				font-family: sans-serif;
-				font-weight: bold;
-				font-size: 130%;
+				font-size: 120%;
 				padding: 0.2em 0.4em;
 				border: none;
+				color: @tone(2);
 			}
 			section > figure.listing > hr {
 				border: none;
 				margin: 0;
 				height: 0.7em;
@@ -415,33 +492,62 @@
 				end
 			end
 			return table.concat(text)
 		end
 
-		function span_renderers.format(sp)
+		function span_renderers.format(sp,...)
 			local tags = { strong = 'strong', emph = 'em', strike = 'del', insert = 'ins', literal = 'code' }
 			if sp.style == 'literal' and not opts['fossil-uv'] then
 				stylesNeeded.code = true
 			end
 			if sp.style == 'del' or sp.style == 'ins' then
 				stylesNeeded.editors_markup = true
 			end
-			return tag(tags[sp.style],nil,htmlSpan(sp.spans))
+			return tag(tags[sp.style],nil,htmlSpan(sp.spans,...))
 		end
 
-		function span_renderers.term(t,b)
+		function span_renderers.term(t,b,s)
 			local r = b.origin:ref(t.ref)
 			local name = t.ref
 			if name:find'%.' then name = name:match '^[^.]*%.(.+)$' end
 			if type(r) ~= 'string' then
 				b.origin:fail('%s is an object, not a reference', t.ref)
 			end
 			stylesNeeded.abbr = true
-			return tag('abbr',{title=r},next(t.spans) and htmlSpan(t.spans) or name)
+			return tag('abbr',{title=r},next(t.spans) and htmlSpan(t.spans,b,s) or name)
 		end
 
-		function span_renderers.link(sp,b)
+		function span_renderers.macro(m,b,s)
+			local r = b.origin:ref(m.macro)
+			if type(r) ~= 'string' then
+				b.origin:fail('%s is an object, not a reference', t.ref)
+			end
+			local mctx = b.origin:clone()
+			mctx.invocation = m
+			return htmlSpan(ct.parse_span(r, mctx),b,s)
+		end
+
+		function span_renderers.var(v,b,s)
+			local val
+			if v.pos then
+				if not v.origin.invocation then
+					v.origin:fail 'positional arguments can only be used in a macro invocation'
+				elseif not v.origin.invocation.args[v.pos] then
+					v.origin:fail('macro invocation %s missing positional argument #%u', v.origin.invocation.macro, v.pos)
+				end
+				val = v.origin.invocation.args[v.pos]
+			else
+				val = v.origin.doc:context_var(v.var, v.origin)
+			end
+			if v.raw then
+				return val
+			else
+				return htmlSpan(ct.parse_span(val, v.origin), b, s)
+			end
+		end
+
+		function span_renderers.link(sp,b,s)
 			local href
 			if b.origin.doc.sections[sp.ref] then
 				href = '#' .. sp.ref
 			else
 				if sp.addr then href = sp.addr else
@@ -449,11 +555,11 @@
 					if type(r) == 'table' then
 						href = '#' .. getSafeID(r)
 					else href = r end
 				end
 			end
-			return tag('a',{href=href},next(sp.spans) and htmlSpan(sp.spans) or href)
+			return tag('a',{href=href},next(sp.spans) and htmlSpan(sp.spans,b,s) or href)
 		end
 		return {
 			span_renderers = span_renderers;
 			htmlSpan = htmlSpan;
 			htmlDoc = htmlDoc;
@@ -488,10 +594,19 @@
 		end
 
 		local block_renderers = {
 			paragraph = function(b,s)
 				return tag('p', nil, sr.htmlSpan(b.spans, b, s), b)
+			end;
+			directive = function(b,s)
+				-- deal with renderer directives
+				local _, cmd, args = b.words(2)
+				if cmd == 'page-title' then
+					if not opts.title then doctitle = args end
+				elseif b.critical then
+					b.origin:fail('critical HTML renderer directive “%s” not supported', cmd)
+				end
 			end;
 			label = function(b,s)
 				if ct.sec.is(b.captions) then
 					local h = math.min(6,math.max(1,b.captions.depth))
 					return tag(f('h%u',h), nil, sr.htmlSpan(b.spans, b, s), b)
@@ -525,11 +640,11 @@
 					end
 				end, b.lines)
 				if b.title then
 					table.insert(nodes,1,tag('figcaption',nil,sr.htmlSpan(b.title)))
 				end
-				langsused[b.lang] = true
+				if b.lang then langsused[b.lang] = true end
 				return tag('figure', {class='listing', lang=b.lang, id=b.id and getSafeID(b)}, catenate(nodes))
 			end;
 			['break'] = function() --[[nop]] end;
 		}
 		return block_renderers;
@@ -556,11 +671,10 @@
 	end
 	local tag = function(t,attrs,body)
 		return f('%s%s</%s>', elt(t,attrs), body, t)
 	end
 
-	local doctitle
 	local ir = {}
 	local toc
 	local dr = getRenderers(tag,elt,table.concat) -- default renderers
 	local plainr = getRenderers(function(t,a,v) return v  end,
 	                            function(t,a)   return '' end, table.concat)
@@ -684,14 +798,76 @@
 		stylesets.block_code_listing = stylesets.block_code_listing .. string.format(
 			[[section > figure.listing[lang="%s"]>figcaption::after
 				{ content: '%s'; color: #%06x }]],
 			k, spec.name or k, spec.color)
 	end
+
+	local prepcss = function(css)
+		local tone = function(fac, sat, sep, alpha)
+			local hsl = function(h,s,l,a)
+				local v = string.format('%s, %u%%, %u%%', h,s,l)
+				if a then
+					return string.format('hsla(%s, %s)', v,a)
+				else
+					return string.format('hsl(%s)', v)
+				end
+			end
+			sat = sat or 1
+			fac = math.max(math.min(fac, 1), 0)
+			sat = math.max(math.min(sat, 1), 0)
+			if opts.accent then
+				local hue = 'var(--accent)'
+				local hsep = tonumber(opts['hue-spread'])
+				if hsep and sep and sep ~= 0 then
+					hue = string.format('calc(%s - %s)', hue, sep * hsep)
+				end
+				return hsl(hue, math.floor(100*sat), math.floor(100*fac), alpha)
+			else
+				local g = math.floor(0xFF * fac)
+				return string.format('#' .. string.rep('%02x',alpha and 4 or 3), g,g,g,alpha and math.floor(0xFF*alpha))
+			end
+		end
+		local replace = function(var,alpha,param)
+			local tonespan = opts.accent and .1 or 0
+			local tbg = opts['dark-on-light'] and 1.0 - tonespan or tonespan
+			local tfg = opts['dark-on-light'] and tonespan or 1.0 - tonespan
+			if var == 'bg' then
+				return tone(tbg,nil,nil,tonumber(alpha))
+			elseif var == 'fg' then
+				return tone(tfg,nil,nil,tonumber(alpha))
+			elseif var == 'tone' then
+				local l, sep, sat
+				for i=1,3 do -- 🙄
+					l,sep,sat = param:match('^%('..string.rep('([^%s]*)%s*',i)..'%)$')
+					if l then break end
+				end
+				l = lerp(tonumber(l), tbg, tfg)
+				return tone(l, tonumber(sat), tonumber(sep), tonumber(alpha))
+			end
+		end
+		css = css:gsub('@(%w+)/([0-9.]+)(%b())', replace)
+		css = css:gsub('@(%w+)(%b())', function(a,b) return replace(a,nil,b) end)
+		css = css:gsub('@(%w+)/([0-9.]+)', replace)
+		css = css:gsub('@(%w+)', function(a,b) return replace(a,nil,b) end)
+		return (css:gsub('%s+',' '))
+	end
 
 	local styles = {}
+	if opts.width then
+		table.insert(styles, string.format([[body {padding:0 1em;margin:auto;max-width:%s}]], opts.width))
+	end
+	if opts.accent then
+		table.insert(styles, string.format(':root {--accent:%s}', opts.accent))
+	end
+	if opts.accent or (not opts['dark-on-light']) then
+		stylesNeeded.accent = true
+	end
+
+
 	for k in pairs(stylesNeeded) do
-		table.insert(styles, (stylesets[k]:gsub('%s+',' ')))
+		if not stylesets[k] then ct.exns.unimpl('styleset %s not implemented (!)',  k):throw() end
+		table.insert(styles, prepcss(stylesets[k]))
 	end
 
 	local head = {}
 	local styletag = ''
 	if opts['link-css'] then
@@ -713,15 +889,10 @@
 	else
 		return dr.htmlDoc(doctitle, next(head) and table.concat(head), body)
 	end
 end
 
-local function
-startswith(str, pfx)
-	return string.sub(str, 1, #pfx) == pfx
-end
-
 local function eachcode(str, ascode)
 	local pos = {
 		code = 1;
 		byte = 1;
 	}
@@ -742,65 +913,84 @@
 		pos.code = pos.code + 1
 		return thischar, lastpos
 	end
 end
 
-local function formatter(sty)
-	return function(s,c)
-		return {
-			kind = 'format';
-			style = sty;
-			spans = ct.parse_span(s, c);
-			origin = c:clone();
-		}
-	end
-end
-ct.spanctls = {
-	{seq = '$', parse = formatter 'literal'};
-	{seq = '!', parse = formatter 'emph'};
-	{seq = '*', parse = formatter 'strong'};
-	{seq = '\\', parse = function(s, c) -- raw
-		return s
-	end};
-	{seq = '$\\', parse = function(s, c) -- raw
-		return {
-			kind = 'format';
-			style = 'literal';
-			spans = {s};
-			origin = c:clone();
-		}
-	end};
-	{seq = '&', parse = function(s, c)
-		local r, t = s:match '^([^%s]+)%s*(.-)$'
-		return {
-			kind = 'term';
-			spans = (t and t ~= "") and ct.parse_span(t, c) or {};
-			ref = r; 
-			origin = c:clone();
-		}
-	end};
-	{seq = '^', parse = function(s, c)
-		local fn, t = s:match '^([^%s]+)%s*(.-)$'
-		return {
-			kind = 'footnote';
-			spans = (t and t~='') and ct.parse_span(t, c) or {};
-			ref = fn;
-			origin = c:clone();
-		}
-	end};
-	{seq = '>', parse = function(s, c)
+do -- define span control sequences
+	local function formatter(sty)
+		return function(s,c)
+			return {
+				kind = 'format';
+				style = sty;
+				spans = ct.parse_span(s, c);
+				origin = c:clone();
+			}
+		end
+	end
+	local function insert_link(s, c)
 		local to, t = s:match '^([^%s]+)%s*(.-)$'
 		if not to then c:fail('invalid link syntax >%s', s) end
 		if t == "" then t = nil end
 		return {
 			kind = 'link';
 			spans = (t and t~='') and ct.parse_span(t, c) or {};
 			ref = to;
 			origin = c:clone();
 		}
-	end};
-}
+	end
+	local function insert_var_ref(raw)
+		return function(s, c)
+			local pos = tonumber(s)
+			return {
+				kind = 'var';
+				pos = pos;
+				raw = raw;
+				var = not pos and s or nil;
+				origin = c:clone();
+			}
+		end
+	end
+	ct.spanctls = {
+		{seq = '$', parse = formatter 'literal'};
+		{seq = '!', parse = formatter 'emph'};
+		{seq = '*', parse = formatter 'strong'};
+		{seq = '\\', parse = function(s, c) -- raw
+			return s
+		end};
+		{seq = '$\\', parse = function(s, c) -- raw
+			return {
+				kind = 'format';
+				style = 'literal';
+				spans = {s};
+				origin = c:clone();
+			}
+		end};
+		{seq = '&', parse = function(s, c)
+			local r, t = s:match '^([^%s]+)%s*(.-)$'
+			return {
+				kind = 'term';
+				spans = (t and t ~= "") and ct.parse_span(t, c) or {};
+				ref = r; 
+				origin = c:clone();
+			}
+		end};
+		{seq = '^', parse = function(s, c)
+			local fn, t = s:match '^([^%s]+)%s*(.-)$'
+			return {
+				kind = 'footnote';
+				spans = (t and t~='') and ct.parse_span(t, c) or {};
+				ref = fn;
+				origin = c:clone();
+			}
+		end};
+		{seq = '>', parse = insert_link};
+		{seq = '→', parse = insert_link};
+		{seq = '🔗', parse = insert_link};
+		{seq = '##', parse = insert_var_ref(true)};
+		{seq = '#', parse = insert_var_ref(false)};
+	}
+end
 
 function ct.parse_span(str,ctx)
 	local function delimited(start, stop, s)
 		local depth = 0
 		if not startswith(s, start) then return nil end
@@ -818,11 +1008,11 @@
 					ctx:fail('out of place %s', stop)
 				end
 			end
 		end
 
-		ctx:fail('%s expected before end of line', stop)
+		ctx:fail('[%s] expected before end of line', stop)
 	end
 	local buf = ""
 	local spans = {}
 	local function flush()
 		if buf ~= "" then
@@ -835,10 +1025,42 @@
 		if skip == true then
 			skip = false
 			buf = buf .. c
 		elseif c == '\\' then
 			skip = true
+		elseif c == '{' then
+			flush()
+			local substr, following = delimited('{','}',str:sub(p.byte))
+			local splitstart, splitstop = substr:find'%s+'
+			local id, argstr
+			if splitstart then
+				id, argstr = substr:sub(1,splitstart-1), substr:sub(splitstop+1)
+			else
+				id, argstr = substr, ''
+			end
+			local o = {
+				kind = 'macro';
+				macro = id;
+				args = {};
+				origin = ctx:clone();
+			}
+
+			do local start = 1
+				local i = 1
+				while i <= #argstr do
+					while i<=#argstr and (argstr:sub(i,i) ~= '|' or argstr:sub(i-1,i) == '\\|') do
+						i = i + 1
+					end
+					local arg = argstr:sub(start, i == #argstr and i or i-1)
+					start = i+1
+					table.insert(o.args, arg)
+					i = i + 1
+				end
+			end
+
+			p.next.byte = p.next.byte + following - 1
+			table.insert(spans,o)
 		elseif c == '[' then
 			flush()
 			local substr, following = delimited('[',']',str:sub(p.byte))
 			p.next.byte = following + p.byte
 			local found = false
@@ -944,26 +1166,51 @@
 	end;
 }
 
 local function insert_table_row(l,c)
 	local row = {}
-	for kind, a1, text, a2 in l:gmatch '([+|])(:?)%s*([^:+|]*)%s*(:?)' do
-		local header = kind == '+'
-		local align
-		if     a1 == ':' and a2 ~= ':' then
-			align = 'left'
-		elseif a1 == ':' and a2 == ':' then
-			align = 'center'
-		elseif a1 ~= ':' and a2 == ':' then
-			align = 'right'
-		end
-		text = text:match '^%s*(.-)%s*$'
-		table.insert(row, {
-			spans = ct.parse_span(text, c);
-			align = align;
-			header = header;
-		})
+	local buf
+	local flush = function()
+		if buf then table.insert(row, buf) end
+		buf = { str = '' }
+	end
+	for c,p in eachcode(l) do
+		if c == '|' or c == '+' and (p.code == 1 or l:sub(p.byte-1,p.byte-1)~='\\') then
+			flush()
+			buf.header = c == '+'
+		elseif c == ':' then
+			local lst = l:sub(p.byte-#c,p.byte-#c)
+			local nxt = l:sub(p.next.byte,p.next.byte)
+			if lst == '|' or lst == '+' and l:sub(p.byte-2,p.byte-2) ~= '\\' then
+				buf.align = 'left'
+			elseif nxt == '|' or nxt == '|' then
+				if buf.align == 'left' then
+					buf.align = 'center'
+				else
+					buf.align = 'right'
+				end
+			else
+				buf.str = buf.str .. c
+			end
+		elseif c:match '%s' then
+			if buf.str ~= '' then buf.str = buf.str .. c end
+		elseif c == '\\' then
+			local nxt = l:sub(p.next.byte,p.next.byte)
+			if nxt == '|' or nxt == '+' or nxt == ':' then
+				buf.str = buf.str .. nxt
+				p.next.byte = p.next.byte + #nxt
+				p.next.code = p.next.code + 1
+			else
+				buf.str = buf.str .. c
+			end
+		else
+			buf.str = buf.str .. c
+		end
+	end
+	if buf.str ~= '' then flush() end 
+	for _,v in pairs(row) do
+		v.spans = ct.parse_span(v.str, c)
 	end
 	if #c.sec.blocks > 1 and c.sec.blocks[#c.sec.blocks].kind == 'table' then
 		local tbl = c.sec.blocks[#c.sec.blocks]
 		table.insert(tbl.rows, row)
 	else
@@ -976,10 +1223,11 @@
 end
 
 ct.ctlseqs = {
 	{seq = '.', fn = insert_paragraph};
 	{seq = '¶', fn = insert_paragraph};
+	{seq = '❡', fn = insert_paragraph};
 	{seq = '#', fn = insert_section};
 	{seq = '§', fn = insert_section};
 	{seq = '+', fn = insert_table_row};
 	{seq = '|', fn = insert_table_row};
 	{seq = '│', fn = insert_table_row};
@@ -1007,18 +1255,26 @@
 			if i == 0 then return cmdline end
 			for w,pos in cmdline:gmatch '([^%s]+)()' do
 				table.insert(wds, w)
 				i = i - 1
 				if i == 0 then
-					return table.unpack(wds), cmdline:sub(pos)
+					table.insert(wds,cmdline:sub(pos))
+					return table.unpack(wds)
 				end
 			end
 		end
 
 		local cmd, rest = words(1)
 		if ct.directives[cmd] then
 			ct.directives[cmd](words,c)
+		elseif cmd == c.doc.stage.mode['render:format'] then
+			-- this is a directive for the renderer; insert it into the tree as is
+			c:insert {
+				kind = 'directive';
+				critical = crit == '!';
+				words = words;
+			}
 		elseif crit == '!' then
 			c:fail('critical directive %s not supported',cmd)
 		end
 	end;};
 	{seq = '~~~', fn = blockwrap(function(l,c)
@@ -1032,11 +1288,11 @@
 		local lang, id, title
 		if l:match '^~~~%s*$' then -- no args
 		elseif l:match '^~~~.*~~~%s*$' then -- CT style
 			local s = l:match '^~~~%s*(.-)%s*~~~%s*$'
 			lang, s = extract('%b[]', s)
-			lang = lang:sub(2,-2)
+			if lang then lang = lang:sub(2,-2) end
 			id, title = extract('#[^%s]+', s)
 			if id then id = id:sub(2) end
 		elseif l:match '^~~~' then -- MD shorthand style
 			lang = l:match '^~~~%s*(.-)%s*$'
 		end
@@ -1069,19 +1325,24 @@
 		return { kind = 'horiz-rule' }
 	end)};
 	{fn = insert_paragraph};
 }
 
-function ct.parse(file, src)
+function ct.parse(file, src, mode)
 	local function
 	is_whitespace(cp)
 		return cp == 0x20
 	end
 
 	local ctx = ct.ctx.mk(src)
 	ctx.line = 0
 	ctx.doc = ct.doc.mk()
+	ctx.doc.src = src
+	ctx.doc.stage = {
+		kind = 'parse';
+		mode = mode;
+	}
 	ctx.sec = ctx.doc:mksec() -- toplevel section
 	ctx.sec.origin = ctx:clone()
 
 	for full_line in file:lines() do ctx.line = ctx.line + 1
 		local l
@@ -1155,30 +1416,42 @@
 	end
 	return new
 end
 
 local function main(input, output, log, mode, vars)
-	local doc = ct.parse(input.stream, input.src)
+	local doc = ct.parse(input.stream, input.src, mode)
 	input.stream:close()
 	if mode['parse:show-tree'] then
 		log:write(dump(doc))
 	end
 
 	if not mode['render:format'] then
 		error 'what output format should i translate the input to?'
 	end
+	if mode['render:format'] == 'none' then return 0 end
 	if not ct.render[mode['render:format']] then
-		error(string.format('output format “%s” unsupported', mode['render:format']))
+		ct.exns.unimpl('output format “%s” unsupported', mode['render:format']):throw()
 	end
 	
 	local render_opts = kmap(function(k,v)
 		return k:sub(2+#mode['render:format'])
 	end, kfilter(mode, function(m)
 		return startswith(m, mode['render:format']..':')
 	end))
+
+	doc.vars = vars
+	
+	-- this is kind of gross but the context object belongs to the parser,
+	-- not the renderer, so that's not a suitable place for this information
+	doc.stage = {
+		kind = 'render';
+		format = mode['render:format'];
+		mode = mode;
+	}
 
 	output:write(ct.render[mode['render:format']](doc, render_opts))
+	return 0
 end
 
 local inp,outp,log = io.stdin, io.stdout, io.stderr
 
 local function entry_cli()
@@ -1229,11 +1502,14 @@
 			if nf then log:close() log = nf else
 				ct.exns.io('could not open log file for writing', 'open',file):throw()
 			end
 		end;
 		define = function(key,value)
-			-- set context key
+			if startswith(key, 'cortav.') or startswith(key, 'env.') then
+				ct.exns.cli 'cannot define variable in restricted namespace':throw()
+			end
+			vars[key] = value
 		end;
 		mode = function(key,value) mode[checkmodekey(key)] = value end;
 		['mode-set'] = function(key) mode[checkmodekey(key)] = true end;
 		['mode-clear'] = function(key) mode[checkmodekey(key)] = false end;
 	}
@@ -1289,17 +1565,20 @@
 		if not file then error('unable to load file ' .. args[1]) end
 		input.stream = file
 		input.src.file = args[1]
 	end
 
-	main(input, outp, log, mode, vars)
+	return main(input, outp, log, mode, vars)
 end
 
--- local ok, e = pcall(entry_cli)
-local ok, e = true, entry_cli()
+local ok, e = pcall(entry_cli)
+-- local ok, e = true, entry_cli()
 if not ok then
 	local str = 'translation failure'
+	if ct.exn.is(e) then
+		str = e.kind.desc
+	end
 	local color = false
 	if log:seek() == nil then
 		-- this is not a very reliable heuristic for detecting
 		-- attachment to a tty but it's better than nothing
 		if os.getenv('COLORTERM') then
@@ -1310,8 +1589,9 @@
 		end
 	end
 	if color then
 		str = string.format('\27[1;31m%s\27[m', str)
 	end
-	log:write(string.format('[%s] %s\n\t%s\n', os.date(), str, e))
+	log:write(string.format('%s: %s\n', str, e))
 	os.exit(1)
 end
+os.exit(e)

ADDED   makefile
Index: makefile
==================================================================
--- makefile
+++ makefile
@@ -0,0 +1,7 @@
+lua != which lua
+luac != which luac
+
+cortav: cortav.lua
+	echo '#!$(lua)' > $@
+	luac -s -o - $< >> $@
+	chmod +x $@