retex_engine/

pdfext.rs

//! `\pdfextension` (LuaTeX manual §3.2.2): PDF literals, matrices,
//! colour stacks, objects, annotations, links, destinations, outlines and
//! document-level dictionaries.
//!
//! Commands that act at shipout become whatsit nodes in the current list;
//! document-level data is collected in [`PdfState`] for the backend.
//!
//! # Object numbers
//!
//! The engine and the PDF writer share one object counter
//! ([`PdfState::counter`]), so the numbers TeX and Lua see
//! (`\pdffeedback lastobj`, `pdf.getpageref`, …) are those in the file.
//! Observed in LuaTeX 1.22:
//!
//! * `\pdfextension annot` and `startlink` take their number when they are
//!   scanned; continuation rectangles of a link get theirs at shipout.
//! * A named or numbered destination gets its number the first time it is
//!   referred to (by an outline or open action when it is scanned, by a
//!   link when the page is written) or met at shipout, whichever comes
//!   first. Pages likewise (`goto page`, `\pdffeedback pageref`).
//! * `\pdfextension outline` allocates the action (written at once), the
//!   numbers of the destination it refers to, the entry, and the title
//!   (written at once as `(title)` and a newline).
//! * Destinations that were referred to but never defined are written at
//!   the end as `[ last-page 0 R /Fit ]`, in the reverse order of their
//!   allocation, each with a warning.

use std::cell::Cell;
use std::collections::HashMap;
use std::rc::Rc;

use crate::Engine;
use crate::nodes::{LateData, NodeData, RUNNING, Whatsit, id, whatsit_sub};
use crate::token::TokenList;

/// Literal modes (`mode` of `pdf_literal` whatsits).
#[allow(missing_docs)]
pub mod literal_mode {
    pub const ORIGIN: u8 = 0;
    pub const PAGE: u8 = 1;
    pub const DIRECT: u8 = 2;
    pub const RAW: u8 = 3;
}

/// Colour-stack commands.
#[allow(missing_docs)]
pub mod colorstack_cmd {
    pub const SET: u8 = 0;
    pub const PUSH: u8 = 1;
    pub const POP: u8 = 2;
    pub const CURRENT: u8 = 3;
}

/// A PDF object created with `\pdfextension obj`.
#[derive(Clone, Debug, Default)]
pub struct PdfObject {
    /// The PDF object number.
    pub num: i32,
    /// The object content (dictionary text, or stream data).
    pub data: Vec<u8>,
    /// Whether this is a stream object.
    pub stream: bool,
    /// Stream dictionary entries (`attr {…}`).
    pub attr: Vec<u8>,
    /// Whether `data` names a file whose content is the object.
    pub file: bool,
    /// Whether the object must not go into an object stream.
    pub uncompressed: bool,
    /// Whether the content has been given (not just reserved).
    pub defined: bool,
    /// Whether it has been written (immediately or at shipout).
    pub written: bool,
}

/// An outline entry (`\pdfextension outline`).
#[derive(Clone, Debug, Default)]
pub struct Outline {
    /// Extra dictionary entries.
    pub attr: Vec<u8>,
    /// The entry's object.
    pub objnum: i32,
    /// The title object.
    pub title: i32,
    /// The action object.
    pub action: i32,
    /// `count` (number of direct children; negative means closed).
    pub count: i32,
}

/// Colour-stack definition.
#[derive(Clone, Debug)]
pub struct ColorStack {
    /// Whether the stack's current value is written at the start of every
    /// page (`page` keyword).
    pub page: bool,
    /// The literal mode of its literals (observed: `direct` for stack 0,
    /// whose literals go inside a text object without ending it;
    /// `origin` for stacks declared without `direct`).
    pub mode: u8,
    /// The initial value.
    pub init: Vec<u8>,
}

/// Kinds of PDF object numbers, as `pdf.getobjtype` names them.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ObjKind {
    /// `\pdfextension obj`, `pdf.obj`, `pdf.reserveobj()`.
    Obj,
    /// `\pdfextension annot`, `pdf.reserveobj("annot")`.
    Annot,
    /// Links (`\pdfextension startlink`); LuaTeX reports `others`.
    Link,
    /// Page objects (`pdf.getpageref`, `\pdffeedback pageref`).
    Page,
    /// Font objects (`pdf.getfontobjnum`, `\pdffeedback fontobjnum`).
    Font,
    /// Image XObjects (`\saveimageresource`).
    Ximage,
    /// Box resources (`\saveboxresource`).
    Xform,
    /// Destinations, outline entries, actions, threads.
    Other,
}

impl ObjKind {
    /// The name returned by `pdf.getobjtype`.
    pub fn name(self) -> &'static str {
        match self {
            ObjKind::Obj => "obj",
            ObjKind::Annot => "annot",
            ObjKind::Link | ObjKind::Other => "others",
            ObjKind::Page => "page",
            ObjKind::Font => "font",
            ObjKind::Ximage => "ximage",
            ObjKind::Xform => "xform",
        }
    }
}

/// Dictionary texts set from Lua (`pdf.setcatalog` and friends). They are
/// independent of the token lists set at the TeX end and are written after
/// them; `None` means never set (the getters return `nil`).
#[derive(Clone, Debug, Default)]
pub struct LuaPdfTexts {
    /// `pdf.setcatalog`.
    pub catalog: Option<Vec<u8>>,
    /// `pdf.setinfo`.
    pub info: Option<Vec<u8>>,
    /// `pdf.setnames`.
    pub names: Option<Vec<u8>>,
    /// `pdf.settrailer` (observed: LuaTeX 1.22 does not write it).
    pub trailer: Option<Vec<u8>>,
    /// `pdf.settrailerid`.
    pub trailer_id: Option<Vec<u8>>,
    /// `pdf.setpageattributes`.
    pub page_attributes: Option<Vec<u8>>,
    /// `pdf.setpageresources`.
    pub page_resources: Option<Vec<u8>>,
    /// `pdf.setpagesattributes`.
    pub pages_attributes: Option<Vec<u8>>,
    /// `pdf.setxformattributes`.
    pub xform_attributes: Option<Vec<u8>>,
    /// `pdf.setxformresources`.
    pub xform_resources: Option<Vec<u8>>,
}

