Skip to content

fix(docx): name a page reference's field after its anchor's own bookmark - #907

Merged
DemchaAV merged 1 commit into
2.5-devfrom
fix/docx-pageref-named-after-body
Oct 15, 2026
Merged

DemchaAV merged 1 commit into
2.5-devfrom
fix/docx-pageref-named-after-body

Conversation

@DemchaAV

Copy link
Copy Markdown
Owner

Why

Since #906, every page reference is written as a PAGEREF field and checked once the body is written. The field was named when the reference was written, through DocxBookmarkNames.nameFor(anchor), so the reference minted its anchor's bookmark name before the anchor's own bookmark did.

Two anchors can clean to the same name, so that order matters. Take a reference to a., an anchor that exists nowhere, followed by paragraphs anchored a and a_2:

  • a. took the name a;
  • the anchor a was pushed to a_2;
  • the anchor a_2 was given a_2 too.

The file held two bookmarks named a_2, so links and fields to either landed wherever Word keeps that name. Before #906, a reference whose anchor got no bookmark minted no name.

What changed

  • writePageReference writes the field with no bookmark name and records its instruction (appendField now returns it) together with the reference's anchor. The reference names no bookmark of its own.
  • settleThePageReferences replaces unfieldTheReferencesWithoutABookmark. Once every section is written, it names each field after the bookmark its anchor was written under, which openAnchor and bookmarkAround record by anchor. A reference whose anchor got no bookmark is taken back to the number it reads, with its note, as before.
  • The unreachable plain-text branch for a blank anchor is gone: PageReferenceNode rejects blank anchors.
  • The recipe says when a field is named.

Verification

Lane: shared-engine (render-docx semantic DOCX backend), no public API change. Follow-up to #906.

A page reference minted its anchor's bookmark name when it was written,
ahead of the anchor's own bookmark, and an anchor that cleans to the
name of another took it: a reference to "a." gave "a." the name "a",
pushed the anchor "a" to "a_2", which the anchor "a_2" is given too,
and the file held two bookmarks of one name.

The field is now written without the name and settled once the body is:
named after the bookmark its anchor was written under, or taken back to
the number it reads where the anchor has none. A reference names no
bookmark of its own.

Tests cover a reference to a layer stack's column, the run style the
number keeps, a reference to an anchor in a later section and a face
set only in a later section's zone.
@DemchaAV
DemchaAV merged commit 43adc83 into 2.5-dev Oct 15, 2026
13 checks passed
@DemchaAV
DemchaAV deleted the fix/docx-pageref-named-after-body branch October 15, 2026 19:59
DemchaAV added a commit that referenced this pull request Oct 15, 2026
…ne (#908)

The Linux baseline held the five documents #899 moves (cv-orange_ops,
cv-serif_headline, invoice-workspace, proposal-editorial,
proposal-northline) as they stood before it, while every CI run since
measures them as #899's did. Both files now match the docx-fidelity
artifact of #907's run (38794754386) byte for byte: 45 lines nearer the
page, 2 further by 0.05pt, all others unchanged.
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.

1 participant