write_pdfa3a.rs

//! Writes a schedule of charges claiming the third part of the archival
//! standard, at level A, carrying the same table in the form a machine reads.
//!
//! The third part is the one that lets a record carry a file of any kind, and
//! level A is the one that asks the page to say what it is made of. Together
//! they make a record a screen reader can follow and a billing system can read
//! without anybody retyping it.
//!
//! The rule and the page number at the foot are marked as furniture, so nothing
//! reading the document aloud says them.
//!
//! Whether the result really is PDF/A-3A 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. The
//! tree names the same language, so a screen reader reads the page in it.
//!
//! Usage: `cargo run --example write_pdfa3a -- tmp/pdfa3a.pdf [font.ttf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_pdfa3a -- tmp/pdfa3a_fr.pdf`

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

use hqf_pdf::content::{Artifact, Content};
use hqf_pdf::cos::Name;
use hqf_pdf::layout::FirstBaseline;
use hqf_pdf::metadata::attachment::{Attachment, Relationship};
use hqf_pdf::metadata::xmp::{Metadata, PdfA};
use hqf_pdf::structure::{Marks, StructElement, StructureTree};
use hqf_pdf::{Document, Error, Font, FontHandle, Page, TextFlow};

#[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, so the
/// caller says when.
const ISSUED: &str = "2026-06-08T09:20: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 file the record carries. What it is to the record is said in `Words`.
const CARRIED_NAME: &str = "schedule.csv";
const CARRIED_TYPE: &str = "text/csv";
const CHANGED: &str = "2026-06-08T09:15:00+02:00";
const CARRIED: &str = "charge,basis,amount\ncarriage,consignment,12.40\n\
                       handling,parcel,1.85\nstorage,day,0.40\n";

/// The words the schedule 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 language the tree says the page is written in, which a screen reader
    /// reads it in.
    lang: &'static str,
    /// What the carried file says it is to the record.
    carried_what: &'static str,
    /// The heading, tagged `H1`.
    heading: &'static str,
    /// The two paragraphs under the heading, each tagged `P`.
    paragraphs: [&'static str; 2],
    /// The page number at the foot, marked as furniture.
    foot: &'static str,
}

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

/// The schedule in English.
const ENGLISH: Words = Words {
    title: "Schedule of charges, second half of 2026",
    subject: "A record that says what it is made of and carries the table behind it",
    lang: "en-GB",
    carried_what: "The charges this page states, as a machine reads them",
    heading: "Schedule of charges, second half of 2026",
    paragraphs: [
        "This schedule claims the third part of the archival standard at its highest level. It \
            may carry a file of any kind, and it says what it is made of: this line is a \
            heading, the block below is a paragraph, and the rule across the foot is furniture \
            that says nothing at all.\nSomething reading the schedule aloud follows the order \
            the tree gives rather than the order the ink was laid down in, and the table behind \
            the page travels inside the file for a program to take whole.",
        "Carriage stands at 12.40 the consignment, handling at 1.85 the parcel, and storage at \
            0.40 the day. A charge takes effect on the day the consignment is accepted.",
    ],
    foot: "Page 1 of 1",
};

/// The schedule in French.
const FRENCH: Words = Words {
    title: "Barème des frais, second semestre 2026",
    subject: "Un document qui dit de quoi il est fait et contient le tableau dont il découle",
    lang: "fr-FR",
    carried_what: "Les frais que cette page indique, sous la forme que lit une machine",
    heading: "Barème des frais, second semestre 2026",
    paragraphs: [
        "Ce barème déclare suivre la troisième partie de la norme d’archivage, à son \
niveau le plus exigeant. Il peut contenir un fichier de toute nature, et il \
dit de quoi il est fait : cette ligne est un titre, le bloc suivant est un \
paragraphe, et le filet en pied de page est un ornement qui ne dit rien.\nUn \
logiciel qui lit le barème à voix haute suit l’ordre que donne l’arbre de \
structure, et non celui dans lequel l’encre a été posée ; le tableau dont la \
page découle voyage dans le fichier, prêt à être repris tel quel par un \
programme.",
        "Le transport coûte 12,40 par envoi, la manutention 1,85 par colis et le \
stockage 0,40 par jour. Un tarif s’applique dès le jour où l’envoi est \
accepté.",
    ],
    foot: "Page 1 sur 1",
};

