throughline-transform

A throughline requirements graph on disk — committed or not — in the forms its readers open. One command, one file:

pipx install throughline-transform      # pulls tl along too

tl-transform md      -C idd             # Markdown, written by the tool itself
tl-transform notes   -C idd             # a folder of notes for Obsidian (zip)
tl-transform notes   -C idd --folder    # …or the folder itself, ready to open as a vault
tl-transform csv     -C idd             # one row per item, a links file, a file per cited source (zip)
tl-transform xlsx    -C idd             # the same as a read-only workbook that still sorts and filters
tl-transform docx    -C idd             # a Word document: title page, contents, a heading per item
tl-transform html    -C idd             # a print-ready page — print it to PDF from any browser
tl-transform assistant -C idd           # a folder an assistant that cannot run tl reads whole: one file per register, and how to answer

It is the command-line half of the throughline editor's export: the same six forms, laid out the same way, from the graph as it stands on your disk. The editor needs the graph on GitHub. This does not — it reads the working tree, and the output says whether that tree was clean, carried uncommitted changes, or was not under version control at all.

What it does not do

It never renders an item's words. The Markdown is asked of tl docs over a document of directives; the structure is read from tl dump. What this package adds is the containers — a workbook, a Word document, a folder of notes, a print-ready page — and the front matter and link syntax a note tool reads. If a requirement here rendered prose, it would drift from what tl docs --check gates, and a document that quietly differs from the published specification is worse than none. That is NG-0001.

It ships no PDF writer (NG-0002). Every browser prints to PDF with a renderer that is already on the machine.

It depends on nothing but the family. throughline alone (composition is the Tool's own since 3.11.1), and the standard library's zipfile for the two Office formats, which are written from their own specifications.

Which tool answers

Every graph is read through tl, which composes a graph that declares [[sources]] itself, so a borrowed clause is written with the reference number a conformance document exists to carry. The tool is found beside this package's interpreter first and on the path second, and is run as a command — its command line is the surface it publishes.

The outputs

Every output carries the repository, ref, commit, working-tree state and tool version it was taken from, because an output outlives the tree that made it and the first question anyone asks of one is what it was true of. A caller that knows them without git — the editor holds them from its clone — states them with --repository, --ref, --commit and --tree clean|dirty|untracked, and git is then not consulted.

--only UID[,UID…], given once or more, narrows any format to the items it names: the catalogue, table and matrices hold only those, the tables only their rows and the links between them, the notes only their notes, and the clauses mirrored are only the ones they cite. The output then says Items: n of N, because a partial document read as a whole one misleads. An identifier the graph does not hold is a usage error (exit 2), and nothing is written.

A quick run is silent. When a step — reading the graph, asking the tool to write the document, writing the file — has run for a second, one line on stderr says which, because a composed graph fetching its sources for the first time otherwise reads as a hang.

One implementation, two surfaces

The throughline editor runs this package as a wheel under Pyodide beside tl, so an export from a browser tab and an export from a terminal are the same bytes for the same graph at the same commit. Pyodide has no processes, so there the tool calls the console entry point tl declares in its package metadata — the same function the command runs — instead of spawning it.

Self-hosting

This repository's own requirements live under idd/ and compose throughline's graph as a pinned source, so a requirement here can cite the clause of the tool it reads (satisfies: tl:SR-0111) and have the citation resolved rather than asserted.

tl -C idd check --strict             # the grounding gate
tl -C idd docs --check               # idd/docs/spec.md must match the graph
tl-transform html -C idd             # and the tool over its own graph

Apache-2.0. Created by Dr Henry J Grech-Cini; see PROVENANCE.md.