Files
coursebank/docs/guide/glossary.md
T
alexmandClaude 7af1cd5b7e
Pipeline / check (pull_request) Successful in 13m38s
Pipeline / docs (pull_request) Skipped
Pipeline / nightly (pull_request) Skipped
Pipeline / release (pull_request) Skipped
fix(lecture): leave prerequisites off a lecture's pages
A target taught in one lecture can name a later lecture that builds on
it, and every page printed whatever named the lecture, so L4.2 opened
with five objectives from L3.2, L3.5, and L4.1. A lecture's objectives,
readings, and page now show an entry only when the lecture lists its
objective in teaches, or when no earlier lecture covers it. The
lectures: link is unchanged, so assembly, coverage, and the reports'
review lists still read it.

Reading prose that cites an objective or target from another lecture
now renders as its number on that lecture's page (L3.5's T 1) rather
than the target's full text. The trailing (T ...) list stays this
page's own.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 13:00:24 -05:00

15 KiB

Terms, equations, values, and misconceptions

Schema 2.1 gives a course four registries beside its objectives and targets: the terms students meet, the equations they use, the numbers they are taught, and the mistakes they commonly make. Each entry is defined once, keyed by id, and a target lists the entries it turns on. The lecture page, the course glossary page, and student reports are built from those lists, so a definition you correct in one place is corrected everywhere it is shown.

A 2.0 course needs none of this and loads unchanged.

The four registries

Registry Id prefix One entry is
terms term- a word or phrase, its one-sentence definition, and what the assigned texts call it
equations eq- a relation in LaTeX, what it says in words, its symbols, and what it implies
values val- a number as taught, the one wording every material uses for it, and its source
misconceptions mis- a belief students hold, in their voice, and its correction

After the prefix, an id is lowercase words joined by hyphens, like every other id in the course. Ids are unique across all six registries, objectives and targets included, so {term-gap} can only ever mean one thing. Ids are also join keys: renaming one orphans every target, option, and brace reference that names it.

A term:

terms:
  term-gap-penalty:
    term: gap penalty
    symbol: 'd'
    definition: 'The score subtracted for each position where one sequence is aligned against a {term-gap}.'
  term-decade:
    term: decade
    definition: 'A factor of ten in a concentration ratio or an equilibrium constant.'
    kind: coined
    textbook:
      - { term: order of magnitude, ref: KKW, locator: '§10.10' }
    variants: [decades]
    exam_wording: ten-fold

kind says whether a student can look the term up under this name: standard (the default), renamed (the course uses its own name for a standard idea), or coined. A renamed or coined term should give the textbook name, and a coined one the exam_wording that items write instead of the label, because an exam should not test vocabulary only your lectures use.

An equation, a value, and a misconception:

equations:
  eq-global-recurrence:
    name: the global alignment recurrence
    tex: 'F(i,j) = \max\begin{cases} F(i-1,j-1) + s(x_i, y_j) \\ F(i-1,j) - d \\ F(i,j-1) - d \end{cases}'
    says: >-
      The best score for the first i letters of one sequence against the first j of the other is the best of
      three moves into that cell.
    symbols:
      - { symbol: 'F(i,j)', meaning: 'the best score for aligning the two prefixes' }
      - { symbol: 'd', term: term-gap-penalty }
    implications:
      - { form: direction, statement: 'Raising {term-gap-penalty} makes the diagonal win more cells.' }
    assumes: ['Each gap position costs the same, whatever its neighbours.']
    fails_when: ['Gaps come in long runs, which a linear penalty charges too much for.']
    recall: true

values:
  val-per-decade:
    name: free energy per ten-fold concentration ratio at 37 °C
    value: 6
    units: kJ/mol
    say: about 6 kJ/mol
    exact: 5.9
    source: { ref: KKW, locator: '§10.10' }
    conflicts: ['5\.7\s*kJ', '5\.8\s*kJ']
    recall: true

misconceptions:
  mis-only-matches-count:
    belief: 'An alignment score counts the matching positions, so the alignment with the most matches scores highest.'
    correction: 'Every column counts: matches add, mismatches cost a little, and gaps cost more.'

An equation's implications are the things a question can ask about a relation without evaluating it, each in one of six forms: direction, limit, scale, dominant_term, held_fixed, or misuse. A value's say is the wording the lecture page, slides, and items all use, and its conflicts are regular expressions for the wordings that must not appear anywhere students read. recall: true means students are expected to know the value, so no item may print it.

