Make cross-chapter links work in both outputs

[Bill Traynor (wmat)]

Makes a cross-chapter link work in both outputs a spec repo produces from one source.

Problem

The template's dual-source layout gives each chapter its own Antora page, so a link to an anchor in another chapter has to name that chapter:

<<chapter2.adoc#some-id>>        not   <<some-id>>

Neither build handled that form until now:

• The PDF rendered it as a broken file reference ("intro.pdf"), because Asciidoctor treats a link as internal only when the path matches one it included, and the assembler includes pages as ../modules/ROOT/pages/intro.
• The site resolved the target but rendered the raw intro.adoc#intro as the link text, since Antora does not generate text for an anchor on another page.

A bare <<some-id>> is not an option either: it works in the PDF and is a broken link on the site.

Changes

• src/cross-page-xrefs.rb, added to the Makefile's REQUIRES: registers each included page under its file name, so the PDF resolves these links and generates the text as before ("Chapter 1", "Table 5", "IRR4").
• antora-playbook.yml registers xref_text_extension from the docs-resources submodule (Add the Antora xref text extension for spec repos docs-resources#261), which supplies the link text on the site. This covers the builds a spec repo runs itself: the local preview, the pull-request preview, and the GitHub Pages site, whose playbook gen-pages-playbook.js derives from this file. docs.riscv.org registers its own copy.
• docs-resources bumped to the commit carrying the extension (b5df347 → 3184f3f, which adds only that file and its README section). Registering without the bump fails with Cannot find module, so UPGRADING 2.7 now says to take the submodule before merging antora-playbook.yml.
• The sample spec links across pages, so this repo's own PR check exercises both paths rather than leaving the feature untested.
• MIGRATION Step 7 says how to write these links; Step 10 covers the registration.

Verification

Built here with VERSION=v0.8 DATE=2026-09-22:

• PDF: builds clean, and the sample link renders "see Chapter 1". Without the helper it rendered "see intro.pdf".
• Site: builds with 0 errors, the extension fills the sample link, and it renders "Introduction".

Also exercised on a real migrated spec (riscv/riscv-high-assurance-cryptography, 175 cross-chapter links): the PDF text is byte-identical with the helper in place, and the site build fills every link.

For existing repos

Nothing breaks: this only matters for a repo that writes page-qualified links. When adopting it, bump docs-resources in the same PR as the playbook change.

🤖 Generated with Claude Code

[Kersten Richter (kersten1)]

LGTM