feat(xref): add --force-local-file-xrefs

[mocenigo]

A document combined outside acdc, or built from selected includes, can keep references to the original files. --force-local-file-xrefs lets the author resolve those references by their local anchors. Complete includes already resolve locally without this flag.

acdc convert --backend pdf --force-local-file-xrefs book.adoc

The parser API is Options::builder().with_force_local_file_xrefs().

For example, when the combined document contains the KLEE-State-field anchor:

<<Zkl-ISA-unpriv.adoc#KLEE-State-field>>
xref:Zkl-ISA-unpriv.adoc#KLEE-State-field[the state field]

Both references resolve within the combined document. The explicit text remains the state field.

Scope and limits

• Disabled by default for every backend, including PDF. Without it, the normal Asciidoctor-compatible include rules apply.
• Requires a nonempty fragment after the first #. Page-only references and empty fragments keep normal behavior.
• Preserves multi-letter URI schemes, including HTTP(S), and targets starting with //. Protected URL text is restored before this check. A single letter before : is treated as a Windows drive.
• Redirects every eligible file-qualified reference, including genuine references to other documents. The fragment must identify the intended local anchor.
• Does not scope duplicate IDs or preserve file identity when choosing an anchor. Two files with an intro anchor cannot be distinguished after their filenames are removed.
• Missing local anchors produce unresolved-reference warnings. --fail-on-warnings can make the conversion return a failure status. Cross-references never load their target files.
• Does not resolve raw Antora resource IDs. For example, guide:chapter.adoc#intro keeps normal behavior because its prefix looks like a URI scheme.

Relationship to Antora

Antora's official PDF Extension uses Assembler to select and combine pages before conversion. Assembler scopes anchors, turns references to pages in the same assembly into internal references, and keeps references to other pages or attachments external. Its prepared source does not need this override. See Assembler concepts and PDF link settings.

Antora also recommends xref:page.adoc#anchor[] for cross-page references. Extensions may not support <<page.adoc#anchor>> in that role. See Antora's xref guidance.

Refs #464.

[nlopes]

I've added --force-local-file-xrefs (rather than the original flag, I prefer this one) so you can keep your current sources when building a combined PDF.

But I think there’s also a way to resolve these links through the normal include rules, in both Asciidoctor PDF and acdc.

After looking through https://github.com/riscv/riscv-high-assurance-cryptography/ I believe the mismatch is between the include path in your PDF master:

include::../modules/ROOT/pages/Zkl-ISA-unpriv.adoc[leveloffset=+1]

and the reference in a chapter:

<<Zkl-ISA-unpriv.adoc#KLE-State-field>>

Both converters compare these paths relative to the master document. Your Ruby extension handles the difference by registering included files under their basenames.

If you’re happy to adjust the PDF build, I’d try using modules/ROOT/pages as the master’s base directory and changing its chapter includes to basenames:

include::Zkl-ISA-unpriv.adoc[leveloffset=+1]

The existing reference then matches the include directly. Asciidoctor supports an explicit base directory; both converters can also read the master through stdin while running from that directory. Shared includes, images, fonts and theme paths would need adjusting.

Another option is to use ifdef::env-site[] to select a reference prefix: empty for Antora, and ../modules/ROOT/pages/ for the combined document. That requires changing the references and updating the tools that inspect them, so I’d start with the build-directory approach perhaps.

In any case, this flag remains useful if you prefer to keep the current layout - its mostly harmless. Matching the include paths has one useful advantage: references to documents outside the assembled book keep their normal external-link behaviour.

[mocenigo]

I've added --force-local-file-xrefs (rather than the original flag, I prefer this one) so you can keep your current sources when building a combined PDF.

But I think there’s also a way to resolve these links through the normal include rules, in both Asciidoctor PDF and acdc.

[...]

In any case, this flag remains useful if you prefer to keep the current layout - its mostly harmless. Matching the include paths has one useful advantage: references to documents outside the assembled book keep their normal external-link behaviour.

Yes there may be other methods but this one is useful as a quick solution/quick check.
Is the short form still "--ifix" ? I suggest to change it to "--flfx" then.

[nlopes]

Is the short form still "--ifix" ? I suggest to change it to "--flfx" then.

I removed the short form. For flags like this one I think it's preferable to force using the long form. If there's a constraint you have on the length of the name, happy to consider.