A register whose every part says where it came from

//! A file whose every part says where it came from.
//!
//! A document says what it is, and that has always been written once, for the
//! whole file. It is not enough for anything assembled out of pieces: a
//! register bound from two sittings, a scan whose plate belongs to somebody
//! other than whoever holds the paper. Here each page carries a packet of its
//! own, the plate on the second page carries one too, and the transcription of
//! each sitting is tied to the page it transcribes rather than to the file at
//! large.
//!
//! Tying a carried file to anything but the document as a whole arrived with
//! PDF 2.0, so the file declares 2.0. Nothing is raised on the caller's behalf:
//! a file that tied one while declaring less would be refused rather than
//! written.
//!
//! The words are held in `Words`, once per language, and `HQF_PDF_LANG` picks
//! which set the register is bound in. Every one of them is written twice: once
//! on the page and once in the packet the page carries, from the one set, so
//! that what a person reads and what a machine reads cannot drift apart. What
//! is not a word stands apart from them — the names the carried files are
//! looked up by, the clerks' own names, and the dates the sittings were written
//! down.
//!
//! Usage: `cargo run --example write_provenance -- tmp/provenance.pdf
//! [font.ttf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_provenance --
//! tmp/provenance_fr.pdf`

use std::env;
use std::fs;
use std::path::{Path, PathBuf};

use hqf_pdf::content::Content;
use hqf_pdf::metadata::attachment::{Attachment, Relationship};
use hqf_pdf::metadata::xmp::{Metadata, Xmp};
use hqf_pdf::{
    AttachmentHandle, Color, Document, Error, Font, FontHandle, Image, ImageHandle, Page, Rgb,
    Version,
};

#[path = "shared/out.rs"]
mod out;

#[path = "shared/licence.rs"]
mod licence;

#[path = "shared/language.rs"]
mod language;

use language::Language;

/// The font the example draws with when none is given on the command line.
fn default_font() -> PathBuf {
    Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("tests")
        .join("fonts")
        .join("DejaVuSans.ttf")
}

/// A4, in points.
const SHEET: (f64, f64) = (595.276, 841.890);

/// How far in from the edge of the sheet everything is set.
const MARGIN: f64 = 64.0;

/// How far in from the left edge what a part says stands, leaving the label to
/// its left.
const SAID: f64 = 220.0;

/// How wide the plate is drawn on the page, in points.
const PLATE: f64 = 180.0;

/// The name the record of the scan is carried under.
const SCAN: &str = "plate-12-scan.xml";

/// One sitting of the register: who wrote it down, when, and the name its
/// transcription is carried under. What the page says of it is a word, and
/// stands in [`Words`] under the same order.
struct Sitting {
    /// Who wrote what is on it, before what such a person is called.
    hand: &'static str,
    /// When it was written down, as the packet states it.
    written: &'static str,
    /// The name the transcription of this sitting is carried under.
    transcript: &'static str,
}

/// The two sittings the register is bound from.
const SITTINGS: [Sitting; 2] = [
    Sitting {
        hand: "R. Delaunay",
        written: "1911-03-14T09:00:00+01:00",
        transcript: "first-sitting.xml",
    },
    Sitting {
        hand: "M. Aubert",
        written: "1911-06-02T14:30:00+02:00",
        transcript: "second-sitting.xml",
    },
];

