write_pdfa1b.rs

//! Writes a certificate of employment claiming the first part of the archival
//! standard, at level B.
//!
//! The first part is the strict one. It is built on PDF 1.4, and it closes what
//! the later editions let back in: nothing on the page is painted so that what
//! lies behind it shows through, no layer can be switched off, and no file
//! travels inside the document. What is left is a sheet that draws itself out
//! of what it carries, which is what the standard asked for in 2005.
//!
//! Level B promises the look of the page and nothing more. Level A, which adds
//! the tree saying what the page is made of, is `write_pdfa1a`.
//!
//! Whether the result really is PDF/A-1B is not for us to say. `veraPDF` says,
//! and `scripts/check_pdfa.sh` asks it.
//!
//! The words of the page and of its metadata are held in `Words`, once per
//! language, and `HQF_PDF_LANG` picks which set the record is written in.
//!
//! Usage: `cargo run --example write_pdfa1b -- tmp/pdfa1b.pdf [font.ttf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_pdfa1b -- tmp/pdfa1b_fr.pdf`

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

use hqf_pdf::content::Content;
use hqf_pdf::layout::Align;
use hqf_pdf::metadata::xmp::{Metadata, PdfA};
use hqf_pdf::{Document, Error, Font, FontHandle, Page, TextFlow, Version};

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

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

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

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

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

/// When the certificate was drawn up. The library never reads the clock — a
/// document that stamped itself with the time would be a different file on
/// every build — so the caller says when.
const ISSUED: &str = "2026-02-04T09:15:00+01:00";

/// Who the file says wrote it, and what produced it, in every language alike.
const AUTHOR: &str = "HQF Development";
const PRODUCER: &str = "hqf-pdf-server";