/// State of the `\latelua` call being executed at shipout.
#[derive(Clone, Debug, Default)]
pub struct LateLuaContext {
    /// Literals queued by `pdf.print`: (literal mode, text).
    pub prints: Vec<(u8, Vec<u8>)>,
    /// Annotations added with `pdf.registerannot`.
    pub annots: Vec<i32>,
}

/// Identifies a destination (`name {…}` or `num n`).
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub enum DestId {
    /// `name {…}`.
    Name(Vec<u8>),
    /// `num n`.
    Num(i32),
}

impl DestId {
    /// How warnings name the identifier: `name 'x'` or `num '3'`.
    fn describe(&self) -> String {
        match self {
            DestId::Name(n) => format!("name '{}'", String::from_utf8_lossy(n)),
            DestId::Num(n) => format!("num '{n}'"),
        }
    }
}

/// The destination types of `\pdfextension dest`.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum DestKind {
    /// `xyz`.
    Xyz,
    /// `fit`.
    Fit,
    /// `fith`.
    FitH,
    /// `fitv`.
    FitV,
    /// `fitb`.
    FitB,
    /// `fitbh`.
    FitBH,
    /// `fitbv`.
    FitBV,
    /// `fitr`.
    FitR,
}

/// The view of `\pdfextension dest`.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct DestView {
    /// The type.
    pub kind: DestKind,
    /// `zoom` for `xyz` (0 when not given).
    pub zoom: i32,
    /// `width`, `height`, `depth` for `fitr` ([`RUNNING`] when not given).
    pub dims: [i32; 3],
}

/// What an action refers to.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum ActionTarget {
    /// `name {…}`.
    Name(Vec<u8>),
    /// `num n`.
    Num(i32),
    /// `page n {view}`.
    Page(i32, Vec<u8>),
}

/// An action specification (`user`, `goto`, `thread`).
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum PdfAction {
    /// `user {…}`.
    User(Vec<u8>),
    /// `goto [file {…}] [struct …] …`.
    Goto {
        /// `file {…}`.
        file: Option<Vec<u8>>,
        /// `struct name {…}` or `struct num n`: the structure destination
        /// (`/SD`).
        structure: Option<ActionTarget>,
        /// The target.
        target: ActionTarget,
        /// `newwindow` (true) or `nonewwindow` (false).
        new_window: Option<bool>,
    },
    /// `thread [file {…}] …`.
    Thread {
        /// `file {…}`.
        file: Option<Vec<u8>>,
        /// The target.
        target: ActionTarget,
    },
}

/// A destination's view in page coordinates (sp), for the backend.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum DestPos {
    /// `/XYZ x y zoom` (zoom in thousandths, 0 for `null`).
    Xyz {
        /// Left.
        x: i32,
        /// Top.
        y: i32,
        /// Zoom times 1000.
        zoom: i32,
    },
    /// `/Fit`.
    Fit,
    /// `/FitB`.
    FitB,
    /// `/FitH y`.
    FitH(i32),
    /// `/FitBH y`.
    FitBH(i32),
    /// `/FitV x`.
    FitV(i32),
    /// `/FitBV x`.
    FitBV(i32),
    /// `/FitR x1 y1 x2 y2`.
    FitR([i32; 4]),
}

/// One rectangle of a link, as written.
#[derive(Clone, Debug)]
pub struct LinkPiece {
    /// The annotation's object number.
    pub objnum: i32,
    /// The rectangle (sp, page coordinates).
    pub rect: [i32; 4],
    /// `attr {…}`.
    pub attr: Vec<u8>,
    /// The action text: a dictionary, or the user text.
    pub action: Vec<u8>,
    /// Whether `action` is user text.
    pub user: bool,
    /// The action, turned into `action` when the page is written (LuaTeX
    /// allocates the destinations links refer to then).
    pub source: PdfAction,
}

/// A link whose `\pdfextension endlink` has not been shipped yet.
#[derive(Clone, Debug)]
pub struct ActiveLink {
    /// Box nesting level (`cur_s`) of the box that holds the startlink;
    /// every later hlist at that level gets a rectangle of its own.
    pub level: i32,
    /// The rectangle being built on the current page, if any.
    pub piece: Option<usize>,
    /// Whether that rectangle is the first one, whose right edge is still
    /// open.
    pub first_open: bool,
    /// `\pdfvariable linkmargin` at the start of the link.
    pub margin: i32,
    /// Whether the current rectangle continues the link from an earlier
    /// box (it then ends at the endlink without margin).
    pub continued: bool,
    /// `attr {…}`.
    pub attr: Vec<u8>,
    /// The action.
    pub action: PdfAction,
    /// The current rectangle before transformation and margin.
    pub raw: [i32; 4],
    /// The transformation (`\pdfextension setmatrix`) where it started.
    pub matrix: Option<[f64; 6]>,
}

/// An annotation's rectangle (sp, page coordinates) and text.
pub type AnnotBody = ([i32; 4], Vec<u8>);

/// The interactive items of the page being shipped, handed to the
/// backend when the page ends.
#[derive(Clone, Debug, Default)]
pub struct PageItems {
    /// Annotations: object number and, unless written by other means
    /// (`pdf.registerannot`), rectangle and text.
    pub annots: Vec<(i32, Option<AnnotBody>)>,
    /// Link rectangles, in the order they were started.
    pub links: Vec<LinkPiece>,
    /// Destinations: object number, whether named, view, and for a
    /// structure destination the structure element's object.
    pub dests: Vec<(i32, bool, DestPos, Option<i32>)>,
    /// Objects to write with the page (`\pdfextension refobj`).
    pub objects: Vec<PdfObject>,
    /// Page attributes: the TeX and the Lua text.
    pub attr: (Vec<u8>, Vec<u8>),
    /// Page resources: the TeX and the Lua text.
    pub resources: (Vec<u8>, Vec<u8>),
}

/// Document-level items computed at the end of the run for the backend.
#[derive(Clone, Debug, Default)]
pub struct DocItems {
    /// Destinations referred to but never defined, in writing order.
    pub missing_dests: Vec<i32>,
    /// Threads referred to but never defined: object and title.
    pub missing_threads: Vec<(i32, Vec<u8>)>,
    /// Named destinations sorted by name.
    pub dest_names: Vec<(Vec<u8>, i32)>,
    /// `\pdfvariable pagesattr` at the end of the run.
    pub pages_attr: Vec<u8>,
    /// `\pdfvariable trailerid` at the end of the run.
    pub trailer_id: Vec<u8>,
}

