write_own_notes.rs

//! Leaves a program's own notes in the file, for itself, where no reading
//! software shows them.
//!
//! A press room sends a proof out and gets it back three days later with a note
//! in the margin. To pick the job up again it has to know which run the sheet
//! belongs to, which plate the page was set for, and which ink the colour bar
//! was drawn against — and none of that is anything a reading software should
//! show.
//!
//! So it travels under the document instead. The file carries the run, the page
//! carries its plate, and the drawing placed twice on it carries the ink it was
//! set against. Each packet is stamped with the moment its program last touched
//! it, and each is filed under the name of that program, so two programs
//! leaving notes in the same file never read each other's.
//!
//! Nothing of any of it is drawn. What is on the page is a proof; what is under
//! it is how the press room finds its way back.
//!
//! Usage: `cargo run --example write_own_notes -- tmp/own_notes.pdf`
//!        `HQF_PDF_LANG=fr cargo run --example write_own_notes -- tmp/notes.pdf`

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

use hqf_pdf::content::Content;
use hqf_pdf::layout::TextFlow;
use hqf_pdf::{Document, Drawing, Font, FontHandle, Page, PrivateData, Rect, Rgb};

#[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.
fn default_font() -> PathBuf {
    Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("tests")
        .join("fonts")
        .join("DejaVuSans.ttf")
}

/// The margin the page is laid out inside.
const MARGIN: f64 = 56.0;

/// How far the page runs across, between the margins.
const WIDTH: f64 = 483.0;

/// The program the notes are filed under. Two programs leaving notes in the
/// same file never read each other's, because each is filed under its own name.
const PROGRAM: &str = "PressDesk";

/// When the program last touched what it left, in ISO 8601.
const TOUCHED: &str = "2026-09-07T08:15:00+02:00";

/// What the file, the page and the drawing each carry.
const FOR_THE_FILE: &str = r#"{"run":47,"press":"K4","proof":3}"#;
const FOR_THE_PAGE: &str = r#"{"plate":"C","screen":175}"#;
const FOR_THE_DRAWING: &str = r#"{"ink":"process cyan","bar":"solid"}"#;

/// How many patches the colour bar is drawn out of.
const PATCHES: usize = 6;

/// How wide and how tall one patch of the bar is.
const PATCH: (f64, f64) = (28.0, 18.0);

/// How far along the bar each patch starts.
const PATCH_AT: [f64; PATCHES] = [0.0, 28.0, 56.0, 84.0, 112.0, 140.0];

/// How strong the ink is in each patch.
const STRENGTH: [f64; PATCHES] = [0.15, 0.3, 0.45, 0.6, 0.8, 1.0];

/// Where the bar is placed on the page, and at what scale.
const PLACED: [(f64, f64, f64); 2] = [(MARGIN, 672.0, 1.0), (MARGIN, 616.0, 0.5)];

/// The words the page is written in, one set per language.
#[derive(Debug)]
struct Words {
    /// The line at the head of the page.
    title: &'static str,
    /// The paragraph under it.
    body: &'static str,
    /// The line under the second bar.
    caption: &'static str,
}

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

/// The page in English.
const ENGLISH: Words = Words {
    title: "Press proof",
    body: "This sheet is a proof, and everything a reading software shows of it \
           is on it: a title, this paragraph, and a colour bar placed twice. \
           Under it the file states the run it belongs to, the page states the \
           plate it was set for, and the bar states the ink it was drawn \
           against.",
    caption: "None of those three is drawn, and no reading software shows them. \
              Each is filed under the name of the program that left it, stamped \
              with the moment that program last touched it, and travels with \
              the file until it opens the file again.",
};

