cortav  Check-in [7ba2577283]

local ct = require 'cortav'
local ss = require 'sirsem'

local default_mode = {
	['render:format'] = 'html';
	['html:gen-styles'] = true;

}

local function
main(input, output, log, mode, suggestions, vars, extrule)
	local doc = ct.parse(input.stream, input.src, mode, function(c)
		                     c.doc.ext = extrule
	                     end)
................................................................................
	local render_opts = ss.kmap(function(k,v)
		return k:sub(2+#mode['render:format'])
	end, ss.kfilter(mode, function(m)
		return ss.str.begins(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;
		suggestions = suggestions;
	}

	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()
	local suggestions, vars, input = default_mode, {}, {

-- [ʞ] cli.lua
--  ~ lexi hale <lexi@hale.su>
--  🄯 AGPLv3
--  ? simple command line driver for the cortav library
local ct = require 'cortav'
local ss = require 'sirsem'

local default_mode = {
	['render:format'] = 'html';
	['html:gen-styles'] = true;
	['groff:color'] = true;
}

local function
main(input, output, log, mode, suggestions, vars, extrule)
	local doc = ct.parse(input.stream, input.src, mode, function(c)
		                     c.doc.ext = extrule
	                     end)
................................................................................
	local render_opts = ss.kmap(function(k,v)
		return k:sub(2+#mode['render:format'])
	end, ss.kfilter(mode, function(m)
		return ss.str.begins(m, mode['render:format']..':')
	end))

	doc.vars = vars





	output:write(ct.render[mode['render:format']](
		doc, render_opts, function(stage)
			stage.mode = mode




		end))
	return 0
end

local inp,outp,log = io.stdin, io.stdout, io.stderr

local function entry_cli()
	local suggestions, vars, input = default_mode, {}, {

* [*paragraphs] ([`.] [` ¶] [`❡]): a paragraph is a simple block of text. the period control sequence is only necessary if the paragraph text starts with text that would be interpreted as a control sequence otherwise
* 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".
** [`#anchor header] opens a new section with both the ID [`anchor] and the title "header".
** [`#>conversation] opens a blockquote section named [`conversation] without a header.
** [`#&id mime] opens a new inline object [`id] of type [`mime]. useful for embedding SVGs. the ID and mime type must be specified.
* [*nonprinting sections] ([`^]): sometimes, you'll want to create a namespace without actually adding a visible new section to the document. you can achieve this by creating a [!nonprinting section] and defining resources within it. nonprinting sections can also be used to store comments, notes, or other information that is useful to have in the source file without it becoming a part of the output
* [*resource] ([`@]): defines a [!resource]. a resource is an file or object that exists outside of the document but which will be included in the document somehow. common examples of resources include images, videos, iframes, or headers/footers. see [>rsrc resources] for more information.
* [*lists] ([`*] [`:]): these are like paragraph nodes, but list nodes that occur next to each other will be arranged so as to show they compose a sequence. depth is determined by the number of stars/colons. like headers, a list entry may have an ID that can be used to refer back to it; it is indicated in the same way. if colons are used, this indicates that the order of the items is signifiant. :-lists and *-lists may be intermixed; however, note than only the last character in the sequence actually controls the depth type.
* [*directives] ([`%]): a directive issues a hint to the renderer in the form of an arbitrary string. directives are normally ignored if they are not supported, but you may cause a warning to be emitted where the directive is not supported with [`%!] or mark a directive critical with [`%!!] so that rendering will entirely fail if it cannot be parsed.
* [*comments] ([`%%]): a comment is a line of text that is simply ignored by the renderer.
* [*asides] ([`!]): indicates text that diverges from the narrative, and can be skipped without interrupting it. think of it like block-level parentheses. asides which follow one another are merged as paragraphs of the same aside, usually represented as a sort of box. if the first line of an aside contains a colon, the stretch of styled-text from the beginning to the aside to the colon will be treated as a "type heading," e.g. "Warning:"
* [*code] ([`~~~]): a line beginning with ~~~ begins or terminates a block of code. code blocks are by default not parsed, but parsing can be activated by preceding the code block with an [`%[*expand]] directive. the opening line should look like one of the below
................................................................................
* strikeout {obj ~|styled-text}: indicates that its text should be struck through or otherwise indicated for deletion
* insertion {obj +|styled-text}: indicates that its text should be indicated as a new addition to the text body.
** consider using a macro definition [`\edit: [~[#1]][+[#2]]] to save typing if you are doing editing work
* 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 {span ^|ref|[$styled-text]}: annotates the text with a defined footnote. in interactive output media [`\[^citations.qtheo Quantum Theosophy: A Neophyte's Catechism]] will insert a link with the next [`Quantum Theosophy: A Neophyte's Catechism] that, when clicked, causes a footnote to pop up on the screen. for static output media, the text will simply have a superscript integer after it denoting where the footnote is to be found.
* superscript {obj '|[$styled-text]}
* subscript {obj ,|[$styled-text]}
* raw {obj \\ |[$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 {obj #|var}: in macros only, inserts the [$var]-th argument. otherwise, inserts a context variable provided by the renderer.
* raw argument {obj ##|var}: like above, but does not evaluate [$var].
* term {obj &|name}, {span &|name|[$expansion]}: quotes a defined term with a link to its definition, optionally with a custom expansion of the term (for instance, to expand the first use of an acronym)
* inline image {obj &@|name}: shows a small image or other object inline. the unicode character [`🖼] can also be used instead of [`&@].
* unicode codepoint {obj U+|hex-integer}: inserts an arbitrary UCS codepoint in the output, specified by [$hex-integer]. lowercase [`u] is also legal.
................................................................................
<p>here is the resource in span context: <span class="res-smiley"></span></p>
<p>and here it is in block context:</p>
<div class=".res-smiley"></div>
~~~

note that empty elements with CSS classes are used in the output, to avoid repeating long image definitions (especially base64 inline encoded ones!)



























































### supported parameters
* [`src] (all): specifies where to find the file, what it is, and how to embed it. each line of [`src] should consist of three whitespace-separated words: embed method, MIME type, and URI.
** embed methods
*** [`local]: loads the resource at build time and embeds it into the output file. not all implementations may allow loading remote network resources at build time.
*** [`remote]: only embeds a reference to the location of the resource. use this for e.g. live iframes, dynamic images, or images hosted by a CDN.
*** [`auto]: embeds a reference in file formats where that's practical, and use a remote reference otherwise.
** MIME types: which file types are supported depends on the individual implementation and renderer backend; additionally, extensions can add support for extra types. MIME-types that have no available handler will, where possible, result in an attachment that can be extracted by the user, usually by clicking on a link. however, the following should be usable with all compliant implementations
................................................................................
*** [`video/*] (interactive outputs only)
*** [`image/svg+xml] is handled specially for HTML files, and may or may not be compatible with other renderer backends.
*** [`font/*] can be used with the HTML backend to reference a web font
*** [`font/woff2] can be used with the HTML backend to reference a web font
*** [`text/plain] (will be inserted as a preformatted text block)
*** [`text/css] (can be used when producing HTML files to link in an extra stylesheet, either by embedding it or referencing it from the header)
*** [`text/x-cortav] (will be parsed and inserted as a formatted text block; context variables can be passed to the file with [`ctx.[$var]] parameters)


*** any MIME-type that matches the type of file being generated by the renderer can be used to include a block of data that will be passed directly to the renderer.
** URI types: additional URI types can be added by extensions or different implementations, but every compliant implementation must support these URIs.
*** [`http], [`https]: accesses resources over HTTP. add a [`file] fallback if possible for the benefit of renderers/viewers that do not have internet access abilities.
*** [`file]: references local files. absolute paths should begin [`file:/]; the slash should be omitted for relative paths. note that this doesn't have quite the same meaning as in HTML -- [`file] can (and usually should be) used with HTML outputs to refer to resources that reside on the same server. a cortav URI of [`file:/etc/passwd] will actually result in the link [`/etc/passwd], not [`file:///etc/passwd] when converted to HTML. generally, you only should use [`http] when you're referring to a resource that exists on a different domain.
*** [`name]: a special URI used generally for referencing resources that are already installed on a target system and do not need to be embedded or linked, the name and type are enough for a renderer on another machine to locate the correct resource. this is useful mostly for [>fonts fonts], where it's more typical to refer to fonts that are installed on your system rather than providing paths to font files.
*** [`gemini]: accesses resources over the gemini protocol. currently you should really only use this for [`local] resources unless you're using the gemtext renderer backend, since nothing but gemini browsers are liable to support this protocol.
* [`desc]: supplies a narrative description of the resources, for use as an "alt-text" when the image cannot be loaded and for screenreaders.
* [`detail]: supplies extra narrative commentary that is displayed contextually, e.g. when the user hovers her mouse cursor over the embedded object.

note that in certain cases, full MIME types do not need to be used. say you're defining a font with the [`name] URI -- you can't necessary know what file type the system fonts on another computer are going to be. in this case, you can just write [`font] instead of [`font/ttf] or [`font/woff2] or similar. all cortav needs to know in this case is what abstract kind of object you're referencing.


##ctxvar 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 accessed with the [` \[#[$name]\]] span.

* {def cortav.file} the name of the file currently being rendered
* {def cortav.path} the absolute path of the file currently being rendered
................................................................................
	font-family: "fontdef-sans";
	src: local("Alegreya Sans"),
		local("Open Sans"),
		local("sans-serif");
}
~~~

there are two things that aren't super clear from the CSS, however. notice how we used [`auto] on a couple of those specs? this means it's up to the renderer to decide whether to link or embed the font. for html, a font specified by name can't really be embedded, but for some file formats, it can be. [`auto] lets us produce valid HTML while still taking advantage of font embedding in other formats.

now that we have our font families defined, we can use their identifiers with the [`%[*font]] directive to control the font stack. the first thing we need to do is push a new font context. there's two ways we can do this:
	fnd: [`%[*font] [#1]]
* {fnd dup} will create a copy of the current font context, allowing us to make some changes and then revert later with the {fnd pop} command. this isn't useful in our case, however, because right now the stack is empty; there's nothing to duplicate.
* {fnd new} will create a brand new empty context for us to work with and push it to the stack. this can also be used to temporarily revert to the system default fonts, and then switch back with {fnd pop}.
* {fnd set} changes one or more entries in the current font context. it can take a space-separated list of arguments in the form [`[$entry]=[$font-id]]. the supported entries are:
** [`body]: the fallback font. if only this is set in a given font context, it will be used for everything
................................................................................
~~~cortav
%% let's pretend we've also defined the fonts 'title', 'cursive', and 'thin'

%font new
%font set body=sans header=serif
%font dup
%font header=title
# lorem ipsum dolor
%font pop

%% we've now set up a default font context, created a new context for the title of the
%% document, and then popped it back off after the title was inserted so that our
%% first font context is active again. everything after that last '%font pop' will
%% be printed in sans, except for headers, which will be printed in 'serif'

lorem ipsum dolor sit amet, sed consectetur apiscing elit…

%font dup
%font set body=cursive
> sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
> Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
%font pop

%% above we created a blockquote whose text is printed in a cursive font; afterwards,
%% we simply remove this new context—

and everything is back the way it was at "lorem ipsum"

%% the font mechanism is at its most powerful when used with multiline macros:

	cursive-quote: %font dup
		%font set body=cursive
		> [#1]
		%font pop

%% now, whenever we want a block with a cursive body, we can simply invoke

&$cursive-quote Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident

%% without affecting the overall font context. in fact, since 'cursive-quote' creates
%% its context using 'dup', it would import all font specifications besides 'body'
%% from the environment it is invoked in
~~~

you may have noticed the rather odd bit at the end of our font definition, with the [`dit] URI. the reasons for this are tragic. groff, while delightful, has a thoroughly antiquated understanding of fonts, and doesn't support normal font formats like truetype. groff ships with a limited number of fonts in its own format, identified by obscurantist letter code ([`HBI] is "Helvetica Bold Italic", for instance) and lacking normal metadata. for this reason, you'll have to tell cortav how you want your fonts translated.
................................................................................
+ encoding-data-ucs-url | where to download UnicodeData.txt from, if encoding-data-ucs is not changed. defaults to the unicode consortium website

#### deterministic builds
some operating systems, like NixOS, require packages that can be built in reproducible ways. this implies that all data, all [!state] that goes into producing a package needs to be accounted for before the build proper begins. the [`cortav] build process needs to be slightly altered to support such a build process.

while the cortav specification itself does not concern itself with matters like whether a particular character is a numeral or a letter, optimal typesetting in some cases requires such information. this is the case for the equation span- and block-types, which need to be able to distinguish between literals, variables, and mathematical symbols in [^alas-math the equations they format]. the ASCII charset is small enough that exhaustive character class information can be manually hardcoded into a cortav implementation, the various encodings of Unicode most certainly are not.

	alas-math: sadly, i was not at any point consulted by any of the generations of mathematicians stretching back into antiquity who devised their notations without any regard for machine-readability. [!for shame!]

for this reason, the reference implementation of cortav embeds the file [`UnicodeData.txt], a database maintained by the Unicode Consortium. this is a rather large file that updates for each new Unicode version, so it is downloaded as part of the build process. to build on NixOS, you'll need to either disable the features that rely on this database (not recommended), or download the database yourself and tell the build script where to find it. this is the approach the official nix expression will take when i can be bothered to write it. see the examples below for how to conduct a deterministic build

~~~ deterministic build with unicode database [sh] ~~~
/src $ mkdir cortav && cd cortav
/src/cortav $ fossil clone https://c.hale.su/cortav .fossil && fossil open .fossil
/src/cortav $ curl https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt > /tmp/unicode.txt
................................................................................
~~~ [sh] deterministic build [!without] unicode database ~~~
/src $ mkdir cortav && cd cortav
/src/cortav $ fossil clone https://c.hale.su/cortav .fossil && fossil open .fossil
/src/cortav $ make build/cortav encoding-data=
~~~

! while most of the data used is taken directly from UnicodeData.txt, the database generated by [`tools/ucs.lua] splices in some extra character information before generating a database. this is partly because certain characters may not be classified in a useful way and need to be manually overwritten. however, the reference implementation also seeks to provide accurate data for certain character sets that are not part of unicode proper and can be expressed in UTF only through its private use areas.
! currently, only the [>corran Corran] script is currently supported in this fashion, but i intend to add [>tengwar Tengwar] as well. if there is a con-script or any other informally encoded script you would like supported by the reference implementation, please open an issue.

[*do note] that no cortav implementation needs to concern itself with character class data. this functionality is provided in the reference implementation strictly as an (optional) extension to the spec to improve usability, not as a normative requirement.

	corran: http://ʞ.cc/fic/spirals/society
	tengwar: https://en.wikipedia.org/wiki/Tengwar

###refimpl-switches switches
................................................................................
* [`@[*fg]]: resolves to a color expression denoting the selected foreground color. equivalent to [`[*tone](1)]
* [`@[*bg]]: resolves to a color expression denoting the selected background color. equivalent to [`[*tone](0)]
* [`@[*tone]\[/[$alpha]\]([$fac] \[[$shift] \[[$saturate]\]\] )]: resolves to a color expression. [$fac] is a floating-point value scaling from the background color to the foreground color. [$shift] is a value in degrees controlling how far the hue will shift relative to the accent. [$saturate] is a floating-point value controlling how satured the color is.

###refimpl-rend-groff groff
the [`groff] backend produces a text file suitable for supplying to a [`groff] compiler. [`groff] is the GNU implementation of a venerable typesetting system from the early days of UNIX

as a convenience, the groff backend supports two modes of operation: it can write a [`groff] file directly to disk, or it can automatically launch a [`groff] process with the appropriate command line options and environment variables. this second mode is recommended unless you're rendering very large files to multiple formats, as [`groff] invocation is nontrivial and it's best to let the renderer handle that for you.







####refimpl-rend-groff-modes modes
[`groff] supports the following modes:

* string [`groff:annotate] controls how footnotes will be handled.
** [`footnote] places footnotes at the end of the page they are referenced on. if the same footnote is used on multiple pages, it will be duplicated on each.
** [`secnote] places footnotes at the end of each section. footnotes used in multiple sections will be duplicated for each
** [`endnote] places all footnotes at the end of the rendered document.
* string [`groff:dev] names an output device (such as [`dvi] or [`pdf]). if this mode is present, [`groff] will be automatically invoked
* string [`groff:title-page] takes an identifier that names a section. this section will be treated as the title page for the document.


### directives
* [`%[*pragma] title-page [$id]] sets the title page to section [$id]. this causes it to be specially formatted, with a large, centered title and subtitle.

### quirks
if the [`toc] extension is active but [`%[*toc]] directive is provided, the table of contents will be given its own section at the start of the document (after the title page, if any).

* [*paragraphs] ([`.] [` ¶] [`❡]): a paragraph is a simple block of text. the period control sequence is only necessary if the paragraph text starts with text that would be interpreted as a control sequence otherwise
* 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".
** [`#anchor header] opens a new section with both the ID [`anchor] and the title "header".


* [*nonprinting sections] ([`^]): sometimes, you'll want to create a namespace without actually adding a visible new section to the document. you can achieve this by creating a [!nonprinting section] and defining resources within it. nonprinting sections can also be used to store comments, notes, or other information that is useful to have in the source file without it becoming a part of the output
* [*resource] ([`@]): defines a [!resource]. a resource is an file or object that exists outside of the document but which will be included in the document somehow. common examples of resources include images, videos, iframes, or headers/footers. see [>rsrc resources] for more information.
* [*lists] ([`*] [`:]): these are like paragraph nodes, but list nodes that occur next to each other will be arranged so as to show they compose a sequence. depth is determined by the number of stars/colons. like headers, a list entry may have an ID that can be used to refer back to it; it is indicated in the same way. if colons are used, this indicates that the order of the items is signifiant. :-lists and *-lists may be intermixed; however, note than only the last character in the sequence actually controls the depth type.
* [*directives] ([`%]): a directive issues a hint to the renderer in the form of an arbitrary string. directives are normally ignored if they are not supported, but you may cause a warning to be emitted where the directive is not supported with [`%!] or mark a directive critical with [`%!!] so that rendering will entirely fail if it cannot be parsed.
* [*comments] ([`%%]): a comment is a line of text that is simply ignored by the renderer.
* [*asides] ([`!]): indicates text that diverges from the narrative, and can be skipped without interrupting it. think of it like block-level parentheses. asides which follow one another are merged as paragraphs of the same aside, usually represented as a sort of box. if the first line of an aside contains a colon, the stretch of styled-text from the beginning to the aside to the colon will be treated as a "type heading," e.g. "Warning:"
* [*code] ([`~~~]): a line beginning with ~~~ begins or terminates a block of code. code blocks are by default not parsed, but parsing can be activated by preceding the code block with an [`%[*expand]] directive. the opening line should look like one of the below
................................................................................
* strikeout {obj ~|styled-text}: indicates that its text should be struck through or otherwise indicated for deletion
* insertion {obj +|styled-text}: indicates that its text should be indicated as a new addition to the text body.
** consider using a macro definition [`\edit: [~[#1]][+[#2]]] to save typing if you are doing editing work
* 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 {span ^|ref|[$styled-text]}: annotates the text with a defined footnote. in interactive output media [`\[^citations.qtheo Quantum Theosophy: A Neophyte's Catechism]] will insert a link with the next [`Quantum Theosophy: A Neophyte's Catechism] that, when clicked, causes a footnote to pop up on the screen. for static output media, the text will simply have a superscript integer after it denoting where the footnote is to be found.
* superscript {obj '|[$styled-text]}
* subscript {obj ,|[$styled-text]}
* raw {obj \\ |[$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, and backslashes.
* raw literal \[$\\[!raw-text]\]: shorthand for [\[$[\…]]]
* macro [`\{[!name] [!arguments]\}]: invokes a [>ex.mac macro], specified with a reference
* argument {obj #|var}: in macros only, inserts the [$var]-th argument. otherwise, inserts a context variable provided by the renderer.
* raw argument {obj ##|var}: like above, but does not evaluate [$var].
* term {obj &|name}, {span &|name|[$expansion]}: quotes a defined term with a link to its definition, optionally with a custom expansion of the term (for instance, to expand the first use of an acronym)
* inline image {obj &@|name}: shows a small image or other object inline. the unicode character [`🖼] can also be used instead of [`&@].
* unicode codepoint {obj U+|hex-integer}: inserts an arbitrary UCS codepoint in the output, specified by [$hex-integer]. lowercase [`u] is also legal.
................................................................................
<p>here is the resource in span context: <span class="res-smiley"></span></p>
<p>and here it is in block context:</p>
<div class=".res-smiley"></div>
~~~

note that empty elements with CSS classes are used in the output, to avoid repeating long image definitions (especially base64 inline encoded ones!)

inline resources are defined a bit differently:

~~~cortav
@smiling-man-business-card text/plain {
	THE SMILING MAN  | tel. 0-Ω00-666█
	if you can read this | email: nameless@smiles.gov
	it is already too late | address: right behind you
}
@smiling-man-business-card image/png;base64 {
	%% incomprehensible gibbering redacted
}
~~~

for an inline resource, the identifier is followed by a MIME type and an opening bracket. the opening bracket may be any of the characters [`\{][`\[][`(][`<], and can optionally be followed by additional characters to help disambiguate the closing bracket. the closing bracket is determined by "flipping" the opening bracket, producing bracket pairs like the following:
* [`\{:][`:}]
* [`<!--] [`--!>]
* [`(*<][`>*)]
* [`<>][`<>] [!(disables nesting!)]
if the open and closing brackets are distinguishable, they will nest appropriately, meaning that [`{][`}] alone is very likely to be a safe choice to escape a syntactically correct C program (that doesn't abuse macros too badly). brackets are searched for during parsing; encoded resources are not decoded until a later stage, so a closing bracket character in a base64-encoded text file cannot break out of its escaping.

as a convenience, if the first line of the resource definition begins with a single tab, one tab will be dropped from every following line in order to allow legible indentation. similarly, if an opening bracket is followed immediately by a newline, this newline is discarded.

text within a resource definition body is not expanded unless the resource definition is preceded with an [`%[*expand]] directive. if an expand directive is found, the MIME type will be used to try and determine an appropriate type of formatting, potentially invoking a separate renderer. for example, [`text/html] will invoke the [`html] backend, and [`application/x-troff] will invoke the [`groff] backend. if no suitable renderer is available, expansions will generate only plain text.

two suffixes are accepted: [`;base64] and [`;hex]. the former will decode the presented strings using the base64 algorithm to obtain the resources data; the second will ignore all characters but ASCII hexadecimal digits and derive the resource data byte-by-byte by reading in hexadecimal pairs. for instance, the following sections are equivalent:

~~~
@propaganda text/plain {
	WORLDGOV SAYS
	“don't waste time with unproductive thoughts
	 your wages will be docked accordingly”
}
~~~
~~~
@propaganda text/plain;hex {
	574f 524c 4447 4f56 2053 4159 530a e280 9c64 6f6e 2774 2077 6173
	7465 2074 696d 6520 7769 7468 2075 6e70 726f 6475 6374 6976 6520
	7468 6f75 6768 7473 0a20 796f 7572 2077 6167 6573 2077 696c 6c20
	6265 2064 6f63 6b65 6420 6163 636f 7264 696e 676c 79e2 809d 0a
}
~~~
~~~
@propaganda text/plain;base64 {
	V09STERHT1YgU0FZUwrigJxkb24ndCB3YXN0ZSB0aW1lIHdpdGggdW5wcm9kdWN0aXZlIHRob3Vn
	aHRzCiB5b3VyIHdhZ2VzIHdpbGwgYmUgZG9ja2VkIGFjY29yZGluZ2x54oCdCg==
}
~~~

inline resources can also be (ab)used for multiline macros:
~~~
@def text/x-cortav {
	* [*[#1]] [!([#2])
	*: [#3]
}
&def nuclear bunker|n|that which will not protect you from the Smiling Man
~~~
to make this usage simpler, resources with a type of [`text/x-cortav] can omit the MIME type field.

### supported parameters
* [`src] (all): specifies where to find the file, what it is, and how to embed it. each line of [`src] should consist of three whitespace-separated words: embed method, MIME type, and URI.
** embed methods
*** [`local]: loads the resource at build time and embeds it into the output file. not all implementations may allow loading remote network resources at build time.
*** [`remote]: only embeds a reference to the location of the resource. use this for e.g. live iframes, dynamic images, or images hosted by a CDN.
*** [`auto]: embeds a reference in file formats where that's practical, and use a remote reference otherwise.
** MIME types: which file types are supported depends on the individual implementation and renderer backend; additionally, extensions can add support for extra types. MIME-types that have no available handler will, where possible, result in an attachment that can be extracted by the user, usually by clicking on a link. however, the following should be usable with all compliant implementations
................................................................................
*** [`video/*] (interactive outputs only)
*** [`image/svg+xml] is handled specially for HTML files, and may or may not be compatible with other renderer backends.
*** [`font/*] can be used with the HTML backend to reference a web font
*** [`font/woff2] can be used with the HTML backend to reference a web font
*** [`text/plain] (will be inserted as a preformatted text block)
*** [`text/css] (can be used when producing HTML files to link in an extra stylesheet, either by embedding it or referencing it from the header)
*** [`text/x-cortav] (will be parsed and inserted as a formatted text block; context variables can be passed to the file with [`ctx.[$var]] parameters)
*** [`application/x-troff] can be used to supply sections of text written in raw [`groff] syntax. these are ignored by other renderers.
*** [`text/html] can be used to supply sections of text written in raw HTML.
*** any MIME-type that matches the type of file being generated by the renderer can be used to include a block of data that will be passed directly to the renderer.
** URI types: additional URI types can be added by extensions or different implementations, but every compliant implementation must support these URIs.
*** [`http], [`https]: accesses resources over HTTP. add a [`file] fallback if possible for the benefit of renderers/viewers that do not have internet access abilities.
*** [`file]: references local files. absolute paths should begin [`file:/]; the slash should be omitted for relative paths. note that this doesn't have quite the same meaning as in HTML -- [`file] can (and usually should be) used with HTML outputs to refer to resources that reside on the same server. a cortav URI of [`file:/etc/passwd] will actually result in the link [`/etc/passwd], not [`file:///etc/passwd] when converted to HTML. generally, you only should use [`http] when you're referring to a resource that exists on a different domain.
*** [`name]: a special URI used generally for referencing resources that are already installed on a target system and do not need to be embedded or linked, the name and type are enough for a renderer on another machine to locate the correct resource. this is useful mostly for [>fonts fonts], where it's more typical to refer to fonts that are installed on your system rather than providing paths to font files.
*** [`gemini]: accesses resources over the gemini protocol. currently you should really only use this for [`local] resources unless you're using the gemtext renderer backend, since nothing but gemini browsers are liable to support this protocol.
* [`desc]: supplies a narrative description of the resources, for use as an "alt-text" when the image cannot be loaded and for screenreaders.
* [`detail]: supplies extra narrative commentary that is displayed contextually, e.g. when the user hovers her mouse cursor over the embedded object. also used for [`desc] if [`desc] is not supplied.

note that in certain cases, full MIME types do not need to be used. say you're defining a font with the [`name] URI -- you can't necessary know what file type the system fonts on another computer are going to be. in this case, you can just write [`font] instead of [`font/ttf] or [`font/woff2] or similar. all cortav needs to know in this case is what abstract kind of object you're referencing. [`groff] fonts (referenced with the [`dit] URI) don't have a specific MIME type either.


##ctxvar 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 accessed with the [` \[#[$name]\]] span.

* {def cortav.file} the name of the file currently being rendered
* {def cortav.path} the absolute path of the file currently being rendered
................................................................................
	font-family: "fontdef-sans";
	src: local("Alegreya Sans"),
		local("Open Sans"),
		local("sans-serif");
}
~~~

there are two things that aren't super clear from the CSS, however. notice how we used [`auto] on a couple of those specs? this means it's up to the renderer to decide whether to link or embed the font. in HTML, a font specified by name can't really be embedded, but for some file formats, it can be. [`auto] lets us produce valid HTML while still taking advantage of font embedding in other formats.

now that we have our font families defined, we can use their identifiers with the [`%[*font]] directive to control the font stack. the first thing we need to do is push a new font context. there's two ways we can do this:
	fnd: [`%[*font] [#1]]
* {fnd dup} will create a copy of the current font context, allowing us to make some changes and then revert later with the {fnd pop} command. this isn't useful in our case, however, because right now the stack is empty; there's nothing to duplicate.
* {fnd new} will create a brand new empty context for us to work with and push it to the stack. this can also be used to temporarily revert to the system default fonts, and then switch back with {fnd pop}.
* {fnd set} changes one or more entries in the current font context. it can take a space-separated list of arguments in the form [`[$entry]=[$font-id]]. the supported entries are:
** [`body]: the fallback font. if only this is set in a given font context, it will be used for everything
................................................................................
~~~cortav
%% let's pretend we've also defined the fonts 'title', 'cursive', and 'thin'

%font new
%font set body=sans header=serif
%font dup
%font header=title
# WorldGov  announcement
%font pop

%% we've now set up a default font context, created a new context for the title of the
%% document, and then popped it back off after the title was inserted so that our
%% first font context is active again. everything after that last '%font pop' will
%% be printed in sans, except for headers, which will be printed in 'serif'

WorldGov would like to congratulate 2274's Employee of the Year, [*The Smiling Man]! The Smiling Man had a few words of encouragement for the weary proles of the world when he graciously accepted his award at this year's ceremonial bloodletting:

%font dup
%font set body=cursive
> It is very important for you to understand that your dreams are the intellectual property of the WorldGov organization.
> Laborers who fail more than one duplicity check per workcycle will receive extra Pit Time.
%font pop

%% above we created a blockquote whose text is printed in a cursive font; afterwards,
%% we simply remove this new context, and everything is back the way it was at "WorldGov would like"

In addition to his 227th consecutive Employee of the Year Award, The Smiling Man has been nominated for a WorldGov Lifetime Achievement Award by the Hyperion Entity in recognition of his exceptional leadership in the Department Which Has No Name. Chief Ritual Officer Mr. Winthrop had this to say:

%% the font mechanism is at its most powerful when used with multiline macros:

	cursive-quote: %font dup
		%font set body=cursive
		> [#1]
		%font pop

%% now, whenever we want a block with a cursive body, we can simply invoke

&$cursive-quote A sea of blood yet lies between us and the Destination. It won't impede me. And I'm so very proud to say that, apparently, it won't impede the Smiling Man either, if the Svalbard contract was any indication! [pause for laughter]

%% without affecting the overall font context. in fact, since 'cursive-quote' creates
%% its context using 'dup', it would import all font specifications besides 'body'
%% from the environment it is invoked in
~~~

you may have noticed the rather odd bit at the end of our font definition, with the [`dit] URI. the reasons for this are tragic. groff, while delightful, has a thoroughly antiquated understanding of fonts, and doesn't support normal font formats like truetype. groff ships with a limited number of fonts in its own format, identified by obscurantist letter code ([`HBI] is "Helvetica Bold Italic", for instance) and lacking normal metadata. for this reason, you'll have to tell cortav how you want your fonts translated.
................................................................................
+ encoding-data-ucs-url | where to download UnicodeData.txt from, if encoding-data-ucs is not changed. defaults to the unicode consortium website

#### deterministic builds
some operating systems, like NixOS, require packages that can be built in reproducible ways. this implies that all data, all [!state] that goes into producing a package needs to be accounted for before the build proper begins. the [`cortav] build process needs to be slightly altered to support such a build process.

while the cortav specification itself does not concern itself with matters like whether a particular character is a numeral or a letter, optimal typesetting in some cases requires such information. this is the case for the equation span- and block-types, which need to be able to distinguish between literals, variables, and mathematical symbols in [^alas-math the equations they format]. the ASCII charset is small enough that exhaustive character class information can be manually hardcoded into a cortav implementation, the various encodings of Unicode most certainly are not.

	alas-math: sadly, i was not at any point consulted by any of the generations of mathematicians stretching back into antiquity, who as a direct consequence devised their notations without [*any] regard for machine-readability. [!for shame!]

for this reason, the reference implementation of cortav embeds the file [`UnicodeData.txt], a database maintained by the Unicode Consortium. this is a rather large file that updates for each new Unicode version, so it is downloaded as part of the build process. to build on NixOS, you'll need to either disable the features that rely on this database (not recommended), or download the database yourself and tell the build script where to find it. this is the approach the official nix expression will take when i can be bothered to write it. see the examples below for how to conduct a deterministic build

~~~ deterministic build with unicode database [sh] ~~~
/src $ mkdir cortav && cd cortav
/src/cortav $ fossil clone https://c.hale.su/cortav .fossil && fossil open .fossil
/src/cortav $ curl https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt > /tmp/unicode.txt
................................................................................
~~~ [sh] deterministic build [!without] unicode database ~~~
/src $ mkdir cortav && cd cortav
/src/cortav $ fossil clone https://c.hale.su/cortav .fossil && fossil open .fossil
/src/cortav $ make build/cortav encoding-data=
~~~

! while most of the data used is taken directly from UnicodeData.txt, the database generated by [`tools/ucs.lua] splices in some extra character information before generating a database. this is partly because certain characters may not be classified in a useful way and need to be manually overwritten. however, the reference implementation also seeks to provide accurate data for certain character sets that are not part of unicode proper and can be expressed in UTF only through its private use areas.
! currently, only the [>corran Corran] script is supported in this fashion, but i intend to add [>tengwar Tengwar] as well. if there is a con-script or any other informally encoded script you would like supported by the reference implementation, please open an issue.

[*do note] that no cortav implementation needs to concern itself with character class data. this functionality is provided in the reference implementation strictly as an (optional) extension to the spec to improve usability, not as a normative requirement.

	corran: http://ʞ.cc/fic/spirals/society
	tengwar: https://en.wikipedia.org/wiki/Tengwar

###refimpl-switches switches
................................................................................
* [`@[*fg]]: resolves to a color expression denoting the selected foreground color. equivalent to [`[*tone](1)]
* [`@[*bg]]: resolves to a color expression denoting the selected background color. equivalent to [`[*tone](0)]
* [`@[*tone]\[/[$alpha]\]([$fac] \[[$shift] \[[$saturate]\]\] )]: resolves to a color expression. [$fac] is a floating-point value scaling from the background color to the foreground color. [$shift] is a value in degrees controlling how far the hue will shift relative to the accent. [$saturate] is a floating-point value controlling how satured the color is.

###refimpl-rend-groff groff
the [`groff] backend produces a text file suitable for supplying to a [`groff] compiler. [`groff] is the GNU implementation of a venerable typesetting system from the early days of UNIX

you can produce a final output directly by piping from the [`cortav] driver into [`groff]. if your document uses an encoding other than ASCII, you'll need to notify [`groff] of this with the [`-K] flag. for example, to render a UTF8 cortav file to PDF:

~~~
$ cortav input.ct -m render:format groff | groff -Tpdf -Kutf8 > output.pdf
~~~

in the future, it is planned to enable the driver to operate groff automatically and directly produce the desired output format when the binary wrapper is in use. doing so securely and hygienically is not possible in pure lua, however.

####refimpl-rend-groff-modes modes
[`groff] supports the following modes:

* string [`groff:annotate] controls how footnotes will be handled.
** [`footnote] places footnotes at the end of the page they are referenced on. if the same footnote is used on multiple pages, it will be duplicated on each.
** [`secnote] places footnotes at the end of each section. footnotes used in multiple sections will be duplicated for each
** [`endnote] places all footnotes at the end of the rendered document.

* string [`groff:title-page] takes an identifier that names a section. this section will be treated as the title page for the document.
* string [`groff:title] sets a specific title to be used in headers instead of relying on header heuristics

### directives
* [`%[*pragma] title-page [$id]] sets the title page to section [$id]. this causes it to be specially formatted, with a large, centered title and subtitle.

### quirks
if the [`toc] extension is active but [`%[*toc]] directive is provided, the table of contents will be given its own section at the start of the document (after the title page, if any).

		return string.format("mode “%s” "..msg, ...)
	end);
	unimpl = ss.exnkind 'feature not implemented';
	ext = ss.exnkind 'extension error';
	enc = ss.exnkind('encoding error', function(msg, ...)
		return string.format('[%s]' .. msg, ...)
	end);



}

ct.ctx = declare {
	mk = function(src) return {src = src} end;
	ident = 'context';
	cast = {
		string = function(me)
................................................................................
		depth = 0;
		kind = 'ordinary';
	} end;
	construct = function(self, id, depth)
		self.id = id
		self.depth = depth
	end;

















}

ct.doc = declare {
	ident = 'doc';
	fns = {
		mksec = function(self, id, depth)
			local o = ct.sec(id, depth)
................................................................................
				if ss.str.begins(substr, i.seq) then
					found = true
					table.insert(spans, i.parse(substr:sub(1+#i.seq), ctx))
					break
				end
			end
			if not found then
				ctx:fail('no recognized control sequence in [%s]', substr)
			end
		elseif c == '\n' then
			flush()
			table.insert(spans,{kind='line-break',origin=ctx:clone()})
		else
			buf = buf .. c
		end
................................................................................
		if (not last) or (last.kind ~= 'reference') then
			c:fail('reference continuations must immediately follow a reference')
		end
		local str = l:match '^\t\t(.-)%s*$'
		last.val = last.val .. '\n' .. str
		c.sec.refs[last.key] = last.val
	end};


	{seq = '\t', fn = blockwrap(function(l,c,j,d)
		local ref, val = l:match '\t+([^:]+):%s*(.*)$'
		local last = d[#d]
		local rsrc
		if last and last.kind == 'resource' then
			last.props[ref] = val
			rsrc = last
		elseif last and last.kind == 'reference' and last.rsrc then
................................................................................
			end
		end
	end
	job:hook('line_end',ctx,l)
end

function ct.parse(file, src, mode, setup)



	local ctx = ct.ctx.mk(src)
	ctx.line = 0
	ctx.doc = ct.doc.mk()
	ctx.doc.src = src
	ctx.sec = ctx.doc:mksec() -- toplevel section
	ctx.sec.origin = ctx:clone()
	ctx.lang = mode['meta:lang']
................................................................................
			end
		end
	end
	ctx.doc.stage = nil
	ctx.doc.docjob:hook('meddle_ast')
	return ctx.doc
end

		return string.format("mode “%s” "..msg, ...)
	end);
	unimpl = ss.exnkind 'feature not implemented';
	ext = ss.exnkind 'extension error';
	enc = ss.exnkind('encoding error', function(msg, ...)
		return string.format('[%s]' .. msg, ...)
	end);
	rdr = ss.exnkind('could not render', function(msg, ...)
		return string.format('(backend %s)'..msg, ...)
	end);
}

ct.ctx = declare {
	mk = function(src) return {src = src} end;
	ident = 'context';
	cast = {
		string = function(me)
................................................................................
		depth = 0;
		kind = 'ordinary';
	} end;
	construct = function(self, id, depth)
		self.id = id
		self.depth = depth
	end;
	fns = {
		visible = function(self)
			if self.kind == 'nonprinting' then return false end
			local invisibles = {
				['break'] = true;
				reference = true;
				resource = true;
				directive = true;
			}
			for k,b in pairs(self.blocks) do
				if not (invisibles[b.kind] or b.invisible) then return true end
				-- extensions that add invisible nodes to the AST must
				-- mark them as such for rendering to work properly!
			end
			return false
		end;
	}
}

ct.doc = declare {
	ident = 'doc';
	fns = {
		mksec = function(self, id, depth)
			local o = ct.sec(id, depth)
................................................................................
				if ss.str.begins(substr, i.seq) then
					found = true
					table.insert(spans, i.parse(substr:sub(1+#i.seq), ctx))
					break
				end
			end
			if not found then
				buf = buf .. c
			end
		elseif c == '\n' then
			flush()
			table.insert(spans,{kind='line-break',origin=ctx:clone()})
		else
			buf = buf .. c
		end
................................................................................
		if (not last) or (last.kind ~= 'reference') then
			c:fail('reference continuations must immediately follow a reference')
		end
		local str = l:match '^\t\t(.-)%s*$'
		last.val = last.val .. '\n' .. str
		c.sec.refs[last.key] = last.val
	end};
	{seq = '\t', pred = function(l)
		return (l:match '\t+([^:]+):%s*(.*)$')
	end; fn = blockwrap(function(l,c,j,d)
		local ref, val = l:match '\t+([^:]+):%s*(.*)$'
		local last = d[#d]
		local rsrc
		if last and last.kind == 'resource' then
			last.props[ref] = val
			rsrc = last
		elseif last and last.kind == 'reference' and last.rsrc then
................................................................................
			end
		end
	end
	job:hook('line_end',ctx,l)
end

function ct.parse(file, src, mode, setup)
	-- this object is threaded down through the parse tree
	-- and copied to store information like the origin of the
	-- element in the source code
	local ctx = ct.ctx.mk(src)
	ctx.line = 0
	ctx.doc = ct.doc.mk()
	ctx.doc.src = src
	ctx.sec = ctx.doc:mksec() -- toplevel section
	ctx.sec.origin = ctx:clone()
	ctx.lang = mode['meta:lang']
................................................................................
			end
		end
	end
	ctx.doc.stage = nil
	ctx.doc.docjob:hook('meddle_ast')
	return ctx.doc
end

function ct.expand_var(v)
	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.invocation.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, true
	else
		return ct.parse_span(val, v.origin), false
	end
end

end
local lines = function(...)
	local s = ss.strac()
	for _, v in pairs{...} do s(v) end
	return s
end






























































































































function ct.render.groff(doc, opts)
	-- rs contains state specific to this render job
	-- that modules will need access to



	local rs = {};
	rs.macsets = {
		strike = {
			'.de ST';
			[[.nr ww \w'\\$1']];
			[[\Z@\v'-.25m'\l'\\n[ww]u'@\\$1']];
			'..';






























































		};
	}
	rs.macsNeeded = {
		order = {};

		count = 0;



	}



	function rs.macAdd(id)
		if rs.macsets[id] then
			rs.macsNeeded.count = macsNeeded.count + 1
			rs.macsNeeded.order[rs.macsNeeded.count] = id


			return true









		else return false end
	end



























	local job = doc:job('render_groff',nil,rs)

















	-- the way this module works is we build up a table for each block
	-- of individual strings paired with attributes that say how they
	-- should be rendered. we then iterate over the table, applying
	-- formats as need be, and inserting blanks after each block



	local spanRenderers = {}
	function spanRenderers.format(rc, s, b, sec)
		local rcc = rc:clone()
		if s.style == 'strong' then
			rcc.prop.bold = true
		elseif s.style == 'emph' then
			rcc.prop.emph = true
		elseif s.style == 'strike' then
			rcc.prop.strike = true
			rs.macAdd 'strike'

		elseif s.style == 'insert' then


		end
		rs.renderSpans(rcc, s.spans, b, sec)
	end;















































	function rs.renderSpans(rc, sp, b, sec)

		for i, v in ipairs(sp) do
			if type(v) == 'string' then
				rc:add(v)

			elseif spanRenderers[v.kind] then
				spanRenderers[v.kind](rc, v, b, sec)
			end
		end
	end

	local blockRenderers = {}
	function	blockRenderers.paragraph(rc, b, sec)
		rs.renderSpans(rc, b.spans, b, sec)
	end
	function rs.renderBlock(b, sec)
		local rc = {
			clone = function(self)
				return {
					clone = self.clone;
					lines = self.lines;
					prop = ss.clone(self.prop);
					mk = self.mk;
					add = self.add;
				}





			end;
			lines = {};
			prop = {};
			mk = function(self, ln)
				local p = ss.clone(self.prop)
				p.txt = ln
				return p

			end;
			add = function(self, ln)
				table.insert(self.lines, self:mk(ln))


			end;
		}

		if blockRenderers[b.kind] then

			blockRenderers[b.kind](rc, b, sec)
		end
		return rc.lines
	end










	function rs.emitLine(ln)
		local q = ss.strac()
		if ln.dsz then
			q('\\ps +' .. tostring(ln.dsz))




		elseif ln.sz then
			q('\\ps ' .. tostring(ln.dsz))

		end








		if ln.bold and ln.emph then
			q '\\f(BI'
		elseif ln.bold then
			q '\\fB'

		elseif ln.emph then
			q '\\fI'

		end











		q(ln.txt)



















































		if ln.bold or ln.emph then
			q'\\f[]'




		end

		if ln.dsz then

			q('.ps -' .. tostring(ln.dsz))
		elseif ln.sz then
			q '.ps'


		end
		return q






















	end

	local ir = {}
	for i, sec in ipairs(doc.secorder) do
		if sec.kind == 'ordinary' then
			local blks = {}
			for j, b in ipairs(sec.blocks) do
				local r = rs.renderBlock(b, sec)
				if r then table.insert(blks, r) end
			end
			table.insert(ir, blks)
		end
	end

	local rd = ss.strac()
	for i, s in ipairs(ir) do
		for j, b in ipairs(s) do
			for z, l in ipairs(b) do
				rd(rs.emitLine(l))
			end
			rd'\n'
		end
	end

	local macs = ss.strac()
	for _, m in pairs(rs.macsNeeded.order) do
		for _, ln in pairs(m) do macs(ln) end
	end



















	return macs:compile'\n' .. rd:compile''
end

end
local lines = function(...)
	local s = ss.strac()
	for _, v in pairs{...} do s(v) end
	return s
end

local function gsan(str)
	local tocodepoint = function(ch)
		return string.format('\\[u%04X]', utf8.codepoint(ch))
	end
	str = str:gsub('(["\'\\])',tocodepoint)
	return str
end

local gtxt = ss.declare {
	ident = 'groff-text';
	mk = function() return {
		lines = {};
	} end;
	fns = {
		raw = function(me, text)
			if me.linbuf == nil then
				me.linbuf = ss.strac()
			end
			me.linbuf(text)
		end;
		txt = function(me, str, ...)
			if str == nil then return end
			me:raw(gsan(str))
			-- WARN this will cause problems if str is ever allowed to
			-- include a line break. we can sanitize by converting
			-- every line break into a new entry in the table, but i
			-- don't think it should be possible for a \n to reach us
			-- at this point, so i'm omitting the safety check as it
			-- would involve an excessive hit to performance
			me:txt(...)
		end;
		brk = function(me)
			me:flush()
			table.insert(me.lines, '')
		end;
		line = function(me, ...)
			me:flush()
			me:txt(...)
		end;
		req = function(me, r)
			me:flush()
			table.insert(me.lines, '.'..r)
		end;
		esc = function(me, e)
			me:raw('\\' .. e)
		end;
		flush = function(me)
			if me.linbuf ~= nil then
				local line = me.linbuf:compile()
				local first = line:sub(1,1)
				-- make sure our lines aren't accidentally interpreted
				-- as groff requests. groff is kinda hostile to script
				-- generation, huh?
				if first == '.' or first == "'" then
					line = '\\&' ..line
				end
				table.insert(me.lines, line)
				me.linbuf = nil
			end
		end;
		compile = function(me)
			me:flush()
			return table.concat(me.lines, '\n')
		end;
	}
}

local function mkColorDef(name, color)
	return '.defcolor '..name..' rgb ' ..
		table.concat({color:rgb_t()}, ' ', 1, 3)
end

local function addAccentTones(rs,hue,spread)
	local base = ss.color(hue, 1, .5)
	local right = spread > 0 and ss.color(hue + spread, 1, .5)
		or ss.color(hue, 0.4, 0.6)
	local left = spread > 0 and ss.color(hue - spread, 1, .5)
		or ss.color(hue, 1, 0.3)

	local steps = 6
	for i=-3,3 do
		local nc, nm
		local o if i > 0
			then o = right nm = 'R'
			else o = left  nm = 'L'
		end
		nc = base + o:alt('alpha', math.abs(i) / 3)
		rs.addColor('accent'..nm..tostring(math.abs(i)),nc)
	end
end
local function mkrc()
	return {
		clone = function(self, origin)
			return {
				origin = origin;
				clone = self.clone;
				prop = ss.clone(self.prop);
				mk = self.mk;
				add = self.add;
				block = self.block;
				blocks = self.blocks;
				span = self.span;
				spans = self.spans;
			}
		end;
		blocks = {};
		prop = {};
		block = function(self)
			local sub = self:clone()
			sub.spans = {}
			sub.blocks = nil
			sub.span = function(me, ln)
				local p = ss.clone(me.prop)
				p.txt = ln
				p.block = sub
				p.origin = me.origin
				table.insert(me.spans, p)
				return p
			end;
			table.insert(self.blocks, sub)
			return sub
		end;
	}
end

function ct.render.groff(doc, opts, setup)
	-- rs contains state specific to this render job
	-- that modules will need access to
	local fail = function(msg, ...)
		ct.exns.rdr(msg, 'groff', ...):throw()
	end
	local rs = {};
	rs.macsets = {
		strike = {
			'.de ST';
			[[.nr ww \w'\\$1']];
			[[\Z@\v'-.25m'\l'\\n[ww]u'@\\$1]];
			'..';
		};
		color = {'.color'};
		insert = {};
		footnote = {
			'.de footnote-blank';
			'.  sp 0.25m';
			'..';
			'.ev footnote-env';
			'.  ps 8p';
			'.  in 0.5c';
			'.  blm footnote-blank';
			'.ev';
			'.de footnote-print';
-- 			'.  sp |\\\\n[.p]u-\\\\n[footnote-pos]u';
			'.  sp 0.5c';
			'.  ev footnote-env';
			'.    fn';
			'.  ev';
			'.  rm fn';
			'.  nr footnote-pos 0';
			-- move the trap past the bottom of the page so it's not
			-- invoked again until more footnotes have been assembled
			'.  ch footnote-print |\\\\n[.p]u+10';
			'.  bp';
			'..';
			'.wh |\\n[.p]u footnote-print';
		};
		root = {
		-- these are macros included in all documents
		-- page offset is hideously broken and unusable; we
		-- zero it out so we can use .in to control indents
		-- instead. note that the upshot of this is we need
		-- to manually specify the indent in every other
		-- environment from now on, .evc doesn't seem to cut it
		-- set up the page title environment & trap
			"'in 2c";
			"'ll 18c";
			"'po 0";
			"'ps 13p";
			"'vs 15p";
			".ev pgti";
			".  evc 0";
			".  fam H";
			".  ps 10pt";
			".ev";
			'.de ph';
			'.  sp 0.6c';
			'.  ev pgti';
			'.  po 1c';
			'.  lt 19c';
			".  tl '\\\\*[doctitle]'\\fB\\\\*[title]\\f[]'%'";
			'.  po 0';
			".  br";
			'.  ev';
			'.  sp 1.2c';
			'..';
			'.wh 0 ph';
			'.de np';
			'.  sp 0.2c';
			'..';
			'.blm np'

		};
	}
	rs.macsNeeded = {
		order = {};
		map = {};
		count = 0;
		deps = {
			insert = {'color'};
			strike = {'color'};
		};
	}
	rs.linkctr = 0

	function rs.macAdd(id)
		if rs.macsets[id] and not rs.macsNeeded.map[id] then
			rs.macsNeeded.count = rs.macsNeeded.count + 1
			rs.macsNeeded.order[rs.macsNeeded.count] = id
			rs.macsNeeded.map[id] = true
			if not rs.macsNeeded.deps[id] then
				return true
			end

			for k,v in pairs(rs.macsNeeded.deps[id]) do
				if not rs.macsNeeded.map[v] then
					rs.macAdd(v)
				end
			end

			return true
		else return false end
	end

	rs.macAdd 'root'

	rs.colors = {}
	rs.addColor = function(name,color)
		if not ss.color.is(color) then
			ss.bug('%s is not a color value', color):throw()
		end
		rs.colors[name] = color
	end

	if opts.accent then
		addAccentTones(rs, tonumber(opts.accent), tonumber(opts['hue-spread']) or 0)
		rs.addColor('new', rs.colors.accentR3)
		rs.addColor('del', rs.colors.accentL3)
	else
		rs.addColor('new', ss.color(80, 1, .3))
		rs.addColor('del', ss.color(0, 1, .3))
	end

	doc.stage = {
		type = 'render';
		format = 'groff';
		groff_render_state = rs;
	}

	setup(doc.stage)
	local job = doc:job('render_groff',nil,rs)

	local function collect(rc, spans, b, s)
		local rcc = rc:clone()
		rcc.spans = {}
		rs.renderSpans(rcc, spans, b, s)
		return rcc.spans
	end
	local function collectText(...)
		local text = collect(...)
		local s = ss.strac()
		for i, l in ipairs(text) do
			s(l.txt)
		end
		return s
	end


	-- the way this module works is we build up a table for each block
	-- of individual strings paired with attributes that say how they
	-- should be rendered. we then iterate over the table, applying
	-- formats as need be, and inserting blanks after each block



	local spanRenderers = {}
	function spanRenderers.format(rc, s, b, sec)
		local rcc = rc:clone()
		if s.style == 'strong' then
			rcc.prop.bold = true
		elseif s.style == 'emph' then
			rcc.prop.emph = true
		elseif s.style == 'strike' then
			rcc.prop.strike = true
			rs.macAdd 'strike'
			rcc.prop.color = 'del'
		elseif s.style == 'insert' then
			rs.macAdd 'insert'
			rcc.prop.color = 'new'
		end
		rs.renderSpans(rcc, s.spans, b, sec)
	end;

	function spanRenderers.link(rc, l, b, sec)
		rs.renderSpans(rc, l.spans, b, sec)
		rs.linkctr = rs.linkctr + 1
		rs.macAdd 'footnote'
		local p = rc:span(string.format('[%u]', rs.linkctr))
		if type(l.ref) == 'string' then
			local t = ''
			if b.origin.doc.sections[l.ref] then
				local hn = b.origin.doc.sections[l.ref].heading_node
				if hn then
					t = collectText(rc, hn.spans, b, sec):compile()
				end
			else
				local obj = l.origin:ref(l.ref)
				if type(obj) == 'string' then
					t = l.origin:ref(l.ref)
				end
			end
			p.div = { fn = tostring(rs.linkctr) .. ') ' .. t }
		end
	end;

	function spanRenderers.raw(rc, s, b, sec)
		rs.renderSpans(rc, s.spans, b, sec)
	end;

	function spanRenderers.var(rc,v,b,s)
		local t, raw = ct.expand_var(v)
		if raw then rc:span(t) else
			rs.renderSpans(rc,t,b,s)
		end
	end
	function spanRenderers.macro(rc, m,b,s)
		local macroname = collectText(rc,
			ct.parse_span(m.macro, b.origin),
			b, s):compile()

		local r = b.origin:ref(macroname)
		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
		rs.renderSpans(rc, ct.parse_span(r, mctx))
	end

	function rs.renderSpans(rc, sp, b, sec)
		rc = rc or mkrc(b.origin)
		for i, v in ipairs(sp) do
			if type(v) == 'string' then

				rc:span(v)
			elseif spanRenderers[v.kind] then
				spanRenderers[v.kind](rc, v, b, sec)
			end
		end
	end

	local blockRenderers = {}
	function	blockRenderers.label(rc, b, sec)
		if ct.sec.is(b.captions) then
			local sizes = {36,24,12,8,4,2}
			local margins = {0,5,2,1,0.5}
			local dedents = {2.5,1.3,0.8,0.4}
			rc.prop.dsz = sizes[b.captions.depth] or 10
			rc.prop.underline = b.captions.depth < 4
			rc.prop.bold = b.captions.depth > 3
			rc.prop.margin = {
				top = margins[b.captions.depth] or 0;
				bottom = 0.1;

			}
			rc.prop.indent = -(dedents[b.captions.depth] or 0)
			rc.prop.underline = true
			rc.prop.chtitle = collectText(rc, b.spans, b.spec):compile()
			if b.captions.depth == 1 then
				rc.prop.breakBefore = true
			end




			rs.renderSpans(rc, b.spans, b, sec)
		else
			ss.bug 'tried to render label for an unknown object type':throw()
		end

	end
	function	blockRenderers.paragraph(rc, b, sec)
		rs.renderSpans(rc, b.spans, b, sec)
	end

	function rs.renderBlock(rc, b, sec, outerBlockRenderContext)
		if blockRenderers[b.kind] then
			local rcc = rc:block()
			blockRenderers[b.kind](rcc, b, sec)
		end

	end

	rs.sanitize = gsan

	local skippedFirstPagebreak = doc.secorder[1]:visible()
	local deferrer = ss.declare {
		ident = 'groff-deferrer';
		mk = function(buf) return {ops={}, tgt=buf} end;
		fns = {
			esc = function(me, str) table.insert(me.ops, {0, str}) end;
			req = function(me, str) table.insert(me.ops, {1, str}) end;
			flush = function(me)



				for i=#me.ops,1,-1 do
					local d = me.ops[i]
					if d[1] == 0 then
						me.tgt:esc(d[2])
					elseif d[1] == 1 then

						me.tgt:req(d[2])
					end
				end
				me.ops = {}
			end;
		};
	}
	function rs.emitSpan(gtxt, s)
		local defer = deferrer(gtxt)
		if s.bold or s.emph then
			if s.bold and s.emph then
				gtxt:esc 'f(BI'
			elseif s.bold then

				gtxt:esc 'fB'
			elseif s.emph then

				gtxt:esc 'fI'
			end
			defer:esc'f[]'
		end


		if s.color and opts.color then
			gtxt:esc('m[' .. s.color .. ']')
			defer:esc('m[]')
		end
		if s.strike then
			gtxt:req('ST "'..s.txt..'"')
		else
			gtxt:txt(s.txt)
		end
		defer:flush()
		if s.div then
			for div, body in pairs(s.div) do
				if div == 'fn' then
					gtxt:req 'ev footnote-env'
				end
				gtxt:req('boxa '..div)
				gtxt:txt(body)
				gtxt:raw '\n'
				gtxt:req 'boxa'
				if div == 'fn' then
					gtxt:req 'ev'
					gtxt:req 'nr footnote-pos (\\n[footnote-pos]u+\\n[dn]u)'
					gtxt:req 'ch footnote-print -(\\n[footnote-pos]u+1c)'
				end
			end
		end
	end
	function rs.emitBlock(gtxt, b)
		local didfinalbreak = false
		local defer = deferrer(gtxt)
		local ln = b.prop
		if ln.chtitle then
			gtxt:req('ds title '..ln.chtitle)
		end
		if ln.breakBefore then
			if skippedFirstPagebreak then
				gtxt:req 'bp'
			else
				skippedFirstPagebreak = true
			end
		end
		if ln.indent then
			if ln.indent < 0 then
				gtxt:req('in '..tostring(ln.indent)..'m')
				defer:req 'in'
				gtxt:req('ll +'..tostring(-ln.indent)..'m')
				defer:req 'll'
			else
				gtxt:req('in +'..tostring(ln.indent)..'m')
				defer:req 'in'
			end
			defer:req 'br'
		end
		if ln.margin then
			if ln.margin.top then
				gtxt:req(string.format('sp %sm', ln.margin.top))
			end
		end



		if ln.underline then
			defer:esc("D'l \\n[.ll]u-\\n[.in]u 0'")
			defer:esc"v'-0.5'"
			defer:req'br'
		end

		if ln.dsz and ln.dsz > 0 then
			gtxt:req('ps +' .. tostring(ln.dsz) .. 'p')
			defer:req('ps -' .. tostring(ln.dsz) .. 'p')
		elseif ln.sz or ln.dsz then

			if ln.sz and ln.sz <= 0 then
				ln.origin:fail 'font sizes must be greater than 0'
			end

			gtxt:req('ps ' .. tostring(ln.sz or ln.dsz) ..'p')
			if ln.dsz then
				defer:req('ps +' .. tostring(0 - ln.dsz) .. 'p')
			else
				defer:req'ps'
			end
		end

		for i,s in pairs(b.spans) do
			rs.emitSpan(gtxt, s)
		end


		if ln.margin then
			if ln.margin.bottom then
				gtxt:req(string.format('sp %sm', ln.margin.bottom))
			end
		end

		defer:flush()

		if not ln.margin then gtxt:brk() end
	end

	local ir = {}
	for i, sec in ipairs(doc.secorder) do
		if sec.kind == 'ordinary' then
			local rc = mkrc()
			for j, b in ipairs(sec.blocks) do
				rs.renderBlock(rc, b, sec)

			end
			table.insert(ir, {blocks = rc.blocks, src = sec})
		end
	end

	local gd = gtxt()
	for i, s in ipairs(ir) do
		for j, b in ipairs(s.blocks) do

			rs.emitBlock(gd,b)


		end
	end

	local macs = ss.strac()
	for _, m in pairs(rs.macsNeeded.order) do
		for _,ln in pairs(rs.macsets[m]) do macs(ln) end
	end
	if rs.macsNeeded.map.color and opts.color then
		for k,v in pairs(rs.colors) do
			macs(mkColorDef(k,v))
		end
	end

	local doctitle = '' if opts.title then
		doctitle = opts.title
	else
		local top = math.huge
		for i,s in ipairs(doc.secorder) do
			if s.heading_node and s.depth < top then
				top = s.depth
				doctitle = collectText(mkrc():block(), s.heading_node.spans, s.heading_node, s):compile()
			end
		end
	end
	macs('.ds doctitle '..doctitle)

	return macs:compile'\n' .. '\n' .. gd:compile()
end

--    good both on a screen and when printed.
--  > cortav -m render:format html

local ct = require 'cortav'
local ss = require 'sirsem'

-- install rendering function for html
function ct.render.html(doc, opts)
	local doctitle = opts['title']
	local f = string.format
	local getSafeID = ct.tool.namespace()

	local footnotes = {}
	local footnotecount = 0

................................................................................
		style_rules = styles; -- use stylesneeded if at all possible
		style_add = addStyle;
		stylesets = stylesets;
		stylesets_active = stylesNeeded;
		obj_htmlid = getSafeID;
		-- remaining fields added later
	}











	local renderJob = doc:job('render_html', nil, render_state_handle)
	doc.stage.job = renderJob;

	local runhook = function(h, ...)
		return renderJob:hook(h, render_state_handle, ...)
	end
................................................................................
				end
			else
				b.origin:fail('%s is not an object that can be embedded', t.ref)
			end
		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.invocation.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.raw(v,b,s)
			return htmlSpan(v.spans, b, s)
		end

--    good both on a screen and when printed.
--  > cortav -m render:format html

local ct = require 'cortav'
local ss = require 'sirsem'

-- install rendering function for html
function ct.render.html(doc, opts, setup)
	local doctitle = opts['title']
	local f = string.format
	local getSafeID = ct.tool.namespace()

	local footnotes = {}
	local footnotecount = 0

................................................................................
		style_rules = styles; -- use stylesneeded if at all possible
		style_add = addStyle;
		stylesets = stylesets;
		stylesets_active = stylesNeeded;
		obj_htmlid = getSafeID;
		-- remaining fields added later
	}

	-- 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 = 'html';
		html_render_state = render_state_handle;
	}

	setup(doc.stage)

	local renderJob = doc:job('render_html', nil, render_state_handle)
	doc.stage.job = renderJob;

	local runhook = function(h, ...)
		return renderJob:hook(h, render_state_handle, ...)
	end
................................................................................
				end
			else
				b.origin:fail('%s is not an object that can be embedded', t.ref)
			end
		end

		function span_renderers.var(v,b,s)
			local r, raw = ct.expand_var(v)










			if raw then return r else


				return htmlSpan(r , b, s)
			end
		end

		function span_renderers.raw(v,b,s)
			return htmlSpan(v.spans, b, s)
		end

-- [ʞ] sirsem.lua
--  ~ lexu hale <lexi@hale.su>

--  ? utility library with functionality common to
--    cortav.lua and its extensions
--    from Ranuir "software utility"
--  > local ss = require 'sirsem.lua'

local ss
do -- pull ourselves up by our own bootstraps
................................................................................
	local new = {}
	for k, v in pairs(list) do
		local nk,nv = fn(k,v)
		new[nk or k] = nv or v
	end
	return new
end





function ss.kfilter(list, fn)
	local new = {}
	for k, v in pairs(list) do
		if fn(k,v) then new[k] = v end
	end
	return new
................................................................................

function ss.declare(c)
	local cls = setmetatable({
		__name = c.ident;
	}, {
		__name = 'class';
		__tostring = function() return c.ident or '(class)' end;

	})

	cls.__call = c.call
	cls.__index = function(self, k)
		if c.default and c.default[k] then
			return c.default[k]
		end
................................................................................
		if c.cast.string then
			cls.__tostring = c.cast.string
		end
		if c.cast.number then
			cls.__tonumber = c.cast.number
		end
	end









	cls.mk = function(...)
		local val = setmetatable(c.mk and c.mk(...) or {}, cls)
		if c.init then
			for k,v in pairs(c.init) do
				val[k] = v
			end
................................................................................
				end
			else
				me:react(sym)
			end
		end;
	};
}





-- convenience buffer for holding strings under
-- construction, accumulating and compiling then in
-- as quick a way as lua permits
ss.strac = ss.declare {
	ident = 'string-accumulator';
	mk = function() return {
................................................................................
		end;
		wrap = function(self,a,b)
			table.insert(self.strs, 1, a)
			table.insert(self.strs, b)
		end;
	};
}

-- [ʞ] sirsem.lua
--  ~ lexi hale <lexi@hale.su>
--    glowpelt (hsl conversion)
--  ? utility library with functionality common to
--    cortav.lua and its extensions
--    from Ranuir "software utility"
--  > local ss = require 'sirsem.lua'

local ss
do -- pull ourselves up by our own bootstraps
................................................................................
	local new = {}
	for k, v in pairs(list) do
		local nk,nv = fn(k,v)
		new[nk or k] = nv or v
	end
	return new
end
function ss.tmap(fn, a, ...)
	if a == nil then return end
	return fn(a), ss.tmap(fn, ...)
end

function ss.kfilter(list, fn)
	local new = {}
	for k, v in pairs(list) do
		if fn(k,v) then new[k] = v end
	end
	return new
................................................................................

function ss.declare(c)
	local cls = setmetatable({
		__name = c.ident;
	}, {
		__name = 'class';
		__tostring = function() return c.ident or '(class)' end;
	   __index = c.cfns;
	})

	cls.__call = c.call
	cls.__index = function(self, k)
		if c.default and c.default[k] then
			return c.default[k]
		end
................................................................................
		if c.cast.string then
			cls.__tostring = c.cast.string
		end
		if c.cast.number then
			cls.__tonumber = c.cast.number
		end
	end

	if c.op then
		cls.__add = c.op.sum
		cls.__sub = c.op.sub
		cls.__div = c.op.div
		cls.__mul = c.op.mul
		cls.__concat = c.op.cat
	end

	cls.mk = function(...)
		local val = setmetatable(c.mk and c.mk(...) or {}, cls)
		if c.init then
			for k,v in pairs(c.init) do
				val[k] = v
			end
................................................................................
				end
			else
				me:react(sym)
			end
		end;
	};
}

function ss.math.clamp(v, l, h)
	return math.max(math.min(v, h or 1), l or 0)
end

-- convenience buffer for holding strings under
-- construction, accumulating and compiling then in
-- as quick a way as lua permits
ss.strac = ss.declare {
	ident = 'string-accumulator';
	mk = function() return {
................................................................................
		end;
		wrap = function(self,a,b)
			table.insert(self.strs, 1, a)
			table.insert(self.strs, b)
		end;
	};
}

-- color class based on c.hale.su/sorcery's, hsl conversion
-- code written by glowpelt. TODO switch to LCH
local function clip(v, ...)
	if v == nil then return end
	return math.max(0,math.min(0xFF,math.floor(v))), clip(...)
end;
local function bytefrac(f, ...)
	if f == nil then return end
	return clip(f*0xFF), bytefrac(...)
end
ss.color = ss.declare {
	ident = 'color';
	mk = function(h,s,l,a) return {
		hue = h or 0.0;
		sat = s or 0.0;
		lum = l or 0.0;
		alpha = a or 1.0;
	} end;
	cfns = {
		byteclip = clip;
		bytefrac = bytefrac;
	};
	cast = {
		string = function(self) return self:hex() end;
		number = function(self) return self:u32() end;
	};
	op = {
		sum = function(self, other)
			if ss.color.is(other) then
				local fac = ss.math.lerp(self.alpha, 1, other.alpha)
				return self:blend(other, fac):warp(function(c)
					c.alpha = ss.math.clamp(self.alpha+other.alpha)
				end)
			else -- color + number = brighter color
				return self:warp(function(c)
					c.lum = c.lum + other
				end)
			end
		end;
		mul = function(self, other)
			if ss.color.is(other) then
				ss.color.exn 'how the heck do you multiply in hsl anyway':throw()
			else
				return self:warp(function(c)
					c.lum = c.lum * other
				end)
			end
		end;
	};
	fns = {
		tuple = function(self)
			return self.hue, self.sat, self.lum, self.alpha
		end;
		warp = function(self, func)
			local n = self:clone()
			func(n)
			return n
		end;
		blend = function(self, other, fac)
			return ss.color(
				ss.math.lerp(fac, self.hue, other.hue),
				ss.math.lerp(fac, self.sat, other.sat),
				ss.math.lerp(fac, self.lum, other.lum),
				ss.math.lerp(fac, self.alpha, other.alpha))
		end;
		hex = function(self)
			local r,g,b,a = bytefrac(self:rgb_t())
			if self.alpha == 1 then a = nil end
			return string.format('#'..string.rep('%02x',a and 4 or 3),
				r,g,b,a)
		end;
		u32 = function(self)
			local r,g,b,a = bytefrac(self:rgb_t())
			return r<<24 | g << 16 | b << 8 | a
		end;
		bytes = function(self)
			return { bytefrac(self:rgb_t()) }
		end;
		alt = function(self, fld, new)
			if self[fld] then
				return self:warp(function(c) c[fld]=new end)
			else
				ss.color.exn('no such field %s in color', fld):throw()
			end
		end;
		rgb = function(self)
			-- convenience function to get a standardized struct
			local r,g,b,a = self:rgb_t()
			return {
				red = r;
				green = g;
				blue = b;
				alpha = a;
			}
		end;
		rgb_t = function(self)
			-- returns rgba values as a tuple
			local value = function(n1, n2, hue)
				if hue > 360 then
					hue = hue - 360
				elseif hue < 0 then
					hue = hue + 360
				end
				if hue < 60 then
					return n1 + (n2 - n1) * hue/60
				elseif hue < 180 then
					return n2
				elseif hue < 240 then
					return n1 + (n2 - n1) * (240 - hue)/60
				else
					return n1
				end
			end
			local h,s,l,alpha = self:tuple()
			local m2
			if l < 0.5 then
				m2 = l * (1 + s)
			else
				m2 = l + s - l * s
			end
			local m1 = 2 * l - m2
			if s == 0 then
				-- Achromatic, there is no hue
				-- In book this errors if hue is not undefined, but we set hue to 0 in this case, not nil or something, so
				return l, l, l, alpha
			else
				-- Chromatic case, so there is a hue
				return
					value(m1, m2, h + 120),
					value(m1, m2, h),
					value(m1, m2, h - 120),
					alpha
			end
		end;
	};
};
ss.color.exn = ss.exnkind 'color error'

ss.cmdfmt = function(cmd, ...)
	return string.format(cmd, ss.tmap(function(s)
		if typeof(s) == 'string' then
			return string.format("%q", s)
			-- FIXME this is incredibly lazy and uses lua quoting, not
			-- bourne shell quoting. it *will* cause problems if anything
			-- exotic finds its way in and needs to be fixed.
			-- TODO provide a proper popen in the C wrapper so wrapped
			-- versions at least can launch programs in a sane and secure
			-- way.
		else
			return s
		end
	end, ...))
end