cortav  Check-in [7ba2577283]

Overview
Comment:continue iterating on groff renderer; add headings, basic formatting, beginnings of a footnote and link system, colors
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 7ba2577283a82ca269a448ad4b2a40725ba066c32a5e68351cd3d3224a24c09e
User & Date: lexi on 2021-12-29 12:19:20
Other Links: manifest | tags
Context
2022-04-17
21:16
various updates fuck man idr what all i did check-in: c0bdfa46df user: lexi tags: trunk
2021-12-29
12:19
continue iterating on groff renderer; add headings, basic formatting, beginnings of a footnote and link system, colors check-in: 7ba2577283 user: lexi tags: trunk
2021-12-27
13:20
add beginnings of groff renderer, document more planned syntaxes check-in: 9215a9c850 user: lexi tags: trunk
Changes

Modified cli.lua from [ad6ab18d31] to [2aa6072a5d].





1
2
3
4
5
6

7
8
9
10
11
12
13
..
33
34
35
36
37
38
39
40
41
42
43
44
45

46
47
48
49
50

51
52
53
54
55
56
57




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, {}, {
>
>
>
>






>







 







|
<
<
<
<
|
>
|
<
<
<
<
>







1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
..
38
39
40
41
42
43
44
45




46
47
48




49
50
51
52
53
54
55
56
-- [ʞ] 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, {}, {

Modified cortav.ct from [4ed3bc7476] to [7b2c420807].

74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
...
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
...
196
197
198
199
200
201
202


























































203
204
205
206
207
208
209
...
211
212
213
214
215
216
217


218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
...
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
...
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
...
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
...
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
...
782
783
784
785
786
787
788
789






790
791
792
793
794
795
796
797
798
799

800
801
802
803
804
805
806
* [*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).








<
<







 







|







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







>
>







|

|







 







|







 







|







|



|
|



|

|










|







 







|







 







|







 







|
>
>
>
>
>
>








<

>







74
75
76
77
78
79
80


81
82
83
84
85
86
87
...
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
...
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
...
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
...
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
...
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
...
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
...
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
...
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861

862
863
864
865
866
867
868
869
870
* [*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).

Modified cortav.lua from [5feb0b86b1] to [bf3719fe9a].

83
84
85
86
87
88
89



90
91
92
93
94
95
96
...
141
142
143
144
145
146
147

















148
149
150
151
152
153
154
...
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
...
986
987
988
989
990
991
992


993
994
995
996
997
998
999
1000
....
1185
1186
1187
1188
1189
1190
1191
1192


1193
1194
1195
1196
1197
1198
1199
....
1267
1268
1269
1270
1271
1272
1273



















		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


























>
>
>







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







|







 







>
>
|







 







|
>
>







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
...
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
...
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
....
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
....
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
....
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
		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

Modified render/groff.lua from [a43bfa19e3] to [ab8e0fd21b].

18
19
20
21
22
23
24





























































































































25
26
27



28
29
30
31
32
33
34






























































35
36
37
38

39



40



41
42
43
44


45









46
47



























48
















49
50
51
52
53


54
55
56
57
58
59
60
61
62
63
64

65


66
67
68
69














































70

71
72
73

74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93





94
95
96
97
98
99
100

101
102
103


104
105

106

107
108
109
110
111









112
113
114
115




116
117

118




119



120
121
122
123

124
125

126


127
128







129


















































130
131
132




133
134
135

136
137
138


139
140






















141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168



















169
170
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







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|


>
>
>





|

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>




>

>
>
>
|
>
>
>

|
|

>
>
|
>
>
>
>
>
>
>
>
>


>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>





>
>











>

>
>




>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

>


<
>







|
|
|
|
|
|
|
|
|
|
|
<
|
>
>
>
>
>
|
<
<
<
<
|
|
>
|
<
|
>
>
|
<
>

>
|

<


>
>
>
>
>
>
>
>
>
|
<
<
<
>
>
>
>
|
<
>
|
>
>
>
>
|
>
>
>
|
|
|
<
>
|
<
>
|
>
>

<
>
>
>
>
>
>
>
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

<
<
>
>
>
>


|
>
|
|
<
>
>
|
<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>





|

|
<

|



|

|
<
|
<
<





|

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|

18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375

376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394

395
396
397
398
399
400
401




402
403
404
405

406
407
408
409

410
411
412
413
414

415
416
417
418
419
420
421
422
423
424
425
426



427
428
429
430
431

432
433
434
435
436
437
438
439
440
441
442
443
444

445
446

447
448
449
450
451

452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510


511
512
513
514
515
516
517
518
519
520

521
522
523

524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553

554
555
556
557
558
559
560
561

562


563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
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

Modified render/html.lua from [c1f1be8e43] to [778a76ed09].

6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
...
417
418
419
420
421
422
423










424
425
426
427
428
429
430
...
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
--    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








|







 







>
>
>
>
>
>
>
>
>
>







 







|
<
<
<
<
<
<
<
<
<
<
|
<
<
|







6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
...
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
...
569
570
571
572
573
574
575
576










577


578
579
580
581
582
583
584
585
--    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

Modified sirsem.lua from [4b787982a7] to [550cdedbd6].

1
2

3
4
5
6
7
8
9
..
43
44
45
46
47
48
49




50
51
52
53
54
55
56
...
546
547
548
549
550
551
552

553
554
555
556
557
558
559
...
587
588
589
590
591
592
593








594
595
596
597
598
599
600
...
885
886
887
888
889
890
891




892
893
894
895
896
897
898
...
935
936
937
938
939
940
941


























































































































































-- [ʞ] 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;
	};
}



























































































































































|
>







 







>
>
>
>







 







>







 







>
>
>
>
>
>
>
>







 







>
>
>
>







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
1
2
3
4
5
6
7
8
9
10
..
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
...
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
...
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
...
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
...
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
-- [ʞ] 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