docs: make HTML link checking actually run, and never false-pass#4104
Merged
Merged
Conversation
grandixximo
added a commit
to grandixximo/linuxcnc
that referenced
this pull request
Jun 2, 2026
Broken links surfaced once HTML link checking actually runs (companion to the checkref fix, LinuxCNC#4104): - qtvcp-widgets.adoc: link to halcmd.1.html#COMMANDS; the section's generated id is _commands. - linuxcncrsh.1.adoc (x3): links to #_linuxcnc_subcommands; the SUBCOMMANDS section's generated id is _subcommands.
Doc link checking has been a silent no-op: recent w3c-linkchecker refuses file:// URIs, so checklink returned an error with no broken-link marker and checkref reported "all links are good!" without inspecting anything. This is how broken cross-document links reached the published docs. - checkref: pass --follow-file-links so checklink actually inspects the local files (and validates cross-document fragments). - checkref: stop reporting success when checklink did not validate a file (nonzero exit or error output); skip with a warning and only vouch for files actually checked, warning instead of passing if none were. Never fail the build on an unusable checklink (environment problem). - Submakefile: run checkref with --warn-on-failure for now, since the long no-op may have let broken links accumulate; report them without breaking the build. Drop the flag once the backlog is cleared. - linuxcnc-checklink.in: fail clearly when @checklink@ is empty instead of "exec: : Permission denied".
grandixximo
force-pushed
the
docs/checkref-no-false-pass
branch
from
af9d51c to
4a3e0d0
Compare
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
2 participants
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.
HTML link checking has been a silent no-op: w3c-linkchecker 5.0.0 refuses
file://URIs by default, socheckrefgot an error with no broken-link marker and printed "all links are good!" without inspecting anything. This is very likely why #4053's broken cross-document links shipped uncaught.This passes
--follow-file-linksso checklink actually inspects local files (including cross-document fragments), and stopscheckrefclaiming success when checklink never validated a file (exit 64 = found-links is still a valid run; only exec failure or an explicit document refusal counts as not-validated).Checking runs report-only (
--warn-on-failure) for now, since the long no-op let a backlog accumulate. Measured on master: 73 pages / 275 broken refs, of which 270 are fixed by #4100 and 2 by #4103; the last 3 are in a companion PR. Once those land, the flag can be dropped so link breakage fails the build again.