Differences From
Artifact [e9d2ad32df]:
84 84
85 85 ## styled text
86 86 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.
87 87
88 88 * strong \[*[!styled-text]\]: causes its text to stand out from the narrative, generally rendered as bold or a brighter color.
89 89 * emphatic \[![!styled-text]\]: indicates that its text should be spoken with emphasis, generally rendered as italics
90 90 * 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
91 -* strikeout \[$[~styled-text]\]: indicates that its text should be struck through or otherwise indicated for deletion
92 -* insertion \[$[+styled-text]\]: indicates that its text should be indicated as a new addition to the text body.
91 +* strikeout \[~[!styled-text]\]: indicates that its text should be struck through or otherwise indicated for deletion
92 +* insertion \[+[!styled-text]\]: indicates that its text should be indicated as a new addition to the text body.
93 93 ** consider using a macro definition [$\edit: [~[#1]][+[#2]]] to save typing if you are doing editing work
94 94 * 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.
95 95 * footnote \[^[!ref] [!styled-text]\]: annotates the text with a defined footnote
96 96 * 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
97 97 * raw literal \[$\\[!raw-text]\]: shorthand for [\[$[\…]]]
98 98 * macro \{[!name] [!arguments]\}: invokes a [>ex.mac macro], specified with a reference
99 99 * argument \[#[!var]\]: in macros only, inserts the [$var]-th argument. otherwise, inserts a context variable provided by the renderer.
................................................................................
199 199 where possible, instead of [$needs x y z], the directive [$when has-ext x y z] should be used instead. this causes the next section to be rendered only if the named extensions are available. [$unless has-ext x y z] can be used to provide an alternative format.
200 200
201 201 extensions are mainly interacted with through directives. all extension directives must be prefixed with the name of the extension.
202 202
203 203 ### toc
204 204 sections that have a title will be included in the table of contents. the table of contents is by default inserted at the break between the first level-1 section and the section immediately following it. you may instead place the directive [$toc] where you wish the TOC to be inserted, or suppress it entirely with [$inhibits toc]. note that some renderers may not display the TOC as part of the document itself.
205 205
206 +toc provides the directives:
207 +
208 +* [$%[*toc]]: insert a table of contents in the specified position. this can be used more than once, but doing so may have confusing, incorrect, or nonsensical results under some renderers, and some may just ignore the directive entirely
209 +* [$%[*toc] mark [!styled-text]]: inserts a TOC entry with the label [!styled-text] pointing to the current location. this can be used to e.g. mark noteworthy images, instances of long quotes or literal blocks, or functions inside an expanded code block.
210 +* [$%[*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.
211 +** the [*html] render backend interprets [!id] as the [$id] element for the anchor tag
212 +** the [*groff] render backend ignores [!id]
213 +
206 214 ### smart-quotes
207 215 a cortav renderer may automatically translate punctuation marks to other punctuation marks depending on their context.
208 216
209 217 ### hilite
210 218 code can be highlighted according to the formal language it is written in.
211 219
212 220 ### lua
................................................................................
378 386 -m html:hue-spread 35 \
379 387 -y html:dark-on-light # could also be written as:
380 388 $ cortav readme.ct -ommmmy readme.html render:format html html:width 40em html:accent 80 html:hue-spread 35 html:dark-on-light
381 389 ~~~
382 390
383 391 ## further directions
384 392
393 +### additional backends
394 +it is eventually intended to support to following backends, if reasonably practicable.
395 +* [*html]: emit HTML and CSS code to typeset the document. [!in progress]
396 +* [*svg]: emit SVG, taking advantage of its precise layout features to produce a nicely formatted and paginated document. pagination can be accomplished through emitting multiple files or by assigning one layer to each page. [!long term]
397 +* [*groff]: the most important output backend, rivalling [*html]. will allow the document to be typeset in a wide variety of formats, including PDF and manpage. [!short term]
398 +* [*gemtext]: essentially a downrezzing of cortav to make it readable to Gemini clients
399 +
400 +some formats may eventually warrant their own renderer, but are not a priority:
401 +* [*text]: cortav source files are already plain text, but a certain amount of layout could be done using ascii art.
402 +* [*ansi]: emit sequences of ANSI escape codes to lay out a document in a terminal-friendly way
403 +* [*tex]: TeX is an unholy abomination and i neither like nor use it, but lots of people do and if cortav ever catches on, a TeX backend should probably be written eventually.
404 +
405 +PDF is not on either list because it's a nightmarish mess of a format and groff, which is installed on most linux systems already, can easily generate PDFs
406 +
385 407 ### LCH support
386 408 right now, the use of color in the HTML renderer is very unsatisfactory. the accent mechanism operates on the basis of the CSS HSL function, which is not perceptually uniform; different hues will present different mixes of brightness and some (yellows?) may be ugly or unreadable.
387 409
388 410 the ideal solution would be to simply switch to using LCH based colors. unfortunately, only Safari actually supports the LCH color function right now, and it's unlikely (unless Lea Verou and her husband manage to work a miracle) that Colors Level 4 is going to be implemented very widely any time soon.
389 411
390 412 this leaves us in an awkward position. we can of course do the math ourselves, working in LCH to implement the internal [$@tone] macro, and then "converting" these colors to HSL. unfortunately, you can't actually convert from LCH to HSL; it's like converting from pounds to kilograms. LCH can represent any color the human visual system can perceive; sRGB can't, and CSS HSL is implemented in sRGB. however, we could at least approximate something that would allow for perceptually uniform brightness, which would be an improvement, and this is probably the direction to go in, unless a miracle occurs and [$lch()] or [$color()] pop up in Blink.
391 413
392 414 it may be possible to do a more reasonable job of handling colors in the postscript and TeX outputs. unsure about SVG but i assume it suffers the same problems HTML/CSS do. does groff even support color??
393 415
394 416 ### intent files
395 417 there's currently no standard way to describe the intent and desired formatting of a document besides placing pragmas in the source file itself. this is extremely suboptimal, as when generating collections of documents, it's ideal to be able to keep all formatting information in one place. users should also be able to specify their own styling overrides that describe the way they prefer to read [$cortav] files, especially for uses like gemini or gopher integration.
396 418
397 419 at some point soon [$cortav] needs to address this by adding intent files that can be activated from outside the source file, such as with a command line flag or a configuration file setting. these will probably consist of lines that are interpreted as pragmata. in addition to the standard intent format however, individual implementations should feel free to provide their own ways to provide intent metadata; e.g. the reference implementation, which has a lua interpreter available, should be able to take a lua script that runs after the parse stage and generates . this will be particularly useful for the end-user who wishes to specify a particular format she likes reading her files in without forcing that format on everyone she sends the compiled document to, as it will be able to interrogate the document and make intelligent decisions about what pragmata to apply.