A <w:altChunk> import pointing at an external payload part of configurable content-type (XHTML, HTML, RTF, plain text).
| Feature ID | Axis bindings | python-docx | docxjs |
|---|---|---|---|
docx/alt-chunk-html--html | payload=html | — | — |
docx/alt-chunk-html--rtf | payload=rtf | — | — |
docx/alt-chunk-html--text | payload=text | — | — |
docx/alt-chunk-html--xhtml | payload=xhtml | — | — |
| Library | Pass | Fail | Pending |
|---|---|---|---|
python-docx | 0 | 0 | 4 |
docxjs | 0 | 0 | 4 |
payload (4 values): xhtml, html, rtf, textscripts/gen_alt_chunk_html.py — runs with --arg_template --content-type "{payload.content_type}" --ext {payload.ext} --out fixtures/docx/alt-chunk-html--{payload.id}.docx
#!/usr/bin/env python3
"""Generate a ``fixtures/docx/alt-chunk-html--<payload>.docx`` fixture.
Parameterised generator for the ``docx/alt-chunk-html`` feature family. One
invocation writes a single fixture embedding an alternate-format import
(``<w:altChunk>``) with the requested payload content-type. Four payload
flavours are exercised:
- ``application/xhtml+xml`` (Word's primary altChunk flavour)
- ``text/html`` (legacy HTML payload)
- ``application/rtf`` (RTF payload)
- ``text/plain`` (plain text payload)
Uses the fork's ``Document.add_alt_chunk`` API, which provisions the payload
part, registers the ``aFChunk`` relationship, and emits a ``<w:altChunk>``
element in the body in one call.
"""
from __future__ import annotations
import argparse
from pathlib import Path
from docx import Document
_REPO_ROOT = Path(__file__).resolve().parent.parent
_PAYLOADS = {
"application/xhtml+xml": (
b'<?xml version="1.0" encoding="UTF-8"?>'
b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" '
b'"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">'
b'<html xmlns="http://www.w3.org/1999/xhtml"><head>'
b"<title>altChunk</title></head>"
b"<body><p>altChunk XHTML payload</p></body></html>"
),
"text/html": (
b"<!DOCTYPE html><html><head><title>altChunk</title></head>"
b"<body><p>altChunk HTML payload</p></body></html>"
),
"application/rtf": (
b"{\\rtf1\\ansi\\ansicpg1252\\deff0\\nouicompat\n"
b"{\\fonttbl{\\f0 Calibri;}}\n"
b"\\f0\\fs22 altChunk RTF payload.\\par}"
),
"text/plain": b"altChunk plain text payload.\n",
}
def _write(content_type: str, ext: str, out: Path) -> None:
payload = _PAYLOADS[content_type]
doc = Document()
doc.add_paragraph("Document preceding the altChunk import.")
doc.add_alt_chunk(payload, content_type=content_type)
out.parent.mkdir(parents=True, exist_ok=True)
doc.save(out, reproducible=True)
def main() -> int:
parser = argparse.ArgumentParser()
parser.add_argument("--content-type", required=True)
parser.add_argument("--ext", required=True)
parser.add_argument("--out", required=True)
ns = parser.parse_args()
out = Path(ns.out)
if not out.is_absolute():
out = _REPO_ROOT / out
_write(ns.content_type, ns.ext, out)
print(out)
return 0
if __name__ == "__main__":
raise SystemExit(main())
{
"$schema": "../manifest.schema.json",
"id": "docx/alt-chunk-html",
"kind": "parameterised",
"title": "altChunk — alternate-format import (parameterised)",
"format": "docx",
"category": "embedded-parts",
"roles": [
"authoring"
],
"summary": "A <w:altChunk> import pointing at an external payload part of configurable content-type (XHTML, HTML, RTF, plain text).",
"spec": {
"source": "ecma-376-5-part-1",
"clause": "17.17",
"element": "w:altChunk",
"rnc_reference": "spec/ecma-376-5/part-1/rnc/WordprocessingML.rnc",
"xsd_reference": "spec/ecma-376-5/part-1/xsd/wml.xsd",
"notes": "An altChunk (alternate-format import) references an external part whose payload is substituted in place at render time. The reference uses an r:id pointing at an aFChunk relationship. This family parameterises the payload content-type to pin the deep-part round-trip across common altChunk payload flavours: application/xhtml+xml (primary Word flavour), text/html (legacy HTML payload), application/rtf (RTF payload), text/plain (plain text). python-docx's Document.add_alt_chunk creates the part, the relationship, and the <w:altChunk> element in a single call."
},
"fixtures": {
"machine": "docx/alt-chunk-html"
},
"generator": {
"python": "scripts/gen_alt_chunk_html.py",
"arg_template": "--content-type \"{payload.content_type}\" --ext {payload.ext} --out fixtures/docx/alt-chunk-html--{payload.id}.docx"
},
"parameters": {
"payload": [
{
"id": "xhtml",
"content_type": "application/xhtml+xml",
"ext": "xhtml"
},
{
"id": "html",
"content_type": "text/html",
"ext": "html"
},
{
"id": "rtf",
"content_type": "application/rtf",
"ext": "rtf"
},
{
"id": "text",
"content_type": "text/plain",
"ext": "txt"
}
]
},
"assertions_template": [
{
"id": "alt-chunk-element-present-{payload.id}",
"part": "word/document.xml",
"namespaces": {
"w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main",
"r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
},
"xpath": "//w:altChunk/@r:id",
"must": "exist",
"description": "A <w:altChunk> element carrying an r:id attribute must be present in the document body."
},
{
"id": "content-type-override-{payload.id}",
"part": "[Content_Types].xml",
"namespaces": {
"ct": "http://schemas.openxmlformats.org/package/2006/content-types"
},
"xpath": "//ct:Override[@ContentType='{payload.content_type}']/@PartName",
"must": "exist",
"description": "An <Override> declaring the payload part's content-type must be registered."
},
{
"id": "afchunk-relationship-{payload.id}",
"part": "word/_rels/document.xml.rels",
"namespaces": {
"r": "http://schemas.openxmlformats.org/package/2006/relationships"
},
"xpath": "//r:Relationship[@Type='http://schemas.openxmlformats.org/officeDocument/2006/relationships/aFChunk']/@Target",
"must": "exist",
"description": "An aFChunk relationship from the document part to the payload must be declared."
}
]
}