Overview
| Comment: | more tweaks, fixes, and additions than i can keep track of. major additions to documentation. spiffed up html renderer's footnotes and TOC dramatically |
|---|---|
| Downloads: | Tarball | ZIP archive | SQL archive |
| Timelines: | family | ancestors | descendants | both | trunk |
| Files: | files | file ages | folders |
| SHA3-256: |
e51980e07ad5b62b24184b8e55dd614f |
| User & Date: | lexi on 2021-12-27 05:51:11 |
| Original Comment: | more tweaks, fixes, and additions than i can keep track up. major additions to documentation. spiffed up html renderer's footnotes and TOC dramatically |
| Other Links: | manifest | tags |
Context
|
2021-12-27
| ||
| 05:52 | defuckered the cli driver so syntax errors will display instead of triggering a panic in the binary wrapper check-in: 83a68319da user: lexi tags: trunk | |
| 05:51 | more tweaks, fixes, and additions than i can keep track of. major additions to documentation. spiffed up html renderer's footnotes and TOC dramatically check-in: e51980e07a user: lexi tags: trunk | |
|
2021-12-26
| ||
| 20:01 | add C wrapper to generate true standalone binary embedding cortav bytecode check-in: a4a0570841 user: lexi tags: trunk | |
Changes
Modified cortav.ct from [5df14cacc3] to [0c4afc6088].
6 6 the cortav [!format] can be called [!cortavgil], or [!gil cortavi], to differentiate it from the reference implementation [!cortavsir] or [!sir cortavi]. 7 7 8 8 %toc 9 9 10 10 ## cortav vs. markdown 11 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. 12 12 13 +however, the differences go much deeper. the most distinctive feature of cortav is that its syntax is strongly recursive. with markdown, you can apply at most one styling to any given block or span or text. with cortav, you can nest as many styles as you like, and you can style text in places markdown wouldn't ordinarily let you: within headings, inside link text, even in code listings if you absolutely insist (this needs to be turned on by a special directive before the listing in question, however). 14 + 15 +this manual describes cortav exhaustively, but if you just want a quick reference on how markdown translates to cortav, look no further. 16 + 17 +* [*headings]: cortav uses almost the same syntax for headings that markdown does, except it only allows the "ATX style" headings, with one or more hash characters at the start of the line. the only differences from markdown are: 18 +** you can use the unicode section character [`§] instead of [`#] if you're feeling snobby 19 +** you must put a space between the control sequence (the sequence of hashes or section symbols, in this case) and the title text. [`# title] creates a section with the heading text "title", but [`#title] creates a new section with no heading at all; instead, it gives the anonymous section the ID [`title]. and of course, you can combine the two: [`#ttl title] creates a section with the heading text "title" and the ID [`ttl]. what are IDs for? we'll get to that in a little bit 20 +* [*paragraphs] are mostly the same as in markdown, except that a paragraph break occurs after every newline character, not every blank line. paragraphs can be indented by however many spaces you like; such indentation will be ignored. (tabs have a special meaning, however). in cortav, you can also explicitly mark a line of text as a paragraph by preceding it with a period character ([`.]), which is useful if you want to start a paragraph with text that would otherwise be interpreted specially. 21 +* [*italic text] -- or rather, [!emphasized] text -- is written as [`\[!my spiffy italic text\]]. in cortav, these spans can be nested within other spans (or titles, or table cells, or…), and the starting and ending point is unambiguous. 22 +* [*bold text] -- or rather, [*strong] text -- is written as [`\[*my commanding bold text\]]. 23 +* [*bold-italic text] -- or rather, [![*emphasized strong text]] -- has no specific notation. rather, you create it by nesting one span within the other, for instance: [`\[*[!my ostentatious bold-italic text\]]]. 24 +* [*links] are quite different from their markdown equivalents. cortav does not have inline links, as it is intended to be easily readable in both formatted and plain-text format, and long URLs rather disrupt the flow of reading. rather, a link tag is written with the notation [`\[>nifty-link my nifty link\]], where the word [`nifty-link] immediately following the arrow is an [!identifier] indicating the destination of the link. (instead of a greater-than sign, you can also use the unicode arrow symbol [`→].) if the identifier is the same as one you've assigned to a section, cortav produces a link within the document to that section. otherwise, it will look for a [!reference] to tell it the URI for the link. a reference is a key-value pair created by adding a line like [`nifty-link: https://zombo.com] [!indented by exactly one tab]. you can place this reference anywhere you like so long as it's in the same section; if you want to name a reference in another section, you have to prefix it with that section's ID, e.g. [`\[>spiffy-section.nifty-link my nifty link declared in a spiffy section\]]. 25 +* [*lists] use a different syntax from markdown. you can start a line with a [`*] to create an unordered list, or [`:] to create an ordered list; indentation doesn't matter. if you want to nest list items, instead of putting two spaces before the child item, you just add another star or colon. and of course, you can nest lists of different kinds within one another. 26 +* [*horizontal rules] use roughly the same syntax: three or more hyphens on a line of their own ([`\---]). underlines also work ([`___], [`-_-], [`__-__-__] etc). 27 +* some markdown implementations support [*tables]. cortav does too, using a very simple notation. 28 +* [*underlines] are supported by some markdown implementations. in cortav, you can apply them with the notation [`\[_my underlined text\]] -- please just use them sparingly when you render to HTML! 29 +* [*strikethrough] is supported by some extended versions of markdown. cortav uses the notation [`\[~my deleted text\]], with the intended semantics of text that is being removed by some revision of a document. (you can also denote text that is being [!added] by using a plus sign instead of a tilde) 30 +* [*images] are a bit more complicated. see the section on [>rsrc resources] for an explanation. 31 +* [*smart quotes] and [*em dashes] are inserted automatically, just as in markdown, provided you have the [>tsmog transmogrify] extension available. (it is part of the reference implementation and defined by the spec, but not required.) in fact, you can insert longer dashes than em dashes just by increasing the number of hyphens. the reference implementation's transmogrifier also translates ascii arrows like [`\-->] into their unicode equivalents ([`→]). 32 +* [*literals] (also known as [*code text]) can be inserted with the [`\[`int main(void);] syntax. note however that literals are not protected from the transmogrifier, and are parsed like any other span, which may cause problems if the source code you're quoting makes use of such forbidden runes. in this case, you'll want to wrap the code span in a raw span. the syntax for this is [`\[`[\\int main(void);\]]], but since this is a bit unwieldy it can also be abbreviated as [`\[`\\int main(void);\]]. 33 + 34 +of course, this is only a small taste of what cortav can do, not even touching on key features like macros, footnotes, or equation formatting. read the sections on [>onblocks blocks] and [>onspans spans] for all the gory details. 35 + 13 36 ## encoding 14 37 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. 15 38 16 39 ## file type 17 40 a cortav source file is identified using a file extension, file type, and/or magic byte sequence. 18 41 19 42 three file extensions are defined as identifying a cortav source file. where relevant, all must be recognized as indicating a cortav source file. ................................................................................ 39 62 it is also possible to indicate the nature of a cortav file without using filesystem metadata. this is done by prefixing the file with a magic byte sequence. the sequence used depends on the encoding. 40 63 * for UTF-8 and ASCII plain text files, [`%ct[!\\n]] (that is, the byte sequence [`0x25 63 74 0A]) should be used 41 64 * for C6B+PS files (parastream), the file should begin with the paragraph [`], which equates to the byte sequence [` 0x3E 2E 14 0C 01 04 00 00 00 03 07 3E 2D], including the parastream header). 42 65 consequently, this sequence should be ignored by a cortav parser at the start of a file (except as an indication of file format). 43 66 44 67 for FreeDesktop-based systems, the [`build/velartrill-cortav.xml] file included in the repository supplies mappings for the extensions and magic byte sequences. a script is also included which can be registered with xdg-open so that double-clicking on a cortav file will render it out and open it in your default web browser. [`$ make install] will generate the necessary FreeDesktop XML files and register them, as well as install the script and the [`cortav] executable itself. for more information see [>refimpl-build building the reference implementation]. 45 68 46 -## structure 69 +##onblocks structure 47 70 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. 48 71 49 72 the first character(s) of every line (the "control sequence") indicates the role of that line. if no control sequence is recognized, the line is treated as a paragraph. the currently supported 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. 50 73 51 74 * [*paragraphs] ([`.] [` ¶] [`❡]): a paragraph is a simple block of text. the period control sequence is only necessary if the paragraph text starts with text that would be interpreted as a control sequence otherwise 52 75 * newlines [` \\]: inserts a line break into previous paragraph and attaches the following text. mostly useful for poetry or lyrics 53 76 * [*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.: 54 77 ** [`#] is a simple section break. 55 78 ** [`#anchor] opens a new section with the ID [`anchor]. 56 79 ** [`# header] opens a new section with the title "header". 57 80 ** [`#anchor header] opens a new section with both the ID [`anchor] and the title "header". 58 81 ** [`#>conversation] opens a blockquote section named [`conversation] without a header. 59 -* [*nonprinting sections] ([`^]): sometimes, you'll want to create a namespace without actually adding a visible new section to the document. you can achieve this by creating a [!nonprinting section] and defining resources within it. nonprinting sections can also be used to store comments, notes, or other information that is useful to have in the source file without it becoming a part of the output 60 82 ** [`#&id mime] opens a new inline object [`id] of type [`mime]. useful for embedding SVGs. the ID and mime type must be specified. 83 +* [*nonprinting sections] ([`^]): sometimes, you'll want to create a namespace without actually adding a visible new section to the document. you can achieve this by creating a [!nonprinting section] and defining resources within it. nonprinting sections can also be used to store comments, notes, or other information that is useful to have in the source file without it becoming a part of the output 61 84 * [*resource] ([`@]): defines a [!resource]. a resource is an file or object that exists outside of the document but which will be included in the document somehow. common examples of resources include images, videos, iframes, or headers/footers. see [>rsrc resources] for more information. 62 85 * [*lists] ([`*] [`:]): these are like paragraph nodes, but list nodes that occur next to each other will be arranged so as to show they compose a sequence. depth is determined by the number of stars/colons. like headers, a list entry may have an ID that can be used to refer back to it; it is indicated in the same way. if colons are used, this indicates that the order of the items is signifiant. :-lists and *-lists may be intermixed; however, note than only the last character in the sequence actually controls the depth type. 63 86 * [*directives] ([`%]): a directive issues a hint to the renderer in the form of an arbitrary string. directives are normally ignored if they are not supported, but you may cause a warning to be emitted where the directive is not supported with [`%!] or mark a directive critical with [`%!!] so that rendering will entirely fail if it cannot be parsed. 64 87 * [*comments] ([`%%]): a comment is a line of text that is simply ignored by the renderer. 65 88 * [*asides] ([`!]): indicates text that diverges from the narrative, and can be skipped without interrupting it. think of it like block-level parentheses. asides which follow one another are merged as paragraphs of the same aside, usually represented as a sort of box. if the first line of an aside contains a colon, the stretch of styled-text from the beginning to the aside to the colon will be treated as a "type heading," e.g. "Warning:" 66 89 * [*code] ([`~~~]): a line beginning with ~~~ begins or terminates a block of code. code blocks are by default not parsed, but parsing can be activated by preceding the code block with an [`%[*expand]] directive. the opening line should look like one of the below 67 90 ** [`~~~] ................................................................................ 77 100 * [*blockquote] ([`>]): alternate blockquote syntax. can be nested by repeating the [`>] character. 78 101 * [*subtitle] ([`--]): attaches a subtitle to the previous header 79 102 * [*embed] ([`&]): embeds a referenced object. can be used to show images or repeat previously defined objects like lists or tables, optionally with a caption. 80 103 ** [`&$[$macro] [$arg1]|[$arg2]|[$argn]…] invokes a block-level macro with the supplied arguments 81 104 *** [`&$mymacro arg 1|arg 2|arg 3] 82 105 ** [`&[$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) 83 106 ***[`&myimg All that remained of the unfortunate blood magic pageant contestants and audience (police photo)] 84 -** [`&-[$section]] embeds a closed disclosure element. in interactive outputs, this will display as a block [!section] which can be clicked on to view the full contents of the referenced section; in static outputs, it will display as an enclosed box with [$section] as the title text 107 +** [`&-[$section] [$styled-text]] embeds a closed disclosure element. in interactive outputs, this will display as a block [!section] which can be clicked on to view the full contents of the referenced section; if [$styled-text] is present, it overrides the title of the section you are embedding. in static outputs, the disclosure object will display as an enclosed box with [$styled-text] as the title text 85 108 *** [`&-ex-a Prosecution Exhibit A (GRAPHIC CONTENT)] 86 -** [`&+[$section]] is like the above, but the disclosure element is open by default 109 +** [`&+[$section] [$styled-text]] is like the above, but the disclosure element is open by default 87 110 * [*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. 88 111 * [*page break] ([`\^^]): for formats that support pagination, like 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 89 -* [*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 112 +* [*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 90 113 * [*table cells] ([`+ |]): see [>ex.tab table examples]. 91 114 * [*equations] ([`=]) block-level equations can be inserted with the [`=] 92 115 * [*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. 93 116 94 -## styled text 117 +##onspans styled text 95 118 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. 96 119 97 120 * strong {obj *|styled-text}: causes its text to stand out from the narrative, generally rendered as bold or a brighter color. 98 121 * emphatic {obj !|styled-text}: indicates that its text should be spoken with emphasis, generally rendered as italics 99 122 * 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 100 123 * variable {obj $|styled-text}: indicates that its text is a stand-in that will be replaced with what it names. generally rendered in italic monospace, ideally of a different color 101 124 * 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. 102 125 * strikeout {obj ~|styled-text}: indicates that its text should be struck through or otherwise indicated for deletion 103 126 * insertion {obj +|styled-text}: indicates that its text should be indicated as a new addition to the text body. 104 127 ** consider using a macro definition [`\edit: [~[#1]][+[#2]]] to save typing if you are doing editing work 105 128 * 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. 106 129 * 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 next [`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. 107 -* superscript {obj '|[$styled-text]}: 108 -* subscript {obj ,|[$styled-text]}: 130 +* superscript {obj '|[$styled-text]} 131 +* subscript {obj ,|[$styled-text]} 109 132 * 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 110 133 * raw literal \[$\\[!raw-text]\]: shorthand for [\[$[\…]]] 111 134 * macro [`\{[!name] [!arguments]\}]: invokes a [>ex.mac macro], specified with a reference 112 135 * argument {obj #|var}: in macros only, inserts the [$var]-th argument. otherwise, inserts a context variable provided by the renderer. 113 136 * raw argument {obj ##|var}: like above, but does not evaluate [$var]. 114 137 * term {obj &|name}, {span &|name|[$expansion]}: quotes a defined term with a link to its definition, optionally with a custom expansion of the term (for instance, to expand the first use of an acronym) 115 138 * inline image {obj &@|name}: shows a small image or other object inline. the unicode character [`🖼] can also be used instead of [`&@]. ................................................................................ 119 142 * critical extension {span %!|ext|…}: like [!extension], but will trigger an error if the requested extension is not available 120 143 * extension text {span %:|ext|styled-text}: like [!extension], but when the requested extension is not present, [$styled-text] wlil be emitted as-is. this is a better way to apply CSS classes, as the text will still be visible when rendered to formats other than HTML. 121 144 * inline comment {obj %%|...}: ignored. useful for editorial annotations not intended to be part of the rendered product. 122 145 123 146 span: [` \[[*[#1]][$[#2]] [#3]\]] 124 147 obj: [` \[[*[#1]][$[#2]]\]] 125 148 149 +##tabs tables 150 +tables are encoded using a very simple notation. any line that begins with a plus [`+] or bar [`|] denotes a table row. each plus or bar separates one column from the other: a plus opens a new header cell, a bar opens a new normal cell. 151 + 152 +the alignment of a cell can be specified by placing colons at one edge or both edges of the given cell. a colon on the left ([`|: my table cell |]) indicates a left-aligned cell, a colon on right a right-aligned cell ([`| my table cell :|]), and a colon on both sides a centered cell ([`|: my table cell :|]). if you want to use a special character without it being eaten by the table parser, just put a backslash in from of it, e.g. [`| this cell \| contains a pipe \+ a plus sign [!and] ends with a colon \:|]. and of course, table cells are just normal spans -- they can contain any other kind of span formatting you like, such as links, emphasis, or footnotes. 153 + 154 +no other features (like colspans or rowspans) are currently part of the spec but they will be added eventually (if i can figure out a decent way to implement them without creating a huge mess). 155 + 156 +you can finish each row with a bar or plus character, but it's not necessary. only do it if you think it makes the source easier to read. 157 + 158 +* [>ex.tab an example of table notation] 159 + 126 160 ##ident identifiers 127 161 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. 128 162 129 163 ##rsrc resources 130 164 a [!resource] represents content that is not encoded directly into the source file, but which is embedded by some means in the output. resources can either be [!embedded], in which case they are compiled into the final document itself, or they can be [!linked], in which case the final document only contains a URI or similar tag referencing the resource. not all render backends support both linking and embedding embedding, nor do all backends support all object types (for instance, [`groff] does not support video embedding.) 131 165 132 166 a resource definition is begun by line consisting of an [`@] sign and an [>ident identifier]. this line is followed by any number of parameters. a parameter is a line beginning with a single tab, a keyword, a colon, and a then a value. additional lines can be added to a parameter by following it with a line that consists of two tabs followed by the text you wish to add. (this is the same syntax used by references.) a resource definition is terminated by a break, or any line that does not begin with a tab ................................................................................ 321 355 * {d include} transcludes another file 322 356 * {d import} reads in the contents of another file as an embeddable section 323 357 * {d quote} transcludes another file, without expanding the text except for paragraphs 324 358 * {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. 325 359 * {d expand} causes the next object (usually a code block) to be fully expanded when it would otherwise not be 326 360 * {d font} controls the font stack, for outputs that support changing fonts. see [>fonts fonts] for more information. 327 361 * {d lang} changes the current language, which is used by extensions to e.g. control typographical conventions, and may be encoded into the output by certain renderers (e.g. HTML). note that quotes and blockquotes can be set to a separate language with a simpler syntax. the language should be notated using IETF language tags 328 -** {d lang is x-ranuir-CR8} sets the current language to Ranuir as spoken in the Central Worlds, written in Corran and encoded using UTF-8. this might be used at the top of a document to set its primary language. 362 +** {d lang is x-ranuir-Cent-CR8} sets the current language to Ranuir as spoken in the Central Worlds, written in Corran and encoded using UTF-8. this might be used at the top of a document to set its primary language. 329 363 ** {d lang push gsw-u-sd-chzh} temporarily switches to Zürich German, e.g. to quote a German passage in an otherwise Ranuir document 330 364 ** {d lang sec en-US} switches to American English for the duration of a section. does not affect the language stack. 331 365 ** {d lang pop} drops the current language off the language stack, returning to whatever was pushed or set before it. this would be used, for instance, at the end of a passage 332 366 * {d pragma} supplies semantic data about author intent, the kind of information the document contains and hints about how it should be displayed to the user. think of them like offhand remarks to the renderer -- there's no guarantee that it'll pay any attention, but if it does, your document will look better. pragmas have no scope; they affect the entire document. the pragma function exists primarily as a means to allow parameters that would normally need to be specified on e.g. the command line to be encoded in the document instead in a way that multiple implementations can understand. a few standard pragmas are defined. 333 367 ** {d pragma layout} gives a hint on how the document should be layed out. the first hint that is understood will be applied; all others will be discarded. standard hints include: 334 368 *** [`essay] 335 369 *** [`narrative] ................................................................................ 453 487 * [`%lua use [!file]]: evaluates [$file] and makes its definitions available 454 488 * [`\[%lua raw [!script]\]]: evaluates [$script] and emits the string it returns (if any) in raw span context. 455 489 * [` \[%lua exp [!script]\]]: evaluates [$script] and emits the string it returns (if any) in expanded span context. 456 490 * [`%lua raw [!script]]: evaluates [$script] and emits the string array it returns (if any) in raw block context. 457 491 * [`%lua exp [!script]]: evaluates [$script] and emits the string array it returns (if any) in expanded block context. 458 492 459 493 the interpreter should provide a [`cortav] table with the objects: 460 -* ctx: contains context variables 494 +* [`ctx]: contains context variables 461 495 462 496 used files should return a table with the following members 463 -* macros: an array of functions that return strings or arrays of strings when invoked. these will be injected into the global macro namespace. 497 +* [`macros]: an array of functions that return strings or arrays of strings when invoked. these will be injected into the global macro namespace. 464 498 465 499 ###ts ts 466 500 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. 467 501 468 502 ts enables the directives: 469 503 * [`%[*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. 470 504 * [`%[*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]. ................................................................................ 571 605 the command line driver is built and installed with a GNU [$make] script. this script accepts the variables shown below with their default values: 572 606 + prefix | [`[$$HOME]/.local] | the path under which the package will be installed 573 607 + build | [`build] | the directory where generated objects will be placed; useful for out-of-tree builds 574 608 + bin-prefix | [`[$$prefix]/bin] | directory to install the executables to" 575 609 + default-format-flags | [`-m html:width 35em] | a list of flags that will be passed by the viewer script to [`cortav] when generating a html fille 576 610 577 611 the following targets are supplied to automate the build: 578 -* [`install] builds everything, installs the executable and the viewer script to [$$bin_prefix], and registers the viewer script with XDG 612 +* [`install] builds everything, installs the bytecode-executable and the viewer script to [$$bin_prefix], and registers the viewer script with XDG 613 +* [`install-bin] is like [`install] but installs the binary version instead of the bytecode one 579 614 * [`excise] deletes everything installed and deregisters the file handlers (note that the same variables must be passed to [`exicse] as were passed to [`install]!) 580 615 * [`clean] deletes build artifacts from the [$$build] directory like it was never there 581 616 * [`wipe] is equivalent to [`$ make excise && make clean] 617 + 618 +if you don't want to install [`cortav], you can just run [`$ make] without arguments to build the executable. 619 + 620 +there are two different ways of building the driver. one is to generate a bytecode file that can be executed directly as a script. this is the most straightforward method, and requires only [`lua] and [`luac]. however, it has several substantial downsides: because it's only a bytecode file, it requires the [`lua] interpreter to run -- and in some environments, the security characteristics of the [`lua] interpreter may make this undesirable. it also must hardcode the path to the lua interpreter (though admittedly this is easy enough to fix if you copy it to another machine of the same architecture). [`lua] is not an entirely predictable environment, as it is controlled by environment variables and may hypothetically do things like load default libraries or alter paths in ways that disrupt the workings of [`cortav]. finally, because the bytecode file is not a binary executable, it cannot directly be given enhanced capabilities on unix-like systems through filesystem metadata -- SUID and caps will be ignored by the kernel. while this is of no importance in ordinary operation, there are niche cases where this could be troublesome. 621 + 622 +a potentially superior alternative is to build [`cortav] as a directly executable binary. when you tell [`make] to build the binary version, it first compiles the driver to raw bytecode, then invokes [`tool/makeshim.lua] to create a C source file embedding that bytecode, which is then piped into a C compiler. the huge downside, of course, is that building the cortav driver in this way requires a C compiler. however, the binary that it produces is easier to distribute to other computers -- you can even statically link in lua so it can run on systems where lua isn't installed. 623 + 624 +to build the binary version, run [`$ make build/cortav.bin]. if you want to make the build to link lua statically, you'll additionally need to supply lua's library prefix in the variable [`lua-lib-prefix]. some example incantations: 625 +* [`$ make build/cortav.bin lua-lib-prefix=/usr/lib] on most Linux distros 626 +* [`$ make build/cortav.bin lua-lib-prefix=/usr/local/lib] on FreeBSD 627 +* [`$ make build/cortav.bin lua-lib-prefix=$(nix path-info nixpkgs.lua5_3)/lib] on NixOS, or on OSX if you're using the Nix package manager 628 + 629 +alternately, you can build lua yourself and link the static library in place without installing it systemwide, which is useful if you want to build a specialized version of lua to link with (or if the sysop doesn't want your grubby luser hands all over his precious filesystem). note that if you're building a self-contained version of [`cortav] to distribute, you may want to slim down the binary by building lua without its parser, as the self-contained version of the driver only needs the bytecode VM part of lua to run. 630 + 631 +#### build variables 632 +there are numerous variables you can use to control the build process. 633 + 634 ++ lua | path to the lua interpreter [`cortav] should be built and run with 635 ++ luac | path to the lua compiler 636 ++ sh | path to a bourne-compatible shell 637 ++ extens | list of paths to extensions to enable, defaults to [`ext/*.lua]. use [`extens\+=[$path]] to add additional extensions from out of tree 638 ++ rendrs | list of paths to renderers to enable, defaults to [`render/*.lua] 639 ++ build | path to the build directory, defaults to [`build]. change this for out-of-tree builds 640 ++ executable | name of the executable to be generated, defaults to [`cortav] 641 ++ default-format-flags | specifies command line options that the viewer script should pass to [`cortav] 642 ++ prefix | where files should be installed, defaults to [`$HOME/.local] 643 ++ bin-prefix | where executables should be installed, defaults to [`$(prefix)/bin] 644 ++ debug | if set, builds executables with debugging symbols; if absent, executables are stripped 645 ++ encoding-data | if set, embeds character class data for supported multibyte encodings into the program. on by default; [`$ make encoding-data=] to unset 646 ++ encoding-data-ucs | path to the UnicodeData.txt file for UCS-based encodings like UTF-8. by default it is automatically downloaded with [`curl] 647 ++ encoding-data-ucs-url | where to download UnicodeData.txt from, if encoding-data-ucs is not changed. defaults to the unicode consortium website 648 + 649 +#### deterministic builds 650 +some operating systems, like NixOS, require packages that can be built in reproducible ways. this implies that all data, all [!state] that goes into producing a package needs to be accounted for before the build proper begins. the [`cortav] build process needs to be slightly altered to support such a build process. 651 + 652 +while the cortav specification itself does not concern itself with matters like whether a particular character is a numeral or a letter, optimal typesetting in some cases requires such information. this is the case for the equation span- and block-types, which need to be able to distinguish between literals, variables, and mathematical symbols in [^alas-math the equations they format]. the ASCII charset is small enough that exhaustive character class information can be manually hardcoded into a cortav implementation, the various encodings of Unicode most certainly are not. 653 + 654 + alas-math: sadly, i was not at any point consulted by any of the generations of mathematicians stretching back into antiquity who devised their notations without any regard for machine-readability. [!for shame!] 655 + 656 +for this reason, the reference implementation of cortav embeds the file [`UnicodeData.txt], a database maintained by the Unicode Consortium. this is a rather large file that updates for each new Unicode version, so it is downloaded as part of the build process. to build on NixOS, you'll need to either disable the features that rely on this database (not recommended), or download the database yourself and tell the build script where to find it. this is the approach the official nix expression will take when i can be bothered to write it. see the examples below for how to conduct a deterministic build 657 + 658 +~~~ deterministic build with unicode database [sh] ~~~ 659 +/src $ mkdir cortav && cd cortav 660 +/src/cortav $ fossil clone https://c.hale.su/cortav .fossil && fossil open .fossil 661 +/src/cortav $ curl https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt > /tmp/unicode.txt 662 +/src/cortav $ make build/cortav encoding-data-ucs=/tmp/unicode.txt 663 +~~~ 664 +~~~ [sh] deterministic build [!without] unicode database ~~~ 665 +/src $ mkdir cortav && cd cortav 666 +/src/cortav $ fossil clone https://c.hale.su/cortav .fossil && fossil open .fossil 667 +/src/cortav $ make build/cortav encoding-data= 668 +~~~ 669 + 670 +! while most of the data used is taken directly from UnicodeData.txt, the database generated by [`tools/ucs.lua] splices in some extra character information before generating a database. this is partly because certain characters may not be classified in a useful way and need to be manually overwritten. however, the reference implementation also seeks to provide accurate data for certain character sets that are not part of unicode proper and can be expressed in UTF only through its private use areas. 671 +! currently, only the [>corran Corran] script is currently supported in this fashion, but i intend to add [>tengwar Tengwar] as well. if there is a con-script or any other informally encoded script you would like supported by the reference implementation, please open an issue. 672 + 673 +[*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. 674 + 675 + corran: http://ʞ.cc/fic/spirals/society 676 + tengwar: https://en.wikipedia.org/wiki/Tengwar 582 677 583 678 ###refimpl-switches switches 584 679 [`cortav.lua] offers various switches to control its behavior. 585 680 + long + short + function + 586 681 | [`--out [!file]] :|:[`-o]:| sets the output file (default stdout) | 587 682 | [`--log [!file]] :|:[`-l]:| sets the log file (default stderr) | 588 683 | [`--define [!var] [!val]] :|:[`-d]:| sets the context variable [$var] to [$val] | ................................................................................ 638 733 [`html] supplies the following render directives. 639 734 640 735 * [`%[*html] link [$rel] [$mime] [$href]]: inserts a [`<link>] tag in the header, for example, to link in an alternate stylesheet, or help feed readers find your atom or rss feed. 641 736 ** [`%[*html] link alternate\\ stylesheet text/css /res/style2.css] 642 737 ** [`%[*html] link alternate application/atom+xml /feed.atom] 643 738 * [`%[*html] style [$id]]: adds the stylesheet referenced by [$id] into the document stylesheet. the stylesheet is specified using a [>rsrc resource]. 644 739 645 -#### stylsheets 740 +#### stylesheets 646 741 the [`html] backend offers some additional directives for external CSS files that are embedded into the document, in order to simplify integration with the accent mechanism. these are: 647 742 648 743 * [`@[*fg]]: resolves to a color expression denoting the selected foreground color. equivalent to [`[*tone](1)] 649 744 * [`@[*bg]]: resolves to a color expression denoting the selected background color. equivalent to [`[*tone](0)] 650 745 * [`@[*tone]\[/[$alpha]\]([$fac] \[[$shift] \[[$saturate]\]\] )]: resolves to a color expression. [$fac] is a floating-point value scaling from the background color to the foreground color. [$shift] is a value in degrees controlling how far the hue will shift relative to the accent. [$saturate] is a floating-point value controlling how satured the color is. 651 746 652 747 ###refimpl-rend-groff groff ................................................................................ 657 752 ####refimpl-rend-groff-modes modes 658 753 [`groff] supports the following modes: 659 754 660 755 * string [`groff:annotate] controls how footnotes will be handled. 661 756 ** [`footnote] places footnotes at the end of the page they are referenced on. if the same footnote is used on multiple pages, it will be duplicated on each. 662 757 ** [`secnote] places footnotes at the end of each section. footnotes used in multiple sections will be duplicated for each 663 758 ** [`endnote] places all footnotes at the end of the rendered document. 664 -* string [`groff:dev] names an output device (such as [`dvi] or[`pdf]). if this mode is present, [`groff] will be automatically invoked 759 +* string [`groff:dev] names an output device (such as [`dvi] or [`pdf]). if this mode is present, [`groff] will be automatically invoked 665 760 * string [`groff:title-page] takes an identifier that names a section. this section will be treated as the title page for the document. 666 761 667 762 ### directives 668 763 * [`%[*pragma] title-page [$id]] sets the title page to section [$id]. this causes it to be specially formatted, with a large, centered title and subtitle. 669 764 670 765 ### quirks 671 766 if the [`toc] extension is active but [`%[*toc]] directive is provided, the table of contents will be given its own section at the start of the document (after the title page, if any). ................................................................................ 732 827 (note . "footnote1-text") 733 828 (ref . "papal-disclaimer") 734 829 (nodes 735 830 "footnode1-caption-text")) 736 831 (text (id . "text4") "has thus far had little to say on the matter, provoking rampant speculation among the faithful.") 737 832 (footnote-def (id . "footnote1-def") 738 833 (nodes "footnote1-text") 739 - (text (id . "footnote1-text") "Currently recognized as legitimate successor to Peter of Terra by 2,756 sects, rejected by 678 of mostly Neo-Lutheran origin, and decried as an antipope by 73, most notably Pope Peter II of Centaurus Secundus, leader of the ongoing relativistic crusade against star systems owned by Microsoft.") 834 + (text (id . "footnote1-text") "Currently recognized as legitimate successor to Peter of Terra by 2,756 sects, rejected by 678 of mostly Neo-Lutheran origin, and decried as an antipope by 73, most notably Pope Peter II of Centaurum Secundus, leader of the ongoing relativistic crusade against star systems owned by Microsoft.") 740 835 ;;; snip ;;; 741 836 (document 742 837 (nodes 743 838 "section1" "section2"))) 744 839 ~~~ 745 840 746 841 some formats may eventually warrant their own renderer, but are not a priority:
Modified ext/toc.lua from [1a479a26d4] to [35da212f52].
1 1 local ct = require 'cortav' 2 2 local ss = require 'sirsem' 3 3 4 4 local css_toc = [[ 5 - 5 + @media screen and (max-width: calc(@[width]:[100vw] * 2)) { 6 + ol.toc { 7 + float: right; 8 + background: @bg; 9 + padding: 0 2em; 10 + margin-right: -4em; 11 + } 12 + } 6 13 ]] 7 14 15 +local css_toc_fixed_lod = [[ 16 + @media (min-width: calc(@[width]:[100vw] * 2)) { 17 + ol.toc { 18 + background: linear-gradient(to right, transparent 25%, @tone(0.1 50)), 19 + @tone/0.4(-0.1 50); 20 + } 21 + ol.toc > li > ol li { 22 + background: linear-gradient(to right, transparent, rgba(0,0,0,0.4)); 23 + } 24 + } 25 +]] 8 26 local css_toc_fixed = [[ 9 - @media (min-width: calc(@[width]:[100vw] + 20em)) { 27 + @media screen and (min-width: calc(@[width]:[100vw] * 2)) { 10 28 ol.toc { 11 29 position: fixed; 12 - padding-top: 1em; padding-bottom: 1em; 13 - padding-right: 1em; 14 - margin-top: 0; margin-bottom: 0; 15 30 right: 0; top: 0; bottom: 0; 16 31 max-width: calc(50vw - ((@[width]:[0]) / 2) - 3.5em); 17 32 overflow-y: auto; 33 + background: @tone/0.4(-0.1 50); 34 + padding: 1em 1em; 35 + padding-right: 0; 36 + border-left: 1px solid @tone(-2 50); 37 + margin: 0; 18 38 } 19 - @media (max-width: calc(@[width]:[100vw] + 30em)) { 39 + @media (max-width: calc(@[width]:[100vw] * 2.5)) { 20 40 ol.toc { 21 41 max-width: calc(100vw - ((@[width]:[0])) - 9.5em); 22 42 } 23 43 body { 24 44 margin-left: 5em; 25 45 } 26 46 } 47 + ol.toc li { 48 + padding: 0; 49 + margin-left: 1em; 50 + } 51 + ol.toc a[href] { 52 + display: block; 53 + padding: 0.15em 0; 54 + color: @tone(0.8 50); 55 + background: linear-gradient(to right, transparent, @tone(0.3 50)); 56 + background-position-x: 10em; 57 + background-repeat: no-repeat; 58 + transition: 0.25s; 59 + } 60 + ol.toc a[href]:not(:hover) { 61 + text-decoration-color: transparent; 62 + } 63 + @supports not (text-decoration-color: transparent) { 64 + ol.toc a[href]:not(:hover) { 65 + text-decoration: none; 66 + } 67 + } 68 + ol.toc a[href]:hover { 69 + color: @tone(1.3 50); 70 + background-position-x: 0%; 71 + } 72 + ol.toc ol { 73 + font-size: 95%; 74 + width: 100%; 75 + padding-left: 0; 76 + } 77 + ol.toc > li { 78 + list-style: upper-roman; 79 + } 80 + ol.toc > li > a { 81 + font-weight: bold; 82 + } 83 + ol.toc > ol > li { 84 + list-style: decimal; 85 + } 86 + ol.toc > li > ol > li > ol > li { 87 + list-style: enclosed; 88 + } 27 89 } 28 90 ]] 29 91 30 92 ct.ext.install { 31 93 id = 'toc'; 32 94 desc = 'provides a table of contents for HTML renderer plus generic fallback'; 33 95 version = ss.version {0,1; 'devel'}; ................................................................................ 37 99 doc_init = function(job) 38 100 job.state.toc_custom_position = false 39 101 end; 40 102 41 103 render_html_init = function(job, render) 42 104 render.stylesets.toc = css_toc 43 105 render.stylesets.tocFixed = css_toc_fixed 106 + render.stylesets.tocFixedLOD = css_toc_fixed_lod 44 107 end; 45 108 46 109 render_html_ir_assemble = function(job, render, ir) 47 110 -- the custom position state is part of the document job, 48 111 -- but rendering is a separate job, so we need to get the 49 112 -- state of this extension in the parent job, which is 50 113 -- done with the job:unwind(depth) call. unwind is a method ................................................................................ 104 167 -- toplevel HTML IR 105 168 local lst = {tag = 'ol', attrs={class='toc'}, nodes={}} 106 169 107 170 -- "renderer.state" contains the stateglob of the renderer 108 171 -- itself, not to be confused with the "state" parameter 109 172 -- which contains this extension's share of the job state 110 173 -- we use it to activate the stylesets we injected earlier 111 - renderer.state.stylesets_active.toc = true 112 - if renderer.state.opts['width'] then 113 - renderer.state.stylesets_active.tocFixed = true 174 + renderer.state.style_add'toc' 175 + if renderer.state.opts.width then 176 + renderer.state.style_add'tocFixed' 177 + end 178 + if not renderer.state.opts['dark-on-light'] then 179 + renderer.state.style_add'tocFixedLOD' 114 180 end 115 181 116 182 -- assemble a tree of links from the document section 117 183 -- structure. this is tricky, because we need a tree, but 118 184 -- all we have is a flat list with depth values attached to 119 185 -- each node. 120 186 local stack = {lst}
Modified makefile from [d74d07de6f] to [9ea6c48a8b].
44 44 45 45 build = build 46 46 executable = cortav 47 47 default-format-flags = -m html:width 40em 48 48 49 49 prefix = $(HOME)/.local 50 50 bin-prefix = $(prefix)/bin 51 -share-prefix = $(prefix)/share/$(executable) 52 51 53 52 lua-standalone = $(if $(lua-lib-prefix),$(lua-lib-prefix)/liblua.a,-llua) 54 53 lua-bindeps = -lm -ldl 55 54 56 55 dbg-flags-luac = $(if $(debug),,-s) 57 56 dbg-flags-cc = $(if $(debug),-g,-s) 58 57 ................................................................................ 66 65 67 66 # by default, we fetch and parse information about encodings we 68 67 # support so that cortav can do fancy things like format math 69 68 # equations by character class (e.g. italicizing variables) 70 69 # this is not necessary for parsing the format, and can be 71 70 # disabled by blanking the encoding-data list when building 72 71 # ($ make encoding-data=) 73 -encoding-data = ucstbls 74 -encoding-files = $(patsubst %,$(build)/%.lc,$(encoding-data)) 75 -encoding-data-ucs = https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt 72 +encoding-data = 1 73 +encoding-data-ucs = $(build)/unicode.txt 74 +encoding-data-ucs-url = https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt 75 + 76 +encoding-files = $(if $(encoding-data),$(build)/ucstbls.lc,) 76 77 77 78 # "standalone" bytecode file that can be run directly as a script 78 -$(build)/$(executable): $(build)/$(executable).ct 79 +$(build)/$(executable): $(build)/$(executable).lc 79 80 echo '#!$(lua)' > $@ 80 81 cat $< >>$@ 81 82 chmod +x $@ 82 83 83 84 # raw bytecode without shebang header, must be run as `lua cortav.lc` 84 85 $(build)/$(executable).lc: sirsem.lua $(encoding-files) cortav.lua $(rendrs) $(extens) cli.lua | $(build)/ 85 86 @echo ' » building with extensions $(extens-names)' 86 87 @echo ' » building with renderers $(rendrs-names)' 87 88 $(luac) $(dbg-flags-luac) -o $@ $^ 88 89 89 90 # true standalone binary, wraps bytecode file and (optionally) lua 90 -$(build)/$(executable).bin: $(build)/$(executable).lc 91 - $(lua) tools/makeshim.lua $< |\ 92 - $(CC) -o$@ -xc - -xnone $(lua-standalone) $(lua-bindeps) 91 +$(build)/$(executable).bin: $(build)/$(executable).lc tool/makeshim.lua 92 + $(lua) tool/makeshim.lua $< |\ 93 + $(CC) -s -o$@ -xc - -xnone $(lua-standalone) $(lua-bindeps) 93 94 94 95 $(build)/cortav.html: cortav.ct $(build)/$(executable) | $(build)/ 95 96 $(build)/$(executable) $< -o $@ -m render:format html -y html:fossil-uv 96 97 97 98 .PHONY: syncdoc 98 99 syncdoc: $(build)/cortav.html 99 100 fossil uv add $< --as cortav.html ................................................................................ 118 119 cp $< $@ 119 120 echo "Exec=$(bin-prefix)/cortav-view.sh" >>$@ 120 121 121 122 %/: 122 123 mkdir -p $@ 123 124 124 125 $(build)/unicode.txt: | $(build)/ 125 - curl $(encoding-data-ucs) > $@ 126 -$(build)/ucstbls.lc: $(build)/unicode.txt tools/ucs.lua | $(build)/ 127 - $(lua) tools/ucs.lua $< | $(luac) -o $@ - 126 + curl $(encoding-data-ucs-url) > $@ 127 +$(build)/ucstbls.lc: $(encoding-data-ucs) tool/ucs.lua | $(build)/ 128 + $(lua) tool/ucs.lua $< | $(luac) -o $@ - 128 129 129 130 .PHONY: install 130 131 install: $(build)/cortav $(build)/cortav-view.sh $(build)/velartrill-cortav-view.desktop | $(bin-prefix)/ 131 132 install $(build)/$(executable) $(bin-prefix) 132 133 install $(build)/cortav-view.sh $(bin-prefix) 133 134 xdg-mime install desk/velartrill-cortav.xml 134 135 xdg-desktop-menu install $(build)/velartrill-cortav-view.desktop
Modified render/html.lua from [1e64ee70c7] to [0a87e02f8c].
20 20 lisp = { color = 0x77ff88 }; 21 21 fortran = { color = 0xff779a }; 22 22 python = { color = 0xffd277 }; 23 23 ruby = { color = 0xcdd6ff }; 24 24 } 25 25 26 26 local stylesets = { 27 + list = [[ 28 + @counter-style enclosed { 29 + system: extends decimal; 30 + prefix: "("; 31 + suffix: ") "; 32 + } 33 + ul, ol { 34 + padding: 0 1em; 35 + } 36 + li { 37 + padding: 0.1em 0; 38 + } 39 + ]]; 40 + list_ordered = [[]]; 41 + list_unordered = [[]]; 27 42 footnote = [[ 28 43 div.footnote { 29 - font-family: 90%; 30 - display: none; 44 + font-family: 90%; 31 45 grid-template-columns: 1em 1fr min-content; 32 46 grid-template-rows: 1fr min-content; 33 47 position: fixed; 34 48 padding: 1em; 35 - background: @tone(0.05); 36 - border: black; 49 + background: @tone(0.03); 37 50 margin:auto; 38 51 } 39 - div.footnote:target { display:grid; } 40 52 @media screen { 41 53 div.footnote { 54 + display: grid; 42 55 left: 10em; 43 56 right: 10em; 44 57 max-width: calc(@width + 2em); 45 58 max-height: 30vw; 46 59 bottom: 1em; 60 + border: 1px solid black; 61 + transform: translateY(200%); 62 + transition: 0.4s; 63 + z-index: 100; 64 + } 65 + div.footnote:target { 66 + transform: translateY(0%); 67 + } 68 + #cover { 69 + position: fixed; 70 + top: 0; 71 + left: 0; 72 + height: 100vh; width: 100vw; 73 + background: linear-gradient(to top, 74 + @tone/0.8(-0.07), 75 + @tone/0.4(-0.07)); 76 + opacity: 0%; 77 + transition: 1s; 78 + pointer-events: none; 79 + backdrop-filter: blur(0px); 80 + } 81 + div.footnote:target ~ #cover { 82 + opacity: 100%; 83 + pointer-events: all; 84 + backdrop-filter: blur(5px); 47 85 } 48 86 } 49 87 @media print { 50 88 div.footnote { 89 + display: grid; 51 90 position: relative; 52 91 } 53 92 div.footnote:first-of-type { 54 93 border-top: 1px solid black; 55 94 } 56 95 } 57 96 58 97 div.footnote > a[href="#0"]{ 59 98 grid-row: 2/3; 60 99 grid-column: 3/4; 61 100 display: block; 62 - padding: 0.2em 0.7em; 63 101 text-align: center; 102 + padding: 0 0.3em; 64 103 text-decoration: none; 65 104 background: @tone(0.2); 66 105 color: @tone(1); 67 106 border: 1px solid black; 68 107 margin-top: 0.6em; 108 + font-size: 150%; 69 109 -webkit-user-select: none; 70 110 -ms-user-select: none; 71 111 user-select: none; 72 112 -webkit-user-drag: none; 73 113 user-drag: none; 74 114 } 75 115 div.footnote > a[href="#0"]:hover { ................................................................................ 90 130 grid-row: 1/2; 91 131 grid-column: 1/2; 92 132 } 93 133 div.footnote > div.text { 94 134 grid-row: 1/2; 95 135 grid-column: 2/4; 96 136 padding-left: 1em; 97 - overflow-y: scroll; 137 + overflow-y: auto; 138 + } 139 + div.footnote > div.text > p:first-child { 140 + margin-top: 0; 98 141 } 99 142 ]]; 100 143 header = [[ 101 144 body { padding: 0 2.5em !important } 102 145 h1,h2,h3,h4,h5,h6 { border-bottom: 1px solid @tone(0.7); } 103 146 h1 { font-size: 200%; border-bottom-style: double !important; border-bottom-width: 3px !important; margin: 0em -1em; } 104 147 h2 { font-size: 130%; margin: 0em -0.7em; } ................................................................................ 205 248 section > aside p:first-child { 206 249 margin: 0; 207 250 } 208 251 ]]; 209 252 code = [[ 210 253 code { 211 254 display: inline-block; 212 - background: @tone(0.9); 213 - color: @bg; 255 + background: @tone(-1); 256 + color: @tone(0.7); 214 257 font-family: monospace; 215 258 font-size: 90%; 216 - padding: 3px 5px; 259 + padding: 2px 5px; 260 + user-select: all; 217 261 } 218 262 ]]; 219 263 var = [[ 220 264 var { 221 265 font-style: italic; 222 266 font-family: monospace; 223 267 color: @tone(0.7); 268 + font-size: 90%; 224 269 } 225 270 code var { 226 - color: @tone(0.25); 271 + color: @tone(0.4); 227 272 } 228 273 ]]; 229 274 math = [[ 230 275 span.equation { 231 276 display: inline-block; 232 277 background: @tone(0.08); 233 278 color: @tone(2); ................................................................................ 238 283 abbr = [[ 239 284 abbr[title] { cursor: help; } 240 285 ]]; 241 286 editors_markup = [[]]; 242 287 block_code_listing = [[ 243 288 figure.listing { 244 289 font-family: monospace; 245 - background: @tone(0.05); 246 - color: @fg; 290 + background: @tone(0.05 20); 291 + color: @tone(1 20); 247 292 padding: 0; 248 293 margin: 0.3em 0; 249 294 counter-reset: line-number; 250 295 position: relative; 251 - border: 1px solid @fg; 296 + border: 1px solid @tone(1 20); 252 297 } 298 + :not(figure.listing) + figure.listing { 299 + margin-top: 1em; 300 + } 301 + figure.listing + :not(figure.listing) { 302 + margin-top: 1em; 303 + } 253 304 figure.listing>div { 254 305 white-space: pre-wrap; 255 306 tab-size: 3; 256 307 -moz-tab-size: 3; 257 308 counter-increment: line-number; 258 309 text-indent: -2.3em; 259 310 margin-left: 2.3em; 260 311 } 261 312 figure.listing>:is(div,hr)::before { 262 313 width: 1.0em; 263 314 padding: 0.2em 0.4em; 264 315 text-align: right; 265 316 display: inline-block; 266 - background-color: @tone(0.2); 317 + background-color: @tone(0.2 20); 267 318 border-right: 1px solid @fg; 268 319 content: counter(line-number); 269 320 margin-right: 0.3em; 270 321 } 271 322 figure.listing>hr::before { 272 323 color: transparent; 273 324 padding-top: 0; 274 325 padding-bottom: 0; 275 326 } 276 327 figure.listing>div::before { 277 - color: @fg; 328 + color: @tone(1 20); 278 329 } 279 330 figure.listing>div:last-child::before { 280 331 padding-bottom: 0.5em; 281 332 } 282 333 figure.listing>figcaption:first-child { 283 334 border: none; 284 - border-bottom: 1px solid @fg; 335 + border-bottom: 1px solid @tone(1 20); 285 336 } 286 337 figure.listing>figcaption::after { 287 338 display: block; 288 339 float: right; 289 340 font-weight: normal; 290 341 font-style: italic; 291 342 font-size: 70%; ................................................................................ 292 343 padding-top: 0.3em; 293 344 } 294 345 figure.listing>figcaption { 295 346 font-family: sans-serif; 296 347 font-size: 120%; 297 348 padding: 0.2em 0.4em; 298 349 border: none; 299 - color: @tone(2); 350 + color: @tone(2 20); 300 351 } 301 352 figure.listing > hr { 302 353 border: none; 303 354 margin: 0; 304 355 height: 0.7em; 305 356 counter-increment: line-number; 306 357 } 307 358 ]]; 359 + root = [[ 360 + body { 361 + font-size: 16pt; 362 + page-break-before: always; 363 + } 364 + h1 { 365 + page-break-before: always; 366 + } 367 + h1,h2,h3,h4,h5,h6 { 368 + page-break-after: avoid; 369 + } 370 + ]]; 371 + } 372 + 373 + local stylesNeeded = { 374 + flags = {}; 375 + order = {}; 308 376 } 377 + local function addStyle(sty) 378 + -- convenience function, also just in case i end up having 379 + -- to change the goddamn implementation again 380 + if not stylesNeeded.flags[sty] then 381 + stylesNeeded.flags[sty] = true 382 + table.insert(stylesNeeded.order, sty) 383 + return true 384 + end 385 + return false 386 + end 309 387 310 - local stylesNeeded = {} 388 + addStyle 'root' 311 389 312 390 local render_state_handle = { 313 391 doc = doc; 314 392 opts = opts; 315 393 style_rules = styles; -- use stylesneeded if at all possible 394 + style_add = addStyle; 316 395 stylesets = stylesets; 317 396 stylesets_active = stylesNeeded; 318 397 obj_htmlid = getSafeID; 319 398 -- remaining fields added later 320 399 } 321 400 322 401 local renderJob = doc:job('render_html', nil, render_state_handle) ................................................................................ 400 479 local spanparse = function(...) 401 480 local s = ct.parse_span(...) 402 481 doc.docjob:hook('meddle_span', s) 403 482 return s 404 483 end 405 484 406 485 local cssRulesFor = {} 486 + function getCSSImageForResource(r) 487 + return '' -- TODO 488 + end 489 + 407 490 local function getSpanRenderers(procs) 408 491 local tag, elt, catenate = procs.tag, procs.elt, procs.catenate 409 492 local span_renderers = {} 410 493 local plainrdr = getBaseRenderers(tagproc.toTXT, span_renderers) 411 494 local htmlSpan = getBaseRenderers(procs, span_renderers).htmlSpan 412 495 413 496 function span_renderers.format(sp,...) 414 497 local tags = { strong = 'strong', emph = 'em', strike = 'del', insert = 'ins', literal = 'code', variable = 'var'} 415 498 if sp.style == 'literal' and not opts['fossil-uv'] then 416 - stylesNeeded.code = true 499 + addStyle 'code' 417 500 elseif sp.style == 'strike' or sp.style == 'insert' then 418 - stylesNeeded.editors_markup = true 501 + addStyle 'editors_markup' 419 502 elseif sp.style == 'variable' then 420 - stylesNeeded.var = true 503 + addStyle 'var' 421 504 end 422 505 return tag(tags[sp.style],nil,htmlSpan(sp.spans,...)) 423 506 end 424 507 425 508 function span_renderers.deref(t,b,s) 426 509 local r = b.origin:ref(t.ref) 427 510 local name = t.ref 428 511 if name:find'%.' then name = name:match '^[^.]*%.(.+)$' end 429 512 if type(r) == 'string' then 430 - stylesNeeded.abbr = true 513 + addStyle 'abbr' 431 514 return tag('abbr',{title=r},next(t.spans) and htmlSpan(t.spans,b,s) or name) 432 515 end 433 516 if r.kind == 'resource' then 434 517 local rid = getSafeID(r, 'res-') 435 518 if r.class == 'image' then 436 519 if not cssRulesFor[r] then 437 520 local css = prepcss(string.format([[ 438 521 section p > .%s { 522 + background: %s; 439 523 } 440 - ]], rid)) 524 + ]], rid, getCSSImageForResource(r))) 441 525 stylesets[r] = css 442 526 cssRulesFor[r] = css 443 - stylesNeeded[r] = true 527 + addStyle(r) 444 528 end 445 - return tag('div',{class=rid},catenate{'blaah'}) 529 + return tag('div',{class=rid},catenate{''}) 446 530 elseif r.class == 'video' then 447 531 local vid = {} 448 532 return tag('video',nil,vid) 449 533 elseif r.class == 'font' then 450 534 b.origin:fail('fonts cannot be instantiated, use %font directive instead') 451 535 end 452 536 else ................................................................................ 504 588 b.origin:fail('%s is an object, not a reference', t.ref) 505 589 end 506 590 local mctx = b.origin:clone() 507 591 mctx.invocation = m 508 592 return htmlSpan(ct.parse_span(r, mctx),b,s) 509 593 end 510 594 function span_renderers.math(m,b,s) 511 - stylesNeeded.math = true 595 + addStyle 'math' 512 596 local spans = {} 513 597 local function fmt(sp, target) 514 598 for i,v in ipairs(sp) do 515 599 if type(v) == 'string' then 516 600 local x = ct.tool.mathfmt(b.origin, v) 517 601 for _,v in ipairs(x) do 518 602 table.insert(target, v) ................................................................................ 539 623 elseif d.crit then 540 624 b.origin:fail('critical extension %s unavailable', d.ext) 541 625 elseif d.failthru then 542 626 return htmlSpan(d.spans, b, s) 543 627 end 544 628 end 545 629 function span_renderers.footnote(f,b,s) 546 - stylesNeeded.footnote = true 630 + addStyle 'footnote' 547 631 local source, sid, ssec = b.origin:ref(f.ref) 548 632 local cnc = getSafeID(ssec) .. ' ' .. sid 549 633 local fn 550 634 if footnotes[cnc] then 551 635 fn = footnotes[cnc] 552 636 else 553 637 footnotecount = footnotecount + 1 ................................................................................ 567 651 local null = function() return catenate{} end 568 652 569 653 local block_renderers = { 570 654 anchor = function(b,s) 571 655 return tag('a',{id = getSafeID(b)},null()) 572 656 end; 573 657 paragraph = function(b,s) 574 - stylesNeeded.paragraph = true; 658 + addStyle 'paragraph' 575 659 return tag('p', nil, sr.htmlSpan(b.spans, b, s), b) 576 660 end; 577 661 directive = function(b,s) 578 662 -- deal with renderer directives 579 663 local _, cmd, args = b.words(2) 580 664 if cmd == 'page-title' then 581 665 if not opts.title then doctitle = args end ................................................................................ 582 666 elseif b.critical then 583 667 b.origin:fail('critical HTML renderer directive “%s” not supported', cmd) 584 668 end 585 669 end; 586 670 label = function(b,s) 587 671 if ct.sec.is(b.captions) then 588 672 if not (opts['fossil-uv'] or opts.snippet) then 589 - stylesNeeded.header = true 673 + addStyle 'header' 590 674 end 591 675 local h = math.min(6,math.max(1,b.captions.depth)) 592 676 return tag(f('h%u',h), nil, sr.htmlSpan(b.spans, b, s), b) 593 677 else 594 678 -- handle other uses of labels here 595 679 end 596 680 end; ................................................................................ 606 690 {align=c.align}, sr.htmlSpan(c.spans, b))) 607 691 end 608 692 table.insert(tb, tag('tr',nil,catenate(row))) 609 693 end 610 694 return tag('table',nil,catenate(tb)) 611 695 end; 612 696 listing = function(b,s) 613 - stylesNeeded.block_code_listing = true 697 + addStyle 'block_code_listing' 614 698 local nodes = ss.map(function(l) 615 699 if #l > 0 then 616 700 return tag('div',nil,sr.htmlSpan(l, b, s)) 617 701 else 618 702 return elt('hr') 619 703 end 620 704 end, b.lines) ................................................................................ 622 706 table.insert(nodes,1, tag('figcaption',nil,sr.htmlSpan(b.title))) 623 707 end 624 708 if b.lang then langsused[b.lang] = true end 625 709 return tag('figure', {class='listing', lang=b.lang, id=b.id and getSafeID(b)}, catenate(nodes)) 626 710 end; 627 711 aside = function(b,s) 628 712 local bn = {} 629 - stylesNeeded.aside = true 713 + addStyle 'aside' 630 714 if #b.lines == 1 then 631 715 bn[1] = sr.htmlSpan(b.lines[1], b, s) 632 716 else 633 717 for _,v in pairs(b.lines) do 634 718 table.insert(bn, tag('p', {}, sr.htmlSpan(v, b, s))) 635 719 end 636 720 end ................................................................................ 688 772 tagproc = tagproc.toIR; 689 773 astproc = astproc.toIR; 690 774 }, block, sec) 691 775 end 692 776 end 693 777 if rd then 694 778 if opts['heading-anchors'] and block == sec.heading_node then 695 - stylesNeeded.headingAnchors = true 779 + addStyle 'headingAnchors' 696 780 table.insert(rd.nodes, ' ') 697 781 table.insert(rd.nodes, { 698 782 tag = 'a'; 699 783 attrs = {href = '#' .. irs.attrs.id, class='anchor'}; 700 784 nodes = {type(opts['heading-anchors'])=='string' and opts['heading-anchors'] or '§'}; 701 785 }) 702 786 end ................................................................................ 735 819 for l in fn.source:gmatch('([^\n]*)') do 736 820 ct.parse_line(l, fn.origin, ftir) 737 821 end 738 822 renderBlocks(ftir,body) 739 823 local note = tag('div',{class='footnote',id=fn.id}, { 740 824 tag('div',{class='number'}, tostring(fn.num)), 741 825 tag('div',{class='text'}, body.nodes), 742 - tag('a',{href='#0'},'close') 826 + tag('a',{href='#0'},'⤫') 743 827 }) 744 828 table.insert(ir, note) 745 829 end 830 + if next(footnotes) then 831 + table.insert(ir, tagproc.toIR.tag('div',{id='cover'},'')) 832 + end 746 833 747 834 -- restructure passes 748 835 runhook('ir_restructure_pre', ir) 749 836 750 837 ---- list insertion pass 751 838 local lists = {} 752 839 for _, sec in pairs(ir) do 753 840 if sec.tag == 'section' then 754 841 local i = 1 while i <= #sec.nodes do local v = sec.nodes[i] 755 842 if v.tag == 'li' then 843 + addStyle 'list' 756 844 local ltag 757 845 if v.src.ordered 758 - then ltag = 'ol' 759 - else ltag = 'ul' 846 + then ltag = 'ol' addStyle 'list_ordered' 847 + else ltag = 'ul' addStyle 'list_unordered' 760 848 end 761 849 local last = i>1 and sec.nodes[i-1] 762 850 if last and last.embed == 'list' and not ( 763 851 last.ref[#last.ref].src.depth == v.src.depth and 764 852 last.ref[#last.ref].src.ordered ~= v.src.ordered 765 853 ) then 766 854 -- add to existing list ................................................................................ 900 988 if opts.width then 901 989 table.insert(styles, string.format([[body {padding:0 1em;margin:auto;max-width:%s}]], opts.width)) 902 990 end 903 991 if opts.accent then 904 992 table.insert(styles, string.format(':root {--accent:%s}', opts.accent)) 905 993 end 906 994 if opts.accent or (not opts['dark-on-light']) and (not opts['fossil-uv']) then 907 - stylesNeeded.accent = true 995 + addStyle 'accent' 908 996 end 909 997 910 998 911 - for k in pairs(stylesNeeded) do 999 + for _,k in pairs(stylesNeeded.order) do 912 1000 if not stylesets[k] then ct.exns.unimpl('styleset %s not implemented (!)', k):throw() end 913 1001 table.insert(styles, prepcss(stylesets[k])) 914 1002 end 915 1003 916 1004 local head = {} 917 1005 local styletag = '' 918 1006 if opts['link-css'] then
Modified tool/makeshim.lua from [3535fb21b6] to [f2235ca34c].
18 18 local main = [[ 19 19 int main(int argc, char** argv) { 20 20 lua_State* l = luaL_newstate(); 21 21 luaL_openlibs(l); 22 22 23 23 // pass arguments thru to lua 24 24 lua_newtable(l); 25 - for(size_t i = argc; i < argc; ++i) { 25 + for(size_t i = 0; i < argc; ++i) { 26 26 lua_pushstring(l,argv[i]); 27 27 lua_rawseti(l, -2, i); 28 28 } 29 29 lua_setglobal(l, "arg"); 30 30 31 31 // load and run our payload 32 32 int e = luaL_loadbufferx(l, ct_bytecode, sizeof(ct_bytecode), "cortav", "b");
Name change from tools/ucs.lua to tool/ucs.lua.