Skip to content

docs(build): name the real target in the generated dependencies - #4361

Merged
BsAtHome merged 1 commit into
LinuxCNC:masterfrom
grandixximo:docs-asciideps-targets
Aug 8, 2026
Merged

docs(build): name the real target in the generated dependencies#4361
BsAtHome merged 1 commit into
LinuxCNC:masterfrom
grandixximo:docs-asciideps-targets

Conversation

@grandixximo

Copy link
Copy Markdown
Contributor

The follow-up I mentioned in #4358, now that it has merged. Thanks for the quick turnaround, @BsAtHome.

docs/src/asciideps derives the target it emits by stripping a .txt suffix, which is what the docs were written in when the script 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 no rule builds. Every include:: and image: 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.adoc 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. 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 in objects/. The unused .dep line went with the rewrite.

Reconnecting the dependencies exposed three latent problems, fixed in the same commit:

  • 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 an image deleted since it was commented out, so the build stopped on it.
  • 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 (5-axis-kinematics.adoc opens with "use image:: for equation png files" inside a //// block).
  • 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; 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 single make, the chapter reaching objects/Master_Documentation.pdf.

Comment thread docs/src/asciideps
Comment thread docs/src/asciideps Outdated
Comment thread docs/src/Submakefile Outdated
Comment thread docs/src/Submakefile Outdated
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
grandixximo force-pushed the docs-asciideps-targets branch from 862c0c9 to 5c31ef1 Compare August 8, 2026 14:06
@grandixximo

Copy link
Copy Markdown
Contributor Author

All four done: warn on a non-file with [ ] instead of test, quotes fixed, the second pipe on its own line, and the long comments cut down to the width of the rest of the file. Trimmed the ones I left in #4358 too.

Comment-only apart from the asciideps guard; output is byte-identical on a page, a Master and a translated source.

@BsAtHome
BsAtHome merged commit 89b2d5b into LinuxCNC:master Aug 8, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants