docs: fix cross-document xref links broken under compat-mode#4100
docs: fix cross-document xref links broken under compat-mode#4100grandixximo wants to merge 2 commits into
Conversation
The resolver rewrote cross-doc <<anchor,Title>> to <<file.adoc#anchor>>, but -a compat-mode (set for the legacy asciidoc-py source) disables that inter-document syntax and parses it as an in-page anchor, so links landed on the current page (tools.html#tutorial.adoc#cha:hal-tutorial). Emit a link: macro instead, which compat-mode leaves intact, with .adoc rewritten to outfilesuffix. link: has no auto reftext, so the index now also captures each target's reftext for bare <<anchor>> uses. Cache v2.
|
@hansu see if this fixes the cross link, alternative is rewriting them all, which I don't think is wise... |
|
Thanks for picking this up so quickly! This works for links for target files where file.adoc = file.html. But for files where adoc are files included in another adoc file it doesn't. For example the link "Halshow" in section 3: https://linuxcnc.org/docs/devel/html/hal/tools.html#_halshow Before this fix it was pointing to: But halshow.adoc is included tutorial.adoc so it should point to A bit tricky, yes... |
An anchor in an include::d partial has no .html of its own; it renders into the page that includes it. The resolver pointed such links at the partial (halshow.html) instead of the including page (tutorial.html). Build the include graph and redirect each anchor to its topmost non-Master_ ancestor. Cache bumped to v3.
grandixximo
force-pushed
the
docs/fix-xref-compat-mode
branch
from
41c081f to
a633132
Compare
|
Good catch. Sent another commit, I think is fixed, the resolver now builds the include graph and redirects anchors defined in |
|
Yeah looks good now, thanks! |
2 participants
Follow-up to #4053. Cross-document references resolve to the current page instead of the target page. For example on
hal/tools.htmlthe "HAL Tutorial" link points to:instead of:
Cause:
xref_resolver.rbrewrote bare<<anchor,Title>>to the inter-document form<<file.adoc#anchor,Title>>. That syntax is asciidoctor-native, and the docs build with-a compat-mode(needed for the legacy asciidoc-py source). Under compat-mode asciidoctor parses<<file.adoc#anchor>>as a literal in-page anchor id, so every cross-doc link lands on the current page.Fix: the resolver now emits a
link:macro, which compat-mode leaves intact, with.adocrewritten tooutfilesuffix(.html/.pdf). Alink:macro has no automatic reference text, so the anchor index also captures each target's reftext (explicit[[id,reftext]]or the following heading) to label bare<<anchor>>uses. Cache format bumped to v2.One file changed; no source
.adocedits. The alternative, rewriting the 365 cross-document xrefs in source by hand, was rejected as far more churn and not self-maintaining.Verified on
hal/tools.html(the reported case), the two no-title cross-doc refs (sec:hal-components,mdiline), and INI[SECTION]bracket labels. All resolve to the correct target page.