Differences From
Artifact [96194d0b88]:
89 89
90 90 on systems with environment variables, these may be accessed as context variables by prefixing their name with [$env.].
91 91
92 92 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.
93 93
94 94 ## directives
95 95 d: [$%[*[##1]]]
96 -* {d format} gives a hint on how the document should be formatted. the first hint that is understood will be applied; all others will be discarded. standard hints include:
97 -** essay
98 -** narrative
99 -** screenplay: uses asides to denote actions, quotes for dialogue
100 -** stageplay: uses asides to denote actions, quotes for dialogue
101 -** manual
102 -** glossary
103 -** news
104 96 * {d author} encodes document authorship
105 97 * {d cols} specifies the number of columns the next object should be rendered with
106 98 * {d include} transcludes another file
107 99 * {d quote} transcludes another file, without expanding the text except for paragraphs
108 100 * {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.
109 101 * {d expand} causes the next object (usually a code block) to be fully expanded when it would otherwise not be
102 +* {d pragma} supplies semantic data about author intent, the kind of information 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
103 +** {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:
104 +*** essay
105 +*** narrative
106 +*** screenplay: uses asides to denote actions, quotes for dialogue
107 +*** stageplay: uses asides to denote actions, quotes for dialogue
108 +*** manual
109 +*** glossary
110 +*** news
111 +** {d pragma accent} specifies an accent hue (in degrees around the color wheel) for renderers which support colorized output
112 +** {d pragma accent-spread} is a factor that controls the "spread" of hues used in the document. if 0, only the accent color will be used; if larger, other hues will be used in addition to the primary accent color.
113 +** {d pragma dark-on-light on|off} controls whether the color scheme used should be light-on-dark or dark-on-light
114 +** {d pragma page-width} indicates how wide the pages should be
110 115
111 116 ##ex examples
112 117
113 118 ~~~ blockquotes #bq [cortav] ~~~
114 119 the following excerpts of text were recovered from a partially erased hard drive found in the Hawthorne manor in the weeks after the Incident. context is unknown.
115 120
116 121 #>
................................................................................
247 252
248 253 ~~~
249 254 $ luac -s -o stdin2html.lc $cortav_repo/{sirsem,cortav,ext/toc}.lua stdin2html.lua
250 255 ~~~
251 256
252 257 and can then be operated with the command [$lua stdin2html.lc], with no further need for the cortav repository files. note that the order of the [$luac] command is important! [$sirsem.lua] must come first, followed by [$cortav.lua], followed by any extensions. your driver script (i.e. the script with the entry point into the application) should always come last.
253 258
259 +### building custom tools
260 +generally, most existing file-format conversion tools (cmark, pandoc, and so on) have a crucial limitation: they hardcode specific assumptions like document structure. this means that the files they output are generally not suitable as-is for the users' purposes, and require further munging, usually by hateful shell or perl scripts. some tools do provide libraries end users to use as a basis for designing their own tools, but these are often limited, and in any case the user ends up having to write their own (non-standard) driver. it's no surprise that very few people end up doing this.
261 +
262 +[$cortav.lua]'s design lends itself to a more elegant solution. one can of course write their own driver using [$cortav] as a library, but most of the time when you're compiling document sources, you just want a binary you can run from the command line or a makefile. with [$cortav.lua], you can extend its capabilities easily while keeping the same driver.
263 +
264 +in the [$cortav] spec, extensions are mostly intended to give different implementations the ability to offer extra capabilities, but the reference implementation uses an extension architecture that makes it easy to write and add your own. for each type of new behavior you want to implement, just create a new extension and list it on the make command line:
265 +
266 +~~~
267 +$ nvim ~/dev/my-cortav-exts/imperial-edict.lua
268 +$ make cortav extens+=$HOME/dev/my-cortav-exts/*.lua
269 +~~~
270 +
271 +the cortav binary this produces will have all the extra capabilities you personally need, without any need to fork [$cortav.lua] itself or even touch the repository.
272 +
273 +there's no reason [$cortav.lua] shouldn't be able to load extensions at runtime as well; i just haven't implemented this behavior yet. it probably would only take a few extra lines of code tho.
274 +
275 +i will eventually document the extension API, but for now, look at [$ext/toc.lua] for a simple example of how to register an extension.
276 +
254 277 ## command line driver
255 278 the [$cortav.lua] command line driver can be run from the repository directory with the command [$lua ./cli.lua], or by first compiling it into a bytecode form that links in all its dependencies. this is the preferred method for installation, as it produces a self-contained executable which loads more quickly, but running the driver in script form may be desirable for development or debugging.
256 279
257 280 the repository contains a GNU makefile to automate compilation of the reference implementation on unix-like OSes. simply run [$$ make cortav] or [$$ gmake cortav] from the repository root to produce a self-contained bytecode executable that can be installed anywhere on your filesystem, with no dependencies other than the lua interpreter.
258 281
259 282 ! note that the makefile strips debugging symbols to save space, so running [$cli.lua] directly as a script may be helpful if you encounter errors and need stacktraces or other debugging information.
260 283
................................................................................
270 293 $ cortav readme.ct
271 294 # reads from readme.ct, writes to standard output
272 295 ~~~
273 296
274 297 ### switches
275 298 [$cortav.lua] offers various switches to control its behavior.
276 299 + long + short + function +
277 -| [$--out [!file]] :|:[$-o]:| sets the output file (default stdout) |
278 -| [$--log [!file]] :|:[$-l]:| sets the log file (default stderr) |
279 -| [$--define [!var] [!val]]:|:[$-d]:| sets the context variable [$var] to [$val] |
280 -| [$--mode-set [!mode]] :|:[$-y]:| activates the [>refimpl-mode mode] with ID [!mode]
281 -| [$--mode-clear [!mode]] :|:[$-n]:| disables the mode with ID [!mode] |
282 -| [$--mode [!id] [!val]] :|:[$-m]:| configures mode [!id] with the value [!val] |
283 -| [$--help] :|:[$-h]:| display online help |
284 -| [$--version] :|:[$-V]:| display the interpreter version |
300 +| [$--out [!file]] :|:[$-o]:| sets the output file (default stdout) |
301 +| [$--log [!file]] :|:[$-l]:| sets the log file (default stderr) |
302 +| [$--define [!var] [!val]] :|:[$-d]:| sets the context variable [$var] to [$val] |
303 +| [$--mode-set [!mode]] :|:[$-y]:| activates the [>refimpl-mode mode] with ID [!mode]
304 +| [$--mode-clear [!mode]] :|:[$-n]:| disables the mode with ID [!mode] |
305 +| [$--mode [!id] [!val]] :|:[$-m]:| configures mode [!id] with the value [!val] |
306 +| [$--mode-set-weak [!mode]] :|:[$-Y]:| activates the [>refimpl-mode mode] with ID [!mode] if the source file does not specify otherwise
307 +| [$--mode-clear-weak [!mode]] :|:[$-N]:| disables the mode with ID [!mode] if the source file does not specify otherwise
308 +| [$--mode-weak [!id] [!val]] :|:[$-M]:| configures mode [!id] with the value [!val] if the source file does not specify otherwise
309 +| [$--help] :|:[$-h]:| display online help |
310 +| [$--version] :|:[$-V]:| display the interpreter version |
285 311
286 312 ###refimpl-mode modes
287 313 most of [$cortav.lua]'s implementation-specific behavior is controlled by use of [!modes]. these are namespaced options which may have a boolean, string, or numeric value. boolean modes are set with the [$-y] [$-n] flags; other modes use the [$-m] flags.
288 314
289 315 most modes are defined by the renderer backend. the following modes affect the behavior of the frontend:
290 316
291 317 + ID + type + effect
................................................................................
315 341 -m render:format html \
316 342 -m html:width 40em \
317 343 -m html:accent 80 \
318 344 -m html:hue-spread 35 \
319 345 -y html:dark-on-light # could also be written as:
320 346 $ cortav readme.ct -ommmmy readme.html render:format html html:width 40em html:accent 80 html:hue-spread 35 html:dark-on-light
321 347 ~~~
348 +
349 +## further directions
350 +
351 +### LCH support
352 +right now, the use of color in the HTML renderer is very unsatisfactory. the accent mechanism operates on the basis of the CSS HSL function, which is not perceptually uniform; different hues will present different mixes of brightness and some (yellows?) may be ugly or unreadable.
353 +
354 +the ideal solution would be to simply switch to using LCH based colors. unfortunately, only Safari actually supports the LCH color function right now, and it's unlikely (unless Lea Verou and her husband manage to work a miracle) that Colors Level 4 is going to be implemented very widely any time soon.
355 +
356 +this leaves us in an awkward position. we can of course do the math ourselves, working in LCH to implement the internal [$@tone] macro, and then "converting" these colors to HSL. unfortunately, you can't actually convert from LCH to HSL; it's like converting from pounds to kilograms. LCH can represent any color the human visual system can perceive; sRGB can't, and CSS HSL is implemented in sRGB. however, we could at least approximate something that would allow for perceptually uniform brightness, which would be an improvement, and this is probably the direction to go in, unless a miracle occurs and [$lch()] or [$color()] pop up in Blink.
357 +
358 +it may be possible to do a more reasonable job of handling colors in the postscript and TeX outputs. unsure about SVG but i assume it suffers the same problems HTML/CSS do. does groff even support color??