What this page is #BNH91U

The wiki is a set of Org files, and Org is pleasant to write in Emacs but awkward to read anywhere else. This page records how the wiki becomes a browsable static site, why the build is expressed in ASDF, and what the Org-subset reader deliberately does and does not understand. It is a design page for luv-wiki, the Lisp system in wiki/org.lisp, wiki/html.lisp, and wiki/asdf.lisp, and for the corpus system luv-wiki-site in luv-wiki-site.asd whose components are the pages themselves.

The rendered site lives at mbrock.github.io/luv once the Pages workflow in wiki.yml has run; locally, make wiki writes it to build/wiki/. Besides the pages it carries a figure index and, per #58SVCM, the whole source of the repository's four primary system families as browsable dexp pages.

Why ASDF, and how the wiki slots into it #RYHRUL

ASDF describes itself as a tool that "plays a role like make or ant" for Lisp systems, and it warns that it is not a general installer. Underneath, though, its model is not Lisp-specific: a component has input files, an operation applied to a component has output files, perform does the work, and the plan is a dependency graph over (operation, component) actions with timestamps. The manual invites extension by subclassing operation and component and defining perform, input-files, output-files, and component-depends-on methods. cffi-toolchain uses exactly this to compile .c files: a c-file component whose compile-op outputs an object file.

The wiki fits the same shape, and more naturally than a fresh script would:

