write_pdfa4.rs

//! Writes terms of carriage claiming the fourth part of the archival standard.
//!
//! The fourth part is built on the second version of PDF, and it drops the
//! levels the earlier parts carry: there is one part and no letter after it.
//! Every face is carried whole inside the file and every colour says what it
//! means, as in every part before it.
//!
//! Whether the result really is PDF/A-4 is not for us to say. `veraPDF` says,
//! and `scripts/check_archival.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_pdfa4 -- tmp/pdfa4.pdf [font.ttf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_pdfa4 -- tmp/pdfa4_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 record 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-05-04T09:00:00+02: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 terms 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,
    /// What the page says of the part it claims.
    body: &'static str,
    /// The terms themselves, one a line.
    terms: &'static str,
}

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

/// The terms in English.
const ENGLISH: Words = Words {
    title: "Terms of carriage, edition of 2026",
    subject: "A record written on the version of PDF the fourth part is built on",
    heading: "Terms of carriage, edition of 2026",
    body: "This record claims the fourth part of the archival standard, the one built on the \
        second version of PDF. It says what it is in its metadata packet and nowhere else: there \
        is no information dictionary behind the page, and the title above is the title the file \
        carries. Everything the part asks for is here and nothing more: every face is carried \
        whole inside the file, every colour says what it means, and the pages keep their looks \
        with no font, no profile and no program to fetch from anywhere.",
    terms: "Goods are carried under the schedule current on the day they are accepted.\nA \
        schedule that changes after acceptance does not reach an order already accepted.",
};

/// The terms in French.
const FRENCH: Words = Words {
    title: "Conditions de transport, édition 2026",
    subject: "Un document bâti sur la version de PDF sur laquelle repose la quatrième partie",
    heading: "Conditions de transport, édition 2026",
    body: "Ce document déclare suivre la quatrième partie de la norme d’archivage, celle \
qui repose sur la deuxième version de PDF. Il dit ce qu’il est dans son paquet \
de métadonnées et nulle part ailleurs : aucun dictionnaire d’informations \
derrière la page, et le titre ci-dessus est le titre même du fichier. Tout ce \
que la partie exige est là, et rien de plus : chaque police est incorporée en \
entier au fichier, chaque couleur dit ce qu’elle signifie, et les pages \
gardent leur apparence sans police, profil ni programme à aller chercher où \
que ce soit.",
    terms: "Les marchandises sont transportées au barème en vigueur le jour de leur prise \
en charge.\nUn barème modifié après la prise en charge ne s’applique pas à une \
commande déjà prise en charge.",
};

/// The terms in German.
const GERMAN: Words = Words {
    title: "Beförderungsbedingungen, Ausgabe 2026",
    subject: "Ein Dokument in der PDF-Version, auf der der vierte Teil aufbaut",
    heading: "Beförderungsbedingungen, Ausgabe 2026",
    body: "Dieses Dokument erklärt Konformität mit dem vierten Teil der Archivnorm, der \
auf der zweiten PDF-Version aufbaut. Was es ist, gibt es in seinem \
Metadatenpaket an und nirgends sonst: Hinter der Seite steht kein \
Informationswörterbuch, und der Titel oben ist der Titel der Datei. Alles, was \
der Teil verlangt, ist vorhanden, und nichts darüber hinaus: Jede Schrift \
steckt vollständig in der Datei, jede Farbe gibt an, was sie bedeutet, und die \
Seiten behalten ihr Aussehen, ohne dass eine Schrift, ein Profil oder ein \
Programm von irgendwoher geholt werden muss.",
    terms: "Waren werden nach dem Tarif befördert, der am Tag ihrer Annahme gilt.\nEin Tarif, \
        der sich nach der Annahme ändert, betrifft keinen bereits angenommenen Auftrag.",
};

/// The terms in Spanish.
const SPANISH: Words = Words {
    title: "Condiciones de transporte, edición de 2026",
    subject: "Un documento escrito en la versión de PDF en la que se basa la cuarta parte",
    heading: "Condiciones de transporte, edición de 2026",
    body: "Este documento declara cumplir la cuarta parte de la norma de archivo, la que \
se basa en la segunda versión de PDF. Dice lo que es en su paquete de \
metadatos y en ningún otro sitio: no hay diccionario de información detrás de \
la página, y el título de arriba es el título del fichero. Aquí está todo lo \
que la parte exige y nada más: cada fuente va entera dentro del fichero, cada \
color dice lo que significa y las páginas conservan su aspecto sin fuentes, \
perfiles ni programas que ir a buscar a ninguna parte.",
    terms: "La mercancía viaja según la tarifa vigente el día en que se acepta.\nUn cambio \
de tarifa posterior a la aceptación no afecta a los pedidos ya aceptados.",
};

