Documents assembled from live pieces of other documents — not copies, but transclusions that maintain their bond to the source and update when the source changes.
A compound document is a document whose content is assembled from pieces of other documents. Each piece is a transclusion — a live reference to a span of text in another work, not a copy.
Think of it like a film editor's decision list (EDL): the final film is a sequence of clips, each pointing back to the original footage. The film IS the assembly — the clips aren't links, they ARE the content. If the original footage is recoloured, the final film reflects the change.
A compound Legal Brief assembled from three source works. Each coloured region is a transclusion — live content from another document, not a copy.
Imagine you're building a legal argument. You have three source works on your Xudanu server:
Your Legal Brief is a compound document — its content is assembled from pieces of all three sources, interleaved with your own analysis:
The Brief is one document whose content literally comes from four places: three transclusions (from Statute, Case Law, and Dissent) plus your own original text. If the Statute work is ever updated, the transclusion in the Brief resolves to the new content.
Create separate documents for each source. For the legal brief example, create "Statute", "Case Law", and "Dissent" with their respective texts.
Open the document you want to build into a compound (or create a new one). Click Build in the document toolbar. A three-panel layout opens: source pool on the left, your document in the center, and a structure outline on the right.
Click "+ Add source" in the left panel and pick a source document from your library. The source text loads in the lower-left panel. Add as many sources as you need — they stay open simultaneously.
Click a source to read its text. Select a passage (click and drag). An "Include passage" button appears at the top. Click it to transclude the passage into your document. The text appears in the center panel with a coloured background and source label.
Between transcluded passages, type your own analysis, commentary, or connecting text. The structure outline on the right shows which sections are [Original] vs [From: Source], giving you a live overview of the document's composition.
Check the structure outline to see how many sources you've drawn from and the ratio of original to transcluded content. Click "Done" to return to the normal editor. Your compound is saved.
To view the compound structure later, click the compound icon in the left rail to open the Compound Panel (read-only), or click Build again to continue assembling.
When a document contains transclusions, you'll see these visual elements:
Anatomy of a compound document: colour-coded transclusion regions with source labels, left-margin bars, a compound badge in the toolbar, and a toggle button.
Each source work gets one of eight colours, determined by a hash of the work ID:
| Colour | Hex | Background tint |
|---|---|---|
| Teal | #00897b | rgba(0,137,123,0.12) |
| Indigo | #5c6bc0 | rgba(92,107,192,0.12) |
| Orange | #f4511e | rgba(244,81,30,0.12) |
| Purple | #7b1fa2 | rgba(123,31,162,0.12) |
| Red | #c62828 | rgba(198,40,40,0.12) |
| Green | #2e7d32 | rgba(46,125,50,0.12) |
| Cyan | #00838f | rgba(0,131,143,0.12) |
| Amber | #e65100 | rgba(230,81,0,0.12) |
Hovering over a transclusion region (or its left-margin bar) shows a tooltip with:
A small button in the editor's filter row shows {"\u25A3"} N where N is the number of transclusion elements. Click it to toggle compound highlighting on or off. This is useful when you want to read the document without visual distractions.
When a document contains transclusions, a badge appears in the document toolbar: {"\u25A3"} 3 sources. This makes it immediately clear that the document is compound — you don't need to open the compound panel to know.
Xudanu provides two complementary tools for working with compound documents:
Click the compound icon in the left rail to open the Compound Structure panel. This is a read-only viewer showing:
[start:end]The panel includes a "Build" button that opens the full Compound Builder for adding new transclusions.
Click "Build" in the document toolbar (or the Build button in the Compound Panel) to open the three-panel assembly view:
See the Compound Builder Guide for detailed examples and stretch goals.
| Compound (Transclusion) | Link | |
|---|---|---|
| What it does | Makes foreign text appear inline in your document | Connects two passages with a typed relationship |
| Content changes | Your document's content changes when source updates | Neither document's content changes |
| Visual | Coloured background + source label | Coloured underline + margin bar |
| Provenance | Recursive chain via again() | One-hop provenance |
| Use when | You want the source text to BE part of your document | You want to reference or annotate a passage |
Xudanu's compound mechanism is architecturally different from Udanax-Gold's:
Gold stored compound spans in a separate side-table alongside the O-tree (two copies that could drift apart). Xudanu stores transclusions directly in the O-tree as RangeElement::Transclusion — a single source of truth.
CompoundSourceChanged events; the frontend also polls every 30 seconds as a fallback| Feature | Udanax-Gold | Xudanu |
|---|---|---|
| Storage model | Side-table (drift-prone) | Inline in O-tree (single source of truth) |
| Collaborative editing | Single-user | CRDT multi-user |
| Span migration | Manual | Automatic through arbitrary deltas |
| Live updates | Pull-based | Push + poll (CompoundSourceChanged event) |
| Recursive resolution | again() method | 32-level recursive with cycle detection |
| Lazy/template filling | PlaceHolder + FillDetector + Agenda | Not implemented (all resolution synchronous) |
| Federated resolution | Theoretical | Not implemented (future work) |
| Flatten/break transclusion | Not implemented | Not implemented (future work) |
RangeElement::Transclusion eliminates the dual-copy drift problem that plagued Gold's side-table architecture. This is a design not found in Gold or any other system.
PlaceHolder (unfilled slots), FillDetector (async fill events), and Agenda (crash-surviving background work queue). These would enable "living documents" that auto-assemble as content appears in the docuverse. Xudanu has stubs for these but doesn't implement them — all resolution is synchronous. This remains a future direction.