/// The schedule in German.
const GERMAN: Words = Words {
    title: "Gebührenübersicht, zweites Halbjahr 2026",
    subject: "Ein Dokument, das angibt, woraus es besteht, und die Tabelle dahinter enthält",
    lang: "de-DE",
    carried_what: "Die Gebühren dieser Seite, so wie eine Maschine sie liest",
    heading: "Gebührenübersicht, zweites Halbjahr 2026",
    paragraphs: [
        "Diese Gebührenübersicht erklärt Konformität mit dem dritten Teil der \
Archivnorm, auf dessen höchster Stufe. Sie darf eine Datei beliebiger Art \
enthalten und gibt an, woraus sie besteht: Diese Zeile ist eine Überschrift, \
der Block darunter ein Absatz, und die Linie am Fuß ist Zierrat ohne jede \
Aussage.\nEin Vorleseprogramm folgt der Ordnung des Strukturbaums statt der \
Reihenfolge, in der die Tinte aufgetragen wurde, und die Tabelle hinter der \
Seite reist in der Datei mit, damit ein Programm sie vollständig übernehmen \
kann.",
        "Die Fracht kostet 12,40 je Sendung, der Umschlag 1,85 je Paket und die \
Lagerung 0,40 je Tag. Eine Gebühr fällt an dem Tag an, an dem die Sendung \
angenommen wird.",
    ],
    foot: "Seite 1 von 1",
};

/// The schedule in Spanish.
const SPANISH: Words = Words {
    title: "Tarifa de gastos, segundo semestre de 2026",
    subject: "Un documento que dice de qué está hecho y contiene la tabla de la que proceden \
sus cifras",
    lang: "es-ES",
    carried_what: "Los gastos que indica esta página, tal como los lee una máquina",
    heading: "Tarifa de gastos, segundo semestre de 2026",
    paragraphs: [
        "Esta tarifa declara cumplir la tercera parte de la norma de archivo en su \
nivel más alto. Puede llevar un fichero de cualquier tipo y dice de qué está \
hecha: esta línea es un título, el bloque de abajo es un párrafo y el filete \
del pie es un adorno que no dice nada.\nUn programa que lea la tarifa en voz \
alta sigue el orden que da el árbol, no el orden en que se puso la tinta, y la \
tabla de la que procede la página viaja dentro del fichero para que un \
programa la tome entera.",
        "El transporte cuesta 12,40 por envío; la manipulación, 1,85 por paquete; y el \
almacenaje, 0,40 por día. Cada gasto se aplica desde el día en que se acepta \
el envío.",
    ],
    foot: "Página 1 de 1",
};

/// The schedule in Italian.
const ITALIAN: Words = Words {
    title: "Tariffario, secondo semestre 2026",
    subject: "Un documento che dice di che cosa è fatto e contiene la tabella da cui nasce",
    lang: "it-IT",
    carried_what: "Le tariffe indicate in questa pagina, come le legge una macchina",
    heading: "Tariffario, secondo semestre 2026",
    paragraphs: [
        "Questo tariffario dichiara di rispettare la terza parte della norma di \
archiviazione al suo livello più alto. Può contenere un file di qualsiasi tipo \
e dice di che cosa è fatto: questa riga è un titolo, il blocco sotto è un \
paragrafo e il filetto a piè di pagina è un ornamento che non dice nulla.\nUna \
sintesi vocale legge il tariffario seguendo l’ordine dato dall’albero della \
struttura, non quello in cui è stato steso l’inchiostro, e la tabella da cui \
nasce la pagina viaggia dentro il file, perché un programma la prenda intera.",
        "Il trasporto costa 12,40 a spedizione, la movimentazione 1,85 a collo e il \
deposito 0,40 al giorno. Una tariffa si applica dal giorno in cui la \
spedizione è accettata.",
    ],
    foot: "Pagina 1 di 1",
};