/// A destination known by its identifier.
#[derive(Clone, Copy, Debug, Default)]
pub struct DestEntry {
    /// The object number.
    pub objnum: i32,
    /// Whether `\pdfextension dest` was shipped for it.
    pub defined: bool,
}

/// Document-level PDF state.
#[derive(Clone, Debug, Default)]
pub struct PdfState {
    /// Images written while shipping the current page, in order of first
    /// use: their file names are printed at the end of the page.
    pub page_images: Vec<u32>,
    /// Objects by PDF object number.
    pub objects: std::collections::BTreeMap<i32, PdfObject>,
    /// `\pdfextension catalog` text.
    pub catalog: Vec<u8>,
    /// The catalog's open action (object number).
    pub open_action: Option<i32>,
    /// `\pdfextension info` text.
    pub info: Vec<u8>,
    /// `\pdfextension names` text.
    pub names: Vec<u8>,
    /// `\pdfextension trailer` text.
    pub trailer: Vec<u8>,
    /// Outline entries in order.
    pub outlines: Vec<Outline>,
    /// `\pdfextension glyphtounicode` pairs.
    pub glyph_to_unicode: Vec<(Vec<u8>, Vec<u8>)>,
    /// Colour stacks; stack 0 is the predefined colour stack.
    pub colorstacks: Vec<ColorStack>,
    /// `\pdffeedback lastobj`.
    pub last_obj: i32,
    /// `\pdffeedback lastannot`.
    pub last_annot: i32,
    /// `\pdffeedback lastlink`.
    pub last_link: i32,
    /// The highest object number allocated so far, shared with the PDF
    /// writer.
    pub counter: Rc<Cell<u32>>,
    /// The kind of each allocated object number.
    pub kinds: HashMap<i32, ObjKind>,
    /// Page object numbers by page number (forward references included).
    pub page_refs: HashMap<i32, i32>,
    /// PDF fonts (resource name number, object number) by font, see
    /// [`Engine::pdf_font`].
    pub fonts: HashMap<u32, (u32, i32)>,
    /// `\pdfextension fontattr` and `pdf.setfontattributes` texts by font.
    pub font_attrs: HashMap<u32, Vec<u8>>,
    /// Map files and map lines (`pdf.mapfile`, `pdf.mapline`,
    /// `\pdfextension mapfile`/`mapline`), in order.
    pub map_entries: Vec<Vec<u8>>,
    /// Texts set from Lua.
    pub lua: LuaPdfTexts,
    /// `\pdffeedback retval`.
    pub retval: i32,
    /// The position (PDF coordinates, sp) of the last `\latelua`, for
    /// `pdf.getpos`.
    pub pos: (i32, i32),
    /// The `\latelua` being executed, if any.
    pub late: Option<LateLuaContext>,
    /// Annotations registered from Lua for the page being shipped.
    pub page_annots: Vec<i32>,
    /// Whether `pdf.obj` opened the output file (in DVI mode LuaTeX then
    /// leaves an empty DVI file when no page is shipped out).
    pub output_opened: bool,
    /// Destinations by identifier.
    pub dests: HashMap<DestId, DestEntry>,
    /// Destination identifiers in the order their numbers were allocated.
    pub dest_order: Vec<DestId>,
    /// Structure destinations by identifier (`\pdfextension dest struct`).
    pub struct_dests: HashMap<DestId, DestEntry>,
    /// Threads referred to by actions: identifier and object number.
    pub threads: Vec<(DestId, i32)>,
    /// The interactive items of the page being shipped.
    pub page: PageItems,
    /// Objects to write as soon as the backend is available again (they
    /// were written during shipout, while the backend is busy).
    pub pending: Vec<PdfObject>,
    /// Document-level items for the backend, computed at the end.
    pub doc: DocItems,
    /// A fatal backend error occurred: no PDF is written.
    pub fatal: bool,
    /// Objects written into object streams and the number of streams.
    pub objstm_stats: (u32, u32),
    /// Whether a stream (form, image or stream object) was written
    /// immediately: with no pages, LuaTeX then fails at the end
    /// ("already written content discarded").
    pub stream_written: bool,
    /// Words of extra memory LuaTeX reports for objects (see
    /// [`Engine::pdf_define_object`]).
    pub obj_words: usize,
    /// Whether the font map note (`{…/pdftex.map}`) was printed.
    pub map_note_done: bool,
    /// Links started but not ended yet, innermost last.
    pub active_links: Vec<ActiveLink>,
}

impl PdfState {
    /// The highest object number allocated so far.
    pub fn max_obj(&self) -> i32 {
        self.counter.get() as i32
    }

    /// The number of named destinations (for the PDF statistics).
    pub fn named_dests(&self) -> usize {
        self.dests
            .keys()
            .filter(|k| matches!(k, DestId::Name(_)))
            .count()
    }
}

impl Engine {
    /// Scans a balanced text (expanded) and returns its characters.
    fn scan_pdf_string(&mut self) -> Vec<u8> {
        let toks = self.scan_toks_expanded();
        self.print_to_string(|e| e.show_token_list(&toks, 0, toks.len(), i64::MAX))
    }

    /// Allocates a PDF object number of kind `kind`.
    pub fn pdf_alloc_obj(&mut self, kind: ObjKind) -> i32 {
        self.figures.taint("PDF objects");
        let n = self.pdf.counter.get() + 1;
        self.pdf.counter.set(n);
        let n = n as i32;
        self.pdf.kinds.insert(n, kind);
        n
    }

    /// The kind of object number `n`, if it was allocated.
    pub fn pdf_obj_kind(&self, n: i32) -> Option<ObjKind> {
        self.pdf.kinds.get(&n).copied()
    }

    /// The object number of page `page` (counting from 1), allocated on
    /// first request (`pdf.getpageref`, `\pdffeedback pageref`).
    pub fn pdf_page_ref(&mut self, page: i32) -> i32 {
        if let Some(&n) = self.pdf.page_refs.get(&page) {
            return n;
        }
        let n = self.pdf_alloc_obj(ObjKind::Page);
        self.pdf.page_refs.insert(page, n);
        n
    }

