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

+217 -9
View File
@@ -74,7 +74,11 @@ fn target_layout<'a>(
course: &'a CourseFile,
lecture: &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();
for objective in course.lecture_objectives(lecture) {
let mine: Vec<&str> = course
@@ -97,6 +101,92 @@ fn target_layout<'a>(
(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.
///
/// # Arguments
@@ -106,10 +196,9 @@ fn target_layout<'a>(
///
/// # 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 {
course
.lecture_entries(lecture)
page_entries(course, lecture)
.iter()
.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) {
// Untiered page: level groups, in the order they print, which is the
// numbering this page has always had.
return by_level(course, &course.lecture_entries(lecture))
return by_level(course, &page_entries(course, lecture))
.into_iter()
.flat_map(|(_, members)| members)
.map(str::to_string)
@@ -217,7 +306,7 @@ pub fn objectives_markdown(course: &CourseFile, lecture: &str, style: Style) ->
if !is_tiered(course, lecture) {
// 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 {
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
// 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]
.into_iter()
.flatten()
.map(|prose| {
course.expand_refs(prose, |id| {
reference_markdown(course, id, number, &|id| {
reference_markdown(course, id, &cited, &|id| {
format!("{DEFAULT_GLOSSARY_HREF}#{}", anchor(id))
})
})
@@ -495,9 +588,14 @@ struct Page<'a> {
}
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> {
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.
@@ -1199,6 +1297,116 @@ After this lecture, you should be able to do the following.
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]
fn the_page_bolds_each_objective_and_enumerates_its_targets() {
let md = objectives_markdown(&tiered_course(), "L1.1", Style::Quarto).expect("renders");