WIP: Prelim use #2
No files matched your search
@@ -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
|
||||||
|
|||||||
@@ -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`).
|
||||||
|
|||||||
@@ -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
@@ -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");
|
||||||
|
|||||||
Reference in new issue
Block a user