    /// The object number of destination `id`, allocated on first use.
    pub fn pdf_dest_obj(&mut self, id: &DestId) -> i32 {
        if let Some(d) = self.pdf.dests.get(id) {
            return d.objnum;
        }
        let n = self.pdf_alloc_obj(ObjKind::Other);
        self.pdf.dests.insert(
            id.clone(),
            DestEntry {
                objnum: n,
                defined: false,
            },
        );
        self.pdf.dest_order.push(id.clone());
        n
    }

    /// The object number of structure destination `id`, allocated on
    /// first use.
    pub fn pdf_struct_dest_obj(&mut self, id: &DestId) -> i32 {
        if let Some(d) = self.pdf.struct_dests.get(id) {
            return d.objnum;
        }
        let n = self.pdf_alloc_obj(ObjKind::Other);
        self.pdf.struct_dests.insert(
            id.clone(),
            DestEntry {
                objnum: n,
                defined: false,
            },
        );
        n
    }

    /// The object number of thread `id`, allocated on first use.
    fn pdf_thread_obj(&mut self, id: DestId) -> i32 {
        if let Some((_, n)) = self.pdf.threads.iter().find(|(t, _)| *t == id) {
            return *n;
        }
        let n = self.pdf_alloc_obj(ObjKind::Other);
        self.pdf.threads.push((id, n));
        n
    }

    /// The PDF font of font `f`: the number in its resource name `/F<n>`
    /// and its object number. Fonts with the same name share one PDF font.
    /// It is created when first asked for (by `\pdffeedback fontname` or
    /// `fontobjnum`, or their Lua counterparts), named after the font
    /// asked for, and gets an object number then (observed: asking for
    /// `cmr10 at 12pt` before `cmr10` names both after the former).
    pub fn pdf_font(&mut self, f: u32) -> (u32, i32) {
        if let Some(&r) = self.pdf.fonts.get(&f) {
            return r;
        }
        let name = self.font(f).name.clone();
        let shared = self
            .pdf
            .fonts
            .iter()
            .filter(|(g, _)| self.font_exists(**g as i32) && self.font(**g).name == name)
            .map(|(_, r)| *r)
            .min();
        let r = match shared {
            Some(r) => r,
            None => (f, self.pdf_alloc_obj(ObjKind::Font)),
        };
        self.pdf.fonts.insert(f, r);
        r
    }

    /// Makes sure the predefined colour stack 0 exists.
    pub fn pdf_ensure_colorstacks(&mut self) {
        if self.pdf.colorstacks.is_empty() {
            self.figures.taint("makes a colour stack");
            self.pdf.colorstacks.push(ColorStack {
                page: true,
                mode: literal_mode::DIRECT,
                init: b"0 g 0 G".to_vec(),
            });
        }
    }

    /// Defines a new colour stack and returns its number; stack 0 is the
    /// predefined one (`\pdffeedback colorstackinit`, `pdf.newcolorstack`).
    pub fn pdf_new_colorstack(&mut self, init: Vec<u8>, page: bool, mode: u8) -> i32 {
        self.pdf_ensure_colorstacks();
        self.figures.taint("makes a colour stack");
        self.pdf.colorstacks.push(ColorStack { page, mode, init });
        (self.pdf.colorstacks.len() - 1) as i32
    }

    /// LuaTeX's checks of the object of `\pdfextension refobj` in PDF
    /// mode (observed): it must be a defined `obj` object.
    fn pdf_check_refobj(&mut self, n: i32) {
        if n == 0 {
            // Observed: object 0 counts as a font.
            self.pdf_fatal("referenced object has wrong type font; should be obj");
        }
        match self.pdf_obj_kind(n) {
            None => self.pdf_fatal("cannot find referenced object"),
            Some(ObjKind::Obj) => {
                if !self.pdf.objects.get(&n).is_some_and(|o| o.defined) {
                    self.pdf_fatal("invalid object");
                }
            }
            Some(k) => {
                let msg = format!(
                    "referenced object has wrong type {}; should be obj",
                    k.name()
                );
                self.pdf_fatal(&msg);
            }
        }
    }

    /// Appends a `pdf_refobj` whatsit for object `n` to the current list
    /// (`\pdfextension refobj`, `pdf.refobj` in `\directlua`).
    pub fn pdf_append_refobj(&mut self, n: i32) {
        self.append_whatsit(whatsit_sub::PDF_REFOBJ, Whatsit::PdfRefobj { objnum: n });
    }

    /// Stores object `obj`, makes it `\pdffeedback lastobj`, and writes it
    /// now if `immediate`.
    ///
    /// Observed: LuaTeX's "words of extra memory" grow by 5 for each
    /// object from `\pdfextension obj` (immediate or not) and from
    /// `pdf.obj`, but not from `pdf.immediateobj` or a reservation.
    pub fn pdf_define_object(&mut self, obj: PdfObject, immediate: bool) {
        if !immediate {
            self.pdf.obj_words += 5;
        }
        let n = obj.num;
        self.pdf.last_obj = n;
        self.pdf.stream_written |= immediate && obj.stream;
        self.pdf.objects.insert(n, obj);
        if immediate {
            self.pdf_write_object(n);
        }
    }

    /// Appends a whatsit to the current list.
    fn append_whatsit(&mut self, subtype: u16, w: Whatsit) {
        // Observed: like every node, it carries the current attributes.
        let p = self.new_node(id::WHATSIT, subtype, NodeData::Whatsit(Box::new(w)));
        self.tail_append(p);
    }

    /// Scans `width`, `height`, `depth` keywords (`scan_rule_spec` for
    /// annotations); unspecified dimensions are running.
    fn scan_pdf_rule_spec(&mut self) -> [i32; 3] {
        let mut d = [RUNNING; 3];
        loop {
            let i = if self.scan_keyword("width") {
                0
            } else if self.scan_keyword("height") {
                1
            } else if self.scan_keyword("depth") {
                2
            } else {
                return d;
            };
            self.scan_normal_dimen();
            d[i] = self.cur_val;
        }
    }

    /// Reports a fatal backend error the way LuaTeX does and ends the run
    /// without writing the PDF file.
    pub fn pdf_fatal(&mut self, msg: &str) -> ! {
        self.pdf_fatal_in("pdf backend", msg)
    }