/// The words the certificate is written in, one set per language.
#[derive(Debug)]
struct Words {
    /// What the file says it is, in its metadata.
    title: &'static str,
    /// What the file says it is about, in its metadata.
    subject: &'static str,
    /// The heading at the top of the page.
    heading: &'static str,
    /// The line under the heading saying what the record is filed under.
    reference: &'static str,
    /// What the page says of the part it claims, in two runs set end to end
    /// with a space between them.
    body: [&'static str; 2],
    /// What each line of the record asks, one a line.
    labels: &'static str,
    /// What each line of the record answers, beside its label.
    answers: &'static str,
    /// The line under the record, saying who signed it.
    signed: &'static str,
}

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

/// The certificate in English.
const ENGLISH: Words = Words {
    title: "Certificate of employment, 4 February 2026",
    subject: "A record an archive keeps under the first edition of the standard",
    heading: "Certificate of employment",
    reference: "Reference 2026-0184, issued 4 February 2026",
    body: [
        "This sheet claims the first part of the archival standard, at the level that promises \
            the look of the page and nothing else. Every face it draws with is carried inside \
            the file, every colour says what it means, and nothing on the page waits on a \
            program, a network or a font that happens to be installed.",
        "The first part is also the strictest: nothing here is painted so that what lies behind \
            it shows through, no part of the page can be switched off, and no file travels \
            inside the document. A record that needs any of those claims a later part instead.",
    ],
    labels: "Employee\nPosition\nEmployed since\nHours",
    answers: "Camille Marchand\nHead of the drawing office\n3 September 2018\nFull time, 35 \
        hours a week",
    signed: "Signed at Cabriès, for HQF Development.",
};

/// The certificate in French.
const FRENCH: Words = Words {
    title: "Attestation d’emploi, 4 février 2026",
    subject: "Un document que conserve un service d’archives selon la première édition de la norme",
    heading: "Attestation d’emploi",
    reference: "Référence 2026-0184, délivrée le 4 février 2026",
    body: [
        "Cette feuille déclare suivre la première partie de la norme d’archivage, au \
niveau qui promet l’apparence de la page et rien d’autre. Chaque police \
employée est incorporée au fichier, chaque couleur dit ce qu’elle signifie, et \
rien sur la page ne dépend d’un programme, d’un réseau ou d’une police \
installée par hasard.",
        "La première partie est aussi la plus stricte : rien n’y est peint de façon à \
laisser voir ce qui se trouve derrière, aucun élément de la page ne peut être \
masqué et aucun fichier ne voyage dans le document. Un document qui a besoin \
de l’une de ces choses se réclame d’une partie ultérieure.",
    ],
    labels: "Nom\nFonction\nDate d’embauche\nTemps de travail",
    answers: "Camille Marchand\nResponsable du bureau d’études\n3 septembre 2018\nTemps plein, \
        35 heures par semaine",
    signed: "Fait à Cabriès, pour HQF Development.",
};

/// The certificate in German.
const GERMAN: Words = Words {
    title: "Beschäftigungsnachweis, 4. Februar 2026",
    subject: "Ein Dokument, das ein Archiv nach dem ersten Teil der Norm aufbewahrt",
    heading: "Beschäftigungsnachweis",
    reference: "Aktenzeichen 2026-0184, ausgestellt am 4. Februar 2026",
    body: [
        "Dieses Blatt erklärt Konformität mit dem ersten Teil der Archivnorm, auf der \
Stufe, die das Aussehen der Seite zusagt und sonst nichts. Jede verwendete \
Schrift steckt in der Datei, jede Farbe gibt an, was sie bedeutet, und nichts \
auf der Seite wartet auf ein Programm, ein Netzwerk oder eine zufällig \
installierte Schrift.",
        "Der erste Teil ist auch der strengste: Nichts ist hier so aufgetragen, dass \
Dahinterliegendes durchscheint, kein Teil der Seite lässt sich ausblenden, und \
keine Datei reist im Dokument mit. Ein Dokument, das etwas davon braucht, \
erklärt stattdessen Konformität mit einem späteren Teil.",
    ],
    labels: "Name\nTätigkeit\nBeschäftigt seit\nArbeitszeit",
    answers: "Camille Marchand\nLeitung des Konstruktionsbüros\n3. September 2018\nVollzeit, 35 \
        Stunden pro Woche",
    signed: "Unterzeichnet in Cabriès für HQF Development.",
};

/// The certificate in Spanish.
const SPANISH: Words = Words {
    title: "Certificado laboral, 4 de febrero de 2026",
    subject: "Un documento que un archivo conserva según la primera edición de la norma",
    heading: "Certificado laboral",
    reference: "Referencia 2026-0184, expedido el 4 de febrero de 2026",
    body: [
        "Esta hoja declara cumplir la primera parte de la norma de archivo, en el nivel \
que promete el aspecto de la página y nada más. Cada fuente que usa va dentro \
del fichero, cada color dice lo que significa y nada en la página depende de \
un programa, de una red ni de una fuente instalada en el equipo.",
        "La primera parte es también la más estricta: aquí nada se pinta de modo que se vea lo \
            que hay detrás, ninguna parte de la página puede ocultarse y ningún fichero viaja \
            dentro del documento. Un documento que necesite algo de eso declara una parte \
            posterior.",
    ],
    labels: "Nombre\nCargo\nEn plantilla desde\nJornada",
    answers: "Camille Marchand\nResponsable de la oficina técnica\n3 de septiembre de \
        2018\nCompleta, 35 horas semanales",
    signed: "Firmado en Cabriès, en nombre de HQF Development.",
};

/// The certificate in Italian.
const ITALIAN: Words = Words {
    title: "Certificato di servizio, 4 febbraio 2026",
    subject: "Un documento che un archivio conserva secondo la prima edizione della norma",
    heading: "Certificato di servizio",
    reference: "Riferimento 2026-0184, rilasciato il 4 febbraio 2026",
    body: [
        "Questo foglio dichiara di rispettare la prima parte della norma di archiviazione, al \
            livello che promette l’aspetto della pagina e nient’altro. Ogni carattere che usa è \
            contenuto nel file, ogni colore dice che cosa significa e nulla sulla pagina dipende \
            da un programma, da una rete o da un font che si trovi installato.",
        "La prima parte è anche la più severa: qui nulla è dipinto in modo da lasciar vedere ciò \
            che sta dietro, nessuna parte della pagina può essere nascosta e nessun file viaggia \
            nel documento. Un documento che ha bisogno di una di queste cose dichiara una parte \
            successiva.",
    ],
    labels: "Dipendente\nMansione\nIn servizio dal\nOrario",
    answers: "Camille Marchand\nResponsabile dell’ufficio tecnico\n3 settembre 2018\nTempo \
        pieno, 35 ore settimanali",
    signed: "Firmato a Cabriès, per HQF Development.",
};

/// The certificate in Portuguese.
const PORTUGUESE: Words = Words {
    title: "Declaração de trabalho, 4 de fevereiro de 2026",
    subject: "Um documento que um arquivo guarda segundo a primeira edição da norma",
    heading: "Declaração de trabalho",
    reference: "Referência 2026-0184, emitida a 4 de fevereiro de 2026",
    body: [
        "Esta folha declara cumprir a primeira parte da norma de arquivo, no nível que promete o \
            aspeto da página e nada mais. Cada tipo de letra que usa está dentro do ficheiro, \
            cada cor diz o que significa e nada na página depende de um programa, de uma rede ou \
            de um tipo de letra que por acaso esteja instalado.",
        "A primeira parte é também a mais rigorosa: nada aqui é pintado de forma a deixar ver o \
            que está por trás, nenhuma parte da página pode ser ocultada e nenhum ficheiro viaja \
            dentro do documento. Um documento que precise de alguma destas coisas declara uma \
            parte posterior.",
    ],
    labels: "Nome\nFunção\nAo serviço desde\nHorário",
    answers: "Camille Marchand\nResponsável pelo gabinete de projeto\n3 de setembro de \
        2018\nTempo inteiro, 35 horas por semana",
    signed: "Assinado em Cabriès, pela HQF Development.",
};

/// The certificate in Dutch.
const DUTCH: Words = Words {
    title: "Werkgeversverklaring, 4 februari 2026",
    subject: "Een document dat een archief bewaart volgens de eerste editie van de norm",
    heading: "Werkgeversverklaring",
    reference: "Kenmerk 2026-0184, afgegeven op 4 februari 2026",
    body: [
        "Dit blad verklaart te voldoen aan het eerste deel van de archiefnorm, op het \
niveau dat het uiterlijk van de pagina belooft en verder niets. Elk lettertype \
dat het gebruikt, zit in het bestand, elke kleur zegt wat ze betekent, en \
niets op de pagina wacht op een programma, een netwerk of een lettertype dat \
toevallig geïnstalleerd is.",
        "Het eerste deel is ook het strengste: niets is hier zo aangebracht dat wat \
erachter ligt doorschemert, geen deel van de pagina kan worden uitgeschakeld \
en geen bestand reist mee in het document. Een document dat iets daarvan nodig \
heeft, verklaart te voldoen aan een later deel.",
    ],
    labels: "Werknemer\nFunctie\nIn dienst sinds\nArbeidsduur",
    answers: "Camille Marchand\nHoofd van het tekenbureau\n3 september 2018\nVoltijd, 35 uur \
per week",
    signed: "Ondertekend te Cabriès, namens HQF Development.",
};

/// 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); 7] = [
    (Language::English, &ENGLISH),
    (Language::French, &FRENCH),
    (Language::German, &GERMAN),
    (Language::Spanish, &SPANISH),
    (Language::Italian, &ITALIAN),
    (Language::Portuguese, &PORTUGUESE),
    (Language::Dutch, &DUTCH),
];

