Differences From
Artifact [ecd572122d]:
1 -# cortav
1 +# cortav specification
2 2 [*cortav] is a markup language designed to be a simpler, but more capable alternative to markdown. its name derives from the [>dict Ranuir words] [!cor] "writing" and [!tav] "document", translating to something like "(plain) text document".
3 3
4 4 dict: http://ʞ.cc/fic/spirals/glossary
5 5
6 +the cortav [!format] can be called [!cortavgil], or [!gil cortavi], to differentiate it from the reference implementation [!cortavsir] or [!sir cortavi].
7 +
6 8 %toc
7 9
8 10 ## cortav vs. markdown
9 -the most important difference between cortav and markdown is that cortav is strictly line-oriented. this choice was made to ensure that cortav was relatively easy to parse. so while a simple [$.ct] file may look a bit like a [$.md] file, in reality it's a lot closer to Gemini structured text than any flavor of markdown.
11 +the most important difference between cortav and markdown is that cortav is strictly line-oriented. this choice was made to ensure that cortav was relatively easy to parse. so while a simple [$.ct] file may look a bit like a [$.md] file, in reality it's a lot closer to gemtext than any flavor of markdown.
10 12
11 13 ## encoding
12 14 a cortav document is made up of a sequence of codepoints. UTF-8 must be supported, but other encodings (such as UTF-32 or C6B) may be supported as well. lines will be derived by splitting the codepoints at the linefeed character or equivalent. note that unearthly encodings like C6B or EBCDIC will need to select their own control sequences.
13 15
14 16 ## structure
15 17 cortav is based on an HTML-like block model, where a document consists of sections, which are made up of blocks, which may contain a sequence of spans. flows of text are automatically conjoined into spans, and blocks are separated by one or more newlines. this means that, unlike in markdown, a single logical paragraph [*cannot] span multiple ASCII lines. the primary purpose of this was to ensure ease of parsing, but also, both markdown and cortav are supposed to be readable from within a plain text editor. this is the 21st century. every reasonable text editor supports soft word wrap, and if yours doesn't, that's entirely your own damn fault.
16 18
17 19 the first character(s) of every line (the "control sequence") indicates the role of that line. if no control sequence is recognized, the sequence [$.] is implied instead. the standard line classes and their associated control sequences are listed below. some control sequences have alternate forms, in order to support modern, readable unicode characters as well as plain ascii text.
18 20
19 -* paragraphs (. ¶ ❡): a paragraph is a simple block of text. the backslash control sequence is only necessary if the paragraph text begins with something that would otherwise be interpreted as a control sequence.
21 +* paragraphs (. ¶ ❡): a paragraph is a simple block of text. the period control sequence is only necessary if the paragraph text begins with something that would otherwise be interpreted as a control sequence.
20 22 * newlines (\): inserts a line break into previous paragraph and attaches the following text. mostly useful for poetry or lyrics.
21 23 * 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.:
22 24 ** [$#] is a simple section break.
23 25 ** [$#anchor] opens a new section with the ID [$anchor].
24 26 ** [$# header] opens a new section with the title "header".
25 27 ** [$#anchor header] opens a new section with both the ID [$anchor] and the title "header".
26 28 ** [$#>conversation] opens a blockquote section named [$conversation] without a header.
................................................................................
52 54
53 55 ## styled text
54 56 most blocks contain a sequence of spans. these spans are produced by interpreting a stream of [*styled-text] following the control sequence. styled-text is a sequence of codepoints potentially interspersed with escapes. an escape is formed by an open square bracket [$\[] followed by a [*span control sequence], and arguments for that sequence like more styled-text. escapes can be nested.
55 57
56 58 * strong \[*[!styled-text]\]: causes its text to stand out from the narrative, generally rendered as bold or a brighter color.
57 59 * emphatic \[![!styled-text]\]: indicates that its text should be spoken with emphasis, generally rendered as italics
58 60 * literal \[$[!styled-text]\]: indicates that its text is a reference to a literal sequence of characters, variable name, or other discrete token. generally rendered in monospace
59 -* 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.
61 +* 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.
60 62 * footnote \[^[!ref] [!styled-text]\]: annotates the text with a defined footnote
61 63 * raw \[\\[!raw-text]\]: causes all characters within to be interpreted literally, without expansion. the only special characters are square brackets, which must have a matching closing bracket
62 64 * raw literal \[$\\[!raw-text]\]: shorthand for [\[$[\…]]]
63 65 * macro \{[!name] [!arguments]}: invokes a [>ex.mac macro], specified with a reference
64 66 * argument \[#[!var]\]: in macros only, inserts the [$var]-th argument. otherwise, inserts a context variable provided by the renderer.
65 67 * raw argument \[##[!var]\]: like above, but does not evaluate [$var].
66 68 * term \[&[!name] ([!label])\]: quotes a defined term with a link to its definition
67 -* inline image \[&@[!name]\]: shows a small image or other object inline
69 +* inline image \[&@[!name]\]: shows a small image or other object inline. the unicode character [$🖼] can also be used instead of [$&@].
68 70
69 71 ## identifiers
70 72 any identifier (including a reference) that is defined within a named section must be referred to from outside that section as [$[!sec].[!obj]], where [$sec] is the ID of the containing section and [$obj] is the ID of the object one wishes to reference.
71 73
72 74 ## context variables
73 -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]].
75 +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]].
74 76
75 -* cortav.file: the name of the file currently being rendered
76 -* cortav.path: the absolute path of the file currently being rendered
77 -* cortav.time: the current system time
78 -* cortav.date: the current system date
79 -* cortav.page: the number of the page currently being rendered
80 -* cortav.id: the identifier of the renderer
81 -* cortav.hash: the SHA3 hash of the source file being rendered
77 +* {def cortav.file} the name of the file currently being rendered
78 +* {def cortav.path} the absolute path of the file currently being rendered
79 +* {def cortav.time} the current system time in the form [$[#cortav.time]]
80 +* {def cortav.date} the current system date in the form [$[#cortav.date]]
81 +* {def cortav.datetime} the current system date and time represented in the locale or system-standard manner (e.g. [$[#cortav.datetime]])
82 +* {def cortav.page} the number of the page currently being rendered
83 +* {def cortav.id} the identifier of the renderer
84 +* {def cortav.hash} the SHA3 hash of the source file being rendered
85 + def: [*[#1]]:
82 86
83 87 on systems with environment variables, these may be accessed as context variables by prefixing their name with [$env.].
84 88
85 89 different renderers may provide context in different ways, such as from command line options or a context file. any predefined variables should carry an appropriate prefix to prevent conflation.
86 90
87 91 ## directives
88 -* format: gives a hint on how the document should be formatted. the first hint that is understood will be applied; all others will be discarded. standard hints include
92 + d: [$%[*[##1]]]
93 +* {d format} gives a hint on how the document should be formatted. the first hint that is understood will be applied; all others will be discarded. standard hints include:
89 94 ** essay
90 95 ** narrative
91 96 ** screenplay: uses asides to denote actions, quotes for dialogue
92 97 ** stageplay: uses asides to denote actions, quotes for dialogue
93 98 ** manual
94 99 ** glossary
95 100 ** news
96 -* author: encodes document authorship
97 -* cols: specifies the number of columns the next object should be rendered with
98 -* include: transcludes another file
99 -* quote: transcludes another file, without expanding the text except for paragraphs
100 -* embed: where possible, embeds another file as an object within the current one. in HTML this could be accomplished with e.g. an iframe.
101 -* expand: causes the next object (usually a code block) to be fully expanded when it would otherwise not be
101 +* {d author} encodes document authorship
102 +* {d cols} specifies the number of columns the next object should be rendered with
103 +* {d include} transcludes another file
104 +* {d quote} transcludes another file, without expanding the text except for paragraphs
105 +* {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.
106 +* {d expand} causes the next object (usually a code block) to be fully expanded when it would otherwise not be
102 107
103 108 ##ex examples
104 109
105 110 ~~~ blockquotes #bq [cortav] ~~~
106 111 the following excerpts of text were recovered from a partially erased hard drive found in the Hawthorne manor in the weeks after the Incident. context is unknown.
107 112
108 113 #>
................................................................................
173 178 the interpreter should provide a [$cortav] table with the objects:
174 179 * ctx: contains context variables
175 180
176 181 used files should return a table with the following members
177 182 * macros: an array of functions that return strings or arrays of strings when invoked. these will be injected into the global macro namespace.
178 183
179 184 ### ts
180 -the [*ts] extension allows documents to be marked up for basic classification constraints and automatically redacted. if you are seriously relying on ts for confidentiality, make damn sure you start the file with [$\[requires ts\]], so that rendering will fail with an error if the extension isn't supported.
185 +the [*ts] extension allows documents to be marked up for basic classification constraints and automatically redacted. if you are seriously relying on ts for confidentiality, make damn sure you start the file with [$%[*requires] ts], so that rendering will fail with an error if the extension isn't supported.
181 186
182 187 ts enables the directives:
183 188 * [$ts class [!scope] [!level] (styled-text)]: indicates a classification level for either the while document (scope [!doc]) or the next section (scope [!sec]). if the ts level is below [$level], the section will be redacted or rendering will fail with an error, as appropriate. if styled-text is included, this will be treated as the name of the classification level.
184 189 * [$ts word [!scope] [!word] (styled-text)]: indicates a codeword clearance that must be present for the text to render. if styled-text is present, this will be used to render the name of the codeword instead of [$word].
185 190 * [$when ts level [!level]]
186 191 * [$when ts word [!word]]
187 192
................................................................................
210 215 <A> we may have a problem
211 216 <B> Hyacinth, I told you not to contact me without—
212 217 <A, shouting> god DAMMIT woman I am trying to SAVE your worthless skin
213 218 <B> Hyacinth! your Godforsaken scrambler!
214 219 <A> …oh, [!fuck].
215 220 (signal lost)
216 221 ~~~
222 +
223 +# reference implementation
224 +the cortav standard is implemented in [$cortav.lua], found in this repository. only the way [$cortav.lua] interprets the cortav language is defined as a reference implementation; other behaviors are simply how [$cortav.lua] implements the specification and may be copied, ignored, tweaked, violently assaulted, or used as inspiration by a compliant parser.
225 +
226 +## invocation
227 +[$cortav.lua] is operated from the command line, either with the command [$lua cortav.lua] or by first compiling it to bytecode; a makefile for producing a "bytecode binary" that can be executed like a normal executable is included in the repository. henceforth it will be assumed you are using the compiled form; if you are instead running [$cortav.lua] directly as an interpreted script, just replace [$$ cortav] with [$$ lua cortav.lua] in incantations.
228 +
229 +when run without commands, [$cortav.lua] will read input from standard input and write to standard output. alternately, a source file can be given as an argument. to write to a specific file instead of the standard output stream, use the [$-o [!file]] flag.
230 +
231 +~~~
232 +$ cortav readme.ct -o readme.html
233 + # reads from readme.ct, writes to readme.html
234 +$ cortav -o readme.html
235 + # reads from standard input, writes to readme.html
236 +$ cortav readme.ct
237 + # reads from readme.ct, writes to standard output
238 +~~~
239 +
240 +### switches
241 +[$cortav.lua] offers various switches to control its behavior.
242 ++ long + short + function +
243 +| [$--out [!file]] :|:[$-o]:| sets the output file (default stdout) |
244 +| [$--log [!file]] :|:[$-l]:| sets the log file (default stderr) |
245 +| [$--define [!var] [!val]]:|:[$-d]:| sets the context variable [$var] to [$val] |
246 +| [$--mode-set [!mode]] :|:[$-y]:| activates the [>refimpl-mode mode] with ID [!mode]
247 +| [$--mode-clear [!mode]] :|:[$-n]:| disables the mode with ID [!mode] |
248 +| [$--mode [!id] [!val]] :|:[$-m]:| configures mode [!id] with the value [!val] |
249 +| [$--help] :|:[$-h]:| display online help |
250 +| [$--version] :|:[$-V]:| display the interpreter version |
251 +
252 +###refimpl-mode modes
253 +most of [$cortav.lua]'s implementation-specific behavior is controlled by use of [!modes]. these are namespaced options which may have a boolean, string, or numeric value. boolean modes are set with the [$-y] [$-n] flags; other modes use the [$-m] flags.
254 +
255 +most modes are defined by the renderer backend. the following modes affect the behavior of the frontend:
256 +
257 ++ ID + type + effect
258 +| [$render:format]:| string | selects the [>refimpl-rend renderer] (default [$html])
259 +| [$parse:show-tree]:| flag | dumps the parse tree to the log after parsing completes
260 +
261 +##refimpl-rend renderers
262 +[$cortav.lua] implements a frontend-backend architecture, separating the parsing stage from the rendering stage. this means new renderers can be added to [$cortav.lua] relatively easily. currently, only an [>refimpl-rend-html HTML renderer] is included; however, a [$groff] backend is planned at some point in the future, so that PDFs and manpages can be generated from cortav files.
263 +
264 +###refimpl-rend-html html
265 +the HTML renderer is activated with the incantation [$-m render:format html]. it is currently the default backend. it produces a single HTML file, optionally with CSS styling data, from a [$.ct] input file.
266 +
267 +it supports the following modes:
268 +
269 +* string (css length) [$html:width] sets a maximum width for the body content in order to make the page more readable on large displays
270 +* number [$html:accent] applies an accent hue to the generated webpage. the hue is specified in degrees, e.g. [$-m html:accent 0] applies a red accent.
271 +* flag [$html:dark-on-light] uses dark-on-light styling, instead of the default light-on-dark
272 +* flag [$html:fossil-uv] outputs an HTML snippet suitable for use with the Fossil VCS webserver. this is intended to be used with the unversioned content mechanism to host rendered versions of documentation written in cortav that's stored in a Fossil repository.
273 +* number [$html:hue-spread] generates a color palette based on the supplied accent hue. the larger the value, the more the other colors diverge from the accent hue.
274 +* string [$html:link-css] generates a document linking to the named stylesheet
275 +* flag [$html:gen-styles] embeds appropriate CSS styles in the document (default on)
276 +* flag [$html:snippet] produces a snippet of html instead of an entire web page. note that proper CSS scoping is not yet implemented (and can't be implemented hygienically since [$scoped] was removed 😢)
277 +* string [$html:title] specifies the webpage titlebar contents (normally autodetected from the document based on headings or directives)
278 +
279 +~~~
280 +$ cortav readme.ct --out readme.html \
281 + -m render:format html \
282 + -m html:width 40em \
283 + -m html:accent 80 \
284 + -m html:hue-spread 35 \
285 + -y html:dark-on-light # could also be written as:
286 +$ cortav readme.ct -ommmmy readme.html render:format html html:width 40em html:accent 80 html:hue-spread 35 html:dark-on-light
287 +~~~
217 288