    /// [`Engine::pdf_fatal`] with another category.
    pub fn pdf_fatal_in(&mut self, category: &str, msg: &str) -> ! {
        self.normalize_selector();
        self.printer.print_nl("! error:  (");
        self.printer.print_str(category);
        self.printer.print_str("): ");
        self.printer.print_str(msg);
        self.printer
            .print_nl("!  ==> Fatal error occurred, no output PDF file produced!");
        self.printer.update_terminal();
        // Observed: LuaTeX stops right there; the log ends without a
        // newline and the PDF file is gone.
        self.pdf.fatal = true;
        self.err.history = crate::error::History::FatalErrorStop;
        let _ = std::fs::remove_file(self.output_path("pdf"));
        self.printer.close_log();
        std::panic::resume_unwind(Box::new(crate::error::JumpOut));
    }

    /// Prints a backend warning on a line of its own
    /// (`warning  (pdf backend): …`).
    pub fn pdf_warning(&mut self, msg: &str) {
        self.printer.print_nl("warning  (pdf backend): ");
        self.printer.print_str(msg);
        self.printer.print_ln();
    }

    /// Scans an action specification (`user {…}` | `goto …` | `thread …`).
    fn scan_pdf_action(&mut self) -> Option<PdfAction> {
        if self.scan_keyword("user") {
            return Some(PdfAction::User(self.scan_pdf_string()));
        }
        let goto = if self.scan_keyword("goto") {
            true
        } else if self.scan_keyword("thread") {
            false
        } else {
            self.pdf_fatal("action type missing");
        };
        let file = if self.scan_keyword("file") {
            Some(self.scan_pdf_string())
        } else {
            None
        };
        // LuaTeX 1.22: `goto struct name {…}` or `struct num n` names the
        // structure destination of the link.
        let structure = if goto && self.scan_keyword("struct") {
            if self.scan_keyword("name") {
                Some(ActionTarget::Name(self.scan_pdf_string()))
            } else if self.scan_keyword("num") {
                self.scan_int();
                Some(ActionTarget::Num(self.cur_val))
            } else {
                self.pdf_fatal("identifier type missing");
            }
        } else {
            None
        };
        let target = if goto && self.scan_keyword("page") {
            self.scan_int();
            let page = self.cur_val;
            ActionTarget::Page(page, self.scan_pdf_string())
        } else if self.scan_keyword("name") {
            ActionTarget::Name(self.scan_pdf_string())
        } else if self.scan_keyword("num") {
            if goto && file.is_some() {
                self.pdf_fatal("'goto' option cannot be used with both 'file' and 'num'");
            }
            self.scan_int();
            ActionTarget::Num(self.cur_val)
        } else {
            self.pdf_fatal("identifier type missing");
        };
        let new_window = if self.scan_keyword("newwindow") {
            Some(true)
        } else if self.scan_keyword("nonewwindow") {
            Some(false)
        } else {
            None
        };
        if new_window.is_some() && !(goto && file.is_some()) {
            self.pdf_fatal(
                "'newwindow' or 'nonewwindow' must be used with 'goto' and 'file' option",
            );
        }
        Some(if goto {
            PdfAction::Goto {
                file,
                structure,
                target,
                new_window,
            }
        } else {
            PdfAction::Thread { file, target }
        })
    }

    /// The PDF text of an action (a dictionary, or the user text),
    /// allocating the objects of the destinations, pages and threads it
    /// refers to.
    pub fn pdf_action_text(&mut self, action: &PdfAction) -> Vec<u8> {
        fn string(out: &mut Vec<u8>, s: &[u8]) {
            out.push(b'(');
            out.extend_from_slice(s);
            out.push(b')');
        }
        let mut d = b"<< ".to_vec();
        match action {
            PdfAction::User(u) => return u.clone(),
            PdfAction::Goto {
                file: None,
                target,
                structure,
                ..
            } => {
                d.extend_from_slice(b"/S /GoTo /D ");
                match target {
                    ActionTarget::Name(n) => {
                        self.pdf_dest_obj(&DestId::Name(n.clone()));
                        string(&mut d, n);
                    }
                    ActionTarget::Num(n) => {
                        let o = self.pdf_dest_obj(&DestId::Num(*n));
                        d.extend_from_slice(format!("{o} 0 R").as_bytes());
                    }
                    ActionTarget::Page(p, spec) => {
                        let o = self.pdf_page_ref((*p).max(1));
                        d.extend_from_slice(format!("[ {o} 0 R ").as_bytes());
                        d.extend_from_slice(spec);
                        d.extend_from_slice(b" ]");
                    }
                }
                // Observed: ` /SD n 0 R` after the destination, numbered
                // after it.
                let sd = structure.as_ref().map(|s| {
                    let id = match s {
                        ActionTarget::Name(n) => DestId::Name(n.clone()),
                        ActionTarget::Num(n) => DestId::Num(*n),
                        ActionTarget::Page(..) => DestId::Num(0),
                    };
                    self.pdf_struct_dest_obj(&id)
                });
                if let Some(o) = sd {
                    d.extend_from_slice(format!(" /SD {o} 0 R").as_bytes());
                }
            }
            PdfAction::Goto {
                file: Some(f),
                target,
                new_window,
                ..
            } => {
                d.extend_from_slice(b"/F ");
                string(&mut d, f);
                d.push(b' ');
                match new_window {
                    Some(true) => d.extend_from_slice(b" /NewWindow true"),
                    Some(false) => d.extend_from_slice(b" /NewWindow false"),
                    None => {}
                }
                match target {
                    ActionTarget::Name(n) => {
                        d.extend_from_slice(b" /S /GoToR /D ");
                        string(&mut d, n);
                    }
                    ActionTarget::Page(p, spec) => {
                        // Observed: /GoTo (not /GoToR), page counted from 0.
                        d.extend_from_slice(format!(" /S /GoTo /D [{} ", p - 1).as_bytes());
                        d.extend_from_slice(spec);
                        d.extend_from_slice(b" ]");
                    }
                    ActionTarget::Num(_) => {}
                }
            }
            PdfAction::Thread { file, target } => {
                if let Some(f) = file {
                    // Observed: the identifier is dropped.
                    d.extend_from_slice(b"/F ");
                    string(&mut d, f);
                    d.extend_from_slice(b"  /S /Thread");
                } else {
                    d.extend_from_slice(b"/S /Thread /D ");
                    match target {
                        ActionTarget::Name(n) => {
                            self.pdf_thread_obj(DestId::Name(n.clone()));
                            string(&mut d, n);
                        }
                        ActionTarget::Num(n) => {
                            let o = self.pdf_thread_obj(DestId::Num(*n));
                            d.extend_from_slice(format!("{o} 0 R").as_bytes());
                        }
                        ActionTarget::Page(..) => {}
                    }
                }
            }
        }
        d.extend_from_slice(b" >>");
        d
    }

