Index: cli.lua ================================================================== --- cli.lua +++ cli.lua @@ -24,16 +24,22 @@ end return new end local function -main(input, output, log, mode, vars) +main(input, output, log, mode, suggestions, vars) local doc = ct.parse(input.stream, input.src, mode) input.stream:close() if mode['parse:show-tree'] then log:write(dump(doc)) end + + -- the document has now had a chance to give its say; if it hasn't specified + -- any modes of its own, we now merge in the 'weak modes' (suggestions) + for k,v in pairs(suggestions) do + if not mode[k] then mode[k] = v end + end if not mode['render:format'] then error 'what output format should i translate the input to?' end if mode['render:format'] == 'none' then return 0 end @@ -53,34 +59,42 @@ -- not the renderer, so that's not a suitable place for this information doc.stage = { kind = 'render'; format = mode['render:format']; mode = mode; + suggestions = suggestions; } output:write(ct.render[mode['render:format']](doc, render_opts)) return 0 end local inp,outp,log = io.stdin, io.stdout, io.stderr local function entry_cli() - local mode, vars, input = default_mode, {}, { + local suggestions, vars, input = default_mode, {}, { stream = inp; src = { file = '(stdin)'; } } + + local mode = {} local optnparams = function(o) local param_opts = { out = 1; log = 1; define = 2; -- key value + ['mode-set'] = 1; ['mode-clear'] = 1; mode = 2; + + ['mode-set-weak'] = 1; + ['mode-clear-weak'] = 1; + ['mode-weak'] = 2; } return param_opts[o] or 0 end local optmap = { @@ -87,12 +101,13 @@ o = 'out'; l = 'log'; d = 'define'; V = 'version'; h = 'help'; - y = 'mode-set', n = 'mode-clear'; - m = 'mode'; + y = 'mode-set', Y = 'mode-set-weak'; + n = 'mode-clear', N = 'mode-clear-weak'; + m = 'mode', M = 'mode-weak'; } local checkmodekey = function(key) if not key:match '[^:]+:.+' then ct.exns.cli('invalid mode key %s', key):throw() @@ -119,10 +134,14 @@ vars[key] = value end; mode = function(key,value) mode[checkmodekey(key)] = value end; ['mode-set'] = function(key) mode[checkmodekey(key)] = true end; ['mode-clear'] = function(key) mode[checkmodekey(key)] = false end; + + ['mode-weak'] = function(key,value) suggestions[checkmodekey(key)] = value end; + ['mode-set-weak'] = function(key) suggestions[checkmodekey(key)] = true end; + ['mode-clear-weak'] = function(key) suggestions[checkmodekey(key)] = false end; } local args = {} local keepParsing = true do local i = 1 while i <= #arg do local v = arg[i] @@ -174,11 +193,11 @@ if not file then error('unable to load file ' .. args[1]) end input.stream = file input.src.file = args[1] end - return main(input, outp, log, mode, vars) + return main(input, outp, log, mode, suggestions, vars) end local ok, e = pcall(entry_cli) -- local ok, e = true, entry_cli() if not ok then Index: cortav.ct ================================================================== --- cortav.ct +++ cortav.ct @@ -91,24 +91,29 @@ 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. ## directives d: [$%[*[##1]]] -* {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: -** essay -** narrative -** screenplay: uses asides to denote actions, quotes for dialogue -** stageplay: uses asides to denote actions, quotes for dialogue -** manual -** glossary -** news * {d author} encodes document authorship * {d cols} specifies the number of columns the next object should be rendered with * {d include} transcludes another file * {d quote} transcludes another file, without expanding the text except for paragraphs * {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. * {d expand} causes the next object (usually a code block) to be fully expanded when it would otherwise not be +* {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 +** {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: +*** essay +*** narrative +*** screenplay: uses asides to denote actions, quotes for dialogue +*** stageplay: uses asides to denote actions, quotes for dialogue +*** manual +*** glossary +*** news +** {d pragma accent} specifies an accent hue (in degrees around the color wheel) for renderers which support colorized output +** {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. +** {d pragma dark-on-light on|off} controls whether the color scheme used should be light-on-dark or dark-on-light +** {d pragma page-width} indicates how wide the pages should be ##ex examples ~~~ blockquotes #bq [cortav] ~~~ 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. @@ -249,10 +254,28 @@ $ luac -s -o stdin2html.lc $cortav_repo/{sirsem,cortav,ext/toc}.lua stdin2html.lua ~~~ 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. +### building custom tools +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. + +[$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. + +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: + +~~~ +$ nvim ~/dev/my-cortav-exts/imperial-edict.lua +$ make cortav extens+=$HOME/dev/my-cortav-exts/*.lua +~~~ + +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. + +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. + +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. + ## command line driver 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. 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. @@ -272,18 +295,21 @@ ~~~ ### switches [$cortav.lua] offers various switches to control its behavior. + long + short + function + -| [$--out [!file]] :|:[$-o]:| sets the output file (default stdout) | -| [$--log [!file]] :|:[$-l]:| sets the log file (default stderr) | -| [$--define [!var] [!val]]:|:[$-d]:| sets the context variable [$var] to [$val] | -| [$--mode-set [!mode]] :|:[$-y]:| activates the [>refimpl-mode mode] with ID [!mode] -| [$--mode-clear [!mode]] :|:[$-n]:| disables the mode with ID [!mode] | -| [$--mode [!id] [!val]] :|:[$-m]:| configures mode [!id] with the value [!val] | -| [$--help] :|:[$-h]:| display online help | -| [$--version] :|:[$-V]:| display the interpreter version | +| [$--out [!file]] :|:[$-o]:| sets the output file (default stdout) | +| [$--log [!file]] :|:[$-l]:| sets the log file (default stderr) | +| [$--define [!var] [!val]] :|:[$-d]:| sets the context variable [$var] to [$val] | +| [$--mode-set [!mode]] :|:[$-y]:| activates the [>refimpl-mode mode] with ID [!mode] +| [$--mode-clear [!mode]] :|:[$-n]:| disables the mode with ID [!mode] | +| [$--mode [!id] [!val]] :|:[$-m]:| configures mode [!id] with the value [!val] | +| [$--mode-set-weak [!mode]] :|:[$-Y]:| activates the [>refimpl-mode mode] with ID [!mode] if the source file does not specify otherwise +| [$--mode-clear-weak [!mode]] :|:[$-N]:| disables the mode with ID [!mode] if the source file does not specify otherwise +| [$--mode-weak [!id] [!val]] :|:[$-M]:| configures mode [!id] with the value [!val] if the source file does not specify otherwise +| [$--help] :|:[$-h]:| display online help | +| [$--version] :|:[$-V]:| display the interpreter version | ###refimpl-mode modes 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. most modes are defined by the renderer backend. the following modes affect the behavior of the frontend: @@ -317,5 +343,16 @@ -m html:accent 80 \ -m html:hue-spread 35 \ -y html:dark-on-light # could also be written as: $ cortav readme.ct -ommmmy readme.html render:format html html:width 40em html:accent 80 html:hue-spread 35 html:dark-on-light ~~~ + +## further directions + +### LCH support +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. + +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. + +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. + +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?? Index: cortav.lua ================================================================== --- cortav.lua +++ cortav.lua @@ -211,17 +211,69 @@ python = { color = 0xcdd6ff }; } local stylesets = { header = [[ - h1 { font-size: 200%; border-bottom-style: double !important; border-bottom-width: 3px !important; } - h2 { font-size: 130%; } - h3 { font-size: 110%; } - h4 { font-size: 100%; font-weight: normal; } + h1,h2,h3,h4,h5,h6 { border-bottom: 1px solid @tone(0.7); } + h1 { font-size: 200%; border-bottom-style: double !important; border-bottom-width: 3px !important; margin: 0em -1em; } + h2 { font-size: 130%; margin: 0em -0.7em; } + h3 { font-size: 110%; margin: 0em -0.5em; } + h4 { font-size: 100%; font-weight: normal; margin: 0em -0.2em; } h5 { font-size: 90%; font-weight: normal; } h6 { font-size: 80%; font-weight: normal; } h3, h4, h5, h6 { border-bottom-style: dotted !important; } + h1,h2,h3,h4,h5,h6 { + margin-top: 0; + margin-bottom: 0; + } + :is(h1,h2,h3,h4,h5,h6) + p { + margin-top: 0.4em; + } + + ]]; + headingAnchors = [[ + :is(h1,h2,h3,h4,h5,h6) > a[href].anchor { + text-decoration: none; + font-size: 1.2em; + padding: 0.3em; + opacity: 0%; + transition: 0.3s; + font-weight: 100; + } + :is(h1,h2,h3,h4,h5,h6):hover > a[href].anchor { + opacity: 50%; + } + :is(h1,h2,h3,h4,h5,h6) > a[href].anchor:hover { + opacity: 100%; + } + + ]] .. -- this is necessary to avoid the sections jumping around + -- when focus changes from one to another + [[ section { + border: 1px solid transparent; + } + + section:target { + margin-left: -2em; + margin-right: -2em; + padding: 0 2em; + background: @tone(0.04); + border: 1px dotted @tone(0.3); + } + + section:target > :is(h1,h2,h3,h4,h5,h6) { + + } + ]]; + paragraph = [[ + p { + margin: 0.7em 0; + } + section { + margin: 1.2em 0; + } + section:first-child { margin-top: 0; } ]]; accent = [[ body { background: @bg; color: @fg } a[href] { color: @tone(0.7 30); @@ -229,11 +281,10 @@ } a[href]:hover { color: @tone(0.9 30); text-decoration-color: @tone/0.7(0.7 30); } - h1,h2,h3,h4,h5,h6 { border-bottom: 1px solid @tone(0.7); } h1 { color: @tone(2); } h2 { color: @tone(1.5); } h3 { color: @tone(1.2); } h4 { color: @tone(1); } h5,h6 { color: @tone(0.8); } @@ -444,10 +495,11 @@ return lst end local block_renderers = { paragraph = function(b,s) + stylesNeeded.paragraph = true; return tag('p', nil, sr.htmlSpan(b.spans, b, s), b) end; directive = function(b,s) -- deal with renderer directives local _, cmd, args = b.words(2) @@ -546,11 +598,22 @@ if #(sec.blocks) > 0 then irs = {tag='section',attrs={id = getSafeID(sec)},nodes={}} for i, block in ipairs(sec.blocks) do local rd = irBlockRdrs[block.kind](block,sec) - if rd then table.insert(irs.nodes, rd) end + if rd then + if opts['heading-anchors'] and block == sec.heading_node then + stylesNeeded.headingAnchors = true + table.insert(rd.nodes, ' ') + table.insert(rd.nodes, { + tag = 'a'; + attrs = {href = '#' .. irs.attrs.id, class='anchor'}; + nodes = {type(opts['heading-anchors'])=='string' and opts['heading-anchors'] or '§'}; + }) + end + table.insert(irs.nodes, rd) + end end end elseif sec.kind == 'blockquote' then elseif sec.kind == 'listing' then elseif sec.kind == 'embed' then Index: makefile ================================================================== --- makefile +++ makefile @@ -1,12 +1,13 @@ lua != which lua luac != which luac -extens ?= $(patsubst ext/%.lua,%,$(wildcard ext/*.lua)) -extens_srcs = $(patsubst %,ext/%.lua,$(extens)) +extens = $(wildcard ext/*.lua) +extens_names ?= $(basename $(notdir $(extens))) -cortav: sirsem.lua cortav.lua $(extens_srcs) cli.lua +cortav: sirsem.lua cortav.lua $(extens) cli.lua + @echo ' ยป building with extensions $(extens_names)' echo '#!$(lua)' > $@ luac -o - $^ >> $@ chmod +x $@ cortav.html: cortav.ct cortav