tl;dr: When building the PDF, pandoc converts each SVG diagram to a temporary PDF in its own scratch dir and deletes it on exit. doc_build doesn't validate those graphics were produced/are intact, and doesn't surface tectonic's failure when one isn't — so a transiently-bad conversion yields a cryptic Unable to load picture or PDF file ... Error producing PDF and no PDF. Seen once in core-spec-wg CI (cleared on re-run); filing because the gap is structural, not incident-specific.
(Code refs below are against main @ c918081.)
Mechanism
- SVGs are persisted to
build/images/ by filter_bundle_images (filters/filter_bundle_images.py:59). But tectonic can't embed SVG, so with --pdf-engine=tectonic (bare name, intentional — doc_builder.py:514-517) pandoc converts each SVG to a PDF into its own ephemeral media-<hash>/ dir, references those temp PDFs in the piped LaTeX, and deletes them on exit.
- The graphic tectonic loads exists only for the duration of one pandoc invocation, and its creation is pandoc-internal — doc_build neither produces nor checks it.
The gap
The standard PDF path (doc_builder.py:500-507) pipes pandoc straight to tectonic and:
- doesn't validate the ephemeral intermediate at the doc_build→pandoc handoff, and
- doesn't propagate the failure —
pandoc(...) runs with a stderr_processor that only logs, so a failed compile neither raises nor checks that pdf was actually written. The build proceeds with no PDF.
The combination turns any transient conversion hiccup into a silent missing-PDF. (The downstream CI consequence is tracked in core-spec-wg#521.)
- Minor adjacent smell:
stabilize_tex_media's if not src.exists(): continue (tools/tectonic:74) silently drops missing media — only reachable via --keep-pdf-latex, but a missing graphic should error, not be skipped.
Candidate fix
Pre-convert diagrams to persistent PDF assets under build/images/ up front (mirroring filters/filter_convert_svg.py's SVG→PNG approach, but to PDF for the LaTeX path). tectonic then loads a stable, validatable file; a bad conversion fails at a clear step; and the capture/stabilize/recreate machinery that exists solely to snapshot pandoc's temps is no longer needed.
tl;dr: When building the PDF, pandoc converts each SVG diagram to a temporary PDF in its own scratch dir and deletes it on exit. doc_build doesn't validate those graphics were produced/are intact, and doesn't surface tectonic's failure when one isn't — so a transiently-bad conversion yields a cryptic
Unable to load picture or PDF file ... Error producing PDFand no PDF. Seen once in core-spec-wg CI (cleared on re-run); filing because the gap is structural, not incident-specific.(Code refs below are against
main@c918081.)Mechanism
build/images/byfilter_bundle_images(filters/filter_bundle_images.py:59). But tectonic can't embed SVG, so with--pdf-engine=tectonic(bare name, intentional —doc_builder.py:514-517) pandoc converts each SVG to a PDF into its own ephemeralmedia-<hash>/dir, references those temp PDFs in the piped LaTeX, and deletes them on exit.The gap
The standard PDF path (
doc_builder.py:500-507) pipes pandoc straight to tectonic and:pandoc(...)runs with astderr_processorthat only logs, so a failed compile neither raises nor checks thatpdfwas actually written. The build proceeds with no PDF.The combination turns any transient conversion hiccup into a silent missing-PDF. (The downstream CI consequence is tracked in core-spec-wg#521.)
stabilize_tex_media'sif not src.exists(): continue(tools/tectonic:74) silently drops missing media — only reachable via--keep-pdf-latex, but a missing graphic should error, not be skipped.Candidate fix
Pre-convert diagrams to persistent PDF assets under
build/images/up front (mirroringfilters/filter_convert_svg.py's SVG→PNG approach, but to PDF for the LaTeX path). tectonic then loads a stable, validatable file; a bad conversion fails at a clear step; and the capture/stabilize/recreate machinery that exists solely to snapshot pandoc's temps is no longer needed.