    /// Writes `body` as object `n` now (actions and titles of outlines,
    /// the open action).
    fn pdf_write_raw(&mut self, n: i32, body: Vec<u8>) {
        let obj = PdfObject {
            num: n,
            data: body,
            defined: true,
            ..Default::default()
        };
        self.pdf_write_object_data(&obj);
    }

    /// Writes an action object for `action` now and returns its number;
    /// user actions are written between newlines.
    fn pdf_write_action(&mut self, action: &PdfAction) -> i32 {
        let n = self.pdf_alloc_obj(ObjKind::Other);
        if let Some(mut be) = self.backend.take() {
            be.begin_object(self);
            self.backend = Some(be);
        }
        let body = match action {
            PdfAction::User(u) => {
                let mut b = b"\n".to_vec();
                b.extend_from_slice(u);
                b.push(b'\n');
                b
            }
            _ => self.pdf_action_text(action),
        };
        self.pdf_write_raw(n, body);
        n
    }

    /// Executes `\pdfextension` (`immediate` when prefixed by
    /// `\immediate`).
    pub fn pdf_extension(&mut self, immediate: bool) {
        if self.eqtb.int(crate::primitives_gen::assign_int::OUTPUTMODE) <= 0 {
            // Observed: in DVI mode LuaTeX ignores `\pdfextension` without
            // reading any keyword.
            return;
        }
        if self.scan_keyword("literal") {
            let late = self.scan_keyword("shipout");
            let mode = if self.scan_keyword("direct") {
                literal_mode::DIRECT
            } else if self.scan_keyword("page") {
                literal_mode::PAGE
            } else if self.scan_keyword("raw") {
                literal_mode::RAW
            } else {
                literal_mode::ORIGIN
            };
            let data = if late {
                LateData::Tokens(self.scan_general_text())
            } else {
                LateData::Bytes(self.scan_pdf_string())
            };
            self.append_whatsit(
                if late {
                    whatsit_sub::PDF_LATE_LITERAL
                } else {
                    whatsit_sub::PDF_LITERAL
                },
                Whatsit::PdfLiteral { mode, data, late },
            );
        } else if self.scan_keyword("lateliteral") {
            let data = LateData::Tokens(self.scan_general_text());
            self.append_whatsit(
                whatsit_sub::PDF_LATE_LITERAL,
                Whatsit::PdfLiteral {
                    mode: literal_mode::ORIGIN,
                    data,
                    late: true,
                },
            );
        } else if self.scan_keyword("save") {
            self.append_whatsit(whatsit_sub::PDF_SAVE, Whatsit::PdfSave);
        } else if self.scan_keyword("restore") {
            self.append_whatsit(whatsit_sub::PDF_RESTORE, Whatsit::PdfRestore);
        } else if self.scan_keyword("setmatrix") {
            let data = self.scan_pdf_string();
            self.append_whatsit(whatsit_sub::PDF_SETMATRIX, Whatsit::PdfSetmatrix { data });
        } else if self.scan_keyword("colorstack") {
            self.scan_int();
            let stack = self.cur_val;
            let (cmd, data) = if self.scan_keyword("set") {
                (colorstack_cmd::SET, self.scan_pdf_string())
            } else if self.scan_keyword("push") {
                (colorstack_cmd::PUSH, self.scan_pdf_string())
            } else if self.scan_keyword("pop") {
                (colorstack_cmd::POP, Vec::new())
            } else if self.scan_keyword("current") {
                (colorstack_cmd::CURRENT, Vec::new())
            } else {
                self.print_err("Color stack action is missing");
                self.help(&[
                    "The expected actions for \\pdfextension colorstack:",
                    "    set, push, pop, current",
                ]);
                self.error();
                return;
            };
            self.append_whatsit(
                whatsit_sub::PDF_COLORSTACK,
                Whatsit::PdfColorstack { stack, cmd, data },
            );
        } else if self.scan_keyword("obj") {
            self.pdf_obj(immediate);
        } else if self.scan_keyword("refobj") {
            self.scan_int();
            let n = self.cur_val;
            if self.eqtb.int(crate::primitives_gen::assign_int::OUTPUTMODE) > 0 {
                self.pdf_check_refobj(n);
            }
            self.pdf_append_refobj(n);
        } else if self.scan_keyword("annot") {
            let objnum = if self.scan_keyword("reserveobjnum") {
                let n = self.pdf_alloc_obj(ObjKind::Annot);
                self.pdf.last_annot = n;
                self.scan_optional_space();
                return;
            } else if self.scan_keyword("useobjnum") {
                self.scan_int();
                self.cur_val
            } else {
                self.pdf_alloc_obj(ObjKind::Annot)
            };
            self.pdf.last_annot = objnum;
            let dims = self.scan_pdf_rule_spec();
            let data = self.scan_pdf_string();
            self.append_whatsit(
                whatsit_sub::PDF_ANNOT,
                Whatsit::PdfAnnot { dims, objnum, data },
            );
        } else if self.scan_keyword("startlink") {
            if self.mode.abs_kind() == crate::maincontrol::ModeKind::Vertical {
                self.pdf_fatal("startlink cannot be used in vertical mode");
            }
            let dims = self.scan_pdf_rule_spec();
            let mut attr = Vec::new();
            if self.scan_keyword("attr") {
                attr = self.scan_pdf_string();
            }
            let Some(action) = self.scan_pdf_action() else {
                return;
            };
            let objnum = self.pdf_alloc_obj(ObjKind::Link);
            self.pdf.last_link = objnum;
            self.append_whatsit(
                whatsit_sub::PDF_START_LINK,
                Whatsit::PdfStartLink {
                    dims,
                    objnum,
                    attr,
                    action,
                },
            );
        } else if self.scan_keyword("endlink") {
            if self.mode.abs_kind() == crate::maincontrol::ModeKind::Vertical {
                self.pdf_fatal("\\pdfextension endlink cannot be used in vertical mode");
            }
            self.append_whatsit(whatsit_sub::PDF_END_LINK, Whatsit::PdfEndLink);
        } else if self.scan_keyword("dest") {
            self.pdf_dest_cmd();
        } else if self.scan_keyword("outline") {
            self.pdf_outline_cmd();
        } else if self.scan_keyword("glyphtounicode") {
            let a = self.scan_pdf_string();
            let b = self.scan_pdf_string();
            self.pdf.glyph_to_unicode.push((a, b));
        } else if self.scan_keyword("catalog") {
            let s = self.scan_pdf_string();
            self.pdf.catalog.extend_from_slice(&s);
            if self.scan_keyword("openaction") {
                if self.pdf.open_action.is_some() {
                    self.pdf_fatal("duplicate of openaction");
                }
                if let Some(a) = self.scan_pdf_action() {
                    let n = self.pdf_write_action(&a);
                    self.pdf.open_action = Some(n);
                }
            }
        } else if self.scan_keyword("info") {
            let s = self.scan_pdf_string();
            self.pdf.info.extend_from_slice(&s);
        } else if self.scan_keyword("names") {
            let s = self.scan_pdf_string();
            self.pdf.names.extend_from_slice(&s);
        } else if self.scan_keyword("trailer") {
            let s = self.scan_pdf_string();
            self.pdf.trailer.extend_from_slice(&s);
        } else if self.scan_keyword("fontattr") {
            self.scan_font_ident();
            let f = self.cur_val as u32;
            let s = self.scan_pdf_string();
            self.pdf.font_attrs.insert(f, s);
        } else if self.scan_keyword("mapfile") {
            let s = self.scan_pdf_string();
            // Observed: the map file is read at once (`{path}` in the log),
            // after the default one for `+` and `=`, and the default one is
            // then not announced at the first page. (Reading a file twice
            // warns about each duplicate entry; that is not reproduced.)
            if self.eqtb.int(crate::primitives_gen::assign_int::OUTPUTMODE) > 0 {
                let text = String::from_utf8_lossy(&s).trim().to_owned();
                let prefix = text.chars().next().filter(|c| matches!(c, '+' | '-' | '='));
                let name = text.trim_start_matches(['+', '-', '=']);
                if prefix != Some('-') {
                    if prefix.is_some() && !self.pdf.map_note_done {
                        self.print_map_file_note("pdftex.map");
                    }
                    self.print_map_file_note(name);
                    self.pdf.map_note_done = true;
                }
            }
            self.pdf.map_entries.push(s);
        } else if self.scan_keyword("mapline") {
            let s = self.scan_pdf_string();
            self.pdf.map_entries.push(s);
        } else if self.scan_keyword("includechars") {
            let _ = self.scan_pdf_string();
        } else if self.scan_keyword("linkstate") {
            self.scan_int();
            let state = self.cur_val;
            self.append_whatsit(
                crate::nodes::whatsit_sub::PDF_LINK_STATE,
                Whatsit::PdfLinkState { state },
            );
        } else if self.scan_keyword("startthread") || self.scan_keyword("thread") {
            // Article threads are not written yet; the syntax is accepted.
            let _ = self.scan_pdf_rule_spec();
            if self.scan_keyword("attr") {
                let _ = self.scan_pdf_string();
            }
            if self.scan_keyword("num") {
                self.scan_int();
            } else if self.scan_keyword("name") {
                let _ = self.scan_pdf_string();
            }
        } else if self.scan_keyword("endthread") {
        } else {
            // LuaTeX 1.22: lower case, no help text.
            self.print_err("unexpected use of \\pdfextension");
            self.help(&[]);
            self.error();
        }
    }

