A manuscript in chapters

Keep a long document as one file per chapter, shared vocabulary in its own file, and a thin master that assembles everything in order. Adding a chapter costs one new file and two lines in the master.

master.wit
shared/schema.wit
shared/sources.wit
chapters/01-introduction.wit
chapters/02-conclusion.wit

Step 1 — Shared vocabulary

Put reusable templates in shared/schema.wit. None of these definitions has a ::body:: slot, so a use takes no body and needs no close: @chapter(1, Introduction) on its own line is complete.

~ shared/schema.wit

#cite(author, year): ::author:: (::year::) !!

#chapter(number, title)
(h2 Chapter ::number:: — ::title:: h2)
chapter#

#heading(title)
(h3 ::title:: h3)
heading#

#watermark: _Draft — not for distribution._ !!

Pin each idea to its source once in shared/sources.wit, so prose cites by idea:

~ shared/sources.wit

reference ./schema.wit

#weil_attention: @cite(Weil, 1952) !!
#berger_looking: @cite(Berger, 1972) !!

Step 2 — One file per chapter

Each chapter references the shared files and wraps its text in one block definition. The master decides where it goes.

~ chapters/01-introduction.wit

reference ../shared/schema.wit
reference ../shared/sources.wit

#chapter_one
@chapter(1, Introduction)

@heading(The problem)

Attention, as @weil_attention argued, is the rarest form of generosity.
chapter_one#

chapters/02-conclusion.wit has the same shape, defining chapter_two.

Step 3 — The master file

Reference the shared files and every chapter, add the metadata, then place the chapters in order. Each chapter definition has no body slot, so @chapter_one alone on a line is the whole use.

~ master.wit

reference ./shared/schema.wit
reference ./chapters/01-introduction.wit
reference ./chapters/02-conclusion.wit

#thesis: { title: Attention as a Moral Practice, author: T Greig, status: draft } !!

(h1 @thesis.title h1)

By @thesis.author

(if @thesis.status is draft)
@watermark
(end)

@chapter_one

@chapter_two

Step 4 — Build the master

wit build master.wit --fragment

Or -o thesis.pdf, or -o thesis.md — the CLI picks the format from the extension.

Result.

<h1>Attention as a Moral Practice</h1>
<p>By T Greig</p>
<p><em>Draft — not for distribution.</em></p>
<h2>Chapter 1 — Introduction</h2>
<h3>The problem</h3>
<p>Attention, as Weil (1952) argued, is the rarest form of generosity.</p>
<h2>Chapter 2 — Conclusion</h2>
…

The full worked version is examples/thesis in the repository.

Pitfalls

Giving a closeless use a body. @chapter_one More text. chapter_one@ is an error (E_BODY_WITHOUT_SLOT): the definition has nowhere to put a body. Add ::body:: to the definition if you want one.
A container definition needs its close. If a definition does have ::body:: — say #part(title) … ::body:: … part# — a use that opens a block must end with part@.

Variations

Gate a draft with a conditional on status, as above. Let every chapter add its own sources to one list — see A bibliography across files.