feat: splitting

This commit is contained in:
alexm committed 2026-09-26 01:15:12 -04:00
1 parent 220363d4d3
commit eabc98ad31
29 files changed
+4843 -234

No files matched your search

+2 -1
View File
@@ -374,7 +374,7 @@ fn entry(
///
/// A linked citation when the location has a URL, and a plain one when it does not.
fn heading(reading: &Reading, key: &str, reference: &Reference, style: Style) -> String {
let label = reference.label.as_deref().unwrap_or(key);
let label = reference.label_or(key);
let locator = reading.locator.as_deref().unwrap_or("");
let linked = match reading.resolve_url(reference) {
Some(url) if !locator.is_empty() => format!("[{locator}]({url})"),
@@ -428,6 +428,7 @@ mod tests {
date: None,
unit: None,
slides_url: None,
teaches: Vec::new(),
readings: vec![
Reading {
reference: Some("kuriyan2013molecules".into()),
+5 -18
View File
@@ -30,7 +30,7 @@
use crate::assessment::{AssessmentFile, Form, Placement};
use crate::catalog::Catalog;
use crate::course::{CourseFile, Reference};
use crate::course::CourseFile;
use crate::error::Result;
use crate::item::{Choice, Citation, Item};
use crate::markup;
@@ -427,9 +427,9 @@ fn cite(course: &CourseFile, citation: &Citation) -> String {
let Some(reference) = course.references.get(key) else {
return citation.display();
};
let label = reference.label.as_deref().unwrap_or(key);
let label = reference.label_or(key);
let locator = citation.locator.as_deref().unwrap_or("");
match resolve_url(citation, reference) {
match citation.href(reference) {
Some(url) if !locator.is_empty() => format!("`{label}` [{locator}]({url})"),
Some(url) => format!("`{label}` [{}]({url})", reference.title),
None if !locator.is_empty() => format!("`{label}` {locator}"),
@@ -437,21 +437,6 @@ fn cite(course: &CourseFile, citation: &Citation) -> String {
}
}
/// The URL for a citation: its own `url`, else the reference `base_url` joined with
/// the citation `path`.
fn resolve_url(citation: &Citation, reference: &Reference) -> Option<String> {
if let Some(url) = &citation.url {
return Some(url.clone());
}
let path = citation.path.as_deref()?;
let base = reference.base_url.as_deref()?;
Some(match (base.ends_with('/'), path.starts_with('/')) {
(true, true) => format!("{base}{}", &path[1..]),
(false, false) => format!("{base}/{path}"),
_ => format!("{base}{path}"),
})
}
/// The `## Question N` heading, marking a bonus item.
fn heading(number: usize, placement: &Placement) -> String {
let bonus = if placement.bonus { " (bonus)" } else { "" };
@@ -593,6 +578,7 @@ items:
number: 1,
item: "l11::q-enthalpy-001".into(),
version: None,
stem_digest: None,
fingerprint: None,
points: Some(1.0),
bonus: false,
@@ -608,6 +594,7 @@ items:
number: 2,
item: "l11::q-enthalpy-op-001".into(),
version: None,
stem_digest: None,
fingerprint: None,
points: Some(2.0),
bonus: false,
+2
View File
@@ -1389,6 +1389,7 @@ items:
number: 1,
item: "b::q-mcq".into(),
version: None,
stem_digest: None,
fingerprint: None,
points: Some(1.0),
bonus: false,
@@ -1404,6 +1405,7 @@ items:
number: 2,
item: "b::q-open".into(),
version: None,
stem_digest: None,
fingerprint: None,
points: Some(2.0),
bonus: false,
+498
View File
@@ -0,0 +1,498 @@
// SPDX-License-Identifier: Prosperity-3.0.0
// Copyright Scientific Computing Studio
// Source: https://git.scient.ing/education/coursebank
//! The bibliography, in the formats other tools read.
//!
//! `references.yaml` is the authoritative copy, and it is shaped for a reading
//! list: it carries a `label` that reports print, and a `role` saying whether
//! the course requires the work or offers it as background. No general citation
//! format has either field, which is why the course keeps its own.
//!
//! What the other formats are for is everything downstream of the reading list:
//!
//! | Format | Read by | Gets you |
//! |:--|:--|:--|
//! | [`Format::Hayagriva`] | Typst | real citations in a printed exam or report |
//! | [`Format::CslJson`] | Zotero, Pandoc, CSL processors | a bibliography in any style |
//! | [`Format::Bibtex`] | LaTeX, most reference managers | the lowest common denominator |
//!
//! All three are generated. The argument is the same one the lecture reading
//! list makes: two copies of a citation drift within a term, and one copy plus a
//! build step does not.
//!
//! # What does not survive the trip
//!
//! `label`, `role`, `base_url`, and `note` have nowhere to go in any of the
//! three, so they stay behind. That is the reason this is an export rather than
//! a migration: the course file is not recoverable from its own bibliography
//! export, and nothing reads these files back in.
use std::collections::BTreeMap;
use serde::Serialize;
use serde_json::{Value, json};
use crate::course::{CourseFile, Reference, ReferenceKind};
use crate::error::Result;
use crate::yaml;
/// Which citation format to write.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Format {
/// Hayagriva YAML, which Typst's `#bibliography` reads natively.
Hayagriva,
/// CSL-JSON, which Zotero, Pandoc, and every CSL processor read.
CslJson,
/// BibTeX, for LaTeX and for reference managers that read nothing else.
Bibtex,
}
impl Format {
/// The conventional file extension.
pub fn extension(self) -> &'static str {
match self {
Format::Hayagriva => "yml",
Format::CslJson => "json",
Format::Bibtex => "bib",
}
}
/// The name used on the command line.
pub fn label(self) -> &'static str {
match self {
Format::Hayagriva => "hayagriva",
Format::CslJson => "csl-json",
Format::Bibtex => "bibtex",
}
}
}
/// Renders a course's bibliography.
///
/// # Arguments
///
/// * `course` - the loaded course.
/// * `format` - which format to write.
///
/// # Returns
///
/// The document, keyed or ordered by citation key so the output is stable
/// between runs.
///
/// # Errors
///
/// Returns [`crate::error::Error::Other`] if the intermediate structure cannot
/// be serialized.
pub fn render(course: &CourseFile, format: Format) -> Result<String> {
match format {
Format::Hayagriva => hayagriva(course),
Format::CslJson => csl_json(course),
Format::Bibtex => Ok(bibtex(course)),
}
}
// --- Hayagriva ---
/// One Hayagriva entry.
#[derive(Debug, Serialize)]
struct Entry {
#[serde(rename = "type")]
kind: &'static str,
title: String,
#[serde(skip_serializing_if = "Vec::is_empty")]
author: Vec<String>,
#[serde(skip_serializing_if = "Option::is_none")]
date: Option<u32>,
#[serde(skip_serializing_if = "Option::is_none")]
edition: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
publisher: Option<String>,
#[serde(rename = "page-range", skip_serializing_if = "Option::is_none")]
page_range: Option<String>,
#[serde(rename = "serial-number", skip_serializing_if = "BTreeMap::is_empty")]
serial_number: BTreeMap<&'static str, String>,
#[serde(skip_serializing_if = "Option::is_none")]
url: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
parent: Option<Parent>,
}
/// The container a Hayagriva entry sits inside.
#[derive(Debug, Serialize)]
struct Parent {
#[serde(rename = "type")]
kind: &'static str,
title: String,
#[serde(skip_serializing_if = "Option::is_none")]
volume: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
issue: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
publisher: Option<String>,
}
/// Renders the bibliography as Hayagriva YAML.
fn hayagriva(course: &CourseFile) -> Result<String> {
let entries: BTreeMap<&String, Entry> = course
.references
.iter()
.map(|(key, reference)| (key, entry(reference)))
.collect();
yaml::to_string(&entries)
}
/// Maps one reference onto a Hayagriva entry.
fn entry(reference: &Reference) -> Entry {
let mut serial: BTreeMap<&'static str, String> = BTreeMap::new();
for (field, value) in [
("doi", &reference.doi),
("isbn", &reference.isbn),
("arxiv", &reference.arxiv),
("pmid", &reference.pmid),
("pmcid", &reference.pmcid),
] {
if let Some(value) = value {
serial.insert(field, value.clone());
}
}
// A chapter sits in a book and an article sits in a periodical, and
// Hayagriva wants that said with a parent rather than a flat field.
let parent = reference
.container
.as_ref()
.map(|title| match reference.kind {
ReferenceKind::Chapter => Parent {
kind: "book",
title: title.clone(),
volume: reference.volume.clone(),
issue: None,
publisher: reference.publisher.clone(),
},
_ => Parent {
kind: "periodical",
title: title.clone(),
volume: reference.volume.clone(),
issue: reference.issue.clone(),
publisher: None,
},
});
Entry {
kind: hayagriva_kind(reference.kind),
title: reference.title.clone(),
author: reference.authors.clone(),
date: reference.year,
edition: reference.edition.clone(),
// The publisher belongs to the container when there is one.
publisher: if parent.is_some() {
None
} else {
reference.publisher.clone()
},
page_range: reference.pages.clone(),
serial_number: serial,
url: reference.url.clone(),
parent,
}
}
/// The Hayagriva entry type for a course reference kind.
fn hayagriva_kind(kind: ReferenceKind) -> &'static str {
match kind {
ReferenceKind::Book => "book",
ReferenceKind::Chapter => "chapter",
// Hayagriva has no preprint type. An article with no periodical parent
// is what a preprint is anyway.
ReferenceKind::Article | ReferenceKind::Preprint => "article",
ReferenceKind::Thesis => "thesis",
ReferenceKind::Website => "web",
ReferenceKind::Software | ReferenceKind::Dataset => "repository",
ReferenceKind::Video => "video",
ReferenceKind::Other => "misc",
}
}
// --- CSL-JSON ---
/// Renders the bibliography as CSL-JSON.
fn csl_json(course: &CourseFile) -> Result<String> {
let items: Vec<Value> = course
.references
.iter()
.map(|(key, reference)| csl_item(key, reference))
.collect();
serde_json::to_string_pretty(&items)
.map(|text| format!("{text}\n"))
.map_err(crate::error::Error::other)
}
/// One CSL-JSON item.
fn csl_item(key: &str, reference: &Reference) -> Value {
let mut item = json!({
"id": key,
"type": csl_kind(reference.kind),
"title": reference.title,
});
let map = item.as_object_mut().expect("built from a JSON object");
if !reference.authors.is_empty() {
map.insert(
"author".to_string(),
Value::Array(reference.authors.iter().map(|a| csl_name(a)).collect()),
);
}
if let Some(year) = reference.year {
map.insert("issued".to_string(), json!({ "date-parts": [[year]] }));
}
for (field, value) in [
("container-title", &reference.container),
("publisher", &reference.publisher),
("volume", &reference.volume),
("issue", &reference.issue),
("page", &reference.pages),
("edition", &reference.edition),
("DOI", &reference.doi),
("ISBN", &reference.isbn),
("PMID", &reference.pmid),
("PMCID", &reference.pmcid),
("URL", &reference.url),
] {
if let Some(value) = value {
map.insert(field.to_string(), Value::String(value.clone()));
}
}
item
}
/// Splits `Family, Given` into a CSL name, or keeps it whole.
///
/// A name with no comma is not a name this code can take apart — an
/// organization, or a single mononym — so it goes in `literal`, which is what
/// CSL has the field for.
fn csl_name(author: &str) -> Value {
match author.split_once(',') {
Some((family, given)) => json!({
"family": family.trim(),
"given": given.trim(),
}),
None => json!({ "literal": author.trim() }),
}
}
/// The CSL type for a course reference kind.
fn csl_kind(kind: ReferenceKind) -> &'static str {
match kind {
ReferenceKind::Book => "book",
ReferenceKind::Chapter => "chapter",
ReferenceKind::Article => "article-journal",
ReferenceKind::Preprint => "article",
ReferenceKind::Thesis => "thesis",
ReferenceKind::Website => "webpage",
ReferenceKind::Software => "software",
ReferenceKind::Dataset => "dataset",
ReferenceKind::Video => "motion_picture",
ReferenceKind::Other => "document",
}
}
// --- BibTeX ---
/// Renders the bibliography as BibTeX.
fn bibtex(course: &CourseFile) -> String {
let mut out = String::new();
for (key, reference) in &course.references {
out.push_str(&bibtex_entry(key, reference));
out.push('\n');
}
out
}
/// One BibTeX entry.
fn bibtex_entry(key: &str, reference: &Reference) -> String {
let mut fields: Vec<(&str, String)> = vec![("title", reference.title.clone())];
if !reference.authors.is_empty() {
fields.push(("author", reference.authors.join(" and ")));
}
if let Some(year) = reference.year {
fields.push(("year", year.to_string()));
}
if let Some(container) = &reference.container {
let field = match reference.kind {
ReferenceKind::Chapter => "booktitle",
_ => "journal",
};
fields.push((field, container.clone()));
}
for (field, value) in [
("volume", &reference.volume),
("number", &reference.issue),
("edition", &reference.edition),
("publisher", &reference.publisher),
("doi", &reference.doi),
("isbn", &reference.isbn),
("url", &reference.url),
("note", &reference.note),
] {
if let Some(value) = value {
fields.push((field, value.clone()));
}
}
if let Some(pages) = &reference.pages {
fields.push(("pages", en_dash(pages)));
}
let body: String = fields
.iter()
.map(|(field, value)| format!(" {field} = {{{}}},\n", escape_tex(value)))
.collect();
format!("@{}{{{key},\n{body}}}\n", bibtex_kind(reference.kind))
}
/// The BibTeX entry type for a course reference kind.
fn bibtex_kind(kind: ReferenceKind) -> &'static str {
match kind {
ReferenceKind::Book => "book",
ReferenceKind::Chapter => "incollection",
ReferenceKind::Article => "article",
ReferenceKind::Thesis => "phdthesis",
ReferenceKind::Website => "online",
// BibTeX proper has nothing for these. `misc` with a `note` is what
// every style guide says to do, and biblatex users can convert.
ReferenceKind::Preprint
| ReferenceKind::Software
| ReferenceKind::Dataset
| ReferenceKind::Video
| ReferenceKind::Other => "misc",
}
}
/// Escapes the characters BibTeX treats as syntax.
///
/// Deliberately short: a publisher called `John Wiley & Sons` is the case that
/// actually occurs, and escaping more than this risks mangling the `$...$` in a
/// title that carries real mathematics.
fn escape_tex(value: &str) -> String {
value.replace('&', "\\&").replace('%', "\\%")
}
/// Turns a hyphenated page range into the en dash BibTeX expects.
fn en_dash(pages: &str) -> String {
let parts: Vec<&str> = pages.split('-').collect();
if parts.len() == 2 && parts.iter().all(|p| !p.is_empty()) {
return format!("{}--{}", parts[0].trim(), parts[1].trim());
}
pages.to_string()
}
#[cfg(test)]
mod tests {
use super::*;
use crate::course::ReferenceRole;
fn course() -> CourseFile {
let mut c = CourseFile::skeleton("BIOSC 1540", "Computational Biology", "2026f");
c.references.insert(
"ismail2023bioinformatics".into(),
Reference {
label: Some("IBB".into()),
kind: ReferenceKind::Book,
role: ReferenceRole::Supplemental,
title: "Bioinformatics: A practical guide".into(),
authors: vec!["Ismail, H. D.".into()],
year: Some(2023),
publisher: Some("CRC Press".into()),
base_url: Some("https://library.example.org/ismail2023/".into()),
isbn: Some("9781032366423".into()),
..Reference::default()
},
);
c.references.insert(
"altschul1990basic".into(),
Reference {
label: Some("BLAST".into()),
kind: ReferenceKind::Article,
role: ReferenceRole::Required,
title: "Basic local alignment search tool".into(),
authors: vec![
"Altschul, S. F.".into(),
"Gish, W.".into(),
"Wiley & Sons".into(),
],
year: Some(1990),
container: Some("Journal of Molecular Biology".into()),
volume: Some("215".into()),
issue: Some("3".into()),
pages: Some("403-410".into()),
doi: Some("10.1016/S0022-2836(05)80360-2".into()),
pmid: Some("2231712".into()),
..Reference::default()
},
);
c
}
#[test]
fn hayagriva_nests_an_article_under_its_periodical() {
let out = render(&course(), Format::Hayagriva).unwrap();
assert!(out.contains("altschul1990basic:"), "{out}");
assert!(out.contains("type: article"), "{out}");
assert!(out.contains("type: periodical"), "{out}");
assert!(out.contains("Journal of Molecular Biology"), "{out}");
assert!(out.contains("page-range: 403-410"), "{out}");
assert!(out.contains("doi: 10.1016/S0022-2836(05)80360-2"), "{out}");
// Parses back as YAML, which is what Typst will do to it.
let back: serde_yaml_ng::Value = serde_yaml_ng::from_str(&out).unwrap();
assert!(back.get("ismail2023bioinformatics").is_some());
}
#[test]
fn hayagriva_keeps_a_books_publisher_on_the_book() {
let out = render(&course(), Format::Hayagriva).unwrap();
let parsed: serde_yaml_ng::Value = serde_yaml_ng::from_str(&out).unwrap();
let book = parsed.get("ismail2023bioinformatics").unwrap();
assert_eq!(book.get("publisher").unwrap().as_str(), Some("CRC Press"));
assert!(book.get("parent").is_none());
// `label`, `role`, and `base_url` have nowhere to go and stay behind.
assert!(book.get("label").is_none());
assert!(book.get("base_url").is_none());
}
#[test]
fn csl_json_splits_names_and_keeps_organizations_whole() {
let out = render(&course(), Format::CslJson).unwrap();
let items: Vec<Value> = serde_json::from_str(&out).unwrap();
let article = items
.iter()
.find(|i| i["id"] == "altschul1990basic")
.unwrap();
assert_eq!(article["type"], "article-journal");
assert_eq!(article["author"][0]["family"], "Altschul");
assert_eq!(article["author"][0]["given"], "S. F.");
assert_eq!(article["author"][2]["literal"], "Wiley & Sons");
assert_eq!(article["issued"]["date-parts"][0][0], 1990);
assert_eq!(article["DOI"], "10.1016/S0022-2836(05)80360-2");
}
#[test]
fn bibtex_escapes_ampersands_and_dashes_a_page_range() {
let out = render(&course(), Format::Bibtex).unwrap();
assert!(out.contains("@article{altschul1990basic,"), "{out}");
assert!(
out.contains("journal = {Journal of Molecular Biology},"),
"{out}"
);
assert!(out.contains("pages = {403--410},"), "{out}");
assert!(out.contains("Wiley \\& Sons"), "{out}");
assert!(out.contains("@book{ismail2023bioinformatics,"), "{out}");
}
#[test]
fn a_course_with_no_bibliography_renders_empty_rather_than_failing() {
let mut c = course();
c.references.clear();
assert_eq!(render(&c, Format::Bibtex).unwrap(), "");
assert_eq!(render(&c, Format::CslJson).unwrap().trim(), "[]");
}
}
+5 -18
View File
@@ -34,7 +34,7 @@
use crate::assessment::{AssessmentFile, Form, Placement};
use crate::catalog::Catalog;
use crate::course::{CourseFile, Reference};
use crate::course::CourseFile;
use crate::error::{Error, Result};
use crate::item::{Choice, Citation, Item, Solution};
use crate::markup;
@@ -472,7 +472,7 @@ fn cite_html(course: &CourseFile, citation: &Citation) -> String {
let Some(reference) = course.references.get(key) else {
return markup::escape_html(&citation.display());
};
let label = reference.label.as_deref().unwrap_or(key);
let label = reference.label_or(key);
let locator = citation.locator.as_deref().unwrap_or("");
let body = if locator.is_empty() {
markup::escape_html(label)
@@ -483,27 +483,12 @@ fn cite_html(course: &CourseFile, citation: &Citation) -> String {
markup::escape_html(locator)
)
};
match resolve_url(citation, reference) {
match citation.href(reference) {
Some(url) => format!("<a href=\"{}\">{body}</a>", markup::escape_html(&url)),
None => body,
}
}
/// Resolves a citation's link, from an explicit URL or a path joined to the
/// reference's base URL.
fn resolve_url(citation: &Citation, reference: &Reference) -> Option<String> {
if let Some(url) = &citation.url {
return Some(url.clone());
}
let path = citation.path.as_deref()?;
let base = reference.base_url.as_deref()?;
Some(match (base.ends_with('/'), path.starts_with('/')) {
(true, true) => format!("{base}{}", &path[1..]),
(false, false) => format!("{base}/{path}"),
_ => format!("{base}{path}"),
})
}
// --- math-aware markup ---
/// One run of source text, split on math delimiters.
@@ -858,6 +843,7 @@ items:
number: 1,
item: "b::q-mcq".into(),
version: None,
stem_digest: None,
fingerprint: None,
points: Some(1.0),
bonus: false,
@@ -873,6 +859,7 @@ items:
number: 2,
item: "b::q-open".into(),
version: None,
stem_digest: None,
fingerprint: None,
points: Some(2.0),
bonus: false,
+3 -1
View File
@@ -431,6 +431,7 @@ mod tests {
number: 1,
item: "b::q-1".into(),
version: None,
stem_digest: None,
fingerprint: None,
points: None,
bonus: false,
@@ -446,6 +447,7 @@ mod tests {
number: 2,
item: "b::q-2".into(),
version: None,
stem_digest: None,
fingerprint: None,
points: None,
bonus: false,
@@ -464,6 +466,6 @@ mod tests {
.filter(|p| p.was_printed())
.map(|p| p.number)
.collect();
assert_eq!(printable, vec![2]);
assert_eq!(printable, vec![1, 2]);
}
}
+1
View File
@@ -1281,6 +1281,7 @@ mod tests {
blueprint: Vec::new(),
patterns: Vec::new(),
warnings: Vec::new(),
dropped_detail: Vec::new(),
}
}