    /// `\pdfextension dest …`.
    fn pdf_dest_cmd(&mut self) {
        let structure = if self.scan_keyword("struct") {
            self.scan_int();
            Some(self.cur_val)
        } else {
            None
        };
        let id = if self.scan_keyword("num") {
            self.scan_int();
            DestId::Num(self.cur_val)
        } else if self.scan_keyword("name") {
            DestId::Name(self.scan_pdf_string())
        } else {
            self.pdf_fatal("identifier type missing");
        };
        let mut view = DestView {
            kind: DestKind::Xyz,
            zoom: 0,
            dims: [RUNNING; 3],
        };
        if self.scan_keyword("xyz") {
            if self.scan_keyword("zoom") {
                self.scan_int();
                view.zoom = self.cur_val;
            }
        } else if self.scan_keyword("fitbh") {
            view.kind = DestKind::FitBH;
        } else if self.scan_keyword("fitbv") {
            view.kind = DestKind::FitBV;
        } else if self.scan_keyword("fitb") {
            view.kind = DestKind::FitB;
        } else if self.scan_keyword("fith") {
            view.kind = DestKind::FitH;
        } else if self.scan_keyword("fitv") {
            view.kind = DestKind::FitV;
        } else if self.scan_keyword("fitr") {
            view.kind = DestKind::FitR;
            view.dims = self.scan_pdf_rule_spec();
        } else if self.scan_keyword("fit") {
            view.kind = DestKind::Fit;
        } else {
            self.pdf_fatal("destination type missing");
        }
        self.append_whatsit(
            whatsit_sub::PDF_DEST,
            Whatsit::PdfDest {
                id,
                view,
                structure,
            },
        );
    }

    /// `\pdfextension outline …`.
    fn pdf_outline_cmd(&mut self) {
        let mut o = Outline::default();
        if self.scan_keyword("attr") {
            o.attr = self.scan_pdf_string();
        }
        if self.scan_keyword("useobjnum") {
            self.scan_int();
            o.action = self.cur_val;
        } else {
            let Some(a) = self.scan_pdf_action() else {
                return;
            };
            o.action = self.pdf_write_action(&a);
        }
        if self.scan_keyword("count") {
            self.scan_int();
            o.count = self.cur_val;
        }
        let title = self.scan_pdf_string();
        o.objnum = self.pdf_alloc_obj(ObjKind::Other);
        o.title = self.pdf_alloc_obj(ObjKind::Other);
        let mut body = b"(".to_vec();
        body.extend_from_slice(&title);
        body.extend_from_slice(b")\n");
        self.pdf_write_raw(o.title, body);
        self.pdf.outlines.push(o);
    }

