Differences From
Artifact [1a665df7bf]:
97 97 ** [`~~~ language] (markdown-style shorthand syntax)
98 98 ** [`~~~ \[language\] ~~~] (cortav syntax)
99 99 ** [`~~~ \[language\] #id ~~~]
100 100 ** [`~~~ title ~~~]
101 101 ** [`~~~ title \[language\] ~~~]
102 102 ** [`~~~ \[language\] title ~~~]
103 103 ** [`~~~ title \[language\] #id ~~~]
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 resource, 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 -** 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 macros. to ensure that a definition is interpreted as a reference, rather than as metadata for an object, precede it with a blank line.
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 +** 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 111 * [*subtitle/caption] ([`\--]): attaches a subtitle to the previous header, or caption to the previous object
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.
113 -** [`$[$macro] [$arg1]|[$arg2]|[$argn]…] invokes a block-level macro with the supplied arguments
114 -*** [`$mymacro arg 1|arg 2|arg 3]
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.
115 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)
116 114 ***[`&myimg All that remained of the unfortunate blood magic pageant contestants and audience (police photo)]
117 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
118 116 *** [`&-ex-a Prosecution Exhibit A (GRAPHIC CONTENT)]
119 117 ** [`&+[$section] [$styled-text]] is like the above, but the disclosure element is open by default
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 +** [`$mymacro arg 1|arg 2|arg 3]
120 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 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 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. uses the same syntax as span links ([`⇒[$ident] [$styled-text]]). can be followed by a caption to add a longer descriptive text. especially useful for gemtext output. ident can be omitted to cross-reference, for example, a physical book.
126 126 * [*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.
................................................................................
368 368 *** [`image/*] (graphical outputs only)
369 369 *** [`video/*] (interactive outputs only)
370 370 *** [`image/svg+xml] is handled specially for HTML files, and may or may not be compatible with other renderer backends.
371 371 *** [`font/*] can be used with the HTML backend to reference a web font
372 372 *** [`font/woff2] can be used with the HTML backend to reference a web font
373 373 *** [`text/plain] (will be inserted as a preformatted text block)
374 374 *** [`text/css] (can be used when producing HTML files to link in an extra stylesheet, either by embedding it or referencing it from the header)
375 -*** [`text/x.cortav] (will be parsed and inserted as a formatted text block; context variables can be passed to the file by setting [`ctx.[$var]] parameters on the resource, e.g. [`ctx.recipient-name: Mr. Winthrop])
375 +*** [`text/x.cortav] (will be parsed and inserted as a formatted text block; context variables can be passed to the file by setting [`.[$var]] properties on the resource, e.g. [`.recipient-name: Mr. Winthrop])
376 376 *** [`application/x-troff] can be used to supply sections of text written in raw [`groff] syntax. these are ignored by other renderers.
377 377 *** [`text/html] can be used to supply sections of text written in raw HTML. these are ignored by non-HTML outputs.
378 378 *** any MIME-type that matches the type of file being generated by the renderer can be used to include a block of data that will be passed directly to the renderer.
379 379 ** URI types: additional URI types can be added by extensions or different implementations, but every compliant implementation must support these URIs.
380 380 *** [`http], [`https]/[`http+tls]: accesses resources over HTTP. add a [`file] fallback if possible for the benefit of renderers/viewers that do not have internet access abilities.
381 381 *** [`file]: references local files. (the meaning of "local" varies depending on the translation format.) absolute paths should begin [`file:/]; the slash should be omitted for relative paths. note that this doesn't have quite the same meaning as in HTML -- [`file] can (and usually should be) used with HTML outputs to refer to resources that reside on the same server. a cortav URI of [`file:/etc/passwd] will actually result in the link [`/etc/passwd], not [`file:///etc/passwd] when converted to HTML. generally, you only should use [`http] when you're referring to a resource that exists on a different domain. on systems where text and binary files are handled differently, the URIs [`file+txt:] and [`file+bin:] can be used to specify an opening mode.
382 382 *** [`asset]: identical to file [`file], except that paths are interpreted relative to the asset base (the parent directory of the source file if not otherwise defined), rather than the current working directory of the [`cortav] translator process.
................................................................................
607 607 zombo: https://zombo.com
608 608 any: anything you want
609 609 ~~~
610 610
611 611 ~~~ macros #mac [cortav] ~~~
612 612 the ranuir word {gloss cor|writing}…
613 613 gloss: [*[#1]] “[#2]”
614 +
615 +$def sur|n|socialism
616 +$def par|n|speech
617 + def: * [*[#1]] [!([#2])]
618 + ** [#3]
619 +
620 +%% equivalent to
621 +
622 +@def {
623 + * [*[#1]] [!([#2])]
624 + ** [#3]
625 +}
626 +$def sur|n|socialism
627 +$def par|n|speech
628 +
629 +%% we could even do the same thing abusing context variables
630 +
631 +@def {
632 + * [*[#word]] [!([#pos])]
633 + ** [#meaning]
634 +}
635 +
636 +$def
637 + .word: sur
638 + .pos: n
639 + .meaning: socialism
640 +$def
641 + .word: par
642 + .pos: n
643 + .meaning: speech
644 +
645 +%% context variables are useful because they inherit from the enclosing context
646 +%% thus, we can exploit resource syntax to create templates with default values
647 +
648 +@agent {
649 + + CODENAME :| [#1]
650 + + CIVILIAN IDENTITY :| [#civil]
651 + + RULES of ENGAGEMENT :| [#roe]
652 + + DANGER LEVEL :| [#danger]
653 +}
654 + .civil: (unknown)
655 + .roe: Monitor; do not engage
656 + .danger: (unknown)
657 +
658 +$agent ZUCCHINI PARABLE
659 + .civil: Zephram "Rolodex" Goldberg
660 + .danger: Category Scarlet
661 +$agent RHADAMANTH EXQUISITE
662 + .roe: Eliminate with extreme prejudice; CBRN deployment authorized
663 + .danger: [*Unquantifiable]
614 664 ~~~
615 665
616 666 ~~~ tables #tab [cortav] ~~~
617 667 here is a glossary table.
618 668
619 669 + english :+ ranuir + zia ţai + thaliste +
620 670 | honor :| tef | pang | mbecheve |