docx/field-ref

Metadata

XPath assertions

Render assertions

Generator source

scripts/gen_field_ref.py

#!/usr/bin/env python3
"""Generate ``fixtures/docx/field-ref.docx``.

A paragraph declaring a ``w:bookmarkStart``/``w:bookmarkEnd`` pair named
``anchor``, followed by a second paragraph that contains a simple REF
field pointing at that bookmark. Uses the fork's high-level
``Paragraph.add_bookmark()`` and ``Paragraph.add_simple_field()``
helpers; the resulting REF is a ``<w:fldSimple>`` with instr
``REF anchor \\h``.
"""

from __future__ import annotations

from pathlib import Path

from docx import Document

_REPO_ROOT = Path(__file__).resolve().parent.parent
_OUT = _REPO_ROOT / "fixtures" / "docx" / "field-ref.docx"


def main() -> int:
    doc = Document()

    # -- Paragraph 1: the bookmark target. add_bookmark() with no
    #    start_run/end_run wraps the paragraph's content. --
    p1 = doc.add_paragraph("Bookmarked passage")
    p1.add_bookmark("anchor")

    # -- Paragraph 2: the cross-reference. --
    p2 = doc.add_paragraph("See: ")
    p2.add_simple_field(r"REF anchor \h", text="Bookmarked passage")

    _OUT.parent.mkdir(parents=True, exist_ok=True)
    doc.save(_OUT, reproducible=True)
    print(_OUT)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

Manifest (expanded)

{
  "$schema": "../manifest.schema.json",
  "id": "docx/field-ref",
  "title": "Field: REF (cross-reference to a bookmark)",
  "format": "docx",
  "category": "fields",
  "summary": "A simple REF field resolving to an in-document bookmark's text.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "17.16.5",
    "element": "w:fldSimple",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/WordprocessingML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/wml.xsd",
    "notes": "REF reproduces the text of a named bookmark. Simple-field form: <w:fldSimple w:instr=\"REF anchor \\h\"> with the cached bookmarked text as a child <w:t>. The bookmark itself is a <w:bookmarkStart>/<w:bookmarkEnd> pair earlier in the document, sharing a numeric w:id."
  },
  "fixtures": {
    "machine": "docx/field-ref",
    "office": "docx/field-ref"
  },
  "generator": {
    "python": "scripts/gen_field_ref.py"
  },
  "assertions": [
    {
      "id": "ref-field-simple-present",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:fldSimple[contains(@w:instr, 'REF')]",
      "must": "exist",
      "description": "A <w:fldSimple> element whose w:instr contains 'REF' must be present."
    },
    {
      "id": "ref-field-targets-anchor",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:fldSimple[contains(@w:instr, 'REF') and contains(@w:instr, 'anchor')]",
      "must": "exist",
      "description": "The REF field's instruction must name the 'anchor' bookmark."
    },
    {
      "id": "ref-bookmark-declared",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:bookmarkStart[@w:name='anchor']",
      "must": "exist",
      "description": "A <w:bookmarkStart w:name='anchor'> must be declared somewhere in the body so the REF has a target."
    }
  ],
  "render_assertions": [
    {
      "id": "ref-field-rendered",
      "kind": "css_selector",
      "selector": ".docx-wrapper [data-field='REF'], .docx-wrapper .field-ref, .docx-wrapper",
      "must": "match-text",
      "value": "See:",
      "description": "A renderer-exposed REF field (or the fallback paragraph) must at least contain the 'See:' label surrounding the reference. The fixture's 'See:' label lives in the second paragraph alongside the REF field's resolved text; match-text checks the first matching element's textContent, so we fall back to the whole .docx-wrapper rather than the first <p>."
    }
  ]
}