/// The schedule in Portuguese.
const PORTUGUESE: Words = Words {
    title: "Tarifário, segundo semestre de 2026",
    subject: "Um documento que diz de que é feito e contém a tabela que lhe dá origem",
    lang: "pt-PT",
    carried_what: "Os encargos que esta página indica, tal como uma máquina os lê",
    heading: "Tarifário, segundo semestre de 2026",
    paragraphs: [
        "Este tarifário declara cumprir a terceira parte da norma de arquivo, no seu \
nível mais alto. Pode conter um ficheiro de qualquer tipo e diz de que é \
feito: esta linha é um título, o bloco abaixo é um parágrafo e o filete do \
rodapé é um ornamento que nada diz.\nUm programa que lê o tarifário em voz \
alta segue a ordem dada pela árvore, e não a ordem em que a tinta foi posta, e \
a tabela que dá origem à página viaja dentro do ficheiro, para que um programa \
a receba inteira.",
        "O transporte custa 12,40 por remessa, o manuseamento 1,85 por volume e a \
armazenagem 0,40 por dia. Cada encargo aplica-se a partir do dia em que a \
remessa é aceite.",
    ],
    foot: "Página 1 de 1",
};

/// The schedule in Dutch.
const DUTCH: Words = Words {
    title: "Tarievenlijst, tweede helft van 2026",
    subject: "Een document dat zegt waaruit het bestaat en de tabel erachter bevat",
    lang: "nl-NL",
    carried_what: "De tarieven op deze pagina, zoals een machine ze leest",
    heading: "Tarievenlijst, tweede helft van 2026",
    paragraphs: [
        "Deze tarievenlijst verklaart te voldoen aan het derde deel van de archiefnorm, \
op het hoogste niveau. Ze mag een bestand van elke soort bevatten en zegt \
waaruit ze bestaat: deze regel is een kop, het blok eronder is een alinea en \
de lijn onderaan is opsmuk die niets zegt.\nEen voorleesprogramma houdt de \
volgorde van de boom aan en niet die waarin de inkt is neergezet, en de tabel \
achter de pagina reist mee in het bestand, zodat een programma haar in zijn \
geheel kan overnemen.",
        "Vervoer kost 12,40 per zending, behandeling 1,85 per pakket en opslag 0,40 per \
dag. Een tarief geldt vanaf de dag waarop de zending wordt aanvaard.",
    ],
    foot: "Pagina 1 van 1",
};

/// 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),
];

/// Where each block of what the page says goes, in the order it is read: the
/// tag it stands under, the size it is set at, the box it goes in, and the
/// leading where it states one. The blocks say the heading and the two
/// paragraphs of `Words`, in that order.
type Placed = (&'static str, f64, f64, f64, f64, Option<f64>);

/// The heading, then the two paragraphs.
const READ: [Placed; 3] = [
    ("H1", 20.0, 72.0, 782.0, 451.0, None),
    ("P", 11.0, 72.0, 730.0, 451.0, Some(16.0)),
    ("P", 11.0, 72.0, 596.0, 451.0, Some(16.0)),
];

/// The rule at the foot of the page, and the box of the line under it. Neither
/// is part of the reading, so both are marked as furniture.
const RULE: (f64, f64, f64, f64) = (72.0, 70.0, 451.0, 1.0);
const FOOT: (f64, f64, f64, f64) = (9.0, 72.0, 68.0, 451.0);

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

    let mut doc = Document::new();
    doc.set_license(licence::licensed());
    doc.set_conformance(PdfA::A3A);

    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);

    doc.attach(Attachment::new(
        CARRIED_NAME,
        words.carried_what,
        CARRIED_TYPE,
        Relationship::Data,
        CHANGED,
        CARRIED.as_bytes().to_vec(),
    ));

    let font = doc.add_font(Font::parse(fs::read(&font_path)?)?);
    let (page, sect) = sheet(&font, words)?;
    doc.add_page(page)?;
    doc.set_structure(
        StructureTree::new()
            .lang(words.lang)
            .child(StructElement::new("Document").child(sect)),
    );

    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 one page, and the branch of the tree that says what is on it.