fn main() -> std::process::ExitCode {
    failure::reported(run())
}

/// Writes the file, and says where it went.
fn run() -> 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 languages do not overwrite each other in `tmp/`.
    let path = args
        .next()
        .unwrap_or_else(|| language.file_name(&out::default_path("pdfa1b")));
    let font_path = args.next().map_or_else(default_font, PathBuf::from);

    let mut doc = Document::new();
    doc.set_license(licence::licensed());
    doc.set_version(Version::V1_4);
    doc.set_conformance(PdfA::A1B);

    let mut facts = Metadata::default();
    facts.title = Some(words.title.to_owned());
    facts.author = Some(AUTHOR.to_owned());
    facts.subject = Some(words.subject.to_owned());
    facts.producer = Some(PRODUCER.to_owned());
    facts.created = Some(ISSUED.to_owned());
    doc.set_metadata(facts);

    let font = doc.add_font(Font::parse(fs::read(&font_path)?)?);
    doc.add_page(sheet(&font, words)?)?;

    let bytes = doc.to_bytes()?;
    if let Some(parent) = Path::new(&path).parent() {
        fs::create_dir_all(parent)?;
    }
    fs::write(&path, &bytes)?;
    println!("wrote {path}: {} bytes", bytes.len());
    Ok(())
}

/// The box the heading is set in.
const HEADING_BOX: Block = Block {
    size: 20.0,
    left: 72.0,
    top: 782.0,
    width: 451.0,
    set: None,
};

/// The box the line under the heading is set in.
const REFERENCE_BOX: Block = Block {
    size: 10.5,
    left: 72.0,
    top: 750.0,
    width: 451.0,
    set: None,
};

/// The box the body is set in.
const BODY_BOX: Block = Block {
    size: 11.0,
    left: 72.0,
    top: 716.0,
    width: 451.0,
    set: Some((16.0, Align::Justify)),
};

