cortav  Check-in [35f8445017]

this paragraph contains some [.important truly important] information.
	important: dense underline font=impact html.class=blink
~~~
you should always give your styles semantic names where practicable, instead of simply describing their graphical characteristics. this is good practice in general, but especially because your document will be renderable to different formats with different characteristics, and what makes text look important on a manpage in the terminal may be quite different from how it looks in a webpage or PDF.

##dir directives
	d: [`%[*[##1]]]

* {d author} encodes document authorship. multiple author directives can be issued to add additional coauthors
* {d cols} specifies the number of columns the next object should be rendered with
* {d include} transcludes another file
* {d import} reads in the contents of another file as an embeddable section
* {d quote} transcludes another file, without expanding the text except for paragraphs 
* {d embed}, where possible, embeds another file as an object within the current one. in HTML this could be accomplished with e.g. an iframe.
* {d expand} causes the next object (usually a code block) to be fully expanded when it would otherwise not be
................................................................................
* [`%[*toc] name [$id styled-text]]: like [`%[*toc] mark] but allows an additional [$id] parameter which specifies the ID the renderer will assign to an anchor element. this is not meaningful for all renderers and when it is, it is up to the renderer to decide what it means.
** the [*html] render backend interprets [$id] as the [`id] element for the anchor tag
** the [*groff] render backend ignores [$id]

###tsmog transmogrify
a cortav renderer may automatically translate punctuation marks or symbol sequences to superior representations depending on their context. to be compliant this extension should implement, at minimum:
* smart quotes (with consideration for the typographical conventions languages like German or Spanish)
** {dir.d transmogrify|language [$lang]} can be used to explicitly set the language; otherwise, it must be determined from the value of {dir.d pragma|lang}. if this is not present, implementations may fall back on their own methods for determining the language in use, such as command-line flags.
* multigraph to glyph conversion, including at least:
** ["--] --> "—"
** ["-->] --> "→"
** ["<--] -->  "←"

an escape character before any of the sequence characters should prevent the sequence from being rendered. raw nodes (that is, ["[\…]] and ["["…]]) should not be scanned for transmogrification, nor should the contents of code blocks unless marked with the [`%[*expand]] directive

transmogrification shall only take place after all other parsing steps are completed.

###hilite hilite
code can be highlighted according to the formal language it is written in. a compliant hilite implementation must implement basic keyword, symbol, comment, pragma, and literal highlighing for the following formal languages.
* C





* [>lua Lua]
* [>html HTML]
* [>scheme Scheme]

* [>terra Terra]


* [>libconfig libconfig]








	lua: https://lua.org
	scheme: https://call-cc.org

	terra: https://terralang.org
	html: https://dev.w3.org/html5/spec-LC/

	libconfig: http://hyperrealm.github.io/libconfig/




the highlighter should make use of semantic HTML tags like [`<var>] where possible.

###lua lua
renderers with a lua interpreter available can evaluate lua code:
* [`%lua use [!file]]: evaluates [$file] and makes its definitions available
* [`\[%lua raw [!script]\]]: evaluates [$script] and emits the string it returns (if any) in raw span context.

this paragraph contains some [.important truly important] information.
	important: dense underline font=impact html.class=blink
~~~
you should always give your styles semantic names where practicable, instead of simply describing their graphical characteristics. this is good practice in general, but especially because your document will be renderable to different formats with different characteristics, and what makes text look important on a manpage in the terminal may be quite different from how it looks in a webpage or PDF.

##dir directives
	d: [`%[*[##1]]]
	dd: [`%[*[##1]] [#2]]
* {d author} encodes document authorship. multiple author directives can be issued to add additional coauthors
* {d cols} specifies the number of columns the next object should be rendered with
* {d include} transcludes another file
* {d import} reads in the contents of another file as an embeddable section
* {d quote} transcludes another file, without expanding the text except for paragraphs 
* {d embed}, where possible, embeds another file as an object within the current one. in HTML this could be accomplished with e.g. an iframe.
* {d expand} causes the next object (usually a code block) to be fully expanded when it would otherwise not be
................................................................................
* [`%[*toc] name [$id styled-text]]: like [`%[*toc] mark] but allows an additional [$id] parameter which specifies the ID the renderer will assign to an anchor element. this is not meaningful for all renderers and when it is, it is up to the renderer to decide what it means.
** the [*html] render backend interprets [$id] as the [`id] element for the anchor tag
** the [*groff] render backend ignores [$id]

###tsmog transmogrify
a cortav renderer may automatically translate punctuation marks or symbol sequences to superior representations depending on their context. to be compliant this extension should implement, at minimum:
* smart quotes (with consideration for the typographical conventions languages like German or Spanish)
** {dir.dd transmogrify|language [$lang]} can be used to explicitly set the language; otherwise, it must be determined from the value of {dir.dd pragma|lang}. if this is not present, implementations may fall back on their own methods for determining the language in use, such as command-line flags.
* multigraph to glyph conversion, including at least:
** ["--] --> "—"
** ["-->] --> "→"
** ["<--] -->  "←"

an escape character before any of the sequence characters should prevent the sequence from being rendered. raw nodes (that is, ["[\\…]] and ["["…]]) should not be scanned for transmogrification, nor should the contents of code blocks unless marked with the [`%[*expand]] directive

transmogrification shall only take place after all other parsing steps are completed.

###hilite hilite
code can be highlighted according to the formal language it is written in. a compliant hilite implementation must implement basic keyword, symbol, comment, pragma, and literal highlighing for the following formal languages.
* [^nocpp C]
	nocpp: all keywords and constructions present in C20 should be highlighted correctly, including e.g. [`typeof] and [`_Static_assert]. C++ support will never be required, due to the extreme complexity of C++ grammar and the likelihood that any naïve hilighter will produce incorrect results in edge cases
* Bourne Shell
* DOS INI
* [>glsl GLSL]
* [>gmake gmake] and [>bmake bmake]
* [>lua Lua]


* [>fennel Fennel]
* [>terra Terra]
* [>scheme Scheme]
* SQL (including PL/SQL)
* [>libconfig libconfig]
* [>groff groff]
* [>html HTML]
* [>css CSS]
* cortav

	glsl: https://www.khronos.org/opengl/wiki/Core_Language_(GLSL)
	gmake: https://www.gnu.org/software/make/
	bmake: https://www.freebsd.org/cgi/man.cgi?query=bmake&sektion=1
	lua: https://lua.org

	fennel: https://fennel-lang.org
	terra: https://terralang.org

	scheme: https://call-cc.org
	libconfig: http://hyperrealm.github.io/libconfig/
	groff: https://www.gnu.org/software/groff/
	html: https://dev.w3.org/html5/spec-LC/
	css: https://www.w3.org/Style/CSS/current-work

the highlighter should make use of semantic HTML tags like [`<var>] where possible.

###lua lua
renderers with a lua interpreter available can evaluate lua code:
* [`%lua use [!file]]: evaluates [$file] and makes its definitions available
* [`\[%lua raw [!script]\]]: evaluates [$script] and emits the string it returns (if any) in raw span context.