Differences From
Artifact [0c4afc6088]:
115 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.
116 116
117 117 ##onspans styled text
118 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.
119 119
120 120 * strong {obj *|styled-text}: causes its text to stand out from the narrative, generally rendered as bold or a brighter color.
121 121 * emphatic {obj !|styled-text}: indicates that its text should be spoken with emphasis, generally rendered as italics
122 +* 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.
122 123 * 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
123 124 * 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
124 125 * 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.
125 126 * strikeout {obj ~|styled-text}: indicates that its text should be struck through or otherwise indicated for deletion
126 127 * insertion {obj +|styled-text}: indicates that its text should be indicated as a new addition to the text body.
127 128 ** consider using a macro definition [`\edit: [~[#1]][+[#2]]] to save typing if you are doing editing work
128 129 * 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.
129 130 * 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.
130 131 * superscript {obj '|[$styled-text]}
131 132 * subscript {obj ,|[$styled-text]}
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
133 +* 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
133 134 * raw literal \[$\\[!raw-text]\]: shorthand for [\[$[\…]]]
134 135 * macro [`\{[!name] [!arguments]\}]: invokes a [>ex.mac macro], specified with a reference
135 136 * argument {obj #|var}: in macros only, inserts the [$var]-th argument. otherwise, inserts a context variable provided by the renderer.
136 137 * raw argument {obj ##|var}: like above, but does not evaluate [$var].
137 138 * 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)
138 139 * inline image {obj &@|name}: shows a small image or other object inline. the unicode character [`🖼] can also be used instead of [`&@].
139 140 * unicode codepoint {obj U+|hex-integer}: inserts an arbitrary UCS codepoint in the output, specified by [$hex-integer]. lowercase [`u] is also legal.
................................................................................
237 238 * {def cortav.page} the number of the page currently being rendered
238 239 * {def cortav.id} the identifier of the renderer
239 240 * {def cortav.hash} the SHA3 hash of the source file being rendered
240 241 def: [*[#1]]:
241 242
242 243 on systems with environment variables, these may be accessed as context variables by prefixing their name with [`env.].
243 244
244 -different renderers may provide context in different ways, such as from command line options or a context file. any predefined variables should carry an appropriate prefix to prevent conflation.
245 +different renderers may provide context in different ways, such as from command line options or a context file. any predefined variables should carry an appropriate prefix to prevent conflation.
245 246
246 247 ##fonts fonts
247 248 for output backends that support font specification, cortav provides a sophisticated font management system by means of the [!font stack].
248 249
249 250 when a document parse begins, the font stack is empty (unless a default font has already been loaded by an intent file).
250 251 when the font stack is empty, cortav does not include font specifications in its output, and thus will use whatever the default of the various rendering programs is.
251 252
................................................................................
256 257 #^fonts
257 258 %% we then define each font as a resource
258 259 @serif
259 260 src: auto font name:Alegreya
260 261 embed font/ttf file:project-fonts/alegreya.ttf
261 262 link font/woff2 file:/assets/font/alegreya.woff2
262 263 auto font name:Times New Roman
264 + auto font dit:TR/bold=TRB/italic=TRI/bold,italic=TRBI
263 265 @sans
264 266 src: link font name:Alegreya Sans
265 267 link font name:Open Sans
266 268 link font name:sans-serif
267 269 ~~~
268 270
269 271 here we have defined two font families, [`fonts.serif] and [`fonts.sans]. each contains a list of references to fonts which will be tried in order. for example, this could be translated into the following CSS:
................................................................................
343 345
344 346 &$cursive-quote Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident
345 347
346 348 %% without affecting the overall font context. in fact, since 'cursive-quote' creates
347 349 %% its context using 'dup', it would import all font specifications besides 'body'
348 350 %% from the environment it is invoked in
349 351 ~~~
352 +
353 +you may have noticed the rather odd bit at the end of our font definition, with the [`dit] URI. the reasons for this are tragic. groff, while delightful, has a thoroughly antiquated understanding of fonts, and doesn't support normal font formats like truetype. groff ships with a limited number of fonts in its own format, identified by obscurantist letter code ([`HBI] is "Helvetica Bold Italic", for instance) and lacking normal metadata. for this reason, you'll have to tell cortav how you want your fonts translated.
354 +
355 +it is possible to use modern fonts with groff, but to do that you'll have to convert and install them, which is outside the scope of this document. however, even if you do this, you should specify a fallback font (if possible) so that people rendering your document on other machines still get somewhat sensible output.
356 +
357 +the syntax of a [`dit] specification is [`dit:[$regular]], where [$regular] specifies the name of the regular font. this can be followed by any number of variant specifications [`/[$variant]=[$name]], where [$variant] is one of the tags described in the [>fonts-sty custom] style section, and [$name] is the name of a DIT font. so the URI in the example names a font [`T] with bold [`TB], italic [`TI], and bold-italic [`TBI].
358 +
359 +the [`groff] backend does do a little magic to make this mess more bearable, however. some of groff's built-in fonts can be accessed by a [`name] URI instead of having to construct them by hand with a [`dit] URI -- the backend hardcodes metadata for these fonts so that documents can render somewhat intellgibly in groff even if the original author did not make special provisions for this. the groff fonts accessible by [`name] are:
360 +* Times New Roman
361 +* Helvetica
362 +* Courier
363 +* Bookman
364 +additionally, as a shortcut, if the regular, bold, italic, and bold-italic variants of a DIT font have the predictable pattern of [`[$X]], [`[$X]B], [`[$X]I], [`[$X]BI] (which many do), you can simply write the URI [`dit:[$X]] and cortav will infer the rest. so the example above could be rewritten as [`dit:T] to exactly the same effect.
365 +
366 +###fonts-sty custom styles
367 +sometimes you want to be able to issue more specific formatting instructions than "italic" or "bold". cortav provides a simple [!custom style] mechanism to allow this. a custom style is simply a reference that binds a name to a sequence of space-separated formatting directives. these directives include:
368 +* [`regular]: applies the regulat form of the font, overriding any previous set styles
369 +* [`medium]: applies a weight of the font between [`regular] and [`bold], defaulting to [`regular] if one is not available
370 +* [`demibold]: applies a weight of the font between [`regular] and [`bold], defaulting to [`bold] if one is not available
371 +* [`bold]: applies the usual "bold" weight of the font
372 +* [`dense]: applies the heaviest available weight of th the font. usually the same as [`bold]
373 +* [`light]: applies the usual "light" weight of the font. most fonts do not have a light weight, so this will be the same as [`regular].
374 +* [`thin]: applies the slimmest available weight of the font. usually the same as [`light].
375 +* [`underline]: underlines the text
376 +* [`strike]: strikes the text out
377 +* [`italic]: applies a slanted variant of the font
378 +* [`oblique]: applies the most slanted variant of the font available. usually the same as [`italic]
379 +* [`font=[$id]]: switches to font [$id] for the duration of the span. [$id] must be the ID of a resource defining a font.
380 +* [`[$ext].[$prop]=[$word]]: attaches extra information for use by formatting extensions. [$ext] must be the ID of the extension.
381 +
382 +once a custom style is defined, you can make use of it using the [` \[.[$id] [$styled-text]\]] span notation, where [$id] is the identifier of the reference containing your style. for instance, to define and use a style named [`important] that [^pls-no specifies a dense, underlined variant of font [`impact]] and applies the CSS class [`blink] when rendered with the [`html] backend:
383 + pls-no: please do not do this
384 +~~~cortav
385 +this paragraph contains some [.important truly important] information.
386 + important: dense underline font=impact html.class=blink
387 +~~~
388 +you should always give your styles semantic names where practicable, instead of simply describing their graphical characteristics. this is good practice in general, but especially because your document will be renderable to different formats with different characteristics, and what makes text look important on a manpage in the terminal may be quite different from how it looks in a webpage or PDF.
350 389
351 390 ##dir directives
352 391 d: [`%[*[##1]]]
353 392 * {d author} encodes document authorship. multiple author directives can be issued to add additional coauthors
354 393 * {d cols} specifies the number of columns the next object should be rendered with
355 394 * {d include} transcludes another file
356 395 * {d import} reads in the contents of another file as an embeddable section