docx/underline-style

Parameter axes

• style (18 values): single, words, double, thick, dotted, dotted-heavy, dash, dashed-heavy, dash-long, dash-long-heavy, dot-dash, dash-dot-heavy, dot-dot-dash, dash-dot-dot-heavy, wave, wavy-heavy, wavy-double, none

Spec notes

Generator source

scripts/gen_underline_style.py — runs with --arg_template --style {style.val} --out fixtures/docx/underline-style--{style.id}.docx

#!/usr/bin/env python3
"""Generate a ``fixtures/docx/underline-style--*.docx`` fixture.

Parameterised generator for the ``docx/underline-style`` family. One
Python invocation per ST_Underline variant produces one fixture whose
single run has ``<w:u w:val="..."/>`` set to the requested style.

Usage::

    gen_underline_style.py --style single --out fixtures/docx/underline-style--single.docx

The ``features/docx/underline-style.json`` manifest's
``generator.arg_template`` field drives these args at expansion time.
"""

from __future__ import annotations

import argparse
from pathlib import Path

from docx import Document
from docx.enum.text import WD_UNDERLINE

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

# Map ST_Underline string values (as they appear on @w:val) to the
# corresponding WD_UNDERLINE enum member. Every entry below corresponds
# to a supported case in the manifest's `parameters.style` list.
UNDERLINE_MAP: dict[str, WD_UNDERLINE] = {
    "single":          WD_UNDERLINE.SINGLE,
    "words":           WD_UNDERLINE.WORDS,
    "double":          WD_UNDERLINE.DOUBLE,
    "thick":           WD_UNDERLINE.THICK,
    "dotted":          WD_UNDERLINE.DOTTED,
    "dottedHeavy":     WD_UNDERLINE.DOTTED_HEAVY,
    "dash":            WD_UNDERLINE.DASH,
    "dashedHeavy":     WD_UNDERLINE.DASH_HEAVY,
    "dashLong":        WD_UNDERLINE.DASH_LONG,
    "dashLongHeavy":   WD_UNDERLINE.DASH_LONG_HEAVY,
    "dotDash":         WD_UNDERLINE.DOT_DASH,
    "dashDotHeavy":    WD_UNDERLINE.DOT_DASH_HEAVY,
    "dotDotDash":      WD_UNDERLINE.DOT_DOT_DASH,
    "dashDotDotHeavy": WD_UNDERLINE.DOT_DOT_DASH_HEAVY,
    "wave":            WD_UNDERLINE.WAVY,
    "wavyHeavy":       WD_UNDERLINE.WAVY_HEAVY,
    "wavyDouble":      WD_UNDERLINE.WAVY_DOUBLE,
    "none":            WD_UNDERLINE.NONE,
}


def _write(style_val: str, out: Path) -> None:
    try:
        enum_member = UNDERLINE_MAP[style_val]
    except KeyError as exc:
        raise SystemExit(
            f"Unsupported ST_Underline value {style_val!r}. "
            f"Known values: {sorted(UNDERLINE_MAP)}"
        ) from exc

    doc = Document()
    paragraph = doc.add_paragraph()
    run = paragraph.add_run("Underlined text")
    run.font.underline = enum_member
    out.parent.mkdir(parents=True, exist_ok=True)
    doc.save(out, reproducible=True)


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--style",
        required=True,
        choices=sorted(UNDERLINE_MAP),
        help="ST_Underline value to apply (matches @w:val).",
    )
    parser.add_argument("--out", required=True, help="Output fixture path.")
    args = parser.parse_args()

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


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

Manifest (parent, unexpanded)

{
  "$schema": "../manifest.schema.json",
  "id": "docx/underline-style",
  "kind": "parameterised",
  "title": "Underline style",
  "format": "docx",
  "category": "text-formatting",
  "summary": "Apply each ST_Underline style variant to a run via w:u/@w:val.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "17.3.2.40",
    "element": "w:u",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/WordprocessingML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/wml.xsd",
    "notes": "<w:u> takes a required @w:val attribute of type ST_Underline (clause 17.18.99). This parameterised manifest exercises eighteen ST_Underline values: single, words, double, thick, dotted, dottedHeavy, dash, dashedHeavy, dashLong, dashLongHeavy, dotDash, dashDotHeavy, dotDotDash, dashDotDotHeavy, wave, wavyHeavy, wavyDouble, and none. Each expanded case targets a distinct fixture `docx/underline-style--<id>.docx` generated from gen_underline_style.py. The literal sibling `docx/underline-text` (default single underline via `run.underline = True`) is preserved as a standalone case. For the 'none' case, python-docx emits `<w:u w:val=\"none\"/>` explicitly, so the xpath still matches."
  },
  "fixtures": {
    "machine": "docx/underline-style"
  },
  "generator": {
    "python": "scripts/gen_underline_style.py",
    "arg_template": "--style {style.val} --out fixtures/docx/underline-style--{style.id}.docx"
  },
  "parameters": {
    "style": [
      {
        "id": "single",
        "val": "single"
      },
      {
        "id": "words",
        "val": "words"
      },
      {
        "id": "double",
        "val": "double"
      },
      {
        "id": "thick",
        "val": "thick"
      },
      {
        "id": "dotted",
        "val": "dotted"
      },
      {
        "id": "dotted-heavy",
        "val": "dottedHeavy"
      },
      {
        "id": "dash",
        "val": "dash"
      },
      {
        "id": "dashed-heavy",
        "val": "dashedHeavy"
      },
      {
        "id": "dash-long",
        "val": "dashLong"
      },
      {
        "id": "dash-long-heavy",
        "val": "dashLongHeavy"
      },
      {
        "id": "dot-dash",
        "val": "dotDash"
      },
      {
        "id": "dash-dot-heavy",
        "val": "dashDotHeavy"
      },
      {
        "id": "dot-dot-dash",
        "val": "dotDotDash"
      },
      {
        "id": "dash-dot-dot-heavy",
        "val": "dashDotDotHeavy"
      },
      {
        "id": "wave",
        "val": "wave"
      },
      {
        "id": "wavy-heavy",
        "val": "wavyHeavy"
      },
      {
        "id": "wavy-double",
        "val": "wavyDouble"
      },
      {
        "id": "none",
        "val": "none"
      }
    ]
  },
  "assertions_template": [
    {
      "id": "underline-val-is-{style.id}",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:r[w:t[normalize-space()='Underlined text']]/w:rPr/w:u/@w:val",
      "must": "equal",
      "value": "{style.val}",
      "description": "The @w:val on <w:u> must equal the ST_Underline variant under test."
    }
  ]
}