/// The terms in Italian.
const ITALIAN: Words = Words {
    title: "Condizioni di trasporto, edizione 2026",
    subject: "Un documento scritto sulla versione di PDF su cui poggia la quarta parte",
    heading: "Condizioni di trasporto, edizione 2026",
    body: "Questo documento dichiara di rispettare la quarta parte della norma di \
archiviazione, quella costruita sulla seconda versione di PDF. Dice che cos’è \
nel suo pacchetto di metadati e in nessun altro punto: dietro la pagina non \
c’è alcun dizionario delle informazioni, e il titolo qui sopra è il titolo del \
file. Tutto ciò che la parte chiede c’è, e niente di più: ogni carattere è \
contenuto per intero nel file, ogni colore dice che cosa significa e le pagine \
conservano il loro aspetto senza font, profili o programmi da andare a \
prendere altrove.",
    terms: "La merce viaggia secondo il tariffario in vigore il giorno in cui è \
accettata.\nUn tariffario cambiato dopo l’accettazione non tocca un ordine già \
accettato.",
};

/// The terms in Portuguese.
const PORTUGUESE: Words = Words {
    title: "Condições de transporte, edição de 2026",
    subject: "Um documento escrito na versão do PDF em que assenta a quarta parte",
    heading: "Condições de transporte, edição de 2026",
    body: "Este documento declara cumprir a quarta parte da norma de arquivo, a que assenta na \
        segunda versão do PDF. Diz o que é no seu pacote de metadados e em mais lado nenhum: não \
        há dicionário de informação por trás da página, e o título acima é o título do ficheiro. \
        Está aqui tudo o que a parte exige e nada mais: cada tipo de letra está inteiro dentro \
        do ficheiro, cada cor diz o que significa e as páginas mantêm o seu aspeto sem tipos de \
        letra, perfis ou programas a ir buscar a lado nenhum.",
    terms: "A mercadoria é transportada segundo a tabela em vigor no dia em que é aceite.\nUma \
        tabela alterada após a aceitação não abrange uma encomenda já aceite.",
};

/// The terms in Dutch.
const DUTCH: Words = Words {
    title: "Vervoersvoorwaarden, editie 2026",
    subject: "Een document op de PDF-versie waarop het vierde deel gebaseerd is",
    heading: "Vervoersvoorwaarden, editie 2026",
    body: "Dit document verklaart te voldoen aan het vierde deel van de archiefnorm, het \
deel dat op de tweede versie van PDF gebaseerd is. Het zegt wat het is in zijn \
metadatapakket en nergens anders: achter de pagina staat geen \
informatiewoordenboek, en de titel hierboven is de titel van het bestand. \
Alles wat het deel vereist, is aanwezig, en niets meer: elk lettertype zit \
volledig in het bestand, elke kleur zegt wat ze betekent, en de pagina’s \
behouden hun uiterlijk zonder lettertype, profiel of programma dat ergens \
vandaan moet komen.",
    terms: "Goederen worden vervoerd volgens het tarief dat geldt op de dag van \
aanvaarding.\nEen tarief dat na aanvaarding wijzigt, raakt geen bestelling die \
al aanvaard is.",
};

/// 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("pdfa4")));
    let font_path = args.next().map_or_else(default_font, PathBuf::from);

    let mut doc = Document::new();
    doc.set_license(licence::licensed());
    // The fourth part is built on the second version of PDF, and the standard
    // refuses a file that declares an earlier one.
    doc.set_version(Version::V2_0);
    doc.set_conformance(PdfA::A4);

    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 body is set in.
const BODY_BOX: Block = Block {
    size: 11.0,
    left: 72.0,
    top: 736.0,
    width: 451.0,
    set: Some((16.0, Align::Justify)),
};

/// The box the terms are set in.
const TERMS_BOX: Block = Block {
    size: 11.0,
    left: 72.0,
    top: 596.0,
    width: 451.0,
    set: Some((17.0, Align::Left)),
};

/// The one page, block by block.
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, &BODY_BOX, words.body)?;
    block(&mut c, font, &TERMS_BOX, words.terms)?;

    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::{BODY_BOX, Block, HEADING_BOX, TERMS_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] = [];

    /// 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();
            assert_eq!(
                lines(&font, &HEADING_BOX, words.heading),
                1,
                "the {code} record breaks {:?} over two lines",
                words.heading
            );

            let count = lines(&font, &BODY_BOX, words.body);
            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 - TERMS_BOX.top,
                "the {code} body takes {count} lines from {}, and the next block \
                 starts at {}",
                BODY_BOX.top,
                TERMS_BOX.top
            );
        }
    }
}