/// The page in French.
const FRENCH: Words = Words {
    title: "Épreuve d'imprimerie",
    body: "Cette feuille est une épreuve, et tout ce qu'un logiciel de lecture \
           en montre est dessus : un titre, ce paragraphe, et une gamme de \
           couleurs placée deux fois. En dessous, le fichier porte le tirage \
           auquel il appartient, la page porte la plaque pour laquelle elle a \
           été composée, et la gamme porte l'encre contre laquelle elle a été \
           tracée.",
    caption: "Aucune des trois n'est dessinée, et aucun logiciel de lecture ne \
              les montre. Elles sont rangées sous le nom du programme qui les a \
              laissées, datées du moment où il y a touché pour la dernière \
              fois, et elles voyagent avec le fichier jusqu'à ce que ce \
              programme le rouvre.",
};

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

/// The colour bar: six patches of increasing strength, side by side.
fn colour_bar() -> Result<Drawing, hqf_pdf::Error> {
    let mut bar = Content::new();
    for (at, strength) in PATCH_AT.iter().zip(STRENGTH) {
        bar.set_fill(Rgb::new(1.0 - strength, strength.mul_add(-0.15, 1.0), 1.0))?;
        bar.rect(*at, 0.0, PATCH.0, PATCH.1)?;
        bar.fill();
    }
    let across = PATCH_AT[PATCHES - 1] + PATCH.0;
    Ok(Drawing::new(bar, Rect::new(0.0, 0.0, across, PATCH.1)))
}

/// Writes a line of ordinary text at `(x, y)`.
fn write(
    content: &mut Content,
    font: &FontHandle,
    x: f64,
    y: f64,
    size: f64,
    text: &str,
) -> Result<(), hqf_pdf::Error> {
    content.begin_text();
    content.set_font(font, size)?;
    content.text_origin(x, y)?;
    content.show_glyphs(&font.glyphs(text));
    content.end_text();
    Ok(())
}

/// Writes a paragraph in a column the width of the page.
fn paragraph(
    content: &mut Content,
    font: &FontHandle,
    size: f64,
    top: f64,
    color: Rgb,
    text: &str,
) -> Result<(), hqf_pdf::Error> {
    let flow = TextFlow::new(font, size).leading(size * 1.4).color(color);
    let lines = flow.break_lines(text, WIDTH);
    content.begin_text();
    flow.draw(content, &lines, MARGIN, top, WIDTH)?;
    content.end_text();
    Ok(())
}

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

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

    // 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 = env::args()
        .nth(1)
        .unwrap_or_else(|| language.file_name(&out::default_path("own_notes")));

    let mut doc = Document::new();
    doc.set_license(licence::licensed());
    doc.set_private_data(PrivateData::new(PROGRAM, TOUCHED, FOR_THE_FILE)?);
    let font = doc.add_font(Font::parse(fs::read(default_font())?)?);

    let bar = doc.add_drawing(colour_bar()?.with_private_data(Some(PrivateData::new(
        PROGRAM,
        TOUCHED,
        FOR_THE_DRAWING,
    )?)));

    let mut content = Content::new();
    write(&mut content, &font, MARGIN, 780.0, 16.0, words.title)?;
    paragraph(&mut content, &font, 10.0, 770.0, Rgb::BLACK, words.body)?;
    for (x, y, scale) in PLACED {
        content.draw_form(bar.name(), x, y, scale)?;
    }
    paragraph(
        &mut content,
        &font,
        8.5,
        560.0,
        Rgb::gray(0.35),
        words.caption,
    )?;

    let mut page = Page::a4();
    page.content = content.into_bytes();
    page.private_data = Some(PrivateData::new(PROGRAM, TOUCHED, FOR_THE_PAGE)?);
    doc.add_page(page)?;

    let bytes = doc.to_bytes()?;
    if let Some(parent) = Path::new(&out).parent() {
        fs::create_dir_all(parent)?;
    }
    fs::write(&out, &bytes)?;
    println!(
        "wrote {out}: {} bytes, notes on the file, the page and the drawing",
        bytes.len()
    );
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::{WORDS, language};

    /// The lines two languages write the same way. There are none: every word
    /// on the page is a word of the language it is in.
    const SPARED: [&str; 0] = [];

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

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