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>
246 lines
15 KiB
Markdown
246 lines
15 KiB
Markdown
# 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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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
|
|
|
|
```console
|
|
$ 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:
|
|
|
|
```console
|
|
$ 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`).
|