• An org-file is a component of the luv-wiki-site system. Its load-op reads the page into a document object and remembers it on the component, so "loading the wiki" means having the corpus in the image as inspectable Lisp objects, which is where the figure vocabulary of #F2N8VX wants to go anyway. org-file inherits from static-file, so the ordinary compile-op is a no-op and dependency propagation works unchanged.
• render-op is a downward, selfward operation: rendering the system renders each page; rendering a page first loads it and, because #ABC123 mentions and backlinks cross pages, also depends on the load of the whole system. Every page's input-files are all the pages, so any edit re-renders the site; ASDF's timestamps make an unchanged corpus a no-op.
• The site is a build product, not a fasl. output-files returns its second value true, which ASDF documents as "do not translate," so pages land in build/wiki/ rather than the compiled-file cache. A static-file such as an image is copied by the same operation; the stylesheet is compiled from Lisp definitions (#UODI74) by the system's own render.
• :build-operation "luv.wiki:render-op" makes (asdf:make :luv-wiki-site) build the site, matching how luvcraft is built.

Two ASDF details are worth remembering. defsystem-depends-on cannot name a system defined in the same .asd file (ASDF reports a circular define-op), so the tooling is the primary system luv-wiki in its own file and the corpus is the primary luv-wiki-site system in another. Class names in a defsystem can be given as strings such as "luv.wiki:org-file", which ASDF reads in its own package; that avoids interning anything into ASDF's package, which the manual asks extensions not to do.

Capture recipes are source; captured media is a cache #IVRWI8

Pictures that carry design evidence should be reproducible without making Git the video store. capture-specification is the semantic boundary: a stable name, wiki figure ID, media kind, extension, description, and an ordinary named renderer function. define-capture is only a thin definition-site macro over that object and function. The body may assemble a gazetteer world, borrow an atelier camera flight, or set up a focused agent interaction; it still ends in the renderer which already owns those things.

The deterministic filename joins figure and recipe, for example Y7X7WK-construction-proposal-still.png. A bare [[capture:Y7X7WK-construction-proposal-still.png]] paragraph transcludes it from media/; MP4 and WebM links become native, muted, looping video figures. The HTML build does not require the bytes to exist. This is important: prose and recipes remain cheap and portable, while a local build without the artifact has an honest missing image rather than silently substituting stale evidence.

capture-op makes (asdf:make :luv/showcase) render the registered set into build/wiki/media/, which is already under the ignored build/ tree. Each run also writes a small manifest naming the source revision and every figure, recipe, kind, and filename. scripts/captures list discovers the set and scripts/captures render can select a few recipes during iteration. Captures announce progress because shader compilation, readback, and video encoding are real GPU work, not a reason for a silent build.

Execution placement is deliberately outside this graph. A GPU worker runs the same command through SSH, but its hostname and checkout path are deployment configuration, never recipe data. Git annex is likewise a publication cache, not part of capture identity: the web host explicitly obtains each annexed file before Caddy serves it. A pointer alone is never mistaken for a browser artifact.

Mentioned in: The showcase is an atlas with three lanes, Publish generated media out of band

The Org subset the reader understands #NS35X9

The reader is not a general Org parser. It reads the subset the wiki actually uses, chosen by surveying the pages: #+title, headings with property drawers, paragraphs, bulleted and numbered lists with wrapped and blank-separated items, example and src blocks, simple tables with an optional header rule, TeX math as $x^2$ or \(...\) inline and \[...\] or $$...$$ on display (drawn by KaTeX, loaded only when a page has math), Mermaid diagrams in #+begin_src mermaid blocks (likewise), bracket links with file:, https:, id:, lisp:, capture: or no scheme, a bare file: link to an image in the wiki directory as an inline image (a paragraph of only that link becomes a figure, and a paragraph of only a lisp: link becomes the definition it names), a bare capture: image or video as ignored generated media under build/wiki/media/, the light #ABC123 mention, and the six emphasis markers with Org's pre- and post-character rules. Anything else stays paragraph text, so an unfamiliar construct can never fail the build; it can only render plainly.

Emphasis rules follow Org: a marker opens only after whitespace or an opening bracket and closes only before whitespace or punctuation, so 2 * 3, foo_bar, and ../src/ are text. Verbatim and code keep their contents raw. Emphasis may cross one line break but not a blank line. Headings whose title starts with one of the work-mark words of #W3K9MK carry that word as a keyword and render with a status badge.

The element model is CLOS: document, heading, paragraph, plain-list, list-item, example-block, src-block, and table at the block level; emphasis, link, and mention inline, with plain strings for text. render-html is a generic function over those classes, so a new element is one class and one method. reference-id is the small protocol that lets both mentions and id: links count as references when the site indexes backlinks.

The reader was written rather than borrowed. deepfire's cl-org-mode (2018, built on parser-combinators) parses headline, drawer, and block structure but leaves section bodies as text and has no inline layer, links, lists, or HTML output, so it would have supplied perhaps a hundred lines and cost two dependencies and a second parser for the inside of sections. Its layered raw-AST/dressed-object design is a good precedent for the shape used here.

Spinneret as the HTML layer #VRKEYI

Spinneret's with-html compiles keyword forms to tags and passes the value of every other body form to its exported generic spinneret:html. Three consequences shaped the renderer:

• ecase inside with-html is misread, because its clause heads look like tags; a small kind-to-tag table with :tag :name is used instead.
• The pretty printer fills text and buffers a space after each write, so a dynamically written "figure" came out as "figure " inside its <b>; output is written with *print-pretty* off and *suppress-inserted-spaces* on, and rendering methods return no values so Spinneret has nothing to space.
• A bare string at the top of with-html is returned, not printed, so text is written explicitly with spinneret:html.

Mentions carry their target with them: each page embeds a small card per figure it mentions (title, page, status, opening prose) and per definition it links (kind, name, lambda list, file and line, docstring), and a few lines of script in site.js show the card as a top-layer popover beside the link on hover, focus, or a first tap, placed below the link or above it when the viewport is short. The same script loads KaTeX and Mermaid from a CDN only for pages that carry math or diagrams. The site stays static and the links stay plain links.

Each page is one HTML file: a header linking to the index and the page's Org source on GitHub, an <h1> from #+title, and a <section> per heading whose id is the figure ID, so page.html#ABC123 is the figure's stable address. Mentions become links with the target's title as a tooltip; dangling ones are struck through. Each figure that is mentioned elsewhere ends with a "Mentioned in" line, the disposable backlink index that #F2N8VX anticipates. A figures.html page lists every figure by page with its work-mark status.

The wiki from a shell: scripts/wiki #GB4FT0

Agents and people who want the table of contents, the work marks, one figure's text, or the places a figure is mentioned should not need Emacs or a browser. scripts/wiki is a small executable built with ASDF's program-op (system luv-wiki/cli, entry point luv.wiki.cli:main, build/wiki-cli), rebuilt by its wrapper when the tooling changed and run inside the Nix shell. It reads the same objects the site renders — pages through the Org reader, code through the Eclector index — so what it prints agrees with the site. Commands: toc, marks, figure, page, mentions, defs, dangling, ids, build; help lists them.

Three details of the executable are worth recording. The Nix sbcl wrapper supplies CL_SOURCE_REGISTRY and ASDF_OUTPUT_TRANSLATIONS to SBCL processes only, so a dumped image would look for compiled files in the wrong place; wiki/build.lisp captures that environment before the dump and main re-establishes it. The build command registers luv.asd, luvcraft.asd, luv-wiki.asd, and luv-wiki-site.asd before asking ASDF to render, so the source browser sees every component tree without loading the GPU, game, or native systems. make wiki uses that command rather than a partial fresh image that knows only the two wiki ASD files.

A fluid dual system: code contributes to the wiki #F6B3NI

The wiki does not want to become Lisp forms; Org in Emacs is the better writing surface, and the reader already gives the corpus to Lisp as objects. The interesting direction is the reverse flow: the code contributing to the discourse where that is more natural than prose, with less text and more references and examples. Two facts make that cheap.

Figure IDs are already valid, readable symbol names, and index.org anticipated a WIKI package of them (#F2N8VX). And code already mentions figures: the interpret-quantity-specification docstring in arithmetic/semantics.lisp cites #PLRP3A and the tests in arithmetic/tests.lisp cite #LNRY72 as the table they check. Nothing yet sees those mentions. Three rungs, cheapest first:

• The site sees code. render-op asks ASDF for the cl-source-file components of the luv systems (pathnames only, no loading), scans them for #ID mentions, and each figure gains a "Referenced from" line beside "Mentioned in", linking to the source line on GitHub. Backlinks then span discourse and code, which is the point of string figures.
• A WIKI package. load-op interns and exports each figure ID into WIKI and hangs the heading off the symbol as documentation or a property. The figure index becomes the package: apropos, completion, and CLIM accept work on figures. A no-op macro (wiki:ref LNRY72) is macroexpanded, so who-macroexpands finds every code reference, and it can note (sb-c:source-location) at compile time into the same table the scanner fills, with plain text as the fallback so the site never depends on the whole system compiling. A symbol should mean only an identity; the heading is resolved late through the index, never stored in code.
• The reverse direction. Wiki prose naming a Lisp symbol could resolve to a definition location when the system is loaded, which is what a McCLIM browser does natively with a symbol presentation and an Edit Definition translator. Do it there first.

The 2021 "chronicle" experiment, dummy macros over dated todo, hmm, done entries so xref finds notes embedded in source, is the same shape as work marks with the status words renamed; what it adds is the reminder that symbols in a package are the identity mechanism and that macroexpansion is free cross-referencing.

Mentioned in: The site shows code references to figures, A WIKI package of figure symbols

The model a McCLIM browser wants #AGTIO4

The loaded documents on the org-file components are already the browser's data source. What the element model still lacks is small and each piece is motivated by a browser affordance:

• figure and work-mark as classes decided at read time, so presentation types map onto classes one to one and each needs one present method.
• Parent links and source line ranges on elements, for "which figure am I in", an Edit Figure command that jumps Emacs to the Org line, and HTML source links that point at the line.
• Mentions stay IDs, not object pointers; the site or index resolves them.
• A second renderer, not a second traversal: when a CLIM presenter exists, render-html should become (render backend element) dispatching on the relationship, with html and clim backends over one model. Two consumers justify that; one does not.

The live loop is then: edit Org in Emacs, (asdf:load-system :luv-wiki-site) re-reads only the changed page, the browser redisplays. Mentions become presentations that jump on click and offer backlinks on right-click; the shader lab's presentation types could accept a figure to attach it to a definition.

Mentioned in: Dexp on McCLIM, A wiki browser frame in mcluv

Code views: a dexp renderer for Common Lisp #N06GKK

Source links that leave the page for GitHub are a poor reading experience, especially on a phone. The wiki should show code in place, and the way it should show it comes from wisp's structure editor, whose "dexp" renderer draws Lisp as nested boxes rather than text with indentation:

The mechanism is small and, since flexbox does the work, responsive for free. Every cons is a div.list with display: flex; flex-wrap: wrap and a small column gap; atoms are inline spans. Forms flow horizontally while they fit and wrap when they do not, so there is no line-breaking logic anywhere. The parentheses are the box's own left and right borders with rounded corners, so a wrapped list becomes a bracket around a paragraph of code, and depth is visible as nesting rather than indentation. Structure is carried in attributes, data-callee on the list and data-package and data-symbol-name on symbols, and CSS does the rest: body forms of defun or let take full width so they stack; quote, backquote, and unquote hide their symbol and paint ', `, and , with ::before; keywords get their colon the same way; the current package's prefix is hidden; the head of a list is coloured by :first-child with no separate classification pass. Ordinary prose text and code then share one flowing layout, which is what a wiki wants.

Two things change in the Common Lisp version. Dexp renders sexp data, so comments and original formatting are gone; the wiki shows source definitions and needs a reader that keeps them, see #SKNK2N. And dexp keeps per-operator layout in CSS selectors that cannot see method qualifiers or lambda-list keywords; the wiki renderer should assign roles in Lisp, using the same table the parinfer checker already keeps in parinfer/implementation.lisp (*binding-form-heads*, *clause-form-heads*, child-role), and emit class"head"= or class"body"= so the stylesheet needs only .list > .body { width: 100% }. Everything else transfers verbatim: side borders as parentheses, quote glyphs, keyword colons, home-package hiding, head colouring, and ; comments as full-width children.

The same renderer serves three places: the "Referenced from" backlinks of #PF39II, where a figure's code references expand in place; a lisp: link protocol, [[lisp:luv.arithmetic:interpret-quantity-specification]], that resolves against a definition index and shows the definition; and the wiki's own #+begin_src lisp blocks, which are read and drawn structurally with the <pre> as fallback whenever reading fails. A paragraph consisting only of a lisp: link becomes the definition itself, drawn from luv's source at build time:

Inside a definition, #ID mentions in strings and comments are links to their figures, so the loop closes: the docstring above points back at #PLRP3A, and that figure lists this definition under "Referenced from code".

Mentioned in: The site shows code references to figures, The dexp HTML renderer

Layouts are objects chosen by operator and role #BGIM3I

The first renderer assigned layout with a table of head counts and a growing set of role strings and special cases; let bindings drawn as a two-column grid, loop keywords starting rows, and lambda lists whose sublists are (var default) clauses made that untenable. The design that replaced it follows clos-design: a layout is an object, and a list is drawn by the layout that its operator and the role its parent gave it select together (dispatch on the relationship, not on one participant).

• list-layout (list role) chooses: a child the parent called bindings gets a grid-layout whatever its first element; lambda-list gets a lambda-list-layout; clause or stacked-clause their clause layouts; otherwise the operator's own layout from a small table (define-layout), with with-=/=define-=/=def naming conventions as the default and flow-layout last.
• child-role (layout list index child) answers the role of each argument (comments are drawn where they occur and never counted): body-layout stacks after a head count, bindings-layout marks the binding list, variables-layout (multiple-value-bind) marks a variable list, spec-layout (dolist, with-open-file) marks one clause, lambda-layout and method-layout find the lambda list, clauses-layout (cond, case, handler-case, defstruct) makes body forms stacked clauses, grid-layout makes children clauses, loop-layout gives loop keywords row-start.
• render-layout (layout list) draws: the general routine with roles, or a clause's name and .rest cell so a grid can align columns.

Hand-written layouts are only hints for the standard forms whose lambda lists say too little (let, cond, defmethod, loop). For everything else, luv's own macros above all, the layout is derived from the real lambda list, the way SLY's slynk-indentation derives indentation from macro arglists: scripts/wiki introspect loads the systems, resolves every operator symbol the corpus uses against its file's in-package, records its kind and sb-introspect:function-lambda-list, and writes arglists.sexp, one readable form per operator, keyed by home package (2151 operators today). From such a lambda list a derived-layout knows that what precedes &body is the head, that a destructuring pattern in a position makes that argument a clause (with-block-content-storage ((domain palette indices) chunk &body body)), that &key marks where pairs begin, and, from SBCL's own parameter names, that BINDINGS, DEFINITIONS, or SLOT-SPECS mean a binding grid and LAMBDA-LIST or VARS a lambda list. The file is committed, so the site renders without loading luv, and it is among render-op's inputs; run the pass again after adding or changing macros.

Two rules apply across layouts. A trailing run of :keyword value arguments is drawn pair by pair in a .pair container that never breaks between key and value; where the pairs are body forms, as in the options of a definer, each pair is a row with the keys aligned, so define-unit and define-quantity read as small tables. And an operator known only by its def prefix is inspected rather than assumed: a list in second position makes it a lambda form, anything else a name followed by options.

The stylesheet knows only roles: a list with body forms is .stacked, a grid of rows with the head in a .head span (#993QQQ); .bindings is a CSS grid, its .clause children subgrids spanning two columns; a .clauses form is a two-column table of .stacked-clause rows (#4175NC); .rest a cell, .pair an inline unit, .break a zero-height row break before a row-start. The rules live beside the layouts, as style definitions (#UODI74). Adding a form's layout is one define-layout line or one class with two methods, and nothing else changes.

Mentioned in: Clauses as tables: cond, case, typecase, handler-case, The dexp HTML renderer

Reading source without loading it: Eclector #SKNK2N

The site is built by luv-wiki, which does not and should not load luv itself; the Vulkan and SDL systems have no business in a documentation build. So definitions must be read from files without interning their symbols or evaluating anything. Eclector is the ally here: a portable Common Lisp reader whose client protocol lets interpret-symbol return a token (package prefix, name, and whether the package is the file's current one) instead of interning, whose parse-result protocol yields source ranges for every object, and which reports skipped input, comments and #+ branches included, as results too. It reads #', #p, #(, ,@, and reader conditionals correctly, which a hand-rolled tokenizer would not; parinfer's tokenizer is deliberately a repair heuristic and stays that.

Reading with Eclector gives a definition index beside the figure index: for every cl-source-file in the registered luv systems' component trees, each top-level form with its kind, name, qualifiers or specializers, file, line range, comment text, and the #ID mentions inside it. Figures ask it who references them; lisp: links ask it where a name is defined; the McCLIM browser can present it directly. Reader conditionals and #. are rendered as visible tokens, never evaluated.

Platform availability belongs to ASDF's :if-feature metadata, not to a #+darwin conditional around the defsystem form. ASDF therefore registers the Objective-C and Metal systems and constructs their component trees on Linux, while their compile and load actions remain invalid there. The wiki deliberately walks those complete trees rather than ASDF's active sub-components, so a Linux documentation build renders the Darwin sources without loading them. Individual files such as the Cocoa canvas helper use the same component-level :if-feature convention.

Mentioned in: Code views: a dexp renderer for Common Lisp, Dexp on McCLIM, The site shows code references to figures, Read luv sources with Eclector into a definition index

Dexp on McCLIM #CEON0R

The token tree from #SKNK2N is a model, like the Org elements, and can be drawn by more than one backend. In McCLIM the natural rendering is the same idea in a different medium: a list is an output record with a rounded border, its children laid out by formatting-item-list or a small flow layout, symbols are presentations of a lisp-symbol type with translators to Edit Definition and to the wiki figures that mention them. Since McCLIM is meant to become a significant part of the 3D world's own interface, a dexp view of live definitions inside luvcraft is not far-fetched. As with the wiki browser, the HTML backend should come first and the CLIM one should drive the (render backend element) refactor of #AGTIO4.

Browsing the whole source from the wiki #58SVCM

Once every source file is read into nodes, showing all of it is one more render. Each Common Lisp file owned by the five root ASD files -- luv, luvcraft, mcluv, luv-wiki, and luv-wiki-site -- becomes a page under source/, drawn entirely as dexp boxes: a table of its definitions on top, every top-level form anchored by its starting line (#L956), the file's in-package hiding that package's prefix, comment blocks kept as one box each. source.html lists the files by system; on a wide screen a source page keeps a sidebar of the systems and their files on the left, the current file's system open, and the status bar reads as a breadcrumb trail (Source › system › file; on wiki pages Pages › title). The reference graph runs both ways through these pages: any symbol that names a definition anywhere in the corpus links to that definition (a defining form is preferred over a method), "Referenced from" summaries and lisp: links point at the local page with GitHub as a secondary ↗, and #ID mentions in docstrings and comments point back at the wiki. Source pages use a wider column than prose, and since dexp needs no monospace alignment the boxes are set in the system sans-serif.

Docstrings, :documentation strings, any multi-line string, and comment blocks are not code and are not drawn as code: their content goes through the same reader as wiki prose and comes out as paragraphs and lists set in the prose face inside the box, with #ID mentions and verbatim markup live. One rule differs from Org: in code prose *name* without spaces is a special variable and reads as code, not bold.

This is the reading surface for keeping up with the codebase: the pages are regenerated by render-op whenever a source file changes, since the files are among its inputs.

Mentioned in: What this page is, Browse the source as dexp pages