diff --git a/CHANGELOG.md b/CHANGELOG.md index e0b17f4..1ef678c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), ### Changed - `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. ### Fixed diff --git a/README.md b/README.md index 00db532..1b5b0da 100644 --- a/README.md +++ b/README.md @@ -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`). 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 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`). diff --git a/docs/guide/glossary.md b/docs/guide/glossary.md index 5f5ca00..d18bd49 100644 --- a/docs/guide/glossary.md +++ b/docs/guide/glossary.md @@ -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. +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`. diff --git a/src/export/lecture.rs b/src/export/lecture.rs index 4170942..8abc45d 100644 --- a/src/export/lecture.rs +++ b/src/export/lecture.rs @@ -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 { + 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 { 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 = [&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 { - 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");