Differences From
Artifact [6a93030d29]:
15 15
16 16 ## structure
17 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.
18 18
19 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.
20 20
21 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.
22 -* newlines (\): inserts a line break into previous paragraph and attaches the following text. mostly useful for poetry or lyrics.
22 +* newlines (\\): inserts a line break into previous paragraph and attaches the following text. mostly useful for poetry or lyrics.
23 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.:
24 24 ** [$#] is a simple section break.
25 25 ** [$#anchor] opens a new section with the ID [$anchor].
26 26 ** [$# header] opens a new section with the title "header".
27 27 ** [$#anchor header] opens a new section with both the ID [$anchor] and the title "header".
28 28 ** [$#>conversation] opens a blockquote section named [$conversation] without a header.
29 29 ** [$#^id] opens a footnote section for the multiline footnote [$id]. the ID must be specified.
................................................................................
54 54
55 55 ## styled text
56 56 most blocks contain a sequence of spans. these spans are produced by interpreting a stream of [*styled-text] following the control sequence. styled-text is a sequence of codepoints potentially interspersed with escapes. an escape is formed by an open square bracket [$\[] followed by a [*span control sequence], and arguments for that sequence like more styled-text. escapes can be nested.
57 57
58 58 * strong \[*[!styled-text]\]: causes its text to stand out from the narrative, generally rendered as bold or a brighter color.
59 59 * emphatic \[![!styled-text]\]: indicates that its text should be spoken with emphasis, generally rendered as italics
60 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
61 +* strikeout \[$[~styled-text]\]: indicates that its text should be struck through or otherwise indicated for deletion
62 +* insertion \[$[+styled-text]\]: indicates that its text should be indicated as a new addition to the text body.
63 +** consider using a macro definition [$\edit: [~[#1]][+[#2]]] to save typing if you are doing editing work
61 64 * 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.
62 65 * footnote \[^[!ref] [!styled-text]\]: annotates the text with a defined footnote
63 66 * 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
64 67 * raw literal \[$\\[!raw-text]\]: shorthand for [\[$[\…]]]
65 -* macro \{[!name] [!arguments]}: invokes a [>ex.mac macro], specified with a reference
68 +* macro \{[!name] [!arguments]\}: invokes a [>ex.mac macro], specified with a reference
66 69 * argument \[#[!var]\]: in macros only, inserts the [$var]-th argument. otherwise, inserts a context variable provided by the renderer.
67 70 * raw argument \[##[!var]\]: like above, but does not evaluate [$var].
68 71 * term \[&[!name] ([!label])\]: quotes a defined term with a link to its definition
69 72 * inline image \[&@[!name]\]: shows a small image or other object inline. the unicode character [$🖼] can also be used instead of [$&@].
70 73
71 74 ## identifiers
72 75 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.
................................................................................
193 196 ts enables the spans:
194 197 * [$\[🔒#[!level] [!styled-text]\]]: redacts the span if the security level is below that specified.
195 198 * [$\[🔒.[!word] [!styled-text]\]]: redacts the span if the specified codeword clearance is not enabled.
196 199 (the padlock emoji is shorthand for [$%ts].)
197 200
198 201 ts redacts spans securely; that is, they are simply replaced with an indicator that they have been redacted, without visually leaking the length of the redacted text.
199 202
200 -~~~ts-example example ~~~ cortav
203 +~~~#ts-example example [cortav] ~~~
201 204 %ts word doc sorrowful-pines SORROWFUL PINES
202 205
203 206 # intercept R1440 TCT S3
204 207 this communication between the ambassador of [*POLITY DOORMAT CRIMSON] "Socialist League world Glory" and an unknown noble of [*POLITY ROSE] "the Empire of a Thousand Suns" was intercepted by [*SYSTEM SUPINE WARBLE].
205 208
206 209 ## involved individuals
207 210 * (A) [*DOORMAT CRIMSON] Ambassador [🔒.morose-frenzy Hyacinth Autumn-Lotus] (confidence 1.0)
................................................................................
250 253 | [$--version] :|:[$-V]:| display the interpreter version |
251 254
252 255 ###refimpl-mode modes
253 256 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 257
255 258 most modes are defined by the renderer backend. the following modes affect the behavior of the frontend:
256 259
257 -+ ID + type + effect
260 ++ ID + type + effect
258 261 | [$render:format]:| string | selects the [>refimpl-rend renderer] (default [$html])
259 262 | [$parse:show-tree]:| flag | dumps the parse tree to the log after parsing completes
260 263
261 264 ##refimpl-rend renderers
262 265 [$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 266
264 267 ###refimpl-rend-html html
................................................................................
281 284 -m render:format html \
282 285 -m html:width 40em \
283 286 -m html:accent 80 \
284 287 -m html:hue-spread 35 \
285 288 -y html:dark-on-light # could also be written as:
286 289 $ cortav readme.ct -ommmmy readme.html render:format html html:width 40em html:accent 80 html:hue-spread 35 html:dark-on-light
287 290 ~~~
288 -