References and citations¶

Every chapter keeps a curated, annotated bibliography: the papers, textbook sections, source files, official docs, talks and articles a learner should turn to, each with a sentence on why and when to read it. It is machine-readable, so ./course validate can check every citation and the website can build one global bibliography.

1. Files¶

chapters/NN-slug/references.yaml   the source of truth (you edit this)
chapters/NN-slug/references.md     GENERATED by `./course refs build NN` (commit it; never edit it)

./course validate warns when references.md is out of date, when an entry is malformed, and when a citation in the chapter's README.md, exercises.md or lessons/*.md does not resolve. The website renders the YAML directly, adds a "Cited in" line to each entry, and merges all chapters into the Bibliography page.

Lessons no longer carry their own reference lists: a lesson may end with ## References holding one line, See the [chapter references](../references.md)., or omit the section.

2. Format: `references.yaml`¶

format: pebble-refs/1
references:
  - key: CHK01                       # how lessons cite it: [CHK01]
    kind: paper                      # paper | book | survey | thesis | source | docs | talk | blog
    role: core                       # core (the chapter assumes you open it) | further (default)
    authors: [Keith D. Cooper, Timothy J. Harvey, Ken Kennedy]
    title: A Simple, Fast Dominance Algorithm
    venue: Software Practice & Experience 4
    year: 2001
    url: https://www.cs.rice.edu/~keith/EMBED/dom.pdf
    annotation: >
      The origin of the CHK algorithm Pebble implements. Read §2–3 after Lesson 15.1 §2: the
      intersect routine and the RPO argument are two pages; the timing tables in §5 back the
      "CHK beats Lengauer–Tarjan below ~30 000 nodes" claim.

  - key: EaC3
    kind: book
    authors: [Keith D. Cooper, Linda Torczon]
    title: Engineering a Compiler
    edition: 3rd ed.
    venue: Morgan Kaufmann
    year: 2022
    sections: "§9.2 (dominance), §9.3 (SSA construction)"
    annotation: >
      The clearest textbook treatment of iterative dominators and frontiers; read it before the
      papers if the lesson's proofs feel too compressed.

  - key: LLVM-GDTC
    kind: source
    repo: llvm/llvm-project
    tag: llvmorg-23.1.2
    path: llvm/include/llvm/Support/GenericDomTreeConstruction.h
    symbols: [SemiNCAInfo::runSemiNCA, SemiNCAInfo::InsertEdge]
    title: LLVM's Semi-NCA dominator tree construction and incremental updates
    annotation: >
      The production implementation behind `DominatorTree`. Read `runSemiNCA` after Lesson 15.1
      §7 and compare its `eval` with the lesson's path compression.

  - key: LLVM-LoopTerm
    kind: docs
    title: LLVM Loop Terminology (and Canonical Forms)
    version: LLVM 23.1.2
    url: https://releases.llvm.org/23.1.0/docs/LoopTerminology.html
    annotation: >
      The exact definitions LoopInfo implements (header, latch, exiting block, loop-simplify
      form, LCSSA); keep it open while doing the Lesson 15.7 exercises.

Fields¶

