Differences From
Artifact [e74ca97d6f]:
557 557 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.
558 558
559 559 ##dir directives
560 560 d: [`%[*[##1]]]
561 561 dd: [`%[*[##1]] [#2]]
562 562 * {d author} encodes document authorship. multiple author directives can be issued to add additional coauthors
563 563 * {d cols} specifies the number of columns the next object should be rendered with
564 -* {d include} transcludes another file
565 -* {d import} reads in the contents of another file as an embeddable section
564 +* {d include} transcludes another file (but see also [>rsrc])
565 +* {d with} imports symbols from another scope:
566 +** {dd with|[$section]} imports all symbols in [$section]
567 +** {dd with|[$section].[$object]} imports [$object] from [$section]
568 +** {dd with|[$name]=[$section]} creates a local alias [$name] for [$section]
569 +** {dd with|[$name]=[$section].[$object]} imports [$object] from [$section] under the name [$name]
570 +* {d global} exports all symbols in the current section so they can be used unprefixed from any other section
571 +** {dd global|[$section]} exports all symbols in [$section]
572 +** {dd global|[$section].[$object]} exports [$object] from [$section]
573 +** {dd global|[$name]=[$section]} creates a global alias [$name] for [$section]
574 +** {dd global|[$name]=[$section].[$object]} exports [$object] from [$section] under the name [$name]
566 575 * {d quote} transcludes another file, without expanding the text except for paragraphs
567 -* {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.
568 576 * {d expand} causes the next object (usually a code block) to be fully expanded when it would otherwise not be
569 577 * {d font} controls the font stack, for outputs that support changing fonts. see [>fonts fonts] for more information.
570 578 * {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
571 -** {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 C6B+U8L (which can also be interpreted as UTF-8, albeit with some lost semantics). this might be used at the top of a document to set its primary language.
572 -** {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
573 -** {d lang sec en-US} switches to American English for the duration of a section. does not affect the language stack.
579 +** {dd lang is|x-ranuir-Cent-CR8} sets the current language to Ranuir as spoken in the Central Worlds, written in Corran and encoded using C6B+U8L (which can also be interpreted as UTF-8, albeit with some lost semantics). this might be used at the top of a document to set its primary language.
580 +** {dd lang push|gsw-u-sd-chzh} temporarily switches to Zürich German, e.g. to quote a German passage in an otherwise Ranuir document
581 +** {dd lang sec|en-US} switches to American English for the duration of a section. does not affect the language stack.
574 582 ** {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
575 583 * {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.
576 584 ** {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:
577 585 *** [`essay]
578 586 *** [`narrative]
579 587 *** [`screenplay]: uses asides to denote actions, quotes for dialogue
580 588 *** [`stageplay]: uses asides to denote actions, quotes for dialogue