Module document_structure

Expand description

Document-level structural data — the parallel IR to DisplayList.

Where DisplayList carries per-page paint operations, DocumentStructure carries the document-scoped metadata that ends up in the PDF catalog, info dictionary, outline tree, page annotation arrays, and so on: /DOCINFO, /OUT, /ANN, /DEST, /PAGE//PAGES, /VIEWERPREFERENCES, /Metadata, /FORM, /EMBED.

Two producers populate this type:

The PostScript interpreter, when pdfmark operators fire — see stet-ops/src/pdfmark_ops.rs. The buffer hangs off stet_core::context::Context::doc_structure.
stet-pdf-reader, when round-tripping a PDF’s structural API into an output PDF.

One consumer: the PDF output device (stet-pdf::PdfDevice) drains the buffer at end-of-job and writes the records into the output PDF. Non-PDF output devices ignore it, so structural data is a no-op for PNG / viewer output.

Structs§

AnnotationRecord: One /ANN entry. Each record contributes a single annotation (/Annot) to one page’s /Annots array. page is 1-based; 0 is reserved for “no explicit page” (the writer substitutes the page being assembled at the time the record fired).
Border: /Border array [Hradius Vradius Width]. PDF spec also allows a dash pattern fourth entry; we capture it but only emit when present.
ChoiceOption: One /Opt entry on a choice field. PDF allows two shapes: a single string (export = display) or [export display] for distinct values.
DestRecord: One /DEST entry — registers a named destination in the document’s /Names /Dests name tree. PDF outline entries and link annotations resolve the matching name against this tree.
DocInfoRecord: /DOCINFO payload — Option<String> for every key so absent entries don’t overwrite values from another producer (or the device’s auto-generated defaults). creation_date and mod_date accept either a parsed PdfDate or a passthrough string the writer emits verbatim.
DocumentStructure: Document-level structural records, parallel to DisplayList.
EmbedRecord: One /EMBED entry — a single attached file. The writer emits one /Filespec dict + one /EmbeddedFile stream per record and assembles them into a /Names /EmbeddedFiles name tree.
FormRecord: /FORM payload — document-level AcroForm dict. All fields are optional; /Fields is implicit (built from /Widget annotations at write time). Multiple /FORM records merge last-wins via FormRecord::merge_over.
MetadataRecord: One /Metadata entry — an XMP stream attached to the document’s /Catalog. The writer wraps the bytes in a /Type /Metadata /Subtype /XML stream object.
OutlineNode: One node in the assembled outline tree.
OutlineRecord: One /OUT entry. Each record contributes a bookmark node to the document outline tree the PDF writer assembles at end-of-job.
OutputIntentRecord: /OUTPUTINTENT payload — one PDF/X or PDF/A OutputIntent declaring the destination color rendering condition for the document. The writer embeds [dest_output_profile] as an /ICCBased stream object and produces an entry in /Catalog /OutputIntents.
PageAdditionalActions: Page-level /AA (additional actions) — open and close hooks the PDF viewer fires when a page becomes / leaves visible. Either hook is optional; both are passed through verbatim from the producer’s action dict.
PageBoxes: Per-page box rectangles. Each entry is Option<[llx, lly, urx, ury]>; None means “leave the device default in place”.
PageOverrideRecord: One /PAGE (single-page override) or /PAGES (document-wide default) entry. The writer applies the keys to the per-page dict at build time; /PAGE wins over /PAGES for any key that’s set on both, and an explicit /PAGE for page N wins over the implicit “current page” target.
PdfDate: Parsed PDF date string of the form D:YYYYMMDDHHmmSSOHH'mm', where O is one of +, -, or Z for the offset sign. All fields after the year are optional in the PDF spec; missing components default to the values shown in PdfDate::default.
ViewerPrefsRecord: One /VIEWERPREFERENCES payload. All keys are optional; later records override earlier ones key-by-key. The “page layout” and “page mode” entries technically live on /Catalog directly (not under /ViewerPreferences) but Adobe pdfmark groups them with the rest of the viewer-control bag, so stet does too.
WidgetAnnotation: /Widget annotation payload — also acts as the field dict when the widget is a single-leaf field (the common case). Multiple widgets sharing the same dotted field_name become /Kids of an implicit parent field at write time (radio groups).

Enums§

AnnotationSubtype: Per-subtype annotation payload. Each variant carries the keys specific to that subtype; shared keys (rect, color, border, title, contents, page) live on the parent AnnotationRecord.
AnnotationTarget: What an annotation activates. Mirrors OutlineDestination but kept distinct because annotations can carry richer action data (e.g. JavaScript) and have their own resolution rules.
DocDate: A document date entry. The writer can either round-trip a raw string (already in PDF date syntax) or format a parsed PdfDate.
FieldType: Field type per PDF 1.7 spec § 12.7.4. The variant maps directly to the /FT name in the output PDF.
FieldValue: Field value — variant shape depends on the field’s /FT. The emitter writes the corresponding PDF object kind for each variant.
GoToTarget: /GoTo action target.
LinkHighlight: /Link highlight mode — controls the visual feedback when the user activates the link region.
OutlineAction: Outline-action passthrough. Despite the name, this enum is shared across every place an “action dict” appears — outline /Action, link annotation /A, page /AA open / close — because the on-the- wire shape is identical.
OutlineDestination: What a bookmark entry navigates to when clicked.
PageOverrideScope: Whether a PageOverrideRecord targets one specific page or the whole document.
StructuralRecord: One accumulated structural record. Each variant corresponds to a PDF catalog / info / page entry the writer knows how to emit.
TextAnnotationIcon: Standard /Text annotation icon names. Anything outside this set falls back to /Note.
TrappedState: /Trapped value as written to the Info dict.
TzSign: Sign of a PDF date timezone offset.
ViewSpec: Outline view spec, mirroring PDF’s /Dest array shape.

Functions§

build_outline_tree: Build an outline tree from a flat sequence of OutlineRecords.