Any entry may carry status: proposed, which a pipeline sets when it adds one; delete the line to approve it. Proposed entries are checked like any other, and coursebank lint counts how many are waiting.

Where entries live

An entry can be defined in three places:

File What goes there
objectives/*.yaml the entries an objective's targets are the first in the course to need
glossary.yaml cross-cutting entries, and whatever migrate glossary brought in, until each one is moved
course.yaml anything, for a course that keeps everything in one file

Lecture files and references.yaml cannot define entries. Wherever an entry is defined, it is course-wide: a target in any later lecture lists it by id, and nothing redefines it. The convention is the objective file whose targets first need the entry, and lint notes an entry that sits elsewhere (glossary-defined-elsewhere), without failing.

Targets point at entries

A target lists the entries it turns on, and says in one student-facing paragraph what meeting it looks like:

learning_targets:
  t-align-gap-penalty-effect:
    text: 'Predict how raising the gap penalty changes the optimal path through the matrix.'
    objective: lo-alignment-recurrence
    level_ceiling: 3
    explanation: >-
      A larger {term-gap-penalty} makes every horizontal or vertical step cost more, so the diagonal wins more
      cells and the optimal path uses fewer gaps.
    terms: [term-gap-penalty]
    equations: [eq-global-recurrence]
    misconceptions: [mis-only-matches-count]
    authoring:
      ceiling_item: 'Show the optimal path under d = 1 and ask which path wins under d = 4.'
      supplied: ['the two sequences', 'the optimal path under the lower penalty']
      relation_form: direction

The lists are what a lecture page draws its glossary sections from, and what decides each entry's first lecture: the first lecture, in teaching order, with a target that lists it. Teaching order is the course's own: lectures in id order, objectives in each lecture's teaches order, and an objective's targets by ceiling and then id. A term first needed in an earlier lecture appears on a later lecture's page as a link back, not as a new definition.

authoring holds the item-writing judgments that settle what a question at the target's ceiling looks like: ceiling_item, supplied data, constraints, number_work, examples, relation_form, and the evidence for the ceiling. It is for the item pipelines and for you; students never see it.

Other fields 2.1 adds

On Field What it does
objective description a short student-facing paragraph under the objective on the lecture page
lecture description the paragraph that opens the lecture page
lecture materials slides, briefs, notebooks, and other links, each {kind, url, title}
reading minutes the reading's length, summed at the top of the readings section
bank option misconception_id the registry misconception the distractor encodes
policy exam_conditions closed book or not, calculator, how equations are given, formats, seconds per item
policy blueprints named level counts, bonus counts, and minutes
policy levels the course's names for levels 1 to 5, used to label ceilings on the lecture page
policy target_text_forbid regular expressions that objective and target text must not match

An option's own misconception text, when it has one, still wins for that item. An option with only a misconception_id counts as designed, and its feedback is the registry's correction. exam_conditions and blueprints are stored and validated, but no command reads them yet.

Brace references

Student-facing prose can name an entry in braces, and every page that shows the prose renders the reference:

Reference Renders as
{term-gap-penalty} the term, linked to its definition
{eq-global-recurrence} the equation's name, linked to it
{val-per-decade} the value's say, such as about 6 kJ/mol
{mis-only-matches-count} the belief, in quotation marks
{t-align-fill-matrix} T 3, the target's number on the page, or the target's text where it has no number
{lo-alignment-recurrence} the objective's text

On a Quarto lecture page, a link points at the definition on the same page when it is there (a term new in that lecture, or an equation its targets use). Every other link points at the course glossary page: glossary.html, unless --glossary-href says otherwise. Braces that are not a prefixed id, such as 10^{59} or \text{final}, are left alone.

The fields that take references are the student-facing ones: definitions, says, implication statements, assumes, fails_when, corrections, objective and lecture descriptions, target explanations, and a reading's summary, focus, and skip.

What students never see

authoring, notes_private, evidence, conflicts, and status are instructor-facing. No lecture page, glossary page, student report, or student export (Canvas, the practice worksheet and its solutions, the site) prints them, and a test renders the example course through every one of those and checks. A proposed entry is shown to students like an approved one, without saying it is proposed.

Pages

$ coursebank lecture page l09 --out site/l09.qmd
$ coursebank lecture glossary --out site/glossary.qmd

lecture page writes, in order: the lecture's description; each objective with its description and its targets, each with its explanation and its ceiling named by policy.levels; the new terms; earlier terms, linked; the equations; the numbers to know; common mistakes; readings, with minutes; and materials. A lecture's pages show what it teaches, not what it builds on: an objective or target already covered in an earlier lecture is left off, even when it names this lecture in lectures:, unless the lecture lists its objective in teaches. lecture glossary lists every term alphabetically with its definition and first lecture, then every equation and value. Both write Quarto Markdown by default (numbered targets as (@) example lists, anchors as {#glossary-term-...}), or plain Markdown with --style plain.

Student reports gain two things. Each missed target shows what meeting it looks like, from its explanation. A chosen option with a misconception_id shows the misconception and its correction, and misses that share one across questions are grouped under it, so a student who made the same mistake three times reads about it once.

Checks

coursebank validate reports these as errors, each prefixed with the file that defines the entry:

Problem Message
an id lacks its registry's prefix term `x`: a term id is `term-` followed by lowercase words
an id is in two registries, or two files `x` is declared as both a, or is defined in two places
a target lists an undeclared entry target `t`: `terms` names `x`, which is not a declared term
an equation symbol names an undeclared term, or has neither term nor meaning equation `eq-x`: symbol `d`
a value has neither value nor range, its range runs backwards, or its term is undeclared value `val-x`:
a source, textbook, or evidence cites a key not in references …: source cites `KEY`, which is not in references
a brace reference does not resolve …: description refers to `{term-x}`, which is not a declared term
a conflicts or target_text_forbid pattern does not compile value `val-x`: conflicts pattern `…` does not compile
an option's misconception_id is undeclared option o-x: misconception_id `mis-x` is not a declared misconception

An unresolved {lo-...} or {t-...} in a reading's summary, focus, or skip stays a lint warning (glossary-unresolved-reference) rather than an error, because 2.0 accepted it.

coursebank lint adds fourteen rules in a glossary family:

Code Severity Flags
glossary-unused low an entry no target, equation symbol, value, or option needs
glossary-no-textbook-name medium a renamed or coined term with no textbook name
glossary-no-exam-wording low a coined term with no exam_wording
glossary-circular-definition low a definition that uses the term it defines
glossary-coined-in-item medium a coined term in an item's stem or options
glossary-value-unsourced low a value with no source
glossary-value-conflict medium a conflicts pattern that matches student-facing text or an item
glossary-forbidden-target-wording medium objective or target text that matches target_text_forbid
glossary-unlisted-term low an explanation that names a term its target neither lists nor inherits from a prerequisite
glossary-recall-value-printed medium an item that prints a recall: true value
glossary-equation-no-implications low a target at ceiling 3 or above that turns on an equation with no implications
glossary-unresolved-reference medium an old prose field that refers to an undeclared objective or target
glossary-defined-elsewhere note an entry outside the objective file whose targets first need it
glossary-proposed note how many entries are waiting for approval

A note is shown by default and never makes lint fail, so a course with proposed entries still passes a lint gate. --min-severity low hides notes.

Regular expressions use Rust's regex syntax, which has no look-around and no backreferences. target_text_forbid matches case-insensitively; conflicts matches as written.

From terms.yaml and values.yaml

A course that kept its terms and numbers in 1.0 side files brings them in with one command:

$ coursebank migrate glossary --terms terms.yaml --values values.yaml --dry-run
$ coursebank migrate glossary --terms terms.yaml --values values.yaml

Ids gain their prefix (decade becomes term-decade), course becomes term, meaning becomes definition, and a value's term: gains the prefix of the id it names. first and lectures are dropped, because 2.1 derives them from the targets that list an entry; the command reports each one that disagrees with what the targets now say, each entry no target lists yet, and each field 2.1 has no place for. The entries go into glossary.yaml, added at the end of its sections if it exists, with comments and quoting copied from the old files. The old files are left alone, and an entry the course already declares is skipped, so a second run changes nothing.

Linking targets to the migrated entries, and moving each entry into the objective file that first needs it, is then yours or a pipeline's to do; lint lists what is left (glossary-unused, glossary-defined-elsewhere).