    /// `\pdfextension obj …`.
    fn pdf_obj(&mut self, immediate: bool) {
        if self.scan_keyword("reserveobjnum") {
            let n = self.pdf_alloc_obj(ObjKind::Obj);
            self.pdf.objects.insert(
                n,
                PdfObject {
                    num: n,
                    ..Default::default()
                },
            );
            self.pdf.last_obj = n;
            // Observed: a space after the keyword is skipped.
            self.scan_optional_space();
            return;
        }
        let n = if self.scan_keyword("useobjnum") {
            self.scan_int();
            self.cur_val
        } else {
            self.pdf_alloc_obj(ObjKind::Obj)
        };
        let uncompressed = self.scan_keyword("uncompressed");
        let mut obj = PdfObject {
            num: n,
            uncompressed,
            defined: true,
            ..Default::default()
        };
        if self.scan_keyword("stream") {
            obj.stream = true;
            if self.scan_keyword("attr") {
                obj.attr = self.scan_pdf_string();
            }
        }
        if self.scan_keyword("file") {
            obj.file = true;
        }
        obj.data = self.scan_pdf_string();
        if immediate {
            self.pdf.obj_words += 5;
        }
        self.pdf_define_object(obj, immediate);
    }

    /// Writes object `n` through the backend now.
    pub fn pdf_write_object(&mut self, n: i32) {
        let Some(obj) = self.pdf.objects.get(&n).cloned() else {
            return;
        };
        if obj.written || !obj.defined {
            return;
        }
        if let Some(o) = self.pdf.objects.get_mut(&n) {
            o.written = true;
        }
        self.pdf_write_object_data(&obj);
    }

    /// Hands `obj` to the backend, or queues it while the backend is busy
    /// shipping a page. A file object prints `<<name>>` as LuaTeX does.
    fn pdf_write_object_data(&mut self, obj: &PdfObject) {
        let Some(obj) = self.pdf_object_payload(obj) else {
            return;
        };
        match self.backend.take() {
            Some(mut be) => {
                be.write_object(self, &obj);
                self.backend = Some(be);
            }
            None => self.pdf.pending.push(obj),
        }
    }

    /// Takes object `n` (defined and not yet written) for writing with the
    /// current page (`\pdfextension refobj`).
    pub(crate) fn pdf_take_page_object(&mut self, n: i32) -> Option<PdfObject> {
        let obj = self.pdf.objects.get_mut(&n)?;
        if obj.written || !obj.defined {
            return None;
        }
        obj.written = true;
        let obj = obj.clone();
        self.pdf_object_payload(&obj)
    }

    /// The object as written: a file object gets the file's contents
    /// (printing `<<name>>` as LuaTeX does).
    fn pdf_object_payload(&mut self, obj: &PdfObject) -> Option<PdfObject> {
        let mut obj = obj.clone();
        if obj.file {
            let name = String::from_utf8_lossy(&obj.data).into_owned();
            let path = self
                .kpse
                .as_ref()
                .and_then(|k| {
                    k.borrow_mut()
                        .find_file(&name, retex_kpath::FileFormat::Tex)
                })
                .unwrap_or_else(|| std::path::PathBuf::from(&name));
            match std::fs::read(&path) {
                Ok(d) => {
                    self.printer.print_str("<<");
                    self.printer.print_bytes(name.as_bytes());
                    self.printer.print_str(">>");
                    obj.data = d;
                    obj.file = false;
                }
                Err(_) => {
                    self.print_err("pdf backend: cannot open file for embedding");
                    self.help(&[]);
                    self.error();
                    return None;
                }
            }
        }
        Some(obj)
    }

    /// A token list of whatsit data, for late expansion.
    pub fn whatsit_tokens(list: &TokenList) -> LateData {
        LateData::Tokens(list.clone())
    }

    /// Works out what the backend needs at the end of the run, and prints
    /// LuaTeX's warnings about destinations and threads that were referred
    /// to but never defined.
    pub fn pdf_finish_document(&mut self) {
        let mut doc = DocItems::default();
        // Observed order: missing pages, then destinations (each in the
        // reverse order of allocation), then threads; the warnings are
        // separated by empty lines.
        let mut warnings = Vec::new();
        let mut pages: Vec<(i32, i32)> = self
            .pdf
            .page_refs
            .iter()
            .filter(|(p, _)| **p > self.total_pages as i32)
            .map(|(p, n)| (*n, *p))
            .collect();
        pages.sort_unstable_by(|a, b| b.cmp(a));
        for (_, p) in pages {
            warnings.push(format!("page {p} has been referenced but does not exist"));
        }
        let order = self.pdf.dest_order.clone();
        for id in order.iter().rev() {
            if let Some(d) = self.pdf.dests.get(id).copied()
                && !d.defined
            {
                warnings.push(format!("unreferenced destination with {}", id.describe()));
                doc.missing_dests.push(d.objnum);
            }
        }
        for (id, n) in self.pdf.threads.clone() {
            warnings.push(format!("unknown thread destination {}", id.describe()));
            let title = match id {
                DestId::Name(n) => n,
                DestId::Num(k) => k.to_string().into_bytes(),
            };
            doc.missing_threads.push((n, title));
        }
        for (i, w) in warnings.iter().enumerate() {
            if i > 0 {
                self.printer.print_ln();
            }
            self.pdf_warning(w);
        }
        let mut names: Vec<(Vec<u8>, i32)> = self
            .pdf
            .dests
            .iter()
            .filter_map(|(k, d)| match k {
                DestId::Name(n) => Some((n.clone(), d.objnum)),
                DestId::Num(_) => None,
            })
            .collect();
        names.sort();
        doc.dest_names = names;
        let toks = |e: &mut Engine, i: u32| {
            let list = e.eqtb.toks_param(i).clone();
            e.print_to_string(|e| e.show_token_list(&list, 0, list.len(), i64::MAX))
        };
        doc.pages_attr = toks(self, crate::backend::PAGES_ATTR);
        doc.trailer_id = toks(self, crate::backend::TRAILER_ID);
        self.pdf.doc = doc;
    }
}