fix(lecture): leave prerequisites off a lecture's pages
Pipeline / check (pull_request) Successful in 13m38s
Pipeline / docs (pull_request) Skipped
Pipeline / nightly (pull_request) Skipped
Pipeline / release (pull_request) Skipped

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>
This commit is contained in:
alexmandClaude committed 2026-11-16 13:00:24 -05:00
1 parent b5cae6afac
commit 7af1cd5b7e
4 files changed
+222 -9

No files matched your search

+2
View File
@@ -28,6 +28,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
### Changed ### Changed
- `lint --min-severity` defaults to `note`, and `lint` fails only on findings above a note. - `lint --min-severity` defaults to `note`, and `lint` fails only on findings above a note.
- Lecture pages (`lecture objectives`, `lecture readings`, `lecture page`) leave off prerequisites. An objective or target covered in an earlier lecture is no longer printed on a later lecture just because it lists that lecture in `lectures:`, unless the later lecture lists its objective in `teaches`. The `lectures:` link itself is unchanged, so assembly, coverage, and the reports' review lists still use it. Target numbers on those pages close up accordingly.
- Reading prose that cites an objective or target from another lecture renders as its number on that lecture's page, such as `L3.5's T 1`, instead of the full text of the target.
- The crate depends on `regex`, built without its optional features. - The crate depends on `regex`, built without its optional features.
### Fixed ### Fixed
+2
View File
@@ -564,6 +564,8 @@ The guide describes the lock as a deterrent, not a grading system of record (`do
`lecture readings ID` and `lecture objectives ID` write the readings block and the learning-objectives block for one lecture, as Quarto Pandoc definition lists (`--style quarto`, the default) or as plain Markdown bullets (`--style plain`). `lecture readings ID` and `lecture objectives ID` write the readings block and the learning-objectives block for one lecture, as Quarto Pandoc definition lists (`--style quarto`, the default) or as plain Markdown bullets (`--style plain`).
They print to standard output without `--out`. They print to standard output without `--out`.
A lecture's pages leave off its prerequisites: an objective or target that names the lecture in its `lectures:` list but was covered in an earlier lecture is not printed, unless the lecture lists its objective in `teaches`.
Prose that cites a prerequisite, such as `{t-control-at-far-steps}`, renders as its number on the page of the lecture that teaches it.
`lecture page ID` writes the whole page for one lecture: its description, each objective with its targets (each with its explanation and its ceiling named by `policy.levels`), new and earlier terms, equations, numbers to know, common mistakes, readings with minutes, and materials. `lecture page ID` writes the whole page for one lecture: its description, each objective with its targets (each with its explanation and its ceiling named by `policy.levels`), new and earlier terms, equations, numbers to know, common mistakes, readings with minutes, and materials.
`lecture glossary` writes the course glossary page: every term alphabetically, then every equation and value, each with the lecture that introduces it. `lecture glossary` writes the course glossary page: every term alphabetically, then every equation and value, each with the lecture that introduces it.
Both take `--style` and `--out`, and `lecture page` takes `--glossary-href` for where links to earlier terms point (default `glossary.html`). Both take `--style` and `--out`, and `lecture page` takes `--glossary-href` for where links to earlier terms point (default `glossary.html`).
+1
View File
@@ -177,6 +177,7 @@ $ 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 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. `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`. Both write Quarto Markdown by default (numbered targets as `(@)` example lists, anchors as `{#glossary-term-...}`), or plain Markdown with `--style plain`.
+217 -9
View File
@@ -74,7 +74,11 @@ fn target_layout<'a>(
course: &'a CourseFile, course: &'a CourseFile,
lecture: &str, lecture: &str,
) -> (Vec<(&'a str, Vec<&'a str>)>, Vec<&'a str>) { ) -> (Vec<(&'a str, Vec<&'a str>)>, Vec<&'a str>) {
let targets = course.lecture_targets(lecture); let targets: Vec<&str> = course
.lecture_targets(lecture)
.into_iter()
.filter(|id| taught_here(course, lecture, id))
.collect();
let mut groups: Vec<(&str, Vec<&str>)> = Vec::new(); let mut groups: Vec<(&str, Vec<&str>)> = Vec::new();
for objective in course.lecture_objectives(lecture) { for objective in course.lecture_objectives(lecture) {
let mine: Vec<&str> = course let mine: Vec<&str> = course
@@ -97,6 +101,92 @@ fn target_layout<'a>(
(groups, leftovers) (groups, leftovers)
} }
/// Whether an objective or target is new in a lecture, rather than a
/// prerequisite the lecture builds on.
///
/// An entry can name a lecture in its `lectures:` list because the lecture
/// reuses it: a target taught in L3.5 that L4.2 depends on lists both. The
/// registry keeps that link, since assembly, coverage, and the reports' review
/// lists read it, but the lecture's pages are about what the lecture teaches,
/// and a student who sees five earlier objectives at the top of the page reads
/// them as new.
///
/// So an entry is on the page when the lecture lists its objective in
/// `teaches`, which is the author saying so, or when no earlier lecture, in
/// teaching order, covers it, which is new material the lecture introduces
/// without declaring it.
///
/// # Arguments
///
/// * `course` - the loaded course file.
/// * `lecture` - the lecture id.
/// * `id` - an objective or target the lecture names.
///
/// # Returns
///
/// `false` for a prerequisite.
fn taught_here(course: &CourseFile, lecture: &str, id: &str) -> bool {
let objective = course.objective_for(id);
let declared = course
.lectures
.get(lecture)
.is_some_and(|l| l.teaches.iter().any(|o| o == objective));
if declared {
return true;
}
// The lecture map is the course's teaching order, so an earlier lecture is
// one that sorts before this one.
!course
.lectures_for(id)
.iter()
.any(|l| l.as_str() < lecture && course.lectures.contains_key(l))
}
/// A target's number on the page of the lecture that teaches it.
///
/// That lecture is the first, in teaching order, that names the target. Prose
/// on a later page cites a prerequisite this way, which reads right next to
/// the "from L3.5" an author writes after it.
///
/// # Arguments
///
/// * `course` - the loaded course file.
/// * `id` - an objective or target id.
///
/// # Returns
///
/// The number, or `None` when no lecture's page shows the entry.
fn home_number(course: &CourseFile, id: &str) -> Option<usize> {
let home = course
.lectures_for(id)
.iter()
.filter(|l| course.lectures.contains_key(*l))
.min()?;
numbered_targets(course, home)
.iter()
.position(|o| o == id)
.map(|i| i + 1)
}
/// The objectives and targets a lecture's pages show: everything it names,
/// less its prerequisites.
///
/// # Arguments
///
/// * `course` - the loaded course file.
/// * `lecture` - the lecture id.
///
/// # Returns
///
/// Registry ids in teaching order.
fn page_entries<'a>(course: &'a CourseFile, lecture: &str) -> Vec<&'a str> {
course
.lecture_entries(lecture)
.into_iter()
.filter(|id| taught_here(course, lecture, id))
.collect()
}
/// Whether a lecture's registry entries use the second tier. /// Whether a lecture's registry entries use the second tier.
/// ///
/// # Arguments /// # Arguments
@@ -106,10 +196,9 @@ fn target_layout<'a>(
/// ///
/// # Returns /// # Returns
/// ///
/// `true` when any entry the lecture names is a target. /// `true` when any entry the lecture's pages show is a target.
fn is_tiered(course: &CourseFile, lecture: &str) -> bool { fn is_tiered(course: &CourseFile, lecture: &str) -> bool {
course page_entries(course, lecture)
.lecture_entries(lecture)
.iter() .iter()
.any(|id| course.is_target(id)) .any(|id| course.is_target(id))
} }
@@ -133,7 +222,7 @@ pub fn numbered_targets(course: &CourseFile, lecture: &str) -> Vec<String> {
if !is_tiered(course, lecture) { if !is_tiered(course, lecture) {
// Untiered page: level groups, in the order they print, which is the // Untiered page: level groups, in the order they print, which is the
// numbering this page has always had. // numbering this page has always had.
return by_level(course, &course.lecture_entries(lecture)) return by_level(course, &page_entries(course, lecture))
.into_iter() .into_iter()
.flat_map(|(_, members)| members) .flat_map(|(_, members)| members)
.map(str::to_string) .map(str::to_string)
@@ -217,7 +306,7 @@ pub fn objectives_markdown(course: &CourseFile, lecture: &str, style: Style) ->
if !is_tiered(course, lecture) { if !is_tiered(course, lecture) {
// Levels in taxonomy order, then whatever declares no ceiling. // Levels in taxonomy order, then whatever declares no ceiling.
for (level, members) in by_level(course, &course.lecture_entries(lecture)) { for (level, members) in by_level(course, &page_entries(course, lecture)) {
if let Some(level) = level { if let Some(level) = level {
out.push_str(&format!("### {}\n\n", level.name())); out.push_str(&format!("### {}\n\n", level.name()));
} }
@@ -346,12 +435,16 @@ fn entry(
// The three prose fields in the order a reader wants them: what it is, what to // The three prose fields in the order a reader wants them: what it is, what to
// take from it, what to leave. // take from it, what to leave.
// Prose may cite a prerequisite, which has no number here; it is cited by
// its number on the page that teaches it. The `_(T ...)_` list below stays
// with this page's numbers, since it is a list of this page's targets.
let cited = |id: &str| number(id).or_else(|| home_number(course, id));
let body: Vec<String> = [&reading.summary, &reading.focus, &reading.skip] let body: Vec<String> = [&reading.summary, &reading.focus, &reading.skip]
.into_iter() .into_iter()
.flatten() .flatten()
.map(|prose| { .map(|prose| {
course.expand_refs(prose, |id| { course.expand_refs(prose, |id| {
reference_markdown(course, id, number, &|id| { reference_markdown(course, id, &cited, &|id| {
format!("{DEFAULT_GLOSSARY_HREF}#{}", anchor(id)) format!("{DEFAULT_GLOSSARY_HREF}#{}", anchor(id))
}) })
}) })
@@ -495,9 +588,14 @@ struct Page<'a> {
} }
impl Page<'_> { impl Page<'_> {
/// A target's position on the page. /// The number prose cites a target by: its position on this page, or, for
/// a prerequisite, on the page of the lecture that teaches it.
fn number(&self, id: &str) -> Option<usize> { fn number(&self, id: &str) -> Option<usize> {
self.numbers.iter().position(|o| o == id).map(|i| i + 1) self.numbers
.iter()
.position(|o| o == id)
.map(|i| i + 1)
.or_else(|| home_number(self.course, id))
} }
/// Where a link to a glossary entry points from this page. /// Where a link to a glossary entry points from this page.
@@ -1199,6 +1297,116 @@ After this lecture, you should be able to do the following.
c c
} }
/// The tiered course with a second lecture that builds on the first.
///
/// L1.2 teaches `lo-later` and its target `t-new`. `lo-first`, taught in
/// L1.1, names L1.2 as well because L1.2 reuses it, and L1.2's reading
/// cites it.
fn two_lecture_course() -> CourseFile {
let mut c = tiered_course();
c.learning_targets
.get_mut("lo-first")
.expect("fixture")
.lectures
.push("L1.2".into());
c.learning_objectives.insert(
"lo-later".into(),
Objective {
text: "Predict binding.".into(),
lectures: vec!["L1.2".into()],
order: Some(3),
..objective_defaults()
},
);
c.learning_targets.insert(
"t-new".into(),
Target {
text: "target t-new".into(),
objective: "lo-later".into(),
lectures: vec!["L1.2".into()],
..Target::default()
},
);
c.lectures.insert(
"L1.2".into(),
Lecture {
title: "Binding".into(),
teaches: vec!["lo-later".into()],
readings: vec![Reading {
reference: Some("kuriyan2013molecules".into()),
locator: Some("§6.2".into()),
targets: vec!["t-new".into(), "lo-first".into()],
focus: Some("Use {lo-first} from L1.1 for {t-new}.".into()),
..Reading::default()
}],
..Lecture::default()
},
);
c
}
#[test]
fn a_prerequisite_is_left_off_the_lecture_that_reuses_it() {
let c = two_lecture_course();
let md = objectives_markdown(&c, "L1.2", Style::Plain).expect("renders");
assert!(md.contains("target t-new"), "{md}");
assert!(!md.contains("objective lo-first"), "{md}");
assert!(!md.contains("Quantify binding."), "{md}");
assert_eq!(numbered_targets(&c, "L1.2"), ["t-new"]);
// The lecture that teaches it still shows it.
assert_eq!(numbered_targets(&c, "L1.1"), ["lo-first", "lo-second"]);
let options = PageOptions {
style: Style::Plain,
..PageOptions::default()
};
let page = page_markdown(&c, "L1.2", &options).expect("renders");
assert!(!page.contains("objective lo-first"), "{page}");
}
#[test]
fn prose_cites_a_prerequisite_by_its_number_where_it_is_taught() {
let c = two_lecture_course();
let md = readings_markdown(&c, "L1.2", Style::Quarto).expect("renders");
// `lo-first` is T 1 on L1.1's page; `t-new` is T 1 on this one.
assert!(md.contains("Use T 1 from L1.1 for T 1."), "{md}");
// The trailing list is this page's targets only.
assert!(md.contains("_(T 1)_"), "{md}");
}
#[test]
fn an_entry_first_covered_here_stays_without_being_declared() {
// A target that names only this lecture is new here, even though the
// lecture's `teaches` does not list its objective.
let mut c = two_lecture_course();
c.learning_targets.insert(
"t-extra".into(),
Target {
text: "target t-extra".into(),
objective: "lo-binding".into(),
lectures: vec!["L1.2".into()],
..Target::default()
},
);
let md = objectives_markdown(&c, "L1.2", Style::Plain).expect("renders");
assert!(md.contains("target t-extra"), "{md}");
assert!(!md.contains("objective lo-first"), "{md}");
}
#[test]
fn a_lecture_that_declares_an_objective_shows_it_again() {
// Listing the objective in `teaches` says the lecture covers it, so an
// objective spread over two lectures appears on both.
let mut c = two_lecture_course();
c.lectures
.get_mut("L1.2")
.expect("fixture")
.teaches
.push("lo-binding".into());
let md = objectives_markdown(&c, "L1.2", Style::Plain).expect("renders");
assert!(md.contains("objective lo-first"), "{md}");
}
#[test] #[test]
fn the_page_bolds_each_objective_and_enumerates_its_targets() { fn the_page_bolds_each_objective_and_enumerates_its_targets() {
let md = objectives_markdown(&tiered_course(), "L1.1", Style::Quarto).expect("renders"); let md = objectives_markdown(&tiered_course(), "L1.1", Style::Quarto).expect("renders");