/// The box the labels of the record are set in, one a line.
const LABELS_BOX: Block = Block {
    size: 11.0,
    left: 72.0,
    top: 580.0,
    width: 451.0,
    set: Some((17.0, Align::Left)),
};

/// The box the answers are set in, beside the labels.
const ANSWERS_BOX: Block = Block {
    size: 11.0,
    left: 200.0,
    top: 580.0,
    width: 323.0,
    set: Some((17.0, Align::Left)),
};

/// The box the line saying who signed is set in.
const SIGNED_BOX: Block = Block {
    size: 11.0,
    left: 72.0,
    top: 480.0,
    width: 451.0,
    set: None,
};

/// The one page: the heading, the reference, what the part promises, the record
/// in two columns, and the line that signs it.
fn sheet(font: &FontHandle, words: &Words) -> Result<Page, Error> {
    let mut c = Content::new();

    block(&mut c, font, &HEADING_BOX, words.heading)?;
    block(&mut c, font, &REFERENCE_BOX, words.reference)?;
    block(&mut c, font, &BODY_BOX, &words.body.join(" "))?;
    block(&mut c, font, &LABELS_BOX, words.labels)?;
    block(&mut c, font, &ANSWERS_BOX, words.answers)?;
    block(&mut c, font, &SIGNED_BOX, words.signed)?;

    let mut page = Page::a4();
    page.content = c.into_bytes();
    Ok(page)
}

/// The box one block of words goes in: its upper-left corner, how far it runs,
/// the size it is set at, and the leading and alignment where the block states
/// them.
struct Block {
    size: f64,
    left: f64,
    top: f64,
    width: f64,
    set: Option<(f64, Align)>,
}

/// Draws one block of words in the box it is given.
fn block(c: &mut Content, font: &FontHandle, at: &Block, text: &str) -> Result<(), Error> {
    let mut flow = TextFlow::new(font, at.size);
    if let Some((leading, align)) = at.set {
        flow = flow.leading(leading).align(align);
    }
    let lines = flow.break_lines(text, at.width);
    c.begin_text();
    flow.draw(c, &lines, at.left, at.top, at.width)?;
    c.end_text();
    Ok(())
}

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

    use super::{
        ANSWERS_BOX, BODY_BOX, Block, HEADING_BOX, LABELS_BOX, REFERENCE_BOX, SIGNED_BOX, WORDS,
        default_font, language,
    };

    /// The lines two languages are allowed to write the same way. No two
    /// languages write one alike.
    const SPARED: [&str; 0] = [];

    /// The least room left between a label and the column beside it.
    const GAP: f64 = 8.0;

    /// How many lines `text` takes in the box `at`.
    fn lines(font: &FontHandle, at: &Block, text: &str) -> usize {
        let mut flow = TextFlow::new(font, at.size);
        if let Some((leading, _)) = at.set {
            flow = flow.leading(leading);
        }
        flow.break_lines(text, at.width).len()
    }

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

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

    /// Every box on the page holds its words: a line meant to stand alone stays
    /// on one line, and the body ends a line above the block under it. Nothing
    /// else on the page says so when a language runs over.
    #[test]
    fn every_language_fits_the_boxes_the_page_sets_it_in() {
        let mut doc = Document::new();
        let font = 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();
            for (at, text) in [
                (HEADING_BOX, words.heading),
                (REFERENCE_BOX, words.reference),
                (SIGNED_BOX, words.signed),
            ] {
                assert_eq!(
                    lines(&font, &at, text),
                    1,
                    "the {code} record breaks {text:?} over two lines"
                );
            }

            let count = lines(&font, &BODY_BOX, &words.body.join(" "));
            let (leading, _) = BODY_BOX.set.expect("the body states its leading");
            let held = f64::from(u32::try_from(count).expect("a body is a few lines")) * leading;
            assert!(
                held <= BODY_BOX.top - LABELS_BOX.top,
                "the {code} body takes {count} lines from {}, and the next block \
                 starts at {}",
                BODY_BOX.top,
                LABELS_BOX.top
            );

            let room = ANSWERS_BOX.left - LABELS_BOX.left - GAP;
            for label in words.labels.lines() {
                let measured = font.measure(label, LABELS_BOX.size);
                assert!(
                    measured <= room,
                    "the {code} record sets {label:?} over {measured:.1} points, \
                     and it has {room:.1} before the column beside it"
                );
            }

            for answer in words.answers.lines() {
                assert_eq!(
                    lines(&font, &ANSWERS_BOX, answer),
                    1,
                    "the {code} record breaks {answer:?} over two lines"
                );
            }
        }
    }
}