feat(render): 2.1 lecture page, glossary page, and student reports
Derive each glossary entry's first lecture from teaching order and split a lecture's terms into new and earlier. Add `coursebank lecture page` (objectives with descriptions, targets with explanations and ceilings named by policy.levels, terms, equations, numbers, common mistakes, readings with minutes, materials) and `coursebank lecture glossary`. Render brace references in student prose as links, values, quoted beliefs, or target numbers. Student reports, Markdown and Typst, show what meeting each target looks like, the correction for a registry misconception, and group misses that share one. A test renders every student-facing output from the example and checks that no authoring, notes_private, evidence, conflicts, or status text reaches it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
10 files changed
+1612
-13
No files matched your search
@@ -181,6 +181,10 @@ pub struct StudentDiagnostic {
|
|||||||
/// One row per question, with no question in it.
|
/// One row per question, with no question in it.
|
||||||
#[serde(skip_serializing_if = "Vec::is_empty")]
|
#[serde(skip_serializing_if = "Vec::is_empty")]
|
||||||
pub questions: Vec<QuestionRow>,
|
pub questions: Vec<QuestionRow>,
|
||||||
|
/// Registry mistakes behind more than one missed question, so the report
|
||||||
|
/// can group those misses under the one thing to fix.
|
||||||
|
#[serde(skip_serializing_if = "Vec::is_empty")]
|
||||||
|
pub mistakes: Vec<MistakeGroup>,
|
||||||
/// Questions thrown out, in number order.
|
/// Questions thrown out, in number order.
|
||||||
///
|
///
|
||||||
/// Reported separately from the question rows so the document can say once,
|
/// Reported separately from the question rows so the document can say once,
|
||||||
@@ -337,6 +341,41 @@ pub struct Measured {
|
|||||||
pub objective: Option<String>,
|
pub objective: Option<String>,
|
||||||
/// The target the question was written against.
|
/// The target the question was written against.
|
||||||
pub target: String,
|
pub target: String,
|
||||||
|
/// The target's explanation, with references rendered as words: what
|
||||||
|
/// meeting it looks like, which is what to practise towards.
|
||||||
|
#[serde(skip_serializing_if = "Option::is_none")]
|
||||||
|
pub explanation: Option<String>,
|
||||||
|
}
|
||||||
|
|
||||||
|
/// A named mistake behind a student's answer, from the course's misconception
|
||||||
|
/// registry. Student-facing: the belief and its correction are written for the
|
||||||
|
/// student.
|
||||||
|
#[derive(Debug, Clone, Serialize)]
|
||||||
|
#[serde(rename_all = "kebab-case")]
|
||||||
|
pub struct Mistake {
|
||||||
|
/// The misconception id.
|
||||||
|
pub id: String,
|
||||||
|
/// The wrong idea as a student holds it. Absent when the chosen option
|
||||||
|
/// carries its own misconception text, which overrides the registry's for
|
||||||
|
/// that item and already reaches the student as feedback.
|
||||||
|
#[serde(skip_serializing_if = "Option::is_none")]
|
||||||
|
pub belief: Option<String>,
|
||||||
|
/// Why it fails and what is true instead.
|
||||||
|
pub correction: String,
|
||||||
|
}
|
||||||
|
|
||||||
|
/// A mistake that more than one missed question drew on.
|
||||||
|
#[derive(Debug, Clone, Serialize)]
|
||||||
|
#[serde(rename_all = "kebab-case")]
|
||||||
|
pub struct MistakeGroup {
|
||||||
|
/// The misconception id.
|
||||||
|
pub id: String,
|
||||||
|
/// The registry's belief.
|
||||||
|
pub belief: String,
|
||||||
|
/// The registry's correction.
|
||||||
|
pub correction: String,
|
||||||
|
/// The questions, by recorded number.
|
||||||
|
pub questions: Vec<u32>,
|
||||||
}
|
}
|
||||||
|
|
||||||
/// One question, described without being reproduced.
|
/// One question, described without being reproduced.
|
||||||
@@ -397,6 +436,10 @@ pub struct QuestionRow {
|
|||||||
/// The worked solution, when [`Options::solutions`] is on.
|
/// The worked solution, when [`Options::solutions`] is on.
|
||||||
#[serde(skip_serializing_if = "Option::is_none")]
|
#[serde(skip_serializing_if = "Option::is_none")]
|
||||||
pub worked: Option<String>,
|
pub worked: Option<String>,
|
||||||
|
/// The registry misconception the chosen option encodes, with its
|
||||||
|
/// correction, when [`Options::feedback`] is on.
|
||||||
|
#[serde(skip_serializing_if = "Option::is_none")]
|
||||||
|
pub mistake: Option<Mistake>,
|
||||||
/// Where the material was taught.
|
/// Where the material was taught.
|
||||||
#[serde(skip_serializing_if = "Vec::is_empty")]
|
#[serde(skip_serializing_if = "Vec::is_empty")]
|
||||||
pub taught_in: Vec<String>,
|
pub taught_in: Vec<String>,
|
||||||
@@ -678,6 +721,7 @@ pub fn student(
|
|||||||
objectives,
|
objectives,
|
||||||
strengths,
|
strengths,
|
||||||
focus,
|
focus,
|
||||||
|
mistakes: shared_mistakes(&questions, course),
|
||||||
questions,
|
questions,
|
||||||
dropped_questions,
|
dropped_questions,
|
||||||
review_lectures,
|
review_lectures,
|
||||||
@@ -706,6 +750,7 @@ fn question_row(
|
|||||||
let mut hint = None;
|
let mut hint = None;
|
||||||
let mut misconception = None;
|
let mut misconception = None;
|
||||||
let mut worked = None;
|
let mut worked = None;
|
||||||
|
let mut mistake = None;
|
||||||
let mut taught_in = Vec::new();
|
let mut taught_in = Vec::new();
|
||||||
let mut review = Vec::new();
|
let mut review = Vec::new();
|
||||||
|
|
||||||
@@ -714,6 +759,20 @@ fn question_row(
|
|||||||
if missed {
|
if missed {
|
||||||
if let Some(letter) = row.chosen().first() {
|
if let Some(letter) = row.chosen().first() {
|
||||||
if let Some(choice) = entry.item.option(letter) {
|
if let Some(choice) = entry.item.option(letter) {
|
||||||
|
if opts.feedback {
|
||||||
|
let course = &catalog.course;
|
||||||
|
mistake = choice.misconception_id.as_deref().and_then(|id| {
|
||||||
|
let registered = course.misconceptions.get(id)?;
|
||||||
|
Some(Mistake {
|
||||||
|
id: id.to_string(),
|
||||||
|
belief: choice
|
||||||
|
.misconception
|
||||||
|
.is_none()
|
||||||
|
.then(|| course.plain_refs(®istered.belief)),
|
||||||
|
correction: course.plain_refs(®istered.correction),
|
||||||
|
})
|
||||||
|
});
|
||||||
|
}
|
||||||
if opts.feedback {
|
if opts.feedback {
|
||||||
// `student_text` falls back to `explanation`, which is
|
// `student_text` falls back to `explanation`, which is
|
||||||
// written for a grader and often names the right
|
// written for a grader and often names the right
|
||||||
@@ -783,6 +842,11 @@ fn question_row(
|
|||||||
// objective is left out.
|
// objective is left out.
|
||||||
objective: (objective != id).then(|| course.text_for(objective)),
|
objective: (objective != id).then(|| course.text_for(objective)),
|
||||||
target: course.text_for(id),
|
target: course.text_for(id),
|
||||||
|
explanation: course
|
||||||
|
.learning_targets
|
||||||
|
.get(id)
|
||||||
|
.and_then(|t| t.explanation.as_deref())
|
||||||
|
.map(|e| course.plain_refs(e)),
|
||||||
}
|
}
|
||||||
})
|
})
|
||||||
.collect()
|
.collect()
|
||||||
@@ -804,11 +868,47 @@ fn question_row(
|
|||||||
hint,
|
hint,
|
||||||
misconception,
|
misconception,
|
||||||
worked,
|
worked,
|
||||||
|
mistake,
|
||||||
taught_in,
|
taught_in,
|
||||||
review,
|
review,
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// The registry mistakes that more than one of a student's missed questions
|
||||||
|
/// drew on, so a report can name the thing to fix once.
|
||||||
|
///
|
||||||
|
/// # Arguments
|
||||||
|
///
|
||||||
|
/// * `questions` - the student's question rows.
|
||||||
|
/// * `course` - the course, for the registry's wording.
|
||||||
|
///
|
||||||
|
/// # Returns
|
||||||
|
///
|
||||||
|
/// One group per shared misconception, in order of its first question.
|
||||||
|
pub fn shared_mistakes(questions: &[QuestionRow], course: &CourseFile) -> Vec<MistakeGroup> {
|
||||||
|
let mut groups: Vec<MistakeGroup> = Vec::new();
|
||||||
|
for q in questions {
|
||||||
|
let Some(mistake) = &q.mistake else {
|
||||||
|
continue;
|
||||||
|
};
|
||||||
|
if let Some(group) = groups.iter_mut().find(|g| g.id == mistake.id) {
|
||||||
|
group.questions.push(q.number);
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
let Some(entry) = course.misconceptions.get(&mistake.id) else {
|
||||||
|
continue;
|
||||||
|
};
|
||||||
|
groups.push(MistakeGroup {
|
||||||
|
id: mistake.id.clone(),
|
||||||
|
belief: course.plain_refs(&entry.belief),
|
||||||
|
correction: course.plain_refs(&entry.correction),
|
||||||
|
questions: vec![q.number],
|
||||||
|
});
|
||||||
|
}
|
||||||
|
groups.retain(|g| g.questions.len() > 1);
|
||||||
|
groups
|
||||||
|
}
|
||||||
|
|
||||||
/// Resolves an item's `review` citations against the course reference registry.
|
/// Resolves an item's `review` citations against the course reference registry.
|
||||||
///
|
///
|
||||||
/// # Arguments
|
/// # Arguments
|
||||||
@@ -2565,6 +2665,7 @@ mod tests {
|
|||||||
strengths: Vec::new(),
|
strengths: Vec::new(),
|
||||||
focus: Vec::new(),
|
focus: Vec::new(),
|
||||||
questions: Vec::new(),
|
questions: Vec::new(),
|
||||||
|
mistakes: Vec::new(),
|
||||||
dropped_questions: Vec::new(),
|
dropped_questions: Vec::new(),
|
||||||
review_lectures: Vec::new(),
|
review_lectures: Vec::new(),
|
||||||
study: Vec::new(),
|
study: Vec::new(),
|
||||||
|
|||||||
@@ -184,6 +184,9 @@ pub struct MissedItem {
|
|||||||
pub learning_targets: Vec<String>,
|
pub learning_targets: Vec<String>,
|
||||||
/// The misconception the chosen distractor was written to detect.
|
/// The misconception the chosen distractor was written to detect.
|
||||||
pub misconception: Option<String>,
|
pub misconception: Option<String>,
|
||||||
|
/// The registry misconception the chosen distractor encodes, when it names
|
||||||
|
/// one. Misses that share it are grouped in the report.
|
||||||
|
pub misconception_id: Option<String>,
|
||||||
/// Feedback written for a student who chose that option.
|
/// Feedback written for a student who chose that option.
|
||||||
pub feedback: Option<String>,
|
pub feedback: Option<String>,
|
||||||
/// Where to go back to: lecture titles and slide numbers.
|
/// Where to go back to: lecture titles and slide numbers.
|
||||||
@@ -675,6 +678,7 @@ fn missed_items(
|
|||||||
continue;
|
continue;
|
||||||
}
|
}
|
||||||
let mut misconception = None;
|
let mut misconception = None;
|
||||||
|
let mut misconception_id = None;
|
||||||
let mut feedback = None;
|
let mut feedback = None;
|
||||||
let mut study = Vec::new();
|
let mut study = Vec::new();
|
||||||
|
|
||||||
@@ -685,6 +689,7 @@ fn missed_items(
|
|||||||
if let Some(letter) = r.chosen().first() {
|
if let Some(letter) = r.chosen().first() {
|
||||||
if let Some(choice) = entry.item.option(letter) {
|
if let Some(choice) = entry.item.option(letter) {
|
||||||
misconception = choice.misconception.clone();
|
misconception = choice.misconception.clone();
|
||||||
|
misconception_id = choice.misconception_id.clone();
|
||||||
feedback = choice.student_text().map(|s| s.to_string());
|
feedback = choice.student_text().map(|s| s.to_string());
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@@ -716,6 +721,7 @@ fn missed_items(
|
|||||||
level: r.level,
|
level: r.level,
|
||||||
learning_targets: r.learning_targets.clone(),
|
learning_targets: r.learning_targets.clone(),
|
||||||
misconception,
|
misconception,
|
||||||
|
misconception_id,
|
||||||
feedback,
|
feedback,
|
||||||
study,
|
study,
|
||||||
});
|
});
|
||||||
|
|||||||
+31
@@ -327,6 +327,37 @@ pub(crate) enum LectureCommand {
|
|||||||
#[arg(long)]
|
#[arg(long)]
|
||||||
out: Option<PathBuf>,
|
out: Option<PathBuf>,
|
||||||
},
|
},
|
||||||
|
/// Write the whole page for one lecture.
|
||||||
|
///
|
||||||
|
/// Its description; each objective with its targets, their ceilings, and
|
||||||
|
/// their explanations; the terms new here and those from earlier lectures;
|
||||||
|
/// the equations, numbers, and common mistakes its targets turn on; the
|
||||||
|
/// readings with their times; and the materials. Only student-facing
|
||||||
|
/// fields are read.
|
||||||
|
Page {
|
||||||
|
/// Lecture id, e.g. L1.1.
|
||||||
|
id: String,
|
||||||
|
/// Which flavour of Markdown to write.
|
||||||
|
#[arg(long, value_enum, default_value = "quarto")]
|
||||||
|
style: StyleArg,
|
||||||
|
/// Where the course glossary page lives, for links to entries this page
|
||||||
|
/// does not define.
|
||||||
|
#[arg(long, default_value = coursebank::lecture::DEFAULT_GLOSSARY_HREF)]
|
||||||
|
glossary_href: String,
|
||||||
|
/// Output path; prints to stdout when omitted.
|
||||||
|
#[arg(long)]
|
||||||
|
out: Option<PathBuf>,
|
||||||
|
},
|
||||||
|
/// Write the course glossary page: every term, equation, and value, with
|
||||||
|
/// the lecture that introduces it.
|
||||||
|
Glossary {
|
||||||
|
/// Which flavour of Markdown to write.
|
||||||
|
#[arg(long, value_enum, default_value = "quarto")]
|
||||||
|
style: StyleArg,
|
||||||
|
/// Output path; prints to stdout when omitted.
|
||||||
|
#[arg(long)]
|
||||||
|
out: Option<PathBuf>,
|
||||||
|
},
|
||||||
/// Show the readings behind each learning target, and which have none.
|
/// Show the readings behind each learning target, and which have none.
|
||||||
Coverage {
|
Coverage {
|
||||||
/// Only this lecture's targets.
|
/// Only this lecture's targets.
|
||||||
|
|||||||
@@ -10,7 +10,9 @@
|
|||||||
|
|
||||||
use coursebank::course::CourseFile;
|
use coursebank::course::CourseFile;
|
||||||
use coursebank::error::Result;
|
use coursebank::error::Result;
|
||||||
use coursebank::lecture::{objectives_markdown, readings_markdown};
|
use coursebank::lecture::{
|
||||||
|
PageOptions, glossary_markdown, objectives_markdown, page_markdown, readings_markdown,
|
||||||
|
};
|
||||||
use coursebank::yaml;
|
use coursebank::yaml;
|
||||||
|
|
||||||
use crate::cli::{Cli, LectureCommand};
|
use crate::cli::{Cli, LectureCommand};
|
||||||
@@ -29,6 +31,25 @@ pub(crate) fn lecture(cli: &Cli, sub: &LectureCommand) -> Result<Outcome> {
|
|||||||
objectives_markdown(&course, id, style.as_style())?,
|
objectives_markdown(&course, id, style.as_style())?,
|
||||||
out.as_deref(),
|
out.as_deref(),
|
||||||
),
|
),
|
||||||
|
LectureCommand::Page {
|
||||||
|
id,
|
||||||
|
style,
|
||||||
|
glossary_href,
|
||||||
|
out,
|
||||||
|
} => {
|
||||||
|
let options = PageOptions {
|
||||||
|
style: style.as_style(),
|
||||||
|
glossary_href: glossary_href.clone(),
|
||||||
|
};
|
||||||
|
emit(page_markdown(&course, id, &options)?, out.as_deref())
|
||||||
|
}
|
||||||
|
LectureCommand::Glossary { style, out } => {
|
||||||
|
let options = PageOptions {
|
||||||
|
style: style.as_style(),
|
||||||
|
..PageOptions::default()
|
||||||
|
};
|
||||||
|
emit(glossary_markdown(&course, &options), out.as_deref())
|
||||||
|
}
|
||||||
LectureCommand::Coverage { lecture: only } => coverage(&course, only.as_deref(), cli.quiet),
|
LectureCommand::Coverage { lecture: only } => coverage(&course, only.as_deref(), cli.quiet),
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
+654
-3
@@ -20,7 +20,26 @@
|
|||||||
//! What this module does not do is invent prose. Everything printed comes from
|
//! What this module does not do is invent prose. Everything printed comes from
|
||||||
//! `summary`, `focus`, and `skip` on the reading, in that order, and a reading with
|
//! `summary`, `focus`, and `skip` on the reading, in that order, and a reading with
|
||||||
//! none of the three renders as a bare citation.
|
//! none of the three renders as a bare citation.
|
||||||
|
//!
|
||||||
|
//! # The lecture page and the glossary page
|
||||||
|
//!
|
||||||
|
//! Since 2.1 a lecture is more than its objectives and readings, and
|
||||||
|
//! [`page_markdown`] renders all of it, in the order the specification gives:
|
||||||
|
//! the lecture's description; each objective with its description and its
|
||||||
|
//! targets (by ceiling, each labelled with the course's own level name and
|
||||||
|
//! followed by its explanation); the terms new in this lecture, then the ones
|
||||||
|
//! from earlier lectures; the equations its targets turn on; the numbers to
|
||||||
|
//! know; the common mistakes; the readings, with minutes; and the materials.
|
||||||
|
//! [`glossary_markdown`] renders the course glossary page that every term on a
|
||||||
|
//! lecture page links to.
|
||||||
|
//!
|
||||||
|
//! Both pages are student pages, so they read only student-facing fields. A
|
||||||
|
//! target's `authoring`, an entry's `notes_private`, `status`, a value's
|
||||||
|
//! `conflicts`, and a misconception's `evidence` are never touched here.
|
||||||
|
|
||||||
|
use std::collections::BTreeSet;
|
||||||
|
|
||||||
|
use crate::course::glossary::{RefKind, TermKind};
|
||||||
use crate::course::{CourseFile, Reading, ReadingRole, Reference};
|
use crate::course::{CourseFile, Reading, ReadingRole, Reference};
|
||||||
use crate::error::{Error, Result};
|
use crate::error::{Error, Result};
|
||||||
use crate::taxonomy::Level;
|
use crate::taxonomy::Level;
|
||||||
@@ -331,9 +350,10 @@ fn entry(
|
|||||||
.into_iter()
|
.into_iter()
|
||||||
.flatten()
|
.flatten()
|
||||||
.map(|prose| {
|
.map(|prose| {
|
||||||
course.expand_objective_refs(prose, |id| match number(id) {
|
course.expand_refs(prose, |id| {
|
||||||
Some(n) => format!("T {n}"),
|
reference_markdown(course, id, number, &|id| {
|
||||||
None => course.text_for(id),
|
format!("{DEFAULT_GLOSSARY_HREF}#{}", anchor(id))
|
||||||
|
})
|
||||||
})
|
})
|
||||||
})
|
})
|
||||||
.collect();
|
.collect();
|
||||||
@@ -388,6 +408,637 @@ fn heading(reading: &Reading, key: &str, reference: &Reference, style: Style) ->
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Where a term or equation link points when no other page is named: the
|
||||||
|
/// course glossary page, as [`glossary_markdown`] writes it and a Quarto site
|
||||||
|
/// renders it.
|
||||||
|
pub const DEFAULT_GLOSSARY_HREF: &str = "glossary.html";
|
||||||
|
|
||||||
|
/// How to render a lecture page or the glossary page.
|
||||||
|
#[derive(Debug, Clone)]
|
||||||
|
pub struct PageOptions {
|
||||||
|
/// Which flavour of Markdown to emit. Quarto gives each glossary entry an
|
||||||
|
/// anchor and links to it on the same page when it is there; Plain links
|
||||||
|
/// every entry to the glossary page.
|
||||||
|
pub style: Style,
|
||||||
|
/// The course glossary page, which entries not on this page link to.
|
||||||
|
pub glossary_href: String,
|
||||||
|
}
|
||||||
|
|
||||||
|
impl Default for PageOptions {
|
||||||
|
fn default() -> PageOptions {
|
||||||
|
PageOptions {
|
||||||
|
style: Style::Quarto,
|
||||||
|
glossary_href: DEFAULT_GLOSSARY_HREF.to_string(),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// The HTML anchor of a glossary entry.
|
||||||
|
///
|
||||||
|
/// Prefixed, because Quarto reserves `eq-` (and `fig-`, `tbl-`, `sec-`) for its
|
||||||
|
/// own cross-references and would claim an equation's id.
|
||||||
|
///
|
||||||
|
/// # Arguments
|
||||||
|
///
|
||||||
|
/// * `id` - the entry id.
|
||||||
|
///
|
||||||
|
/// # Returns
|
||||||
|
///
|
||||||
|
/// The anchor, without `#`.
|
||||||
|
pub fn anchor(id: &str) -> String {
|
||||||
|
format!("glossary-{id}")
|
||||||
|
}
|
||||||
|
|
||||||
|
/// One brace reference as Markdown, following the specification's table: a
|
||||||
|
/// term as its name linked to its entry, an equation as its name linked to its
|
||||||
|
/// display, a value as its `say`, a misconception as its belief in quotation
|
||||||
|
/// marks, and a target or objective as its number on the page (`T 4`), or its
|
||||||
|
/// text when it is not numbered here.
|
||||||
|
///
|
||||||
|
/// # Arguments
|
||||||
|
///
|
||||||
|
/// * `course` - the course.
|
||||||
|
/// * `id` - the referenced id.
|
||||||
|
/// * `number` - a target's position on this page, if it has one.
|
||||||
|
/// * `href` - where a term or equation link points.
|
||||||
|
///
|
||||||
|
/// # Returns
|
||||||
|
///
|
||||||
|
/// The Markdown.
|
||||||
|
fn reference_markdown(
|
||||||
|
course: &CourseFile,
|
||||||
|
id: &str,
|
||||||
|
number: &impl Fn(&str) -> Option<usize>,
|
||||||
|
href: &dyn Fn(&str) -> String,
|
||||||
|
) -> String {
|
||||||
|
match RefKind::of(id) {
|
||||||
|
Some(RefKind::Term | RefKind::Equation) if course.resolves(id) => {
|
||||||
|
format!("[{}]({})", course.ref_words(id), href(id))
|
||||||
|
}
|
||||||
|
Some(RefKind::Value | RefKind::Misconception) if course.resolves(id) => {
|
||||||
|
course.ref_words(id)
|
||||||
|
}
|
||||||
|
_ => match number(id) {
|
||||||
|
Some(n) => format!("T {n}"),
|
||||||
|
None => course.text_for(id),
|
||||||
|
},
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// What one page needs to render prose: target numbers, and which glossary
|
||||||
|
/// entries have an anchor on it.
|
||||||
|
struct Page<'a> {
|
||||||
|
course: &'a CourseFile,
|
||||||
|
options: &'a PageOptions,
|
||||||
|
numbers: Vec<String>,
|
||||||
|
anchored: BTreeSet<String>,
|
||||||
|
}
|
||||||
|
|
||||||
|
impl Page<'_> {
|
||||||
|
/// A target's position on the page.
|
||||||
|
fn number(&self, id: &str) -> Option<usize> {
|
||||||
|
self.numbers.iter().position(|o| o == id).map(|i| i + 1)
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Where a link to a glossary entry points from this page.
|
||||||
|
fn href(&self, id: &str) -> String {
|
||||||
|
if self.options.style == Style::Quarto && self.anchored.contains(id) {
|
||||||
|
format!("#{}", anchor(id))
|
||||||
|
} else {
|
||||||
|
format!("{}#{}", self.options.glossary_href, anchor(id))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Student-facing prose, with references rendered and whitespace runs
|
||||||
|
/// collapsed, since YAML folding leaves them behind.
|
||||||
|
fn prose(&self, text: &str) -> String {
|
||||||
|
let collapsed = text.split_whitespace().collect::<Vec<_>>().join(" ");
|
||||||
|
self.course.expand_refs(&collapsed, |id| {
|
||||||
|
reference_markdown(self.course, id, &|t| self.number(t), &|e| self.href(e))
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
/// A LaTeX fragment as inline math, or as written in the Plain style.
|
||||||
|
fn math(&self, tex: &str) -> String {
|
||||||
|
match self.options.style {
|
||||||
|
Style::Quarto => format!("${}$", tex.trim()),
|
||||||
|
Style::Plain => tex.trim().to_string(),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// A bolded glossary label, with an anchor in the Quarto style.
|
||||||
|
fn label(&self, id: &str, text: &str) -> String {
|
||||||
|
match self.options.style {
|
||||||
|
Style::Quarto => format!("[**{text}**]{{#{}}}", anchor(id)),
|
||||||
|
Style::Plain => format!("**{text}**"),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// The glossary entries a lecture's targets list, each kind in the order its
|
||||||
|
/// targets first list them.
|
||||||
|
#[derive(Debug, Default)]
|
||||||
|
struct Needs {
|
||||||
|
terms: Vec<String>,
|
||||||
|
equations: Vec<String>,
|
||||||
|
values: Vec<String>,
|
||||||
|
misconceptions: Vec<String>,
|
||||||
|
}
|
||||||
|
|
||||||
|
impl Needs {
|
||||||
|
/// Collects from targets in page order.
|
||||||
|
fn of(course: &CourseFile, targets: &[&str]) -> Needs {
|
||||||
|
let mut needs = Needs::default();
|
||||||
|
for id in targets {
|
||||||
|
let Some(target) = course.learning_targets.get(*id) else {
|
||||||
|
continue;
|
||||||
|
};
|
||||||
|
for (into, from) in [
|
||||||
|
(&mut needs.terms, &target.terms),
|
||||||
|
(&mut needs.equations, &target.equations),
|
||||||
|
(&mut needs.values, &target.values),
|
||||||
|
(&mut needs.misconceptions, &target.misconceptions),
|
||||||
|
] {
|
||||||
|
for x in from {
|
||||||
|
if !into.contains(x) {
|
||||||
|
into.push(x.clone());
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
needs
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Renders the whole page for one lecture: what the lecture is, what it asks of
|
||||||
|
/// a student, and everything they study from.
|
||||||
|
///
|
||||||
|
/// # Arguments
|
||||||
|
///
|
||||||
|
/// * `course` - the loaded course file.
|
||||||
|
/// * `lecture` - the lecture id.
|
||||||
|
/// * `options` - the Markdown flavour and the glossary page's address.
|
||||||
|
///
|
||||||
|
/// # Returns
|
||||||
|
///
|
||||||
|
/// The Markdown, ending in a newline. A section with nothing in it is left
|
||||||
|
/// out.
|
||||||
|
///
|
||||||
|
/// # Errors
|
||||||
|
///
|
||||||
|
/// Returns [`Error::Unresolved`] when the lecture id, or a reference a reading
|
||||||
|
/// cites, is not registered.
|
||||||
|
pub fn page_markdown(course: &CourseFile, lecture: &str, options: &PageOptions) -> Result<String> {
|
||||||
|
let lec = course.lecture(lecture, "lecture page")?;
|
||||||
|
let numbers = numbered_targets(course, lecture);
|
||||||
|
let ordered: Vec<&str> = numbers
|
||||||
|
.iter()
|
||||||
|
.filter(|id| course.is_target(id))
|
||||||
|
.map(String::as_str)
|
||||||
|
.collect();
|
||||||
|
let needs = Needs::of(course, &ordered);
|
||||||
|
let (new_terms, earlier_terms): (Vec<&String>, Vec<&String>) = needs
|
||||||
|
.terms
|
||||||
|
.iter()
|
||||||
|
.filter(|id| course.terms.contains_key(*id))
|
||||||
|
.partition(|id| course.first_lecture(id) == Some(lecture));
|
||||||
|
|
||||||
|
let anchored: BTreeSet<String> = new_terms
|
||||||
|
.iter()
|
||||||
|
.map(|id| id.to_string())
|
||||||
|
.chain(needs.equations.iter().cloned())
|
||||||
|
.collect();
|
||||||
|
let page = Page {
|
||||||
|
course,
|
||||||
|
options,
|
||||||
|
numbers,
|
||||||
|
anchored,
|
||||||
|
};
|
||||||
|
|
||||||
|
let mut out = format!("# {lecture}: {}\n\n", lec.title);
|
||||||
|
if let Some(description) = &lec.description {
|
||||||
|
out.push_str(&format!("{}\n\n", page.prose(description)));
|
||||||
|
}
|
||||||
|
out.push_str(&objectives_section(&page, lecture));
|
||||||
|
out.push_str(&terms_section(&page, &new_terms, &earlier_terms));
|
||||||
|
out.push_str(&equations_section(&page, &needs.equations));
|
||||||
|
out.push_str(&values_section(&page, &needs.values));
|
||||||
|
out.push_str(&mistakes_section(&page, &needs.misconceptions));
|
||||||
|
out.push_str(&page_readings_section(&page, lec.readings.as_slice())?);
|
||||||
|
out.push_str(&materials_section(&page, lec));
|
||||||
|
Ok(format!("{}\n", out.trim_end()))
|
||||||
|
}
|
||||||
|
|
||||||
|
/// One target or untiered objective, as a list item with its level label and
|
||||||
|
/// explanation.
|
||||||
|
fn target_item(page: &Page<'_>, id: &str) -> String {
|
||||||
|
let course = page.course;
|
||||||
|
let text = page.prose(&course.text_for(id));
|
||||||
|
let level = course
|
||||||
|
.effective_level_ceiling(id)
|
||||||
|
.map(|l| format!(" ({})", course.policy.level_name(l)))
|
||||||
|
.unwrap_or_default();
|
||||||
|
let explanation = course
|
||||||
|
.learning_targets
|
||||||
|
.get(id)
|
||||||
|
.and_then(|t| t.explanation.as_deref())
|
||||||
|
.map(|e| page.prose(e));
|
||||||
|
match page.options.style {
|
||||||
|
Style::Quarto => {
|
||||||
|
let mut item = format!("(@) **{text}**{level}\n");
|
||||||
|
if let Some(e) = explanation {
|
||||||
|
item.push_str(&format!("\n {e}\n\n"));
|
||||||
|
}
|
||||||
|
item
|
||||||
|
}
|
||||||
|
Style::Plain => {
|
||||||
|
let mut item = format!("- **{text}**{level}\n");
|
||||||
|
if let Some(e) = explanation {
|
||||||
|
item.push_str(&format!(" {e}\n"));
|
||||||
|
}
|
||||||
|
item
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Each objective with its description and its targets.
|
||||||
|
fn objectives_section(page: &Page<'_>, lecture: &str) -> String {
|
||||||
|
let course = page.course;
|
||||||
|
let mut out = String::new();
|
||||||
|
if !is_tiered(course, lecture) {
|
||||||
|
// Every entry is an objective standing as its own target, so the
|
||||||
|
// objectives are the list, in the numbering the readings point at.
|
||||||
|
out.push_str("## Objectives\n\n");
|
||||||
|
for id in &page.numbers {
|
||||||
|
out.push_str(&target_item(page, id));
|
||||||
|
}
|
||||||
|
out.push('\n');
|
||||||
|
return out;
|
||||||
|
}
|
||||||
|
let (groups, leftovers) = target_layout(course, lecture);
|
||||||
|
for (objective, targets) in groups {
|
||||||
|
out.push_str(&format!(
|
||||||
|
"## {}\n\n",
|
||||||
|
page.prose(&course.text_for(objective))
|
||||||
|
));
|
||||||
|
if let Some(description) = course
|
||||||
|
.learning_objectives
|
||||||
|
.get(objective)
|
||||||
|
.and_then(|o| o.description.as_deref())
|
||||||
|
{
|
||||||
|
out.push_str(&format!("{}\n\n", page.prose(description)));
|
||||||
|
}
|
||||||
|
for target in targets {
|
||||||
|
out.push_str(&target_item(page, target));
|
||||||
|
}
|
||||||
|
out.push('\n');
|
||||||
|
}
|
||||||
|
if !leftovers.is_empty() {
|
||||||
|
out.push_str("## Also covered\n\n");
|
||||||
|
for id in leftovers {
|
||||||
|
out.push_str(&target_item(page, id));
|
||||||
|
}
|
||||||
|
out.push('\n');
|
||||||
|
}
|
||||||
|
out
|
||||||
|
}
|
||||||
|
|
||||||
|
/// The terms new in this lecture, then those introduced earlier.
|
||||||
|
fn terms_section(page: &Page<'_>, new: &[&String], earlier: &[&String]) -> String {
|
||||||
|
let course = page.course;
|
||||||
|
let mut out = String::new();
|
||||||
|
if !new.is_empty() {
|
||||||
|
out.push_str("## New terms\n\n");
|
||||||
|
for id in new {
|
||||||
|
let term = &course.terms[id.as_str()];
|
||||||
|
let symbol = term
|
||||||
|
.symbol
|
||||||
|
.as_deref()
|
||||||
|
.map(|s| format!(" {}", s.trim()))
|
||||||
|
.unwrap_or_default();
|
||||||
|
// The textbook name matters for a renamed or coined term, which a
|
||||||
|
// student cannot otherwise look up; for a standard one it repeats
|
||||||
|
// the term.
|
||||||
|
let textbook = if matches!(term.kind, TermKind::Renamed | TermKind::Coined)
|
||||||
|
&& !term.textbook.is_empty()
|
||||||
|
{
|
||||||
|
let names: Vec<&str> = term.textbook.iter().map(|t| t.term.as_str()).collect();
|
||||||
|
format!(" (textbooks: {})", names.join("; "))
|
||||||
|
} else {
|
||||||
|
String::new()
|
||||||
|
};
|
||||||
|
out.push_str(&format!(
|
||||||
|
"- {}{symbol}: {}{textbook}\n",
|
||||||
|
page.label(id, &term.term),
|
||||||
|
page.prose(&term.definition)
|
||||||
|
));
|
||||||
|
}
|
||||||
|
out.push('\n');
|
||||||
|
}
|
||||||
|
if !earlier.is_empty() {
|
||||||
|
if new.is_empty() {
|
||||||
|
out.push_str("## Terms\n\n");
|
||||||
|
}
|
||||||
|
let listed: Vec<String> = earlier
|
||||||
|
.iter()
|
||||||
|
.map(|id| {
|
||||||
|
let first = course.first_lecture(id).unwrap_or("?");
|
||||||
|
format!(
|
||||||
|
"[{}]({}) ({first})",
|
||||||
|
course.terms[id.as_str()].term,
|
||||||
|
page.href(id)
|
||||||
|
)
|
||||||
|
})
|
||||||
|
.collect();
|
||||||
|
out.push_str(&format!(
|
||||||
|
"Terms from earlier lectures: {}\n\n",
|
||||||
|
listed.join(", ")
|
||||||
|
));
|
||||||
|
}
|
||||||
|
out
|
||||||
|
}
|
||||||
|
|
||||||
|
/// The equations the lecture's targets turn on, each in full.
|
||||||
|
fn equations_section(page: &Page<'_>, ids: &[String]) -> String {
|
||||||
|
let course = page.course;
|
||||||
|
let present: Vec<&String> = ids
|
||||||
|
.iter()
|
||||||
|
.filter(|id| course.equations.contains_key(*id))
|
||||||
|
.collect();
|
||||||
|
if present.is_empty() {
|
||||||
|
return String::new();
|
||||||
|
}
|
||||||
|
let mut out = String::from("## Equations\n\n");
|
||||||
|
for id in present {
|
||||||
|
let eq = &course.equations[id.as_str()];
|
||||||
|
match page.options.style {
|
||||||
|
Style::Quarto => {
|
||||||
|
out.push_str(&format!("### {} {{#{}}}\n\n", eq.name, anchor(id)));
|
||||||
|
}
|
||||||
|
Style::Plain => out.push_str(&format!("### {}\n\n", eq.name)),
|
||||||
|
}
|
||||||
|
out.push_str(&format!("$${}$$\n\n", eq.tex.trim()));
|
||||||
|
out.push_str(&format!("{}\n\n", page.prose(&eq.says)));
|
||||||
|
let mut lines = Vec::new();
|
||||||
|
for symbol in &eq.symbols {
|
||||||
|
let term = symbol.term.as_deref().and_then(|t| course.terms.get(t));
|
||||||
|
let meaning = term
|
||||||
|
.map(|t| t.term.clone())
|
||||||
|
.or_else(|| symbol.meaning.as_deref().map(|m| page.prose(m)))
|
||||||
|
.unwrap_or_default();
|
||||||
|
let units = symbol
|
||||||
|
.units
|
||||||
|
.as_deref()
|
||||||
|
.or_else(|| term.and_then(|t| t.units.as_deref()))
|
||||||
|
.map(|u| format!(" ({u})"))
|
||||||
|
.unwrap_or_default();
|
||||||
|
lines.push(format!("{}: {meaning}{units}", page.math(&symbol.symbol)));
|
||||||
|
}
|
||||||
|
for implication in &eq.implications {
|
||||||
|
lines.push(format!(
|
||||||
|
"What it tells you ({}): {}",
|
||||||
|
implication.form.label(),
|
||||||
|
page.prose(&implication.statement)
|
||||||
|
));
|
||||||
|
}
|
||||||
|
for a in &eq.assumes {
|
||||||
|
lines.push(format!("Assumes: {}", page.prose(a)));
|
||||||
|
}
|
||||||
|
for a in &eq.fails_when {
|
||||||
|
lines.push(format!("Fails when: {}", page.prose(a)));
|
||||||
|
}
|
||||||
|
for line in lines {
|
||||||
|
out.push_str(&format!("- {line}\n"));
|
||||||
|
}
|
||||||
|
out.push('\n');
|
||||||
|
}
|
||||||
|
out
|
||||||
|
}
|
||||||
|
|
||||||
|
/// The numbers the lecture's targets use, in their one approved wording.
|
||||||
|
fn values_section(page: &Page<'_>, ids: &[String]) -> String {
|
||||||
|
let course = page.course;
|
||||||
|
let present: Vec<&String> = ids
|
||||||
|
.iter()
|
||||||
|
.filter(|id| course.values.contains_key(*id))
|
||||||
|
.collect();
|
||||||
|
if present.is_empty() {
|
||||||
|
return String::new();
|
||||||
|
}
|
||||||
|
let mut out = String::from("## Numbers to know\n\n");
|
||||||
|
for id in present {
|
||||||
|
let value = &course.values[id.as_str()];
|
||||||
|
let recall = if value.recall == Some(true) {
|
||||||
|
" (know this one)"
|
||||||
|
} else {
|
||||||
|
""
|
||||||
|
};
|
||||||
|
out.push_str(&format!("- {}: {}{recall}\n", value.name, value.say));
|
||||||
|
}
|
||||||
|
out.push('\n');
|
||||||
|
out
|
||||||
|
}
|
||||||
|
|
||||||
|
/// The mistakes the lecture's targets draw on, each with its correction.
|
||||||
|
fn mistakes_section(page: &Page<'_>, ids: &[String]) -> String {
|
||||||
|
let course = page.course;
|
||||||
|
let present: Vec<&String> = ids
|
||||||
|
.iter()
|
||||||
|
.filter(|id| course.misconceptions.contains_key(*id))
|
||||||
|
.collect();
|
||||||
|
if present.is_empty() {
|
||||||
|
return String::new();
|
||||||
|
}
|
||||||
|
let mut out = String::from("## Common mistakes\n\n");
|
||||||
|
for id in present {
|
||||||
|
let m = &course.misconceptions[id.as_str()];
|
||||||
|
out.push_str(&format!(
|
||||||
|
"- *{}* {}\n",
|
||||||
|
page.prose(&m.belief),
|
||||||
|
page.prose(&m.correction)
|
||||||
|
));
|
||||||
|
}
|
||||||
|
out.push('\n');
|
||||||
|
out
|
||||||
|
}
|
||||||
|
|
||||||
|
/// The readings, each with its reading time, and what to take from it.
|
||||||
|
fn page_readings_section(page: &Page<'_>, readings: &[Reading]) -> Result<String> {
|
||||||
|
if readings.is_empty() {
|
||||||
|
return Ok(String::new());
|
||||||
|
}
|
||||||
|
let course = page.course;
|
||||||
|
let mut out = String::from("## Readings\n\n");
|
||||||
|
let minutes: u32 = readings
|
||||||
|
.iter()
|
||||||
|
.filter(|r| r.role == ReadingRole::Assigned)
|
||||||
|
.filter_map(|r| r.minutes)
|
||||||
|
.sum();
|
||||||
|
if minutes > 0 {
|
||||||
|
out.push_str(&format!("About {minutes} minutes of assigned reading.\n\n"));
|
||||||
|
}
|
||||||
|
for role in [ReadingRole::Assigned, ReadingRole::Supplemental] {
|
||||||
|
let group: Vec<&Reading> = readings.iter().filter(|r| r.role == role).collect();
|
||||||
|
if group.is_empty() {
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
if role == ReadingRole::Supplemental {
|
||||||
|
out.push_str("\n### Supplemental\n\n");
|
||||||
|
}
|
||||||
|
for reading in group {
|
||||||
|
let Some(key) = reading.reference.as_deref() else {
|
||||||
|
if let Some(text) = &reading.text {
|
||||||
|
out.push_str(&format!("- {text}\n"));
|
||||||
|
}
|
||||||
|
continue;
|
||||||
|
};
|
||||||
|
let reference = course.reference(key, "lecture page")?;
|
||||||
|
let label = reference.label_or(key);
|
||||||
|
let locator = reading.locator.as_deref().unwrap_or("");
|
||||||
|
let place = match (page.options.style, reading.resolve_url(reference)) {
|
||||||
|
(Style::Quarto, Some(url)) if !locator.is_empty() => format!("[{locator}]({url})"),
|
||||||
|
(Style::Quarto, Some(url)) => format!("[{}]({url})", reference.title),
|
||||||
|
_ if !locator.is_empty() => locator.to_string(),
|
||||||
|
_ => reference.title.clone(),
|
||||||
|
};
|
||||||
|
let time = reading
|
||||||
|
.minutes
|
||||||
|
.map(|m| format!(" ({m} min)"))
|
||||||
|
.unwrap_or_default();
|
||||||
|
let focus = reading
|
||||||
|
.focus
|
||||||
|
.as_deref()
|
||||||
|
.map(|f| format!(": {}", page.prose(f)))
|
||||||
|
.unwrap_or_default();
|
||||||
|
out.push_str(&format!("- {label} {place}{time}{focus}\n"));
|
||||||
|
for extra in [&reading.summary, &reading.skip].into_iter().flatten() {
|
||||||
|
out.push_str(&format!(" {}\n", page.prose(extra)));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
out.push('\n');
|
||||||
|
Ok(out)
|
||||||
|
}
|
||||||
|
|
||||||
|
/// The lecture's links: its materials, and the older `slides_url` when no
|
||||||
|
/// material is the slides.
|
||||||
|
fn materials_section(page: &Page<'_>, lecture: &crate::course::Lecture) -> String {
|
||||||
|
let mut links: Vec<(String, String)> = lecture
|
||||||
|
.materials
|
||||||
|
.iter()
|
||||||
|
.map(|m| (m.label().to_string(), m.url.clone()))
|
||||||
|
.collect();
|
||||||
|
let has_slides = lecture
|
||||||
|
.materials
|
||||||
|
.iter()
|
||||||
|
.any(|m| m.kind == crate::course::glossary::MaterialKind::Slides);
|
||||||
|
if let (Some(url), false) = (&lecture.slides_url, has_slides) {
|
||||||
|
links.insert(0, ("slides".to_string(), url.clone()));
|
||||||
|
}
|
||||||
|
if links.is_empty() {
|
||||||
|
return String::new();
|
||||||
|
}
|
||||||
|
let mut out = String::from("## Materials\n\n");
|
||||||
|
for (title, url) in links {
|
||||||
|
match page.options.style {
|
||||||
|
Style::Quarto => out.push_str(&format!("- [{title}]({url})\n")),
|
||||||
|
Style::Plain => out.push_str(&format!("- {title}: {url}\n")),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
out
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Renders the course glossary page: every term alphabetically with its
|
||||||
|
/// definition and the lecture that introduces it, then every equation and every
|
||||||
|
/// value with theirs.
|
||||||
|
///
|
||||||
|
/// # Arguments
|
||||||
|
///
|
||||||
|
/// * `course` - the loaded course file.
|
||||||
|
/// * `options` - the Markdown flavour. Links between entries stay on this
|
||||||
|
/// page.
|
||||||
|
///
|
||||||
|
/// # Returns
|
||||||
|
///
|
||||||
|
/// The Markdown, ending in a newline.
|
||||||
|
pub fn glossary_markdown(course: &CourseFile, options: &PageOptions) -> String {
|
||||||
|
let options = PageOptions {
|
||||||
|
glossary_href: String::new(),
|
||||||
|
..options.clone()
|
||||||
|
};
|
||||||
|
let page = Page {
|
||||||
|
course,
|
||||||
|
options: &options,
|
||||||
|
numbers: Vec::new(),
|
||||||
|
anchored: course
|
||||||
|
.terms
|
||||||
|
.keys()
|
||||||
|
.chain(course.equations.keys())
|
||||||
|
.cloned()
|
||||||
|
.collect(),
|
||||||
|
};
|
||||||
|
let first = |id: &str| match course.first_lecture(id) {
|
||||||
|
Some(lecture) => {
|
||||||
|
let title = course
|
||||||
|
.lectures
|
||||||
|
.get(lecture)
|
||||||
|
.map(|l| format!(": {}", l.title))
|
||||||
|
.unwrap_or_default();
|
||||||
|
format!(" *First in {lecture}{title}.*")
|
||||||
|
}
|
||||||
|
None => String::new(),
|
||||||
|
};
|
||||||
|
|
||||||
|
let mut out = String::from("# Glossary\n\n");
|
||||||
|
if !course.terms.is_empty() {
|
||||||
|
out.push_str("## Terms\n\n");
|
||||||
|
let mut terms: Vec<(&String, &crate::course::glossary::Term)> =
|
||||||
|
course.terms.iter().collect();
|
||||||
|
terms.sort_by_key(|(id, t)| (t.term.to_lowercase(), (*id).clone()));
|
||||||
|
for (id, term) in terms {
|
||||||
|
let symbol = term
|
||||||
|
.symbol
|
||||||
|
.as_deref()
|
||||||
|
.map(|s| format!(" {}", s.trim()))
|
||||||
|
.unwrap_or_default();
|
||||||
|
out.push_str(&format!(
|
||||||
|
"- {}{symbol}: {}{}\n",
|
||||||
|
page.label(id, &term.term),
|
||||||
|
page.prose(&term.definition),
|
||||||
|
first(id)
|
||||||
|
));
|
||||||
|
}
|
||||||
|
out.push('\n');
|
||||||
|
}
|
||||||
|
if !course.equations.is_empty() {
|
||||||
|
out.push_str("## Equations\n\n");
|
||||||
|
let mut equations: Vec<_> = course.equations.iter().collect();
|
||||||
|
equations.sort_by_key(|(id, e)| (e.name.to_lowercase(), (*id).clone()));
|
||||||
|
for (id, eq) in equations {
|
||||||
|
match options.style {
|
||||||
|
Style::Quarto => out.push_str(&format!("### {} {{#{}}}\n\n", eq.name, anchor(id))),
|
||||||
|
Style::Plain => out.push_str(&format!("### {}\n\n", eq.name)),
|
||||||
|
}
|
||||||
|
out.push_str(&format!(
|
||||||
|
"$${}$$\n\n{}{}\n\n",
|
||||||
|
eq.tex.trim(),
|
||||||
|
page.prose(&eq.says),
|
||||||
|
first(id)
|
||||||
|
));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if !course.values.is_empty() {
|
||||||
|
out.push_str("## Numbers\n\n");
|
||||||
|
let mut values: Vec<_> = course.values.iter().collect();
|
||||||
|
values.sort_by_key(|(id, v)| (v.name.to_lowercase(), (*id).clone()));
|
||||||
|
for (id, value) in values {
|
||||||
|
out.push_str(&format!("- {}: {}{}\n", value.name, value.say, first(id)));
|
||||||
|
}
|
||||||
|
out.push('\n');
|
||||||
|
}
|
||||||
|
format!("{}\n", out.trim_end())
|
||||||
|
}
|
||||||
|
|
||||||
#[cfg(test)]
|
#[cfg(test)]
|
||||||
mod tests {
|
mod tests {
|
||||||
use super::*;
|
use super::*;
|
||||||
|
|||||||
@@ -336,7 +336,26 @@ pub fn student(
|
|||||||
course.text_for(objective)
|
course.text_for(objective)
|
||||||
));
|
));
|
||||||
}
|
}
|
||||||
|
// What meeting the target looks like, which is what to
|
||||||
|
// practise towards.
|
||||||
|
if let Some(explanation) = course
|
||||||
|
.learning_targets
|
||||||
|
.get(target)
|
||||||
|
.and_then(|t| t.explanation.as_deref())
|
||||||
|
{
|
||||||
|
out.push_str(&format!(
|
||||||
|
"What meeting it looks like: {}\n\n",
|
||||||
|
course.plain_refs(explanation)
|
||||||
|
));
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
// A named registry misconception carries a student-facing belief
|
||||||
|
// and correction. The option's own text, when it has one, wins for
|
||||||
|
// the belief, and keeps the sentence it has always had.
|
||||||
|
let registry = m
|
||||||
|
.misconception_id
|
||||||
|
.as_deref()
|
||||||
|
.and_then(|id| course.misconceptions.get(id));
|
||||||
if let Some(text) = &m.feedback {
|
if let Some(text) = &m.feedback {
|
||||||
out.push_str(&format!("{text}\n\n"));
|
out.push_str(&format!("{text}\n\n"));
|
||||||
} else if let Some(misconception) = &m.misconception {
|
} else if let Some(misconception) = &m.misconception {
|
||||||
@@ -344,10 +363,38 @@ pub fn student(
|
|||||||
"The option you chose is the one students pick when {misconception}\n\n"
|
"The option you chose is the one students pick when {misconception}\n\n"
|
||||||
));
|
));
|
||||||
}
|
}
|
||||||
|
if let Some(entry) = registry {
|
||||||
|
if m.misconception.is_none() {
|
||||||
|
out.push_str(&format!(
|
||||||
|
"This answer reflects a common mistake: *{}*\n\n",
|
||||||
|
course.plain_refs(&entry.belief)
|
||||||
|
));
|
||||||
|
}
|
||||||
|
out.push_str(&format!("{}\n\n", course.plain_refs(&entry.correction)));
|
||||||
|
}
|
||||||
if !m.study.is_empty() {
|
if !m.study.is_empty() {
|
||||||
out.push_str(&format!("Review: {}\n\n", m.study.join("; ")));
|
out.push_str(&format!("Review: {}\n\n", m.study.join("; ")));
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// The same mistake behind more than one answer is worth more than any
|
||||||
|
// one question: it is the thing to fix once.
|
||||||
|
let groups = shared_mistakes(&summary.missed);
|
||||||
|
if !groups.is_empty() {
|
||||||
|
out.push_str("## The same mistake, more than once\n\n");
|
||||||
|
for (id, numbers) in groups {
|
||||||
|
let Some(entry) = course.misconceptions.get(id) else {
|
||||||
|
continue;
|
||||||
|
};
|
||||||
|
let numbers: Vec<String> = numbers.iter().map(u32::to_string).collect();
|
||||||
|
out.push_str(&format!(
|
||||||
|
"**Questions {}**: *{}*\n\n{}\n\n",
|
||||||
|
numbers.join(", "),
|
||||||
|
course.plain_refs(&entry.belief),
|
||||||
|
course.plain_refs(&entry.correction)
|
||||||
|
));
|
||||||
|
}
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
if let Some(closing) = &opts.closing {
|
if let Some(closing) = &opts.closing {
|
||||||
@@ -366,6 +413,31 @@ pub fn student(
|
|||||||
out
|
out
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Registry misconceptions that more than one missed question drew on.
|
||||||
|
///
|
||||||
|
/// # Arguments
|
||||||
|
///
|
||||||
|
/// * `missed` - a student's missed items.
|
||||||
|
///
|
||||||
|
/// # Returns
|
||||||
|
///
|
||||||
|
/// Each shared misconception id with the question numbers, in order of the
|
||||||
|
/// first question that drew it.
|
||||||
|
pub fn shared_mistakes(missed: &[crate::students::MissedItem]) -> Vec<(&str, Vec<u32>)> {
|
||||||
|
let mut groups: Vec<(&str, Vec<u32>)> = Vec::new();
|
||||||
|
for m in missed {
|
||||||
|
let Some(id) = m.misconception_id.as_deref() else {
|
||||||
|
continue;
|
||||||
|
};
|
||||||
|
match groups.iter_mut().find(|(g, _)| *g == id) {
|
||||||
|
Some((_, numbers)) => numbers.push(m.number),
|
||||||
|
None => groups.push((id, vec![m.number])),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
groups.retain(|(_, numbers)| numbers.len() > 1);
|
||||||
|
groups
|
||||||
|
}
|
||||||
|
|
||||||
/// Writes the instructor's report on one administration.
|
/// Writes the instructor's report on one administration.
|
||||||
///
|
///
|
||||||
/// # Arguments
|
/// # Arguments
|
||||||
|
|||||||
@@ -368,6 +368,12 @@ pub fn student_value(diagnostic: &StudentDiagnostic, config: &RenderConfig) -> V
|
|||||||
.map(|text| markup_value(text, content)),
|
.map(|text| markup_value(text, content)),
|
||||||
);
|
);
|
||||||
pair.insert("target", markup_value(&m.target, content));
|
pair.insert("target", markup_value(&m.target, content));
|
||||||
|
pair.insert_some(
|
||||||
|
"explanation",
|
||||||
|
m.explanation
|
||||||
|
.as_ref()
|
||||||
|
.map(|text| markup_value(text, content)),
|
||||||
|
);
|
||||||
pair
|
pair
|
||||||
})
|
})
|
||||||
.collect(),
|
.collect(),
|
||||||
@@ -381,6 +387,22 @@ pub fn student_value(diagnostic: &StudentDiagnostic, config: &RenderConfig) -> V
|
|||||||
] {
|
] {
|
||||||
value.insert_some(key, text.map(|t| markup_value(t, content)));
|
value.insert_some(key, text.map(|t| markup_value(t, content)));
|
||||||
}
|
}
|
||||||
|
value.insert_some(
|
||||||
|
"mistake",
|
||||||
|
question.mistake.as_ref().map(|mistake| {
|
||||||
|
let mut entry = Value::dict();
|
||||||
|
entry.insert("id", Value::str(&mistake.id));
|
||||||
|
entry.insert_some(
|
||||||
|
"belief",
|
||||||
|
mistake
|
||||||
|
.belief
|
||||||
|
.as_ref()
|
||||||
|
.map(|text| markup_value(text, content)),
|
||||||
|
);
|
||||||
|
entry.insert("correction", markup_value(&mistake.correction, content));
|
||||||
|
entry
|
||||||
|
}),
|
||||||
|
);
|
||||||
value.insert(
|
value.insert(
|
||||||
"taught-in",
|
"taught-in",
|
||||||
Value::Array(question.taught_in.iter().map(Value::str).collect()),
|
Value::Array(question.taught_in.iter().map(Value::str).collect()),
|
||||||
@@ -410,6 +432,33 @@ pub fn student_value(diagnostic: &StudentDiagnostic, config: &RenderConfig) -> V
|
|||||||
),
|
),
|
||||||
);
|
);
|
||||||
|
|
||||||
|
out.insert(
|
||||||
|
"mistakes",
|
||||||
|
Value::Array(
|
||||||
|
diagnostic
|
||||||
|
.mistakes
|
||||||
|
.iter()
|
||||||
|
.map(|group| {
|
||||||
|
let mut entry = Value::dict();
|
||||||
|
entry.insert("id", Value::str(&group.id));
|
||||||
|
entry.insert("belief", markup_value(&group.belief, content));
|
||||||
|
entry.insert("correction", markup_value(&group.correction, content));
|
||||||
|
entry.insert(
|
||||||
|
"questions",
|
||||||
|
Value::Array(
|
||||||
|
group
|
||||||
|
.questions
|
||||||
|
.iter()
|
||||||
|
.map(|n| Value::Int(*n as i64))
|
||||||
|
.collect(),
|
||||||
|
),
|
||||||
|
);
|
||||||
|
entry
|
||||||
|
})
|
||||||
|
.collect(),
|
||||||
|
),
|
||||||
|
);
|
||||||
|
|
||||||
let dropped_questions = if config.student_sections.dropped_questions {
|
let dropped_questions = if config.student_sections.dropped_questions {
|
||||||
diagnostic.dropped_questions.as_slice()
|
diagnostic.dropped_questions.as_slice()
|
||||||
} else {
|
} else {
|
||||||
|
|||||||
@@ -146,6 +146,7 @@
|
|||||||
(
|
(
|
||||||
objective: [A sample objective to work on.],
|
objective: [A sample objective to work on.],
|
||||||
target: [A sample learning target under it.],
|
target: [A sample learning target under it.],
|
||||||
|
explanation: [What a student who has met the target could say about it.],
|
||||||
),
|
),
|
||||||
),
|
),
|
||||||
correct: false,
|
correct: false,
|
||||||
@@ -155,9 +156,28 @@
|
|||||||
class-rate: 0.58,
|
class-rate: 0.58,
|
||||||
feedback: [This is the note written for the option that was chosen.],
|
feedback: [This is the note written for the option that was chosen.],
|
||||||
hint: [This is the question you would ask someone reconsidering that option.],
|
hint: [This is the question you would ask someone reconsidering that option.],
|
||||||
|
mistake: (
|
||||||
|
id: "mis-sample",
|
||||||
|
belief: [A wrong idea, as a student would hold it.],
|
||||||
|
correction: [Why it fails, and what is true instead.],
|
||||||
|
),
|
||||||
taught-in: ("Enthalpy (L1.1), slides 12, 13",),
|
taught-in: ("Enthalpy (L1.1), slides 12, 13",),
|
||||||
review: ((citation: "KKW §6.2", title: "Molecules and Medicine", url: "https://example.edu/6/2"),),
|
review: ((citation: "KKW §6.2", title: "Molecules and Medicine", url: "https://example.edu/6/2"),),
|
||||||
),
|
),
|
||||||
|
(
|
||||||
|
number: 14,
|
||||||
|
level: 2,
|
||||||
|
targets: ("t-sample-gap",),
|
||||||
|
measured: ((target: [A sample learning target under it.],),),
|
||||||
|
correct: false,
|
||||||
|
credit: 0.0,
|
||||||
|
bonus: false,
|
||||||
|
blank: false,
|
||||||
|
class-rate: 0.61,
|
||||||
|
mistake: (id: "mis-sample", correction: [Why it fails, and what is true instead.]),
|
||||||
|
taught-in: (),
|
||||||
|
review: (),
|
||||||
|
),
|
||||||
(
|
(
|
||||||
number: 37,
|
number: 37,
|
||||||
level: 1,
|
level: 1,
|
||||||
@@ -183,6 +203,14 @@
|
|||||||
review: (),
|
review: (),
|
||||||
),
|
),
|
||||||
),
|
),
|
||||||
|
mistakes: (
|
||||||
|
(
|
||||||
|
id: "mis-sample",
|
||||||
|
belief: [A wrong idea, as a student would hold it.],
|
||||||
|
correction: [Why it fails, and what is true instead.],
|
||||||
|
questions: (2, 14),
|
||||||
|
),
|
||||||
|
),
|
||||||
dropped-questions: ((number: 35, full-credit: true),),
|
dropped-questions: ((number: 35, full-credit: true),),
|
||||||
review-lectures: (
|
review-lectures: (
|
||||||
(
|
(
|
||||||
@@ -960,17 +988,24 @@
|
|||||||
let target = [
|
let target = [
|
||||||
#text(weight: "bold")[This question asked you to:] #markup(m.target)
|
#text(weight: "bold")[This question asked you to:] #markup(m.target)
|
||||||
]
|
]
|
||||||
if objective == none {
|
// What meeting the target looks like: the account to practise
|
||||||
|
// towards, from the target's own explanation.
|
||||||
|
let explanation = m.at("explanation", default: none)
|
||||||
|
let lines = (target,)
|
||||||
|
if explanation != none {
|
||||||
|
lines.push(text(size: size-small)[
|
||||||
|
#text(weight: "bold")[What meeting it looks like:] #markup(explanation)
|
||||||
|
])
|
||||||
|
}
|
||||||
|
if objective != none {
|
||||||
|
lines.push(text(size: size-small, fill: luma(110))[
|
||||||
|
Counts toward: #markup(objective)
|
||||||
|
])
|
||||||
|
}
|
||||||
|
if lines.len() == 1 {
|
||||||
target
|
target
|
||||||
} else {
|
} else {
|
||||||
stack(
|
stack(dir: ttb, spacing: step * 0.3, ..lines)
|
||||||
dir: ttb,
|
|
||||||
spacing: step * 0.3,
|
|
||||||
target,
|
|
||||||
text(size: size-small, fill: luma(110))[
|
|
||||||
Counts toward: #markup(objective)
|
|
||||||
],
|
|
||||||
)
|
|
||||||
}
|
}
|
||||||
}),
|
}),
|
||||||
)
|
)
|
||||||
@@ -982,6 +1017,18 @@
|
|||||||
let feedback = q.at("feedback", default: none)
|
let feedback = q.at("feedback", default: none)
|
||||||
if feedback != none { parts.push(markup(feedback)) }
|
if feedback != none { parts.push(markup(feedback)) }
|
||||||
|
|
||||||
|
// A named mistake from the course's registry, written for the student: the
|
||||||
|
// belief (absent when the option's own text already said it) and why it
|
||||||
|
// fails.
|
||||||
|
let mistake = q.at("mistake", default: none)
|
||||||
|
if mistake != none {
|
||||||
|
let belief = mistake.at("belief", default: none)
|
||||||
|
parts.push(callout("A common mistake", {
|
||||||
|
if belief != none [#emph(markup(belief)) ]
|
||||||
|
markup(mistake.correction)
|
||||||
|
}))
|
||||||
|
}
|
||||||
|
|
||||||
let hint = q.at("hint", default: none)
|
let hint = q.at("hint", default: none)
|
||||||
if hint != none { parts.push(callout("Try this", markup(hint))) }
|
if hint != none { parts.push(callout("Try this", markup(hint))) }
|
||||||
|
|
||||||
@@ -1045,7 +1092,9 @@
|
|||||||
q.at("feedback", default: none) != none
|
q.at("feedback", default: none) != none
|
||||||
or q.at("hint", default: none) != none
|
or q.at("hint", default: none) != none
|
||||||
or q.at("worked", default: none) != none
|
or q.at("worked", default: none) != none
|
||||||
|
or q.at("mistake", default: none) != none
|
||||||
or q.at("review", default: ()).len() > 0
|
or q.at("review", default: ()).len() > 0
|
||||||
|
or q.at("measured", default: ()).any(m => m.at("explanation", default: none) != none)
|
||||||
)
|
)
|
||||||
))
|
))
|
||||||
|
|
||||||
@@ -1063,6 +1112,24 @@
|
|||||||
]
|
]
|
||||||
]
|
]
|
||||||
|
|
||||||
|
// The same registry mistake behind more than one missed question: the thing
|
||||||
|
// to fix once, with the questions it cost.
|
||||||
|
#let mistakes = cb-data.at("mistakes", default: ())
|
||||||
|
#if show-feedback and mistakes.len() > 0 [
|
||||||
|
= The same mistake, more than once
|
||||||
|
|
||||||
|
#for group in mistakes [
|
||||||
|
#block(breakable: false, above: entry-gap, width: 100%)[
|
||||||
|
#pad(right: prose-pad-inset)[#stack(
|
||||||
|
dir: ttb,
|
||||||
|
spacing: step,
|
||||||
|
[#text(weight: "bold")[Questions #group.questions.map(str).join(", "):] #emph(markup(group.belief))],
|
||||||
|
markup(group.correction),
|
||||||
|
)]
|
||||||
|
]
|
||||||
|
]
|
||||||
|
]
|
||||||
|
|
||||||
// ─────────────────────────────────────────────────────────────────────────────
|
// ─────────────────────────────────────────────────────────────────────────────
|
||||||
// Footer note
|
// Footer note
|
||||||
// ─────────────────────────────────────────────────────────────────────────────
|
// ─────────────────────────────────────────────────────────────────────────────
|
||||||
|
|||||||
@@ -818,6 +818,91 @@ impl super::CourseFile {
|
|||||||
out
|
out
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Replaces each brace reference in prose with whatever the caller renders
|
||||||
|
/// for it.
|
||||||
|
///
|
||||||
|
/// A reference is a brace pair around a declared id: a prefixed glossary
|
||||||
|
/// id (`{term-...}`, `{eq-...}`, `{val-...}`, `{mis-...}`) or any declared
|
||||||
|
/// objective or target id, which is the 2.0 rule and keeps unprefixed
|
||||||
|
/// target ids working. Anything else, `$U_\text{final}$` or `10^{59}`
|
||||||
|
/// included, passes through untouched.
|
||||||
|
///
|
||||||
|
/// # Arguments
|
||||||
|
///
|
||||||
|
/// * `prose` - the field to expand.
|
||||||
|
/// * `render` - called with each referenced id.
|
||||||
|
///
|
||||||
|
/// # Returns
|
||||||
|
///
|
||||||
|
/// The prose with references replaced.
|
||||||
|
pub fn expand_refs(&self, prose: &str, render: impl Fn(&str) -> String) -> String {
|
||||||
|
let mut out = String::with_capacity(prose.len());
|
||||||
|
let mut rest = prose;
|
||||||
|
while let Some(open) = rest.find('{') {
|
||||||
|
let (head, tail) = rest.split_at(open);
|
||||||
|
out.push_str(head);
|
||||||
|
let Some(close) = tail.find('}') else {
|
||||||
|
out.push_str(tail);
|
||||||
|
return out;
|
||||||
|
};
|
||||||
|
let name = &tail[1..close];
|
||||||
|
if self.resolves(name)
|
||||||
|
|| self.learning_objectives.contains_key(name)
|
||||||
|
|| self.learning_targets.contains_key(name)
|
||||||
|
{
|
||||||
|
out.push_str(&render(name));
|
||||||
|
} else {
|
||||||
|
out.push_str(&tail[..=close]);
|
||||||
|
}
|
||||||
|
rest = &tail[close + 1..];
|
||||||
|
}
|
||||||
|
out.push_str(rest);
|
||||||
|
out
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Prose with every reference rendered as plain words, for a report or a
|
||||||
|
/// terminal: a term as its name, an equation as its name, a value as its
|
||||||
|
/// `say`, a misconception as its belief in quotation marks, and an
|
||||||
|
/// objective or target as its text.
|
||||||
|
///
|
||||||
|
/// # Arguments
|
||||||
|
///
|
||||||
|
/// * `prose` - the field to expand.
|
||||||
|
///
|
||||||
|
/// # Returns
|
||||||
|
///
|
||||||
|
/// The prose, with whitespace runs collapsed to single spaces.
|
||||||
|
pub fn plain_refs(&self, prose: &str) -> String {
|
||||||
|
let collapsed = prose.split_whitespace().collect::<Vec<_>>().join(" ");
|
||||||
|
self.expand_refs(&collapsed, |id| self.ref_words(id))
|
||||||
|
}
|
||||||
|
|
||||||
|
/// The words a reference stands for, as [`plain_refs`](Self::plain_refs)
|
||||||
|
/// prints them.
|
||||||
|
///
|
||||||
|
/// # Arguments
|
||||||
|
///
|
||||||
|
/// * `id` - a declared id of any registry.
|
||||||
|
///
|
||||||
|
/// # Returns
|
||||||
|
///
|
||||||
|
/// The words.
|
||||||
|
pub fn ref_words(&self, id: &str) -> String {
|
||||||
|
if let Some(t) = self.terms.get(id) {
|
||||||
|
return t.term.clone();
|
||||||
|
}
|
||||||
|
if let Some(e) = self.equations.get(id) {
|
||||||
|
return e.name.clone();
|
||||||
|
}
|
||||||
|
if let Some(v) = self.values.get(id) {
|
||||||
|
return v.say.clone();
|
||||||
|
}
|
||||||
|
if let Some(m) = self.misconceptions.get(id) {
|
||||||
|
return format!("\u{201c}{}\u{201d}", m.belief.trim());
|
||||||
|
}
|
||||||
|
self.text_for(id)
|
||||||
|
}
|
||||||
|
|
||||||
/// A lecture's targets in teaching order: its objectives in the order the
|
/// A lecture's targets in teaching order: its objectives in the order the
|
||||||
/// lecture page prints them, each objective's targets by ceiling and then
|
/// lecture page prints them, each objective's targets by ceiling and then
|
||||||
/// id, and then any target the lecture covers whose objective it does not
|
/// id, and then any target the lecture covers whose objective it does not
|
||||||
|
|||||||
@@ -0,0 +1,516 @@
|
|||||||
|
// SPDX-License-Identifier: Prosperity-3.0.0
|
||||||
|
// Copyright Scienting
|
||||||
|
// Source: https://git.scient.ing/education/coursebank
|
||||||
|
|
||||||
|
//! What 2.1 renders: the lecture page, the glossary page, and the student
|
||||||
|
//! reports, and what it must never render for a student.
|
||||||
|
|
||||||
|
mod common;
|
||||||
|
|
||||||
|
use std::path::Path;
|
||||||
|
|
||||||
|
use common::{design, v21_course};
|
||||||
|
use coursebank::assessment::{AssessmentFile, Form};
|
||||||
|
use coursebank::catalog::Catalog;
|
||||||
|
use coursebank::lecture::{PageOptions, Style, glossary_markdown, page_markdown};
|
||||||
|
use coursebank::responses::{Response, ResponseSet};
|
||||||
|
use coursebank::typst::config::{RenderConfig, Variant};
|
||||||
|
|
||||||
|
/// The example lecture page in the Plain style, which is the style the
|
||||||
|
/// preview was written in.
|
||||||
|
fn plain_page(catalog: &Catalog) -> String {
|
||||||
|
let options = PageOptions {
|
||||||
|
style: Style::Plain,
|
||||||
|
..PageOptions::default()
|
||||||
|
};
|
||||||
|
page_markdown(&catalog.course, "l09", &options).expect("renders")
|
||||||
|
}
|
||||||
|
|
||||||
|
/// A page line with its link targets removed: `[gap](glossary.html#x)`
|
||||||
|
/// becomes `[gap]`, which is how the prototype's preview writes a link.
|
||||||
|
fn unlinked(line: &str) -> String {
|
||||||
|
let mut out = String::new();
|
||||||
|
let mut rest = line;
|
||||||
|
while let Some(at) = rest.find("](") {
|
||||||
|
out.push_str(&rest[..=at]);
|
||||||
|
let after = &rest[at + 2..];
|
||||||
|
match after.find(')') {
|
||||||
|
Some(close) => rest = &after[close + 1..],
|
||||||
|
None => {
|
||||||
|
rest = after;
|
||||||
|
break;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
out.push_str(rest);
|
||||||
|
out
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn the_lecture_page_has_the_content_and_order_of_the_preview() {
|
||||||
|
let catalog = Catalog::load(&v21_course("page-snapshot")).unwrap();
|
||||||
|
let rendered: Vec<String> = plain_page(&catalog)
|
||||||
|
.lines()
|
||||||
|
.map(unlinked)
|
||||||
|
.filter(|l| !l.trim().is_empty())
|
||||||
|
.collect();
|
||||||
|
|
||||||
|
let preview_text =
|
||||||
|
std::fs::read_to_string(design().join("examples/v21/lecture-page-preview.md")).unwrap();
|
||||||
|
// The prototype prints a target reference as the raw id; coursebank prints
|
||||||
|
// its number on the page, as the 2.0 readings page always has.
|
||||||
|
let preview_text = preview_text.replace("(T t-align-fill-matrix)", "(T 3)");
|
||||||
|
let preview: Vec<&str> = preview_text
|
||||||
|
.lines()
|
||||||
|
.filter(|l| !l.trim().is_empty() && !l.starts_with("<!--"))
|
||||||
|
.collect();
|
||||||
|
|
||||||
|
// Every preview line appears, in the preview's order.
|
||||||
|
let mut at = 0;
|
||||||
|
for line in &preview {
|
||||||
|
match rendered[at..].iter().position(|r| r == line) {
|
||||||
|
Some(offset) => at += offset + 1,
|
||||||
|
None => panic!(
|
||||||
|
"missing or out of order: {line:?}\n\nrendered:\n{}",
|
||||||
|
rendered.join("\n")
|
||||||
|
),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// And the page adds only what the specification asks for beyond the
|
||||||
|
// prototype: the workload line, and the reading's summary and skip notes.
|
||||||
|
let extra: Vec<&String> = rendered
|
||||||
|
.iter()
|
||||||
|
.filter(|r| !preview.contains(&r.as_str()))
|
||||||
|
.collect();
|
||||||
|
assert_eq!(
|
||||||
|
extra,
|
||||||
|
vec![
|
||||||
|
"About 40 minutes of assigned reading.",
|
||||||
|
" Introduces the alignment matrix and [the global alignment recurrence], then \
|
||||||
|
contrasts the global and local fills.",
|
||||||
|
" Gloss the affine-gap extension. It comes in a later lecture.",
|
||||||
|
],
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn the_quarto_page_anchors_new_terms_and_links_to_them() {
|
||||||
|
let catalog = Catalog::load(&v21_course("page-quarto")).unwrap();
|
||||||
|
let page = page_markdown(&catalog.course, "l09", &PageOptions::default()).unwrap();
|
||||||
|
assert!(page.contains("[**gap penalty**]{#glossary-term-gap-penalty} $d$:"));
|
||||||
|
assert!(page.contains("[gap penalty](#glossary-term-gap-penalty)"));
|
||||||
|
assert!(page.contains("### the global alignment recurrence {#glossary-eq-global-recurrence}"));
|
||||||
|
assert!(page.contains("(@) **Define the alignment matrix"));
|
||||||
|
assert!(page.contains("- $F(i,j)$: the best score"));
|
||||||
|
assert!(page.contains("- [Lecture brief](https://example.edu/briefs/l09)"));
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn a_later_lecture_lists_earlier_terms_with_the_lecture_that_introduced_them() {
|
||||||
|
let root = v21_course("page-later");
|
||||||
|
std::fs::write(
|
||||||
|
root.join("lectures/l10.yaml"),
|
||||||
|
"lectures:\n l10:\n title: Database search\n teaches: [lo-search]\n",
|
||||||
|
)
|
||||||
|
.unwrap();
|
||||||
|
std::fs::write(
|
||||||
|
root.join("objectives/lo-search.yaml"),
|
||||||
|
"learning_objectives:\n lo-search: { text: Search a database., level_ceiling: 2 }\n\
|
||||||
|
learning_targets:\n t-search-seeds:\n text: Explain why a search starts from \
|
||||||
|
short exact matches.\n objective: lo-search\n level_ceiling: 2\n terms: \
|
||||||
|
[term-gap-penalty, term-seed]\nterms:\n term-seed: { term: seed, definition: A short \
|
||||||
|
exact match a search extends. }\n",
|
||||||
|
)
|
||||||
|
.unwrap();
|
||||||
|
let catalog = Catalog::load(&root).unwrap();
|
||||||
|
let course = &catalog.course;
|
||||||
|
assert_eq!(course.first_lecture("term-gap-penalty"), Some("l09"));
|
||||||
|
assert_eq!(course.first_lecture("term-seed"), Some("l10"));
|
||||||
|
assert_eq!(course.first_lecture("val-per-decade"), None);
|
||||||
|
|
||||||
|
let page = page_markdown(course, "l10", &PageOptions::default()).unwrap();
|
||||||
|
assert!(page.contains("[**seed**]{#glossary-term-seed}"), "{page}");
|
||||||
|
assert!(
|
||||||
|
page.contains(
|
||||||
|
"Terms from earlier lectures: [gap penalty](glossary.html#glossary-term-gap-penalty) \
|
||||||
|
(l09)"
|
||||||
|
),
|
||||||
|
"{page}"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn the_glossary_page_lists_terms_alphabetically_with_their_first_lecture() {
|
||||||
|
let catalog = Catalog::load(&v21_course("glossary-page")).unwrap();
|
||||||
|
let page = glossary_markdown(&catalog.course, &PageOptions::default());
|
||||||
|
let terms: Vec<&str> = page
|
||||||
|
.lines()
|
||||||
|
.filter_map(|l| l.strip_prefix("- [**"))
|
||||||
|
.map(|l| l.split("**]").next().unwrap())
|
||||||
|
.collect();
|
||||||
|
assert_eq!(
|
||||||
|
terms,
|
||||||
|
vec![
|
||||||
|
"alignment matrix",
|
||||||
|
"decade",
|
||||||
|
"gap",
|
||||||
|
"gap penalty",
|
||||||
|
"global alignment",
|
||||||
|
"local alignment",
|
||||||
|
"substitution score",
|
||||||
|
"traceback",
|
||||||
|
]
|
||||||
|
);
|
||||||
|
assert!(page.contains("*First in l09: Pairwise alignment.*"));
|
||||||
|
// A link between entries stays on this page.
|
||||||
|
assert!(page.contains("aligned against a [gap](#glossary-term-gap)"));
|
||||||
|
assert!(page.contains("## Equations"));
|
||||||
|
assert!(
|
||||||
|
page.contains("- free energy per ten-fold concentration ratio at 37 °C: about 6 kJ/mol")
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
/// A second item that encodes the same registry misconception, so a student
|
||||||
|
/// who misses both has one mistake behind two answers.
|
||||||
|
const SECOND_ITEM: &str = "
|
||||||
|
- id: q-align-equal-matches
|
||||||
|
status: draft
|
||||||
|
level: 2
|
||||||
|
stem: 'Two alignments of one pair have equal matches. Which scores higher?'
|
||||||
|
learning_targets: [t-align-score-columns]
|
||||||
|
options:
|
||||||
|
- { id: o-fewer-gaps, text: 'The one with fewer gaps.', correct: true }
|
||||||
|
- { id: o-tie, text: 'Neither; equal matches mean equal scores.', misconception_id: mis-only-matches-count }
|
||||||
|
";
|
||||||
|
|
||||||
|
/// The record both items were given on.
|
||||||
|
const RECORD: &str = "
|
||||||
|
assessment: { id: alignment-quiz, title: Alignment quiz }
|
||||||
|
items:
|
||||||
|
- { number: 1, item: q-align-which-scores-higher, learning_targets: [t-align-score-columns] }
|
||||||
|
- { number: 2, item: q-align-equal-matches, learning_targets: [t-align-score-columns] }
|
||||||
|
";
|
||||||
|
|
||||||
|
/// One response row.
|
||||||
|
fn response(student: &str, number: u32, item: &str, chosen: &str, credit: f64) -> Response {
|
||||||
|
Response {
|
||||||
|
administration_id: "BIOSC 1540/2027s/alignment-quiz".into(),
|
||||||
|
course: "BIOSC 1540".into(),
|
||||||
|
term: "2027s".into(),
|
||||||
|
assessment_id: "alignment-quiz".into(),
|
||||||
|
date: None,
|
||||||
|
form: None,
|
||||||
|
form_position: None,
|
||||||
|
student_key: student.into(),
|
||||||
|
sid: None,
|
||||||
|
name: None,
|
||||||
|
email: None,
|
||||||
|
section: None,
|
||||||
|
item_number: number,
|
||||||
|
item_ref: Some(item.into()),
|
||||||
|
item_version: None,
|
||||||
|
variant: None,
|
||||||
|
selected: vec![chosen.into()],
|
||||||
|
selected_source: vec![chosen.into()],
|
||||||
|
eliminated: vec![],
|
||||||
|
eliminated_source: vec![],
|
||||||
|
correct: Some(credit >= 0.999),
|
||||||
|
credit,
|
||||||
|
points_possible: 1.0,
|
||||||
|
score: credit,
|
||||||
|
response_time_seconds: None,
|
||||||
|
level: None,
|
||||||
|
learning_targets: vec!["t-align-score-columns".into()],
|
||||||
|
topics: vec![],
|
||||||
|
bonus: false,
|
||||||
|
dropped: false,
|
||||||
|
dropped_full_credit: false,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// The example with a second item, and the record and responses for a student
|
||||||
|
/// who missed both by the same mistake.
|
||||||
|
fn administered(tag: &str) -> (Catalog, AssessmentFile, ResponseSet) {
|
||||||
|
let root = v21_course(tag);
|
||||||
|
let bank = root.join("banks/alignment.yaml");
|
||||||
|
let mut text = std::fs::read_to_string(&bank).unwrap();
|
||||||
|
text.push_str(SECOND_ITEM);
|
||||||
|
std::fs::write(&bank, text).unwrap();
|
||||||
|
let catalog = Catalog::load(&root).unwrap();
|
||||||
|
let record: AssessmentFile = serde_yaml_ng::from_str(RECORD).unwrap();
|
||||||
|
let mut set = ResponseSet::new();
|
||||||
|
set.rows = vec![
|
||||||
|
response(
|
||||||
|
"s1",
|
||||||
|
1,
|
||||||
|
"q-align-which-scores-higher",
|
||||||
|
"o-matches-only",
|
||||||
|
0.0,
|
||||||
|
),
|
||||||
|
response("s1", 2, "q-align-equal-matches", "o-tie", 0.0),
|
||||||
|
response(
|
||||||
|
"s2",
|
||||||
|
1,
|
||||||
|
"q-align-which-scores-higher",
|
||||||
|
"o-columns-all-count",
|
||||||
|
1.0,
|
||||||
|
),
|
||||||
|
response("s2", 2, "q-align-equal-matches", "o-fewer-gaps", 1.0),
|
||||||
|
];
|
||||||
|
(catalog, record, set)
|
||||||
|
}
|
||||||
|
|
||||||
|
/// The Markdown report for the student who missed both.
|
||||||
|
fn markdown_report(catalog: &Catalog, record: &AssessmentFile, set: &ResponseSet) -> String {
|
||||||
|
let cohort = coursebank::students::summarize(set, &catalog.course, Some(catalog), None);
|
||||||
|
let summary = cohort
|
||||||
|
.students
|
||||||
|
.iter()
|
||||||
|
.find(|s| s.student_key == "s1")
|
||||||
|
.unwrap();
|
||||||
|
coursebank::report::student(
|
||||||
|
summary,
|
||||||
|
&cohort,
|
||||||
|
&catalog.course,
|
||||||
|
record,
|
||||||
|
&coursebank::report::StudentOptions::default(),
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
/// The PDF report's payload for the student who missed both, as Typst source.
|
||||||
|
fn typst_report(catalog: &Catalog, set: &ResponseSet) -> String {
|
||||||
|
let cohort = coursebank::students::summarize(set, &catalog.course, Some(catalog), None);
|
||||||
|
let summary = cohort
|
||||||
|
.students
|
||||||
|
.iter()
|
||||||
|
.find(|s| s.student_key == "s1")
|
||||||
|
.unwrap();
|
||||||
|
let diagnostic = coursebank::diagnostic::student(
|
||||||
|
summary,
|
||||||
|
&cohort,
|
||||||
|
catalog,
|
||||||
|
set,
|
||||||
|
None,
|
||||||
|
&coursebank::diagnostic::Options::default(),
|
||||||
|
);
|
||||||
|
let config = RenderConfig::for_variant(Variant::StudentReport);
|
||||||
|
coursebank::typst::diagnostic::student_value(&diagnostic, &config).to_typst(0)
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn a_student_report_explains_the_target_and_groups_misses_by_misconception() {
|
||||||
|
let (catalog, record, set) = administered("report-markdown");
|
||||||
|
let report = markdown_report(&catalog, &record, &set);
|
||||||
|
|
||||||
|
assert!(
|
||||||
|
report.contains(
|
||||||
|
"What meeting it looks like: An alignment's score is the sum over its columns."
|
||||||
|
),
|
||||||
|
"{report}"
|
||||||
|
);
|
||||||
|
// The registry's belief and correction, for an option that names the
|
||||||
|
// misconception and says nothing itself.
|
||||||
|
assert!(
|
||||||
|
report.contains(
|
||||||
|
"This answer reflects a common mistake: *An alignment score counts the matching \
|
||||||
|
positions"
|
||||||
|
),
|
||||||
|
"{report}"
|
||||||
|
);
|
||||||
|
assert!(
|
||||||
|
report.contains("Every column counts: matches add"),
|
||||||
|
"{report}"
|
||||||
|
);
|
||||||
|
// Both misses share the misconception, so they are grouped under it.
|
||||||
|
assert!(
|
||||||
|
report.contains("## The same mistake, more than once\n\n**Questions 1, 2**:"),
|
||||||
|
"{report}"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn the_pdf_report_carries_the_same_explanation_mistake_and_grouping() {
|
||||||
|
let (catalog, _, set) = administered("report-typst");
|
||||||
|
let payload = typst_report(&catalog, &set);
|
||||||
|
assert!(payload.contains("explanation:"), "{payload}");
|
||||||
|
assert!(payload.contains("mistake: ("), "{payload}");
|
||||||
|
assert!(payload.contains("mis-only-matches-count"), "{payload}");
|
||||||
|
let compact: String = payload.split_whitespace().collect();
|
||||||
|
assert!(
|
||||||
|
compact.contains("mistakes:((id:\"mis-only-matches-count\""),
|
||||||
|
"{payload}"
|
||||||
|
);
|
||||||
|
assert!(compact.contains("questions:(1,2,)"), "{payload}");
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Instructor-facing text that must never reach a student: `authoring`,
|
||||||
|
/// `notes_private`, `evidence`, `conflicts`, and `status`.
|
||||||
|
fn private_text(catalog: &Catalog) -> Vec<String> {
|
||||||
|
let course = &catalog.course;
|
||||||
|
let mut out = Vec::new();
|
||||||
|
for target in course.learning_targets.values() {
|
||||||
|
if let Some(a) = &target.authoring {
|
||||||
|
out.extend(a.ceiling_item.clone());
|
||||||
|
out.extend(a.number_work.clone());
|
||||||
|
out.extend(a.supplied.iter().cloned());
|
||||||
|
out.extend(a.constraints.iter().cloned());
|
||||||
|
out.extend(a.examples.iter().cloned());
|
||||||
|
}
|
||||||
|
}
|
||||||
|
for m in course.misconceptions.values() {
|
||||||
|
out.extend(m.evidence.iter().filter_map(|e| e.detail.clone()));
|
||||||
|
}
|
||||||
|
for v in course.values.values() {
|
||||||
|
out.extend(v.conflicts.iter().cloned());
|
||||||
|
}
|
||||||
|
out.extend(
|
||||||
|
course
|
||||||
|
.terms
|
||||||
|
.values()
|
||||||
|
.filter_map(|t| t.notes_private.clone()),
|
||||||
|
);
|
||||||
|
out.extend(
|
||||||
|
course
|
||||||
|
.equations
|
||||||
|
.values()
|
||||||
|
.filter_map(|e| e.notes_private.clone()),
|
||||||
|
);
|
||||||
|
out.extend(
|
||||||
|
course
|
||||||
|
.values
|
||||||
|
.values()
|
||||||
|
.filter_map(|v| v.notes_private.clone()),
|
||||||
|
);
|
||||||
|
out.extend(
|
||||||
|
course
|
||||||
|
.misconceptions
|
||||||
|
.values()
|
||||||
|
.filter_map(|m| m.notes_private.clone()),
|
||||||
|
);
|
||||||
|
|
||||||
|
// A short note can repeat words a student-facing field also uses (`supplied:
|
||||||
|
// the scoring scheme` beside a target that says "the scoring scheme"), and
|
||||||
|
// finding those on a page proves nothing. Only text that appears nowhere a
|
||||||
|
// student is meant to read is a test of the rule.
|
||||||
|
let public: Vec<String> = course
|
||||||
|
.student_prose()
|
||||||
|
.iter()
|
||||||
|
.map(|p| p.text.to_string())
|
||||||
|
.chain(catalog.entries.iter().flat_map(|e| {
|
||||||
|
std::iter::once(e.item.stem.clone())
|
||||||
|
.chain(e.item.options.iter().map(|o| o.text.clone()))
|
||||||
|
}))
|
||||||
|
.collect();
|
||||||
|
out.retain(|secret| !public.iter().any(|p| p.contains(secret.as_str())));
|
||||||
|
out
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn instructor_fields_never_reach_a_student_page_report_or_export() {
|
||||||
|
let (mut catalog, record, set) = administered("rule-5");
|
||||||
|
// The example has no private notes, so give every registry entry one.
|
||||||
|
let course = &mut catalog.course;
|
||||||
|
for (id, t) in course.terms.iter_mut() {
|
||||||
|
t.notes_private = Some(format!("PRIVATE NOTE on {id}"));
|
||||||
|
}
|
||||||
|
for (id, e) in course.equations.iter_mut() {
|
||||||
|
e.notes_private = Some(format!("PRIVATE NOTE on {id}"));
|
||||||
|
}
|
||||||
|
for (id, v) in course.values.iter_mut() {
|
||||||
|
v.notes_private = Some(format!("PRIVATE NOTE on {id}"));
|
||||||
|
}
|
||||||
|
for (id, m) in course.misconceptions.iter_mut() {
|
||||||
|
m.notes_private = Some(format!("PRIVATE NOTE on {id}"));
|
||||||
|
}
|
||||||
|
// Every course in the wild that has a proposed entry would print the word
|
||||||
|
// somewhere if status leaked; the example has two.
|
||||||
|
let secrets = private_text(&catalog);
|
||||||
|
assert!(secrets.len() > 10, "{secrets:#?}");
|
||||||
|
|
||||||
|
let form = Form {
|
||||||
|
id: "A".into(),
|
||||||
|
seed: 0,
|
||||||
|
shuffle_items: false,
|
||||||
|
shuffle_options: false,
|
||||||
|
};
|
||||||
|
let mut outputs: Vec<(String, String)> = Vec::new();
|
||||||
|
for style in [Style::Quarto, Style::Plain] {
|
||||||
|
let options = PageOptions {
|
||||||
|
style,
|
||||||
|
..PageOptions::default()
|
||||||
|
};
|
||||||
|
outputs.push((
|
||||||
|
format!("lecture page ({style:?})"),
|
||||||
|
page_markdown(&catalog.course, "l09", &options).unwrap(),
|
||||||
|
));
|
||||||
|
outputs.push((
|
||||||
|
format!("glossary page ({style:?})"),
|
||||||
|
glossary_markdown(&catalog.course, &options),
|
||||||
|
));
|
||||||
|
}
|
||||||
|
outputs.push((
|
||||||
|
"readings page".into(),
|
||||||
|
coursebank::lecture::readings_markdown(&catalog.course, "l09", Style::Quarto).unwrap(),
|
||||||
|
));
|
||||||
|
outputs.push((
|
||||||
|
"student report".into(),
|
||||||
|
markdown_report(&catalog, &record, &set),
|
||||||
|
));
|
||||||
|
outputs.push(("student PDF report".into(), typst_report(&catalog, &set)));
|
||||||
|
let qti =
|
||||||
|
coursebank::qti::build(&catalog, &record, &coursebank::qti::QtiOptions::default()).unwrap();
|
||||||
|
outputs.push(("Canvas quiz".into(), qti.quiz_xml));
|
||||||
|
for variant in [
|
||||||
|
coursebank::practice::Variant::Worksheet,
|
||||||
|
coursebank::practice::Variant::Solutions,
|
||||||
|
] {
|
||||||
|
let options = coursebank::practice::Options {
|
||||||
|
form: form.clone(),
|
||||||
|
variant,
|
||||||
|
answer_space: false,
|
||||||
|
};
|
||||||
|
outputs.push((
|
||||||
|
format!("practice {variant:?}"),
|
||||||
|
coursebank::practice::render(&catalog, &record, &options).unwrap(),
|
||||||
|
));
|
||||||
|
}
|
||||||
|
let site =
|
||||||
|
coursebank::site::render(&catalog, &record, coursebank::site::Options::new(form)).unwrap();
|
||||||
|
outputs.push(("site page".into(), site.page));
|
||||||
|
outputs.push(("site questions".into(), site.questions_qmd));
|
||||||
|
|
||||||
|
for (name, text) in &outputs {
|
||||||
|
for secret in &secrets {
|
||||||
|
assert!(
|
||||||
|
!text.contains(secret.as_str()),
|
||||||
|
"{name} prints instructor-facing text {secret:?}"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
assert!(
|
||||||
|
!text.contains("proposed"),
|
||||||
|
"{name} prints an entry's status"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[test]
|
||||||
|
fn the_cli_writes_the_page_and_the_glossary() {
|
||||||
|
let root = v21_course("cli-page");
|
||||||
|
let run = |args: &[&str]| {
|
||||||
|
std::process::Command::new(env!("CARGO_BIN_EXE_coursebank"))
|
||||||
|
.arg("-C")
|
||||||
|
.arg(&root)
|
||||||
|
.args(args)
|
||||||
|
.output()
|
||||||
|
.unwrap()
|
||||||
|
};
|
||||||
|
let page = run(&["lecture", "page", "l09", "--style", "plain"]);
|
||||||
|
assert!(page.status.success());
|
||||||
|
assert!(String::from_utf8_lossy(&page.stdout).starts_with("# l09: Pairwise alignment"));
|
||||||
|
|
||||||
|
let out = root.join("glossary.qmd");
|
||||||
|
let glossary = run(&["lecture", "glossary", "--out", out.to_str().unwrap()]);
|
||||||
|
assert!(glossary.status.success());
|
||||||
|
assert!(Path::new(&out).is_file());
|
||||||
|
}
|
||||||
Reference in new issue
Block a user