/// The words the register is bound in, one set per language.
#[derive(Debug)]
struct Words {
    /// What the file says it is.
    title: &'static str,
    /// What each sitting is called, in its band and in its own packet.
    sittings: [&'static str; 2],
    /// What whoever wrote a sitting down is called, set after their name.
    clerk: &'static str,
    /// What a page says it is about.
    subject: &'static str,
    /// What each page says under its band.
    lines: [[&'static str; 3]; 2],
    /// The heading over what a page says of itself, the one over what the file
    /// carries, and the one over what the plate says of itself.
    headings: [&'static str; 3],
    /// What a part is asked about: its title, the hand that wrote it, when it
    /// was written, and the file tied to it.
    asked: [&'static str; 4],
    /// What claims each carried file, in the order they are carried.
    claimed_by: [&'static str; 3],
    /// The row that says the file at large claims none of them.
    at_large: [&'static str; 2],
    /// What the plate is called, on the page and in its own packet.
    plate: &'static str,
    /// What the plate is asked, and who answers to it.
    holder: [&'static str; 2],
    /// What the plate says it is about.
    plate_subject: &'static str,
    /// What each carried file says it is: a transcription, and the record of a
    /// scan.
    carried: [&'static str; 2],
    /// The closing note at the foot of the last page.
    closing: [&'static str; 4],
}

impl Words {
    /// The words the register is bound in, in `language`.
    fn of(language: Language) -> &'static Self {
        language::pick(&WORDS, language)
    }

    /// Who wrote the sitting at `index` down: their name, then what such a
    /// person is called.
    fn hand(&self, index: usize) -> String {
        format!("{}, {}", SITTINGS[index].hand, self.clerk)
    }
}

/// The register in English.
const ENGLISH: Words = Words {
    title: "A register bound from two sittings",
    sittings: ["First sitting", "Second sitting"],
    clerk: "clerk",
    subject: "One sitting of the register",
    lines: [
        [
            "This page carries a packet of its own, saying what it is, whose hand",
            "wrote it and when. The file says nothing on its behalf: read the page",
            "out of the file and what it says travels with it.",
        ],
        [
            "The plate below is a part in its own right. It says who holds it, which",
            "is not who holds the paper, and it carries the record of the scan it",
            "came off — tied to the plate, not to the file.",
        ],
    ],
    headings: [
        "What this page says about itself",
        "What this file carries, and which part claims it",
        "What the plate says about itself",
    ],
    asked: [
        "Its title",
        "The hand that wrote it",
        "When it was written",
        "The file tied to it",
    ],
    claimed_by: [
        "The first page",
        "The second page",
        "The plate on the second page",
    ],
    at_large: ["Claimed by the file at large", "nothing"],
    plate: "Plate 12, second sitting",
    holder: ["Who holds it", "Departmental archive"],
    plate_subject: "The plate, which is held apart from the paper",
    carried: ["The sitting, transcribed", "How the plate was scanned"],
    closing: [
        "Every carried file is offered to every reader through the list of embedded",
        "files, whichever part of the document claims it. What the tie adds is which",
        "part it belongs to — and a file one part claims leaves the tie the document",
        "itself holds, so nothing is ever said to belong to two things at once.",
    ],
};

/// The register in French.
const FRENCH: Words = Words {
    title: "Un registre relié à partir de deux séances",
    sittings: ["Première séance", "Deuxième séance"],
    clerk: "greffier",
    subject: "Une séance du registre",
    lines: [
        [
            "Cette page porte son propre paquet, qui dit ce qu'elle est, de quelle",
            "main elle a été écrite et quand. Le fichier ne dit rien à sa place :",
            "sortez la page du fichier et ce qu'elle dit part avec elle.",
        ],
        [
            "La planche ci-dessous est une pièce à part entière. Elle dit qui la",
            "détient, qui n'est pas celui qui détient le papier, et elle porte le",
            "relevé de la numérisation d'où elle vient — lié à elle, pas au fichier.",
        ],
    ],
    headings: [
        "Ce que cette page dit d'elle-même",
        "Ce que ce fichier porte, et quelle partie le revendique",
        "Ce que la planche dit d'elle-même",
    ],
    asked: [
        "Son titre",
        "La main qui l'a écrite",
        "Quand elle a été écrite",
        "Le fichier qui lui est lié",
    ],
    claimed_by: [
        "La première page",
        "La deuxième page",
        "La planche de la deuxième page",
    ],
    at_large: ["Revendiqué par le fichier entier", "rien"],
    plate: "Planche 12, deuxième séance",
    holder: ["Qui la détient", "Archives départementales"],
    plate_subject: "La planche, détenue à part du papier",
    carried: [
        "La séance, transcrite",
        "Comment la planche a été numérisée",
    ],
    closing: [
        "Chaque fichier porté est proposé à tout lecteur par la liste des pièces",
        "jointes, quelle que soit la partie du document qui le revendique. Le lien",
        "ajoute à quelle partie il appartient — et un fichier qu'une partie revendique",
        "quitte le lien que le document tient, donc rien n'est jamais à deux choses.",
    ],
};

/// Every language the example is written in. A language is added by writing its
/// own set of words and naming it here.
static WORDS: [(Language, &Words); 2] =
    [(Language::English, &ENGLISH), (Language::French, &FRENCH)];

/// Draws one line of text with its baseline at `(x, y)`.
fn text(
    content: &mut Content,
    font: &FontHandle,
    size: f64,
    x: f64,
    y: f64,
    line: &str,
) -> Result<(), Error> {
    content.begin_text();
    content.set_font(font.name(), size)?;
    content.text_origin(x, y)?;
    content.show_glyphs(&font.glyphs(line));
    content.end_text();
    Ok(())
}

/// The plate: a square of grey read off a pattern, so that the example needs no
/// file beside it.
fn plate() -> Result<Image, Error> {
    let side: u32 = 64;
    let mut samples = Vec::with_capacity((side * side) as usize);
    for down in 0..side {
        for across in 0..side {
            let value = ((across * 4) ^ (down * 4)) & 0xFF;
            samples.push(u8::try_from(value).unwrap_or(u8::MAX));
        }
    }
    Image::from_gray(side, side, &samples)
}

/// The band across the head of a page, and the lines under it.
fn head(
    content: &mut Content,
    font: &FontHandle,
    words: &Words,
    index: usize,
) -> Result<(), Error> {
    content.save_state();
    content.set_fill(Rgb::new(0.16, 0.20, 0.26))?;
    content.rect(0.0, SHEET.1 - 96.0, SHEET.0, 96.0)?.fill();
    content.set_fill(Rgb::new(1.0, 1.0, 1.0))?;
    text(
        content,
        font,
        20.0,
        MARGIN,
        SHEET.1 - 58.0,
        words.sittings[index],
    )?;
    content.restore_state();

    content.save_state();
    content.set_fill(Color::Gray(0.25))?;
    let mut y = SHEET.1 - 140.0;
    for line in words.lines[index] {
        text(content, font, 11.0, MARGIN, y, line)?;
        y -= 18.0;
    }
    content.restore_state();
    Ok(())
}

/// What one part of the file says about itself, set as a pair of columns.
fn says(
    content: &mut Content,
    font: &FontHandle,
    top: f64,
    heading: &str,
    rows: &[(&str, &str)],
) -> Result<(), Error> {
    content.save_state();
    content.set_stroke(Color::Gray(0.82))?;
    content.set_line_width(0.4)?;
    content.move_to(MARGIN, top)?;
    content.line_to(SHEET.0 - MARGIN, top)?;
    content.stroke();
    content.restore_state();

    content.save_state();
    content.set_fill(Color::Gray(0.1))?;
    text(content, font, 13.0, MARGIN, top - 28.0, heading)?;
    content.restore_state();

    content.save_state();
    content.set_fill(Color::Gray(0.3))?;
    let mut y = top - 56.0;
    for (said, written) in rows {
        text(content, font, 11.0, MARGIN, y, said)?;
        text(content, font, 10.0, MARGIN + SAID, y, written)?;
        y -= 20.0;
    }
    content.restore_state();
    Ok(())
}

/// The closing note, set at the foot of the last page.
fn foot(content: &mut Content, font: &FontHandle, words: &Words) -> Result<(), Error> {
    content.save_state();
    content.set_fill(Color::Gray(0.45))?;
    let mut y = 178.0;
    for line in words.closing {
        text(content, font, 10.5, MARGIN, y, line)?;
        y -= 17.0;
    }
    content.set_fill(Color::Gray(0.5))?;
    text(content, font, 8.0, MARGIN, 62.0, "HQF Development")?;
    content.restore_state();
    Ok(())
}

/// The first page: what it says of itself, and the transcription tied to it.
fn first_sheet(font: &FontHandle, words: &Words) -> Result<Vec<u8>, Error> {
    let mut content = Content::new();
    head(&mut content, font, words, 0)?;
    let hand = words.hand(0);
    says(
        &mut content,
        font,
        SHEET.1 - 220.0,
        words.headings[0],
        &[
            (words.asked[0], words.sittings[0]),
            (words.asked[1], &hand),
            (words.asked[2], SITTINGS[0].written),
            (words.asked[3], SITTINGS[0].transcript),
        ],
    )?;
    says(
        &mut content,
        font,
        SHEET.1 - 380.0,
        words.headings[1],
        &[
            (SITTINGS[0].transcript, words.claimed_by[0]),
            (SITTINGS[1].transcript, words.claimed_by[1]),
            (SCAN, words.claimed_by[2]),
            (words.at_large[0], words.at_large[1]),
        ],
    )?;
    Ok(content.into_bytes())
}

/// The second page: the plate, what the plate says of itself, and the note.
fn second_sheet(font: &FontHandle, plate: &ImageHandle, words: &Words) -> Result<Vec<u8>, Error> {
    let mut content = Content::new();
    head(&mut content, font, words, 1)?;

    let top = SHEET.1 - 220.0;
    content.draw_image(plate, MARGIN, top - PLATE, PLATE, PLATE)?;
    content.save_state();
    content.set_stroke(Color::Gray(0.7))?;
    content.set_line_width(0.5)?;
    content.rect(MARGIN, top - PLATE, PLATE, PLATE)?.stroke();
    content.set_fill(Color::Gray(0.45))?;
    text(
        &mut content,
        font,
        9.0,
        MARGIN,
        top - PLATE - 14.0,
        words.plate,
    )?;
    content.restore_state();

    says(
        &mut content,
        font,
        top - PLATE - 44.0,
        words.headings[2],
        &[
            (words.asked[0], words.plate),
            (words.holder[0], words.holder[1]),
            (words.asked[3], SCAN),
        ],
    )?;
    foot(&mut content, font, words)?;
    Ok(content.into_bytes())
}

/// The packet a page speaks in: what it is, whose hand wrote it, and when.
fn said_by(words: &Words, index: usize) -> Xmp {
    Xmp::facts(Metadata {
        title: Some(words.sittings[index].to_owned()),
        author: Some(words.hand(index)),
        subject: Some(words.subject.to_owned()),
        created: Some(SITTINGS[index].written.to_owned()),
        ..Metadata::default()
    })
}

/// A transcription carried inside the file, under the name it is looked up by.
fn transcription(words: &Words, index: usize) -> Attachment {
    Attachment {
        file_name: SITTINGS[index].transcript.to_owned(),
        description: words.carried[0].to_owned(),
        media_type: "text/xml".to_owned(),
        relationship: Relationship::Alternative,
        modified: SITTINGS[index].written.to_owned(),
        data: format!("<sitting hand=\"{}\"/>\n", words.hand(index)).into_bytes(),
    }
}

/// The two pages, each carrying its own packet and the file tied to it.
fn bind(
    doc: &mut Document,
    font: &FontHandle,
    plate: &ImageHandle,
    words: &Words,
    carried: [AttachmentHandle; 2],
) -> Result<(), Error> {
    let mut first = Page::new(SHEET.0, SHEET.1);
    first.content = first_sheet(font, words)?;
    first.metadata = Some(said_by(words, 0));
    first.associated_files = vec![carried[0]];
    doc.add_page(first)?;

    let mut second = Page::new(SHEET.0, SHEET.1);
    second.content = second_sheet(font, plate, words)?;
    second.metadata = Some(said_by(words, 1));
    second.associated_files = vec![carried[1]];
    doc.add_page(second)?;
    Ok(())
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let language = Language::from_environment()?;
    let words = Words::of(language);

    let mut args = env::args().skip(1);
    // A named file is written as named; the default one carries the language,
    // so the two languages do not overwrite each other in `tmp/`.
    let out = args
        .next()
        .unwrap_or_else(|| language.file_name(&out::default_path("provenance")));
    let font_path = args.next().map_or_else(default_font, PathBuf::from);

    let mut doc = Document::new();
    doc.set_license(licence::licensed());
    let font = doc.add_font(Font::parse(fs::read(&font_path)?)?);

    // Each transcription is claimed by the page it transcribes; the record of
    // the scan is claimed by the plate itself. Nothing here is claimed by the
    // file at large, so the file ties nothing to its catalogue.
    let carried = [
        doc.attach(transcription(words, 0)),
        doc.attach(transcription(words, 1)),
    ];
    let scan = doc.attach(Attachment {
        file_name: SCAN.to_owned(),
        description: words.carried[1].to_owned(),
        media_type: "text/xml".to_owned(),
        relationship: Relationship::Supplement,
        modified: "2026-02-19T11:05:00+01:00".to_owned(),
        data: b"<scan dpi=\"600\" bits=\"8\"/>\n".to_vec(),
    });

    let plate = doc.add_image(
        plate()?
            .with_metadata(Some(Xmp::facts(Metadata {
                title: Some(words.plate.to_owned()),
                author: Some(words.holder[1].to_owned()),
                subject: Some(words.plate_subject.to_owned()),
                ..Metadata::default()
            })))
            .associated_with(&[scan]),
    );

    bind(&mut doc, &font, &plate, words, carried)?;

    // Tying a carried file to anything but the document as a whole is ISO
    // 32000-2, so the file says 2.0 on its first line.
    doc.set_version(Version::V2_0);
    doc.set_metadata(Metadata {
        title: Some(words.title.to_owned()),
        producer: Some("hqf-pdf".to_owned()),
        ..Metadata::default()
    });

    let written = doc.to_bytes()?;
    if let Some(parent) = Path::new(&out).parent() {
        fs::create_dir_all(parent)?;
    }
    fs::write(&out, &written)?;
    println!(
        "wrote {out}: {} bytes, every part saying where it came from",
        written.len()
    );
    Ok(())
}

#[cfg(test)]
mod tests {
    use hqf_pdf::{Document, Font};

    use super::{MARGIN, SAID, SHEET, WORDS, default_font, language};

    /// The lines two languages are allowed to write the same way. Every line in
    /// `Words` is drawn on a page and written into a packet, and no two
    /// languages write one alike; the names the carried files are looked up by,
    /// the clerks' names and the dates are not in `Words` at all.
    const SPARED: [&str; 0] = [];

    /// The room a line set from the left margin has before it reaches the
    /// margin on the other side.
    const PAPER: f64 = SHEET.0 - 2.0 * MARGIN;

    /// The room a label has before it reaches what the part says beside it.
    const GUTTER: f64 = 10.0;

    #[test]
    fn every_language_binds_the_register_in_its_own_words() {
        let untranslated = language::untranslated_lines(&WORDS, &SPARED);

        assert!(
            untranslated.is_empty(),
            "the register says these in more than one language: {untranslated:?}"
        );
    }

    /// Nothing on either page is broken to a width: a label longer than the
    /// room it has runs on under what the part says beside it, and a line of
    /// prose longer than the paper runs off the sheet.
    #[test]
    fn every_language_writes_lines_that_fit_the_room_they_have() {
        let mut doc = Document::new();
        let text = doc.add_font(
            Font::parse(std::fs::read(default_font()).expect("the committed font is there"))
                .expect("the committed font parses"),
        );

        for (named, words) in WORDS {
            let code = named.code();
            let lines = words
                .sittings
                .map(|line| (20.0, line.to_owned(), PAPER))
                .into_iter()
                .chain(
                    words
                        .lines
                        .into_iter()
                        .flatten()
                        .map(|line| (11.0, line.to_owned(), PAPER)),
                )
                .chain(words.headings.map(|line| (13.0, line.to_owned(), PAPER)))
                .chain(
                    words
                        .asked
                        .map(|line| (11.0, line.to_owned(), SAID - GUTTER)),
                )
                .chain([
                    (11.0, words.at_large[0].to_owned(), SAID - GUTTER),
                    (11.0, words.holder[0].to_owned(), SAID - GUTTER),
                ])
                .chain(words.closing.map(|line| (10.5, line.to_owned(), PAPER)));

            for (size, line, room) in lines {
                let measured = text.measure(&line, size);
                assert!(
                    measured <= room,
                    "the {code} register draws {line:?} over {measured:.1} \
                     points, and it has {room:.1}"
                );
            }
        }
    }

    /// The right-hand column of every pair is set from the same left edge, so
    /// what a part says has to stay on the paper from there.
    #[test]
    fn every_language_keeps_what_a_part_says_on_the_paper() {
        let mut doc = Document::new();
        let text = doc.add_font(
            Font::parse(std::fs::read(default_font()).expect("the committed font is there"))
                .expect("the committed font parses"),
        );
        let room = SHEET.0 - MARGIN - (MARGIN + SAID);

        for (named, words) in WORDS {
            let code = named.code();
            let said = words
                .sittings
                .map(str::to_owned)
                .into_iter()
                .chain([words.hand(0), words.hand(1)])
                .chain(words.claimed_by.map(str::to_owned))
                .chain([
                    words.at_large[1].to_owned(),
                    words.holder[1].to_owned(),
                    words.plate.to_owned(),
                ]);

            for line in said {
                let measured = text.measure(&line, 10.0);
                assert!(
                    measured <= room,
                    "the {code} register says {line:?} over {measured:.1} \
                     points, and the column leaves {room:.1}"
                );
            }
        }
    }
}