Field	Required for	Meaning
`key`	all	Unique within the chapter. Papers, surveys, theses, talks, blogs: author initials or first surname + two-digit year (+ `a`/`b` to disambiguate): `CHK01`, `Tar74`, `GTW06`. Books: a short mnemonic, e.g. `EaC3`, `Dragon2`. Source / docs: `PROJECT-Topic`, e.g. `LLVM-GDTC`, `GCC-Dominance`. Reuse the same key for the same work in every chapter (the global bibliography merges by key).
`kind`	all	One of the eight kinds below; it decides the group the entry is listed under.
`title`	all	The work's title (for `source`: a one-line description of the file).
`annotation`	all	≥ 40 characters: why a learner should read it and when (after which lesson/section, for which question). Say which part is worth it ("§3–4; skip the lower bound in §6").
`authors`	paper, book, survey, thesis, talk, blog	A list of full names.
`year`	paper, book, survey, thesis, talk, blog	Integer.
`venue`	paper, survey, thesis, talk	Journal/conference with volume/issue, publisher, institution + report number, or event name.
`sections`	book	The chapters/sections to read, e.g. `"§9.2–9.3, pp. 478–502"`. A book entry without sections fails validation: point the learner at pages, not at a 900-page volume.
`repo`, `tag`, `path`	source	`llvm/llvm-project`, `llvmorg-23.1.2`, repository-relative path. The site links to `https://github.com/<repo>/blob/<tag>/<path>`. Pinned versions: STYLE.md §8.
`symbols`	source (optional)	Functions/classes to look for. No line numbers.
`url`	docs, talk, blog	Stable URL (versioned docs for LLVM: `releases.llvm.org/<version>/docs/...`).
`doi` / `url` / `pdf`	paper, survey, thesis (one of them)	Prefer the DOI; add the authors' PDF as `pdf` when it is freely available. If none exists, add a `note` saying where to find it (e.g. "IBM Research Report; scanned copy in the Allen archive").
`edition`, `version`	optional	Book edition; docs/tool version.
`role`	optional	`core` = the chapter assumes you open it (every core entry must be cited somewhere in the chapter); default `further`.
`note`	optional	Anything else (errata, "the journal version fixes a bug in the conference version").

Kinds (and the heading each is listed under)¶

`kind`	Heading	Examples
`paper`	Foundational and research papers	the origin paper of every technique in the map; the paper behind each variant
`book`	Textbooks and monographs	Engineering a Compiler 3e, the Dragon book 2e, Appel, Muchnick, SSA-based Compiler Design, Nielson–Nielson–Hankin, Pierce's TAPL — always with sections
`survey`	Surveys and tutorials	e.g. Georgiadis et al.'s experimental studies; tutorial chapters
`thesis`	Theses and technical reports	PhD theses, TRs
`source`	Source code (pinned versions)	LLVM, GCC, rustc, Swift, V8, Cranelift, tree-sitter, ANTLR, Bison files
`docs`	Official documentation and specifications	LLVM LangRef, pass docs, GCC internals, language specs
`talk`	Talks and videos	LLVM Dev Meeting talks, conference videos (with URL)
`blog`	Blog posts and articles	engineering blogs — never as the origin of a technique

Minimum per chapter¶

A chapter's bibliography has at least 12 entries, including at least one paper, one book (with sections), one source and one docs. Every technique in the technique map has its origin paper. Talks and blog posts are welcome as extra reading when they add something (a production war story, a visual explanation). ./course validate checks the counts; the reviewer checks the quality (REVIEW_CHECKLIST.md step 6).

3. Citing in Markdown¶

Cite inline with the key in square brackets. On the website every citation becomes a link to the entry.

You write	Meaning
`[CHK01]`	one work
`[Geo05, GTW06]`	several works
`[LT79, §3]` or `[EaC3 §9.2]`	with a locator: `§`, `p.`/`pp.`, `Ch.`, `Theorem`, `Lemma`, `Fig.`, `Table`, `Alg.`
`Lengauer and Tarjan [LT79] show…`	textual citation

A bracket group counts as a citation when every part is a known key or a locator. A group that looks like an author-year key ([Tar74]) but isn't in references.yaml is reported as unresolved, so typos are caught. Other brackets ([A, t] in a table, [x] in a set) are left alone.
Don't cite inside code spans or fenced code (they are not scanned).
Source pointers in the running text still name the path and symbol (STYLE.md §8); add the source entry to the bibliography and cite it where the pointer appears: "SemiNCAInfo::runSemiNCA [LLVM-GDTC]".

4. Commands¶

./course refs build 15     # regenerate chapters/15-*/references.md from references.yaml
./course refs verify       # every chapter: references.md in sync with its YAML
./course validate          # + schema, minimum counts, citations resolve, core entries cited
./course serve             # see it on the website (chapter References page + Bibliography)