Multi-file documents & references

reference ./path.wit pulls another file's definitions and data into the document. Use it to split a thesis, manual or cookbook into chapter files that share one set of templates and sources.

The reference line

Put reference and a path on its own line. The path starts with ./, ../, / or ~/, or ends in .wit, and is relative to the referencing file. A line that merely begins with the word "reference" stays prose.

A referenced file contributes definitions and data, not its prose. So each chapter wraps its text in a definition, and the root file places it:

~ thesis.wit
reference ./chapters/intro.wit

(h1 @title h1)

@intro

~ chapters/intro.wit
#title: Tidal Memory !!

#intro
(h2 Introduction h2)
Coastal towns remember floods for about three generations.
intro#

<h1>Tidal Memory</h1>
<h2>Introduction</h2>
<p>Coastal towns remember floods for about three generations.</p>

One namespace

Everything from every referenced file shares one namespace, and visibility is transitive: if the root references A and A references B, the root sees B's definitions. Definitions are hoisted, so a use may come before the reference line that brings it in:

~ book.wit
The keeper is @keeper.name.

reference ./chapters/one.wit

~ chapters/one.wit
reference ../shared/people.wit

~ shared/people.wit
#keeper: { name: Aldous Vane } !!

That renders The keeper is Aldous Vane.

Shared files

Two chapters may both reference one shared schema or source list; it is loaded once. Additive entries (+#name) from every file collect into one list, each file contributing once — see Additive partials.

Errors

A missing file is E_MISSING_REFERENCE_FILE.
A cycle — including a file that references itself — is E_CIRCULAR_REFERENCE.
An error inside a referenced file is reported against that file.
Two files defining the same name is E_DUPLICATE_DEFINITION.

Common mistakes