WIP: Prelim use #2

Draft
alexm wants to merge 40 commits from prelim-use into main
pull from: prelim-use
4 changed files with 222 additions and 9 deletions
Showing only changes of commit 7af1cd5b7e - Show all commits

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");