Differences From
Artifact [fb6019b4ad]:
104 104 *[*definition] ([^def-ex tab]): a line [^def-tab-enc beginning with a tab] is a multipurpose metadata syntax. the tab may be followed by an identifier, a colon, and a value string, in which case it opens a new definition; alternatively, a second tab character turns the line into a [*definition continuation], adding the remaining characters as a new line to the definition value on the previous line. when a new definition is opened on a line immediately following certain kinds of objects, such as resources, embeds, or multiline macro expansions, it attaches key-value metadata to that object. when a definition is not preceded by such an object, an independent [*reference] is created instad.
105 105 ** a [*reference] is a general mechanism for out-of-line metadata, and references are used in many different ways -- e.g. to specify link destinations, footnote contents, abbreviations, or macro bodies. to ensure that a definition is interpreted as a reference, rather than as metadata for an object, precede it with a blank line.
106 106 def-tab-enc: in encodings without tab characters, a definition is opened by a line beginning with two blanks, and continued by a line beginning with four blanks.
107 107 def-ex: [*open a new reference]: [`[!\\t][$key]: [$value]]
108 108 [*continue a reference]: [`[!\\t\\t][$value]]
109 109 * [*quotation] ([`<]): a line of the form [`<[$name]> [$quote]] denotes an utterance by [$name].
110 110 * [*blockquote] ([`>]): alternate blockquote syntax. can be nested by repeating the [`>] character.
111 -* [*subtitle/caption] ([`\--]): attaches a subtitle to the previous header, or caption to the previous object
111 +* [*subtitle/caption] (["--]): attaches a subtitle to the previous header, or caption to the previous object
112 112 * [*embed] ([`&]): embeds a referenced object. can be used to show images or repeat previously defined objects like lists or tables, optionally with a caption. an embed line can be followed immediately by a sequence of [*definitions] in the same way that resource definitions can, to override resource properties on a per-instance basis. note that only presentation-related properties like [$desc] can be meaningful overridden, as embed does not trigger a re-render of the parse tree; if you want to override e.g. context variables, use a multiline macro invocation instead.
113 113 ** [`&[$image]] embeds an image or other block-level object. [!image] can be a reference with a url or file path, or it can be an embed section (e.g. for SVG files)
114 114 ***[`&myimg All that remained of the unfortunate blood magic pageant contestants and audience (police photo)]
115 115 ** [`&-[$ident] [$styled-text]] embeds a closed disclosure element containing the text of the named object (a nonprinting section or cortav resource should usually be used to store the content; it can also name an image or video, of course). in interactive outputs, this will display as a block which can be clicked on to view the full contents of the referenced object [$ident]; if [$styled-text] is present, it overrides the title of the section you are embedding (if any). in static outputs, the disclosure object will display as an enclosed box with [$styled-text] as the title text
116 116 *** [`&-ex-a Prosecution Exhibit A (GRAPHIC CONTENT)]
117 117 ** [`&+[$section] [$styled-text]] is like the above, but the disclosure element is open by default
118 118 * [`$[$macro] [$arg1]|[$arg2]|[$argn]…] invokes a block-level macro with the supplied arguments, and can be followed by a property override definition list the same way embed and resource lines can. note that while both [`$[$id]] and [`&[$id]] can be used to instantiate resources of type [`text/x.cortav], there is a critical difference: [`$[$id]] renders out the sub-document separately each time it is named, allowing for parameter expansion and for context variables to be overridden for each invocation. by contrast, [`&[$id]] can only insert copies of the same render; no parameters can be passed and context variables will be expanded to their value at the time the resource was defined.
119 119 ** [`$mymacro arg 1|arg 2|arg 3]
120 -* [*horizontal rule] ([`\---]): inserts a horizontal rule or other context break; does not end the section. must be followed by newline. underlines can also be used in place of dashes ([`___], [`-_-], [`__-__-__] etc), as can horizontal unicode box drawing characters ([`─ ━ ┈] etc).
121 -* [*page break] ([`\^^]): for formats that support pagination, like EPUB or HTML (when printed), indicates that the rest of the current page should be blank. for formats that do not, extra margins will be inserted. does not create a new section
122 -* [*page rule] ([`\^-^]): inserts a page break for formats that support them, and a horizontal rule for formats that do not. does not create a new section. comprised of any number of horizontal rule characters surrounded by a pair of carets (e.g. [`^-^] [`^_^] [`^----^] [`^__--^] [`^┈┈┈┈┈^])
120 +* [*horizontal rule] (["---]): inserts a horizontal rule or other context break; does not end the section. must be followed by newline. underlines can also be used in place of dashes ([`___], [`-_-], [`__-__-__] etc), as can horizontal unicode box drawing characters ([`─ ━ ┈] etc).
121 +* [*page break] (["^^]): for formats that support pagination, like EPUB or HTML (when printed), indicates that the rest of the current page should be blank. for formats that do not, extra margins will be inserted. does not create a new section
122 +* [*page rule] (["^-^]): inserts a page break for formats that support them, and a horizontal rule for formats that do not. does not create a new section. comprised of any number of horizontal rule characters surrounded by a pair of carets (e.g. [`^-^] [`^_^] [`^----^] [`^__--^] [`^┈┈┈┈┈^])
123 123 * [*table cells] ([`+ |]): see [>ex.tab table examples].
124 124 * [*equations] ([`=]): block-level equations can be inserted with the [`=] sequence
125 125 * [*cross-references] ([`=>] [`⇒]): inserts a block-level link. has two forms for the sake of gemtext compatibility. [$styled-text] is a descriptive text of the destination. especially useful for menus and gemtext output.
126 -** the cortav syntax is [`=>[$ident] [$styled-text]], where [$ident] is an identifier; links to the same destination as [` \[>[$ident] [$styled-text]\]] would
126 +** the cortav syntax is [`=>[$ident] [$styled-text]], where [$ident] is an identifier; links to the same destination as [`\[>[$ident] [$styled-text]\]] would
127 127 ** the compatibility syntax is [`=> [$uri] [$styled-text]] (note the space before [$uri]!). instead of taking an identifier for an object in the document, it directly accepts a URI. note that this is not formally equivalent to gemtext's link syntax, which also allows paths in place of URIs; [`cortav] does not. the gemtext line ["=> /somewhere] would need to be expressed as ["=> file:/somewhere], and ["=> /somewhere?key=val] as ["http:/somewhere?key=val] (or ["gemini:/somewhere?key=val], if the result is to be served over a gemini server).
128 128 * [*empty lines] (that is, lines consisting of nothing but whitespace) constitute a [!break], which terminates multiline objects that do not have a dedicated termination sequence, for example lists and asides.
129 129
130 130 ##onspans styled text
131 131 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.
132 132
133 133 * strong {obj *|styled-text}: causes its text to stand out from the narrative, generally rendered as bold or a brighter color.
................................................................................
134 134 * emphatic {obj !|styled-text}: indicates that its text should be spoken with emphasis, generally rendered as italics
135 135 * custom style {span .|id|[$styled-text]}: applies a specially defined font style. for example, if you have defined [`caution] to mean "demibold italic underline", cortav will try to apply the proper weight and styling within the constraints of the current font to the span [$styled-text]. see the [>fonts-sty fonts section] for more information about this mechanism.
136 136 * literal {obj `|styled-text}: indicates that its text is a reference to a literal sequence of characters or other discrete token. generally rendered in monospace
137 137 * variable {obj $|styled-text}: indicates to the reader that its text is a placeholder, rather than a literal representation. generally rendered in italic monospace, ideally of a different color
138 138 * underline {obj _|styled-text}: underlines the text. use sparingly on text intended for webpages -- underlined text [!is] distinct from links, but underlining non-links is still a violation of convention.
139 139 * strikeout {obj ~|styled-text}: indicates that its text should be struck through or otherwise indicated for deletion
140 140 * insertion {obj +|styled-text}: indicates that its text should be indicated as a new addition to the text body.
141 -** consider using a macro definition [`\edit: [~[#1]][+[#2]]] to save typing if you are doing editing work
142 -* 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.
143 -* 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 text [`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.
141 +** consider using a macro definition ["edit: [~[#1]][+[#2]]] to save typing if you are doing editing work
142 +* 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.
143 +* 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 text [`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. [$ref] can be the ID of a reference, in which case the reference value is parsed as [`cortav] markup to form the body of the footnote; it can also be the ID of a resource, which can be of any MIME type compatible with the current renderer, as as [`text/x.cortav], [`text/plain], or [`image/png].
144 144 * superscript {obj '|[$styled-text]}
145 145 * subscript {obj ,|[$styled-text]}
146 146 * 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.
147 147 * raw literal [` \["[$raw-text]\]]: shorthand for a raw inside a literal, that is ["[`[\\…]]]
148 148 * macro [` \{[$name] [$arguments]}]: invokes a [>ex.mac macro] inline, specified with a reference. if the result of macro expansion contains newlines, they will be treated as line breaks, rather than paragraph breaks as they would be in a multiline context.
149 149 * argument {obj #|var}: in macros only, inserts the [$var]-th argument. otherwise, inserts a context variable provided by the renderer.
150 150 * raw argument {obj ##|var}: like above, but does not evaluate [$var].
................................................................................
645 645 .pos: n
646 646 .meaning: speech
647 647
648 648 %% context variables are useful because they inherit from the enclosing context
649 649 %% thus, we can exploit resource syntax to create templates with default values
650 650
651 651 @agent {
652 - + CODENAME :| [#1]
653 - + CIVILIAN IDENTITY :| [#civil]
652 + + CODENAME :| [#1]
653 + + CIVILIAN IDENTITY :| [#civil]
654 654 + RULES of ENGAGEMENT :| [#roe]
655 - + DANGER LEVEL :| [#danger]
655 + + DANGER LEVEL :| [#danger]
656 656 }
657 657 .civil: (unknown)
658 658 .roe: Monitor; do not engage
659 659 .danger: (unknown)
660 660
661 661 $agent ZUCCHINI PARABLE
662 662 .civil: Zephram "Rolodex" Goldberg
................................................................................
672 672 + english :+ ranuir + zia ţai + thaliste +
673 673 | honor :| tef | pang | mbecheve |
674 674 | rakewyrm:| hirvag | hi phang | nache umwelinde |
675 675 | eat :| fese | dzia | rotechqa |
676 676
677 677 and now the other way around!
678 678
679 -+:english :| honor |
680 -+:ranuir :| tef |
681 -+:zia ţai :| pang |
679 ++:english :| honor |
680 ++:ranuir :| tef |
681 ++:zia ţai :| pang |
682 682 +:thalishte:| mbecheve |
683 683 ~~~
684 684
685 685 ##extns extensions
686 686 the cortav specification also specifies a number of extensions that do not have to be supported for a renderer to be compliant. the extension mechanism supports the following directives.
687 687
688 688 * inhibits: prevents an extension from being used even where available
................................................................................
752 752
753 753 the highlighter should make use of semantic HTML tags like [`<var>] where possible.
754 754
755 755 ###lua lua
756 756 renderers with a lua interpreter available can evaluate lua code:
757 757 * [`%lua use [!file]]: evaluates [$file] and makes its definitions available
758 758 * [`\[%lua raw [!script]\]]: evaluates [$script] and emits the string it returns (if any) in raw span context.
759 -* [` \[%lua exp [!script]\]]: evaluates [$script] and emits the string it returns (if any) in expanded span context.
759 +* [`\[%lua exp [!script]\]]: evaluates [$script] and emits the string it returns (if any) in expanded span context.
760 760 * [`%lua raw [!script]]: evaluates [$script] and emits the string array it returns (if any) in raw block context.
761 761 * [`%lua exp [!script]]: evaluates [$script] and emits the string array it returns (if any) in expanded block context.
762 762
763 763 the interpreter should provide a [`cortav] table with the objects:
764 764 * [`ctx]: contains context variables
765 765
766 766 used files should return a table with the following members
................................................................................
774 774 [`ts] enables the directives:
775 775 * [`%[*ts] class [$scope level] ([$styled-text])]: indicates a classification level for either the whole 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.
776 776 * [`%[*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].
777 777 * [`%[*when] ts level [$level]]
778 778 * [`%[*when] ts word [$word]]
779 779
780 780 [`ts] enables the spans:
781 -* [` \[🔒#[$level] [$styled-text]\]]: redacts the span if the security level is below that specified.
782 -* [` \[🔒.[$word] [$styled-text]\]]: redacts the span if the specified codeword clearance is not enabled.
781 +* [`\[🔒#[$level] [$styled-text]\]]: redacts the span if the security level is below that specified.
782 +* [`\[🔒.[$word] [$styled-text]\]]: redacts the span if the specified codeword clearance is not enabled.
783 783 (the padlock emoji is shorthand for [`%[*ts]].)
784 784
785 785 [`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. redacted sections are simply omitted.
786 786
787 787 ~~~#ts-example example [cortav] ~~~
788 788 %ts word doc sorrowful-pines SORROWFUL PINES
789 789
................................................................................
945 945 [*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.
946 946
947 947 corran: http://ʞ.cc/fic/spirals/society
948 948 tengwar: https://en.wikipedia.org/wiki/Tengwar
949 949
950 950 ###refimpl-switches switches
951 951 [`cortav.lua] offers various switches to control its behavior.
952 -+ long + short + function +
952 ++ long + short + function +
953 953 | [`--out [$file]] :|:[`-o]:| sets the output file (default stdout) |
954 954 | [`--log [$file]] :|:[`-l]:| sets the log file (default stderr) |
955 955 | [`--define [$var] [$val]] :|:[`-d]:| sets the context variable [$var] to [$val] |
956 956 | [`--mode-set [$mode]] :|:[`-y]:| activates the [>refimpl-mode mode] with ID [!mode]
957 957 | [`--mode-clear [$mode]] :|:[`-n]:| disables the mode with ID [!mode] |
958 958 | [`--mode [$id] [$val]] :|:[`-m]:| configures mode [$id] with the value [$val] |
959 959 | [`--mode-set-weak [$mode]] :|:[`-Y]:| activates the [>refimpl-mode mode] with ID [$mode] if the source file does not specify otherwise