docx/field-type--section

Metadata

XPath assertions

Render assertions

No render assertions declared.

Generator source

scripts/gen_field_type.py

#!/usr/bin/env python3
"""Generate a ``fixtures/docx/field-type--<id>.docx`` fixture.

Parameterised generator for the ``docx/field-type`` feature family.
Emits a single paragraph containing one ``w:fldSimple`` element carrying
the Word field instruction supplied via ``--instr`` and the cached
result text supplied via ``--cached``. The cached value is written as
the field's child run text; Word refreshes it on open if the field is
marked dirty. Consumed by ``features/docx/field-type.json``'s
``generator.arg_template``.
"""

from __future__ import annotations

import argparse
from pathlib import Path

from docx import Document

_REPO_ROOT = Path(__file__).resolve().parent.parent


def _write(instr: str, cached: str, out: Path) -> None:
    doc = Document()
    paragraph = doc.add_paragraph()
    # ``text=None`` for empty cached results so python-docx omits the
    # inner ``<w:t>`` rather than writing an empty one.
    paragraph.add_simple_field(instr, text=cached or None)
    out.parent.mkdir(parents=True, exist_ok=True)
    doc.save(out, reproducible=True)


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--instr", required=True, help="Word field instruction, e.g. 'PAGE \\* MERGEFORMAT'")
    parser.add_argument("--cached", default="", help="Cached result text (may be empty)")
    parser.add_argument("--out", required=True, help="Output .docx path (absolute or repo-relative)")
    args = parser.parse_args()

    out_path = Path(args.out)
    if not out_path.is_absolute():
        out_path = _REPO_ROOT / out_path
    _write(args.instr, args.cached, out_path)
    print(out_path)
    return 0


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

Manifest (expanded)

{
  "$schema": "../manifest.schema.json",
  "id": "docx/field-type--section",
  "kind": "literal",
  "title": "Field: instruction types",
  "format": "docx",
  "category": "fields",
  "summary": "A family covering 30 common Word field instruction codes carried as simple fields (w:fldSimple).",
  "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": "Each expanded case emits a single <w:fldSimple w:instr=\"...\"> carrying a distinct field instruction code (PAGE, DATE, AUTHOR, HYPERLINK, IF, ...). The cached result is written as the child <w:t>; Word refreshes it on open if the field is marked dirty. This manifest expands into 30 concrete test cases, one per field instruction, each backed by fixture docx/field-type--<id>.docx generated from gen_field_type.py. Cached values are intentionally not asserted — some instructions (COMMENTS, INCLUDETEXT) carry an empty cached result. The assertion pins w:instr verbatim; python-docx serialises the inner double-quotes as &quot; inside the attribute, which is unescaped back to \" when the XML parser reads @w:instr."
  },
  "fixtures": {
    "machine": "docx/field-type--section",
    "office": "docx/field-type--section"
  },
  "generator": {
    "python": "scripts/gen_field_type.py",
    "arg_template": "--instr '{field.instr}' --cached '{field.cached}' --out fixtures/docx/field-type--{field.id}.docx"
  },
  "_expansion": {
    "parent_id": "docx/field-type",
    "bindings": {
      "field": "section"
    }
  },
  "assertions": [
    {
      "id": "field-instr-section",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:fldSimple/@w:instr",
      "must": "equal",
      "value": "SECTION \\* MERGEFORMAT",
      "description": "The fixture must contain a <w:fldSimple> whose w:instr attribute equals the expected field instruction verbatim. Uses `must: equal` (literal string compare) rather than `match` because several instructions carry backslash-escape sequences (\\*, \\@, \\h, \\f) that would require regex-escaping to embed in the manifest."
    }
  ]
}