fn sheet(font: &FontHandle, words: &Words) -> Result<(Page, StructElement), Error> {
    let mut c = Content::new();
    let mut marks = Marks::new();
    let mut sect = StructElement::new("Sect");

    let said = [words.heading, words.paragraphs[0], words.paragraphs[1]];
    for ((tag, size, left, top, width, leading), text) in READ.into_iter().zip(said) {
        let mut flow = TextFlow::new(font, size).first_baseline(FirstBaseline::Points(0.0));
        if let Some(leading) = leading {
            flow = flow.leading(leading);
        }
        let lines = flow.break_lines(text, width);
        c.begin_text();
        let runs = flow.draw_tagged(
            &mut c,
            &lines,
            left,
            top,
            width,
            &Name::new(tag),
            &mut marks,
        )?;
        c.end_text();

        let mut element = StructElement::new(tag);
        for run in runs {
            element = element.content(0, run);
        }
        sect = sect.child(element);
    }

    foot(&mut c, font, words.foot)?;

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

/// The rule and the page number at the foot, both marked as furniture so that
/// nothing reading the document aloud says them.
fn foot(c: &mut Content, font: &FontHandle, text: &str) -> Result<(), Error> {
    let (left, low, width, height) = RULE;
    c.begin_artifact(Artifact::Footer);
    c.save_state();
    c.set_fill_rgb(0.0, 0.0, 0.0)?;
    c.rect(left, low, width, height)?;
    c.fill();
    c.restore_state();
    c.end_marked();

    let (size, left, top, width) = FOOT;
    let flow = TextFlow::new(font, size).first_baseline(FirstBaseline::Points(0.0));
    let lines = flow.break_lines(text, width);
    c.begin_artifact(Artifact::Footer);
    c.begin_text();
    flow.draw(c, &lines, left, top, width)?;
    c.end_text();
    c.end_marked();
    Ok(())
}

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

    use super::{FOOT, READ, RULE, WORDS, default_font, language};

    /// The lines two languages are allowed to write the same way: Spanish and
    /// Portuguese number a page with the same words.
    const SPARED: [&str; 1] = [r#"foot: "Página 1 de 1""#];

    #[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:?}"
        );
    }

    /// The heading and the page number each hold one line, and each paragraph
    /// ends a line above what stands under it: the second paragraph, then the
    /// rule at the foot. A paragraph one line too long is drawn over the next
    /// block, and nothing else on the page says so.
    #[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"),
        );
        let (_, heading_size, _, _, heading_width, _) = READ[0];
        let (foot_size, _, _, foot_width) = FOOT;
        let floors = [READ[2].3, RULE.1];

        for (named, words) in WORDS {
            let code = named.code();
            for (size, width, text) in [
                (heading_size, heading_width, words.heading),
                (foot_size, foot_width, words.foot),
            ] {
                let lines = TextFlow::new(&font, size).break_lines(text, width).len();
                assert_eq!(
                    lines, 1,
                    "the {code} record breaks {text:?} onto {lines} lines"
                );
            }

            for ((placed, text), floor) in READ[1..].iter().zip(words.paragraphs).zip(floors) {
                let (_, size, _, top, width, leading) = *placed;
                let leading = leading.expect("a paragraph states its leading");
                let lines = TextFlow::new(&font, size)
                    .leading(leading)
                    .break_lines(text, width)
                    .len();
                let count = f64::from(u32::try_from(lines).expect("a paragraph is a few lines"));
                assert!(
                    count * leading <= top - floor,
                    "the {code} record sets a paragraph on {lines} lines from {top}, \
                     and it has down to {floor}"
                );
            }
        }
    }
}