docs(build): name the real target in the generated dependencies - #4361
Merged
Conversation
BsAtHome
reviewed
Aug 8, 2026
asciideps derives the target it emits by stripping a `.txt` suffix, which is what the docs were written in when it landed in 2011. Since the sources became `.adoc` nothing is stripped, so it generates rules for targets like docs/build/adoc/en/hal/tutorial.adoc.html that nothing builds: every include:: and image: dependency it has extracted since then has been inert. Editing hal/halshow.adoc therefore never re-rendered hal/tutorial.html, which include::s it, and editing a chapter never rebuilt the Master PDF pulling it in. Master_Documentation.adoc alone include::s 119 files, so all four English PDFs stayed stale until docclean. The target is not derivable from the source path, so pass it in: a page is consumed by its .html, a Master document is never rendered as HTML and its English PDF lands in objects/. The unused `.dep` line went with the rewrite. Reconnecting the dependencies exposed three latent problems, fixed here: - Commented-out image: macros counted as dependencies. The macro is matched anywhere on the line so inline refs are caught, which also matched a ref behind a `//`; one in gui/gmoccapy.adoc points at a since-deleted image, stopping the build. - Images referenced inline were never staged into the translated adoc tree, because .adoc-images-stamp anchored its scan at the start of the line. The translated PDFs embed images from that tree, so they have been missing all 39 of them. Both extractors now key on the macro shape rather than a bare `image:`, so prose mentioning one is not taken for a path. - Staged translated images had no rule of their own. Named as prerequisites, a clean -j build reached one before the bulk stamp had written it and fell through to the "Required image file" error rule. Each now stages on demand; the bulk pass stays, since asciideps records only the last macro on a line and cannot be the guarantee that asciidoctor-pdf finds every image. Verified with HTML, PDF and the seven translations enabled: a clean build renders 5210 pages and 32 Master PDFs with no unresolved directives, the two builds after it do no work, and touching a page, a partial, a chapter or an image rebuilds exactly what depends on it in a single `make`.
grandixximo
force-pushed
the
docs-asciideps-targets
branch
from
August 8, 2026 14:06
862c0c9 to
5c31ef1
Compare
Contributor
Author
|
All four done: warn on a non-file with Comment-only apart from the |
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 follow-up I mentioned in #4358, now that it has merged. Thanks for the quick turnaround, @BsAtHome.
docs/src/asciidepsderives the target it emits by stripping a.txtsuffix, which is what the docs were written in when the script landed in 2011. Since the sources became.adocnothing is stripped, so it generates rules for targets likethat no rule builds. Every
include::andimage:dependency it has extracted since then has been attached to a target nobody asks for, so the whole dependency extractor has been inert.What that costs: editing
hal/halshow.adocnever re-renderedhal/tutorial.html, whichinclude::s it, and editing a chapter never rebuilt the Master PDF pulling it in.Master_Documentation.adocaloneinclude::s 119 files, so all four English PDFs stayed stale untildocclean. Editing an image never rebuilt the page showing it either.The target is not derivable from the source path, so it is passed in: a page is consumed by its
.html, a Master document is never rendered as HTML and its English PDF lands inobjects/. The unused.depline went with the rewrite.Reconnecting the dependencies exposed three latent problems, fixed in the same commit:
image:macros counted as dependencies. The macro is matched anywhere on the line so inline refs are caught, which also matched a ref behind a//. One ingui/gmoccapy.adocpoints at an image deleted since it was commented out, so the build stopped on it..adoc-images-stampanchored its scan at the start of the line. The translated PDFs embed images from that tree, so they have been missing all 39 of them. Both extractors now key on the macro shape rather than a bareimage:, so prose mentioning one is not taken for a path (5-axis-kinematics.adocopens with "use image:: for equation png files" inside a////block).-jbuild reached one before the bulk stamp had written it and fell through to the "Required image file" error rule; it only succeeded on a second run. Each now stages on demand. The bulk pass stays, since asciideps records only the last macro on a line and cannot be the guarantee that asciidoctor-pdf finds every image.Verified with HTML, PDF and the seven translations enabled: a clean build renders 5210 pages and 32 Master PDFs with no unresolved directives, the two builds after it do no work, and touching a page, an
include::d partial, a Master chapter or an image rebuilds exactly what depends on it in a singlemake, the chapter reachingobjects/Master_Documentation.pdf.