docs: schema 2.1 guide, codes, changelog, and report
A guide page for the four registries: where entries live, how targets point at them, the other new fields, the brace-reference table, what students never see, the lecture and glossary pages, every new error and lint rule, and the migration from terms.yaml and values.yaml. The setup guide points at it. The README covers glossary.yaml, the nine schemas, the 2.1 checks, the glossary lint family and the note severity, the new lecture commands and report sections, migrate glossary, and schema version 2.1. Module docs and the changelog follow. docs/design/2.1/CODES.md maps the specification's E, W, and I codes to coursebank's messages and lint codes, each with its test, and REPORT.md records what changed, the two remaining schema differences, every choice made where the specification left room, and suggested changes to it. A new test covers the validation messages the specification does not number. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
11 files changed
+535
-29
No files matched your search
@@ -0,0 +1,67 @@
|
||||
# Codes: the specification's placeholders, mapped onto coursebank
|
||||
|
||||
coursebank's validation errors are plain messages with no code, and its lint rules have kebab-case codes prefixed by family (`cue-`, `clarity-`, `complete-`, `pool-`, `evidence-`).
|
||||
The specification's codes map onto those as below.
|
||||
An error is identified by its message, which starts with the entry it is about in backticks, so `validate` can prefix it with the file that defines that entry.
|
||||
The message wording is stable: the tests in `tests/validate_2_1.rs` assert it.
|
||||
|
||||
## Errors (`coursebank validate`, exit 2)
|
||||
|
||||
| Spec | Message (`x` stands for the id) | Where | Test |
|
||||
|---|---|---|---|
|
||||
| E2101 | ``term `x` is defined in two places: A and B. An id has one definition site; delete one or rename it.`` (two files, one registry; the 2.0 message, now for the four new registries too) | `fragment.rs`, `duplicate` | `schema_2_1.rs`: `a_glossary_id_defined_twice_names_both_files` |
|
||||
| E2101 | `` `x` is declared as both a term and a value; an id is unique across all registries `` (any two of objectives, targets, terms, equations, values, misconceptions) | `glossary.rs`, `registry_id_problems` | `e2101_an_id_in_two_registries` |
|
||||
| E2101 (added) | ``term `x`: a term id is `term-` followed by lowercase words joined by hyphens, such as `term-…` `` (the schemas' `propertyNames` patterns, enforced at load since nothing validates YAML against the JSON Schema) | `glossary.rs`, `registry_id_problems` | `e2101_a_registry_id_without_its_prefix` |
|
||||
| E2102 | ``target `t`: `terms` names `x`, which is not a declared term`` (also when the id belongs to another registry) | `glossary.rs`, `target_link_problems` | `e2102_a_target_lists_an_undeclared_entry`, `e2102_an_id_listed_under_the_wrong_registry` |
|
||||
| E2103 | ``equation `eq-x`: symbol `d` names the term `term-y`, which is not declared`` | `glossary.rs`, `entry_problems` | `e2103_a_symbol_naming_an_undeclared_term` |
|
||||
| E2103 | ``equation `eq-x`: symbol `d` needs a `term` or a `meaning` `` | `glossary.rs`, `entry_problems` | `e2103_a_symbol_with_neither_term_nor_meaning` |
|
||||
| E2104 | ``value `val-x`: give a `value` or a `range` `` | `glossary.rs`, `entry_problems` | `e2104_a_value_with_neither_value_nor_range` |
|
||||
| E2104 | ``value `val-x`: range runs from 9 down to 1; write the low end first`` | `glossary.rs`, `entry_problems` | `e2104_a_range_that_runs_high_to_low_and_an_undeclared_term` |
|
||||
| E2104 | ``value `val-x`: term `term-y` is not declared`` | `glossary.rs`, `entry_problems` | the same test |
|
||||
| E2105 | ``term `x`: textbook cites `KEY`, which is not in references`` (also `source` on equations and values, `evidence` on misconceptions) | `glossary.rs`, `entry_problems` | `e2105_a_citation_key_not_in_references` |
|
||||
| E2106 | ``lecture `l09`: description refers to `{term-x}`, which is not a declared term`` (owner and field vary; every student-facing prose field) | `glossary.rs`, `brace_problems` | `e2106_a_brace_reference_that_does_not_resolve`, `e2106_a_new_field_checks_every_kind` |
|
||||
| E2106 (narrowed) | an unresolved `{lo-…}` or `{t-…}` in a reading's `summary`, `focus`, or `skip` is not an error but the lint rule `glossary-unresolved-reference`, because 2.0 accepted it (Q2, option b) | `lint/glossary.rs` | `e2106_an_old_reading_keeps_its_2_0_behaviour_for_targets`, `an_unresolved_target_reference_in_an_old_reading_field_is_a_warning` |
|
||||
| E2107 | ``value `val-x`: conflicts pattern `…` does not compile: …`` | `glossary.rs`, `pattern_problems` | `e2107_a_pattern_that_does_not_compile` |
|
||||
| E2107 | ``policy.target_text_forbid: pattern `…` does not compile: …`` | `glossary.rs`, `pattern_problems` | the same test |
|
||||
| E2108 | ``option o-x: misconception_id `mis-x` is not a declared misconception`` | `bank.rs`, `validate_item` | `e2108_an_option_names_an_undeclared_misconception` |
|
||||
|
||||
Errors the specification does not number, added because the schemas imply them (required, non-empty, or in a range) and the loader would otherwise accept the file:
|
||||
|
||||
| Message | Test (`tests/validate_2_1.rs`) |
|
||||
|---|---|
|
||||
| ``term `x`: empty term``, `empty definition`, ``textbook name N is empty``; ``equation `eq-x`: empty name`` (or `tex`, `says`), ``a symbol has no `symbol` ``, ``a direction implication has no statement``; ``value `val-x`: empty name``, `empty say`; ``misconception `mis-x`: empty belief``, `empty correction` | `empty_required_text_and_out_of_range_numbers_are_errors` (one of each kind) |
|
||||
| ``lecture `l09`: material 2 has no url``; ``lecture `l09` reading 1: minutes must be at least 1`` | the same test |
|
||||
| ``policy.levels: `7` is not a level; levels run from 1 to 5``; ``policy.blueprints: `module` counts items at `6`, which is not a level`` | `policy_levels_and_blueprints_are_keyed_by_level` |
|
||||
| ``policy.levels: level 3 has an empty name``; ``policy.blueprints: `module` gives no time; minutes must be above 0``; `policy.exam_conditions: seconds_per_item must be above 0` | `empty_required_text_and_out_of_range_numbers_are_errors` |
|
||||
|
||||
## Lint (`coursebank lint`)
|
||||
|
||||
Every 2.1 rule is in a new `glossary` family.
|
||||
|
||||
| Spec | Code | Severity | Test (`tests/lint_2_1.rs`) |
|
||||
|---|---|---|---|
|
||||
| W2101 | `glossary-unused` | low | `w2101_an_entry_nothing_needs` |
|
||||
| W2102 | `glossary-no-textbook-name` | medium | `w2102_a_renamed_term_with_no_textbook_name` |
|
||||
| W2103 | `glossary-no-exam-wording` | low | `w2103_a_coined_term_with_no_exam_wording` |
|
||||
| W2104 | `glossary-circular-definition` | low | `w2104_a_definition_that_uses_its_term` |
|
||||
| W2105 | `glossary-coined-in-item` | medium | `w2105_a_coined_term_in_an_item` |
|
||||
| W2106 | `glossary-value-unsourced` | low | `w2106_a_value_with_no_source` |
|
||||
| W2107 | `glossary-value-conflict` | medium | `w2107_a_value_variant_in_student_prose_and_in_an_item` |
|
||||
| W2108 | `glossary-forbidden-target-wording` | medium | `w2108_target_text_the_policy_forbids` |
|
||||
| W2109 | `glossary-unlisted-term` | low | `w2109_an_explanation_using_a_term_its_target_does_not_list`, `w2109_a_term_inherited_from_a_prerequisite_target_is_listed` |
|
||||
| W2110 | `glossary-recall-value-printed` | medium | `w2110_an_item_prints_a_recall_value` |
|
||||
| W2111 | `glossary-equation-no-implications` | low | `w2111_a_deep_target_on_an_equation_with_no_implications` |
|
||||
| (added) | `glossary-unresolved-reference` | medium | `an_unresolved_target_reference_in_an_old_reading_field_is_a_warning` |
|
||||
| I2112 | `glossary-defined-elsewhere` | note | `i2112_an_entry_defined_away_from_the_objective_that_first_needs_it` |
|
||||
| I2113 | `glossary-proposed` | note | `i2113_counts_proposed_entries` |
|
||||
|
||||
`note` is a new severity below `low` (Q3). Notes print by default, `--min-severity low` hides them, and `lint` never exits non-zero for notes alone (`notes_are_printed_but_do_not_fail_lint`).
|
||||
On the example course the glossary family reports exactly `glossary-unused` on `val-per-decade` and one `glossary-proposed` finding counting two entries (`the_example_draws_exactly_the_two_expected_glossary_findings`).
|
||||
|
||||
Two existing rules changed with 2.1: `complete-distractor-design` accepts a `misconception_id` as the distractor's design, and `complete-student-feedback` accepts a `misconception_id` that resolves, since the registry's correction is the feedback (`a_registry_misconception_designs_a_distractor_and_gives_it_feedback`).
|
||||
|
||||
## Regular expressions
|
||||
|
||||
`conflicts` and `target_text_forbid` use the Rust `regex` crate (1.x, `std`, `unicode-perl`, `unicode-case`).
|
||||
Its syntax matches Python's `re` for everything the examples use (`\b`, `\s`, `\.`, `\^`, `\{?`), and it has no look-around and no backreferences; a pattern that uses them fails E2107 with the crate's reason.
|
||||
`target_text_forbid` matches case-insensitively, as the prototype's `re.I` does; `conflicts` matches as written.
|
||||
@@ -0,0 +1,98 @@
|
||||
# coursebank 2.1: implementation report
|
||||
|
||||
Branch `schema-2.1`, six commits, one per phase, nothing pushed.
|
||||
Every phase ended with `cargo fmt`, `cargo clippy --all-targets -- -D warnings`, `cargo test`, and `cargo doc --no-deps` clean.
|
||||
The 2.1 work adds 57 integration tests (schema 7, validate 18, lint 19, render 8, migrate 5) and 14 unit tests, and every existing test still passes unchanged.
|
||||
|
||||
## What changed, by phase
|
||||
|
||||
| Phase | Commit | Files |
|
||||
|---|---|---|
|
||||
| 1. Types and schemas | `51a2fd2` | `src/model/course/glossary.rs` (new: every entry type, `RefKind`, the brace scanner), `src/model/course.rs` (the four registries, new fields on objectives, targets, lectures, readings, policy; `SCHEMA_VERSION = "2.1"`), `src/model/course/fragment.rs` (four sections, `Role::Glossary`, `glossary.yaml`), `src/model/layout.rs`, `src/model/item.rs` (`misconception_id`), `src/authoring/jsonschema.rs` (`Kind::Glossary` and every changed builder), `tests/schema_2_1.rs`, `tests/docs.rs` |
|
||||
| 2. Validation | `960cf6c` | `src/model/course/glossary.rs` (`glossary_problems`: E2101 to E2107 and the prefix check), `src/model/bank.rs` (E2108), `Cargo.toml` (`regex`), `tests/validate_2_1.rs`, `tests/common/mod.rs` |
|
||||
| 3. Lint | `b8fdf4d` | `src/authoring/lint.rs` (14 rules, `glossary` family; two existing rules accept `misconception_id`), `src/authoring/lint/glossary.rs` (new), `src/model/catalog.rs` (`Severity::Note`), `src/cli.rs`, `src/commands/project.rs` (notes never fail lint), `tests/lint_2_1.rs` |
|
||||
| 4. Derived data and rendering | `50a1e08` | `src/model/course/glossary.rs` (first use, teaching order, `expand_refs`), `src/export/lecture.rs` (`page_markdown`, `glossary_markdown`, brace rendering), `src/cli.rs` and `src/commands/lectures.rs` (`lecture page`, `lecture glossary`), `src/analysis/students.rs`, `src/export/report.rs`, `src/analysis/diagnostic.rs`, `src/export/typst/diagnostic.rs`, `src/export/typst/templates/student-report.typ`, `tests/render_2_1.rs` |
|
||||
| 5. Migration | `6c07122` | `src/migrate/glossary.rs` (new), `src/migrate.rs`, `src/cli.rs`, `src/commands/project.rs`, `tests/migrate_2_1.rs` |
|
||||
| 6. Documentation | this commit | `docs/guide/glossary.md` (new) and `src/guide.rs`, `docs/guide/setup.md`, `README.md`, `CHANGELOG.md`, module docs in `src/lib.rs`, `src/model.rs`, `src/authoring.rs`, `docs/design/2.1/CODES.md`, this file, one more test in `tests/validate_2_1.rs` |
|
||||
|
||||
The rendered example lecture page was sent as a private artifact in Phase 4.
|
||||
|
||||
## Code mapping
|
||||
|
||||
In `CODES.md`. In short: E2101 to E2108 are validation messages without codes, as every coursebank error is; W2101 to W2111 are the `glossary-*` lint rules; I2112 and I2113 are `glossary-defined-elsewhere` and `glossary-proposed` at a new `note` severity.
|
||||
Two additions: a prefix error next to E2101, and the lint rule `glossary-unresolved-reference` that takes E2106's place in 2.0 reading fields.
|
||||
|
||||
## Generated versus target schemas
|
||||
|
||||
The schemas are not generated from the Rust types: `src/authoring/jsonschema.rs` writes each one by hand with `serde_json::json!`, and that was the case before 2.1.
|
||||
So rule 2 became: port every edit in `build_schemas.py` into those builders, with the descriptions copied word for word.
|
||||
Hand-written JSON can say `propertyNames`, so the id patterns are in the schemas; the validator also enforces them, because nothing checks YAML against the JSON Schema at load time.
|
||||
|
||||
`tests/schema_2_1.rs` compares each of the nine generated schemas with `docs/design/2.1/schemas/` as JSON values. Two differences remain, both older than 2.1 and both one word:
|
||||
|
||||
| File | Path | Generated | Target |
|
||||
|---|---|---|---|
|
||||
| `calibration.schema.json` | `/properties/items/additionalProperties/properties/variants/items/properties/option_stats/description` | behaviour | behavior |
|
||||
| `course.schema.json` | `/properties/policy/properties/grade_scale/items/properties/group/description` | Colour | Color |
|
||||
|
||||
`schemas-original/` has the American spellings, which no commit in this repository ever had.
|
||||
I kept the code's spelling; a test fails if either difference disappears or another appears.
|
||||
|
||||
## What I did differently from the specification, and why
|
||||
|
||||
1. **Lecture files and `references.yaml` cannot define glossary entries.** The specification says any fragment may; the target schemas add the registries only to `course`, `objective`, and `glossary`, and I followed the schemas. A lecture file that tries gets the existing "a section belongs to a kind of file" error.
|
||||
2. **Teaching order is coursebank's: lectures in id order.** The prototype sorts lectures by `(date, id)`. The specification says to use the existing order, which is the lecture map's id order. They agree on the example.
|
||||
3. **E2106 on 2.0 fields (Q2, option b).** The four new prefixes are errors everywhere. An unresolved `{lo-…}` or `{t-…}` in a reading's `summary`, `focus`, or `skip` stays a medium lint finding, because 2.0 accepted it and rule 1 says no new errors.
|
||||
4. **Note severity (Q3).** `glossary-defined-elsewhere` and `glossary-proposed` are notes. `lint --min-severity` now defaults to `note`, and `lint` exits 2 only when something is above a note, so a course with proposed entries passes a lint gate.
|
||||
5. **`regex` crate (Q1).** Built without default features (`std`, `unicode-perl`, `unicode-case`). No look-around and no backreferences; such a pattern fails E2107 with the crate's reason.
|
||||
6. **The preview's `(T t-align-fill-matrix)` renders as `(T 3)`**, the target's number on the page, as 2.0's readings page always did. The prototype prints the raw id.
|
||||
7. **Three lines the preview does not have.** The page prints "About 40 minutes of assigned reading." above the readings, and each reading's `summary` and `skip`, which the 2.0 readings page prints and the specification's "readings (with minutes)" does not rule out. The snapshot test allows exactly these three.
|
||||
8. **Anchors are `glossary-<id>`**, such as `#glossary-term-gap`, not `#term-gap`. Quarto reserves the `eq-` prefix for numbered equations, so `{#eq-global-recurrence}` would be read as an equation cross-reference.
|
||||
9. **Report wording.** An option's own `misconception` text keeps its 2.0 sentence. An option with only a `misconception_id` prints "This answer reflects a common mistake: *belief*", then the correction. Misses sharing one are grouped under "The same mistake, more than once" with their question numbers. The registry belief and correction are student-facing by design, so they print without `--misconceptions`; the option's own text keeps that switch.
|
||||
10. **Two existing lint rules changed.** `complete-distractor-design` accepts a `misconception_id` as design, and `complete-student-feedback` accepts one that resolves, since the correction is the feedback.
|
||||
11. **`policy.exam_conditions` and `policy.blueprints` are stored and validated, but nothing reads them.** No phase asked for it. `assemble --blueprint NAME` reading `policy.blueprints` is a small follow-up.
|
||||
12. **More errors than E2101 to E2108.** Required text that is present but empty, a material without a URL, `minutes: 0`, level keys outside 1 to 5, and non-positive durations. They follow from the schemas, cannot fire on 2.0 data, and are listed in `CODES.md`.
|
||||
13. **Proposed entries look approved to students.** Nothing on a student page says "proposed"; the rule-5 test checks the word never appears.
|
||||
14. **The example needed one edit.** The bank item had no `status`, which coursebank requires; I added `status: draft` with a comment. With `approved`, validation would also require `cognitive_process`, `sources`, and `design`.
|
||||
15. **The value `say: 'about 10^{59}'` renders literally**, caret and braces, because `say` is printed as written and the example does not put it in math markup.
|
||||
16. **The prototype was read, not run.** `pyv` has no vendored PyYAML on this machine, so `check21.py --selftest` could not run. Each self-test mutation became a test, built by reading the prototype.
|
||||
17. **Migration details the specification leaves open:**
|
||||
- a value's `term:` gains the prefix of the id it names, and is reported;
|
||||
- fields 2.1 has no place for are dropped and reported;
|
||||
- an existing `glossary.yaml` is added to as text, never rewritten;
|
||||
- entries declared anywhere in the course are skipped, so a second run is a no-op;
|
||||
- an id that would be invalid with its prefix, two entries that would share an id, and an id another registry already uses are refused before anything is written;
|
||||
- an entry written as a flow mapping is written by the serializer instead of copied.
|
||||
|
||||
On the example, `coursebank lint` reports the two expected glossary findings and one existing finding: `cue-absolute` on option `o-length`, which says "always".
|
||||
|
||||
## Running the migration on your course
|
||||
|
||||
From the course root, with the 1.0 files wherever they are:
|
||||
|
||||
```console
|
||||
$ coursebank migrate glossary --terms terms.yaml --values values.yaml --dry-run
|
||||
$ coursebank migrate glossary --terms terms.yaml --values values.yaml
|
||||
$ coursebank validate
|
||||
$ coursebank lint --only glossary-unused,glossary-defined-elsewhere,glossary-proposed
|
||||
```
|
||||
|
||||
The dry run prints the report and the file it would write.
|
||||
The report lists renamed ids, every dropped `first` or `lectures` that the targets now contradict, entries no target lists yet, and fields dropped.
|
||||
Before you link any targets, every entry will be under "no target lists these yet", and every old `first` and `lectures` will be reported as contradicted, because nothing lists the new ids yet.
|
||||
`terms.yaml` and `values.yaml` are left in place.
|
||||
Then add the ids to each target's `terms` and `values`, and move each entry into the objective file that first needs it; `glossary-defined-elsewhere` names those files.
|
||||
|
||||
## Suggested changes to the specification
|
||||
|
||||
1. Say which fragments may define entries: objective files, `glossary.yaml`, and `course.yaml`, as the schemas already do, rather than "any fragment".
|
||||
2. Define teaching order: lectures by id or by date. The prototype and the spec's "existing order" differ for a course whose lecture ids do not sort by date.
|
||||
3. Write down E2106's exemption for 2.0 reading fields, so rule 1 and E2106 do not contradict each other.
|
||||
4. Define the I-codes' effect on exit status: shown, never failing.
|
||||
5. Say whether `say` is plain text or markup. If markup, the example should write `about $10^{59}$`.
|
||||
6. Give the anchors a prefix of their own (`glossary-`), and note that Quarto reserves `eq-`, `fig-`, `tbl-`, and `sec-`.
|
||||
7. Make `lecture-page-preview.md` print target numbers (`T 3`) rather than raw ids, and decide whether a reading's `summary` and `skip` belong on the page.
|
||||
8. Add `status:` to the example bank item, since coursebank requires it.
|
||||
9. Name the regular-expression dialect as the subset Python's `re` and Rust's `regex` share: no look-around, no backreferences.
|
||||
10. In the migration table, add a value's `term:` (prefix it) and say what happens to unknown fields and to an existing `glossary.yaml`.
|
||||
11. Decide whether `policy.blueprints` should feed `assemble`, and say so; today it is data with no reader.
|
||||
@@ -0,0 +1,244 @@
|
||||
# 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.
|
||||
`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`).
|
||||
@@ -208,6 +208,12 @@ stimuli:
|
||||
Items reference it with `stimulus: s-dock-poses`.
|
||||
Declaring it here rather than pasting it into four items means a correction to the table happens once.
|
||||
|
||||
### Terms, equations, values, and misconceptions
|
||||
|
||||
Four more registries hold what students study from besides the objectives: the terms they meet (`term-`), the equations they use (`eq-`), the numbers they are taught (`val-`), and the mistakes they commonly make (`mis-`).
|
||||
Each is defined once, in the objective file whose targets first need it or in a `glossary.yaml` beside `course.yaml`, and targets list the entries they turn on.
|
||||
They are optional, and [`glossary`](crate::guide::glossary) covers them, the lecture pages built from them, and the migration from 1.0 `terms.yaml` and `values.yaml`.
|
||||
|
||||
## Check it
|
||||
|
||||
```console
|
||||
@@ -229,6 +235,7 @@ Exit codes are meaningful.
|
||||
|
||||
## Where to go next
|
||||
|
||||
[`glossary`](crate::guide::glossary) adds terms, equations, values, and misconceptions, and builds lecture pages from them.
|
||||
[`authoring`](crate::guide::authoring) writes the first bank.
|
||||
[`first_exam`](crate::guide::first_exam) takes an exam from blueprint to student report.
|
||||
|
||||
|
||||
Reference in new issue
Block a user