Repository navigation
PDF set: the PDFs of a docset link to each other (2/3) - #22
Open
tobiaskaestner wants to merge 3 commits into
Open
tobiaskaestner wants to merge 3 commits into
tobiaskaestner wants to merge 3 commits into
Conversation
volker-kempert
approved these changes
Oct 29, 2026
A PDF's links to other documents went to the HTML site (base_url), or became text in a development build. deploy/pdf/<doc>/ held the whole LaTeX build directory, and the PDF had the name of the project title. Now the PDFs of a set are one deliverable that works offline: - deploy/pdf is the PDF set: one <title>_<version>.pdf per document with a latex builder (registry title, white space as "-"; the version the document shows). `docrefs.py pdf-deliver` copies latexmk's PDF there after the build and removes the other versions of the same document; `pdf-remove` is the clean step. Two documents with the same title part are a configure-time error. - The LaTeX build directory is a work area at <build>/<doc>/latex. docrefs takes the build root and the doc id from ZDOCS_DOC_BUILD_DIR and ZDOCS_DOC_ID, as the path of OUTPUT_DIR no longer gives them. - zdocs_conf sets hyperref's destlabel: each LaTeX label (Sphinx writes one per need, section and page, "<page>:<anchor>") is a named destination of the same name. - pdf_links turns a link to a document of the set into a link to its PDF, <title>_<version>.pdf#<page>:<anchor>, which hyperref writes as a "go to remote" action. docrefs gives the map (zdocs_pdf_peers) in a non-HTML build only. Links to other documents keep the rules before. Checked on the four safety-toolbox PDFs: 687 links between them, all with a target (a spike with Evince and pdf.js before), with the published and with a development base URL. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
A link from one PDF of deploy/pdf into another names a file and a named destination. If either is missing, the link is dead, and a PDF is mailed and filed as it is. doccheck now reads the PDFs of deploy/pdf (check C) and fails on a link into a PDF that is not in the set, or into a destination that the PDF does not have. It reads "go to remote" actions and relative URI links to <file>.pdf#[nameddest=]<dest>. It needs pypdf, now pinned in requirements-doc.txt (6.15.0); without it, a set with PDFs is a finding. Without PDFs, the check has nothing to read. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
ADR 0013 records the decision: deploy/pdf is a set of <title>_<version>.pdf that link to each other, the LaTeX build directory is a work area, and doc-check checks the links. The how-to for publishing says how to distribute the set (one folder, file names kept, built and released together); the deploy layout, the registry `title:` and the doc-check reference follow. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
tobiaskaestner
force-pushed
the
tkaestner/pdf-links
branch
from
October 29, 2026 11:09
4d84b5c to
7e7ad96
Compare
tobiaskaestner
force-pushed
the
tkaestner/pdf-set
branch
from
October 29, 2026 11:09
e17ca3f to
33c250c
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The second of three stacked PRs for the PDF output (base: #21). The PDFs of a docset become one set that links to itself and works offline.
deploy/pdf is the PDF set. Each document with a
latexbuilder gives one<title>_<version>.pdfindeploy/pdf(the registry title with-for white space, and the version that the document shows).docrefs.py pdf-delivercopies the PDF there after latexmk and removes the other versions of the same document.pdf-removeis the clean step. Two documents with the same title part give an error at configure time. The LaTeX build directory is now a work area at<build>/<doc>/latex.Links between the PDFs. zdocs_conf sets the hyperref option
destlabel, so each LaTeX label (<page>:<anchor>, one per need, section and page) is also a named destination. pdf_links changes a link to a document of the set into<title>_<version>.pdf#<page>:<anchor>, which hyperref writes as a "go to remote" action. Links to documents outside the set use the rules of #21.doc-check reads the set (check C). It fails on a link to a PDF that is not in the set, or to a destination that the target PDF does not have. It needs pypdf, which is now pinned in
requirements-doc.txt(6.15.0).Docs. ADR 0013 records the decision. The publishing how-to tells how to give the set to readers: one folder, the file names unchanged, built and released together. The deploy layout, the registry
title:and the doc-check reference are updated.Checks: unit 533, zdocs docs 0 warnings. safety-toolbox: 4 PDFs, 687 links between them, 0 broken, with the published and with the development base URL. Before the engine change, a manual click test of a prototype set in Evince found all links working. Not done yet: click tests in Firefox and Chromium, and an acceptance test with two linked PDFs. The matching acceptance changes (test_15, test_18, test_22) come in a separate zdocs-tests PR.
🤖 Generated with Claude Code