Files
java-word-pdf/docs/standards/docx/README.md
T
Pjandro abfa673b85
PR checks / web (pull_request) Successful in 34s
PR checks / java (pull_request) Successful in 1m9s
Main: tests, deploy, autotests / web (push) Successful in 31s
Main: tests, deploy, autotests / java (push) Successful in 1m11s
Main: tests, deploy, autotests / images-web (push) Successful in 33s
Main: tests, deploy, autotests / images-app (push) Successful in 40s
Main: tests, deploy, autotests / deploy (push) Successful in 1m42s
Main: tests, deploy, autotests / autotests (push) Successful in 39s
Main: tests, deploy, autotests / rollback (push) Has been skipped
Доки: окружение [MS-DOC] в docs/standards/doc (CFB/OSHARED/ODRAW/OLEPS/OFFCRYPTO/OVBA/WMF/EMF) + README по категориям
2026-10-29 21:00:03 +00:00

68 lines
7.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Нормативная документация форматов Word
Источник истины для chart-движка (`wordpdf-core/.../internal/chart/`) и нормализаторов: любые правки диаграмм/SmartArt/представления docx — по документам ниже, а не по догадкам. Правило закреплено в `AGENTS.md` (секция «Chart-движок»). Документация бинарного .doc — `../doc/README.md`.
SHA-256 `.md`-файлов — справочные: они производные от инструментов извлечения (poppler/pandoc), при регенерации другим инструментом могут измениться; первичен PDF/docx в таблице «Источники».
### Источники
|Файл|Документ|Редакция/дата|URL|SHA-256|
|---|---|---|---|---|
|`ECMA-376-1_5th_edition_december_2016.pdf`|ECMA-376 Part 1 «Fundamentals and Markup Language Reference»|5-е изд., декабрь 2016|https://ecma-international.org/wp-content/uploads/ECMA-376-1_5th_edition_december_2016.pdf|`7cccfd0ad0e2ef89316acece15e44a8a088d0603ce4bba4e7b0361b50d13a37d`|
|`ecma376-part1-5th.md`|Тот же текст, извлечённый из PDF (поиск по номерам секций)|5-е изд.|производный (см. регенерацию)|`86af445c080d9a481eaa426fc1721d50a1c4eff875535f9d03fe93d2b95b21b6`|
|`ms-oi29500.md`|[MS-OI29500] «Office Implementation Information for ISO/IEC-29500 Standards» — как Word реально пишет docx (§2.1 — комментарий к Part 1, §3.1 — к Part 4)|260818 (август 2026)|https://officeprotocoldocs-f5hpbjgea6b8gneq.b02.azurefd.net/files/MS-OI29500/%5bMS-OI29500%5d-260818.docx|`3e3eabb060a3772d096f001e7fee682fc4be12a2dd55ea360430fff14dd5845d`|
|`ms-odrawxml.md`|[MS-ODRAWXML] «Office Drawing Extensions to Office Open XML» — расширения Word/Excel для чартов (ChartEx, стили/цвета)|261006 (октябрь 2026)|https://officeprotocoldocs-f5hpbjgea6b8gneq.b02.azurefd.net/files/MS-ODRAWXML/%5bMS-ODRAWXML%5d-261006.docx|`f5a2517c4984b2ba2f0ade504bd0c9660c74f619290910a9b491c0f2ca9db64a`|
|`schema/strict/`|Полный набор XSD Strict (21 файл: `wml`/`sml`/`pml`/`dml-*`/`shared-*`)|5-е изд.|вложенный `OfficeOpenXML-XMLSchema-Strict.zip` в https://ecma-international.org/wp-content/uploads/ECMA-376-1_5th_edition_december_2016.zip|`9d0bcad9cf06054785b03762fcfadbf6bab7e54a5f9d69434e34b7fd464d4129` (zip)|
|`schema/transitional/`|Полный набор XSD Transitional (26 файлов, +5 `vml-*`)|5-е изд.|вложенный `OfficeOpenXML-XMLSchema-Transitional.zip` в https://ecma-international.org/wp-content/uploads/ECMA-376-4_5th_edition_december_2016.zip|`bd25da1109f73762356596918bf5ff8b74a1331642dba5f1c1d1dfc6bed34ecd` (zip)|
### Что где искать
- **Диаграммы (`c:chart`)** — ECMA-376 §21.2 (`grep -n "^21.2" ecma376-part1-5th.md`; каждый элемент — секция вида `21.2.2.132 overlay (Overlay)`) + `schema/transitional/dml-chart.xsd` (он же в `schema/strict/`); расширения Word — `ms-odrawxml.md`.
- **Диаграммы-схемы SmartArt (`dgm:`)** — ECMA-376 §21.4 + `schema/transitional/dml-diagram.xsd`. Кэш разложенной схемы (`word/diagrams/drawing1.xml`, relationship `…/office/2007/relationships/diagramDrawing`) — проприетарный MS-формат (`dsp:`, [MS-ODRAWXML]), нормативного ECMA-XSD нет; authoritative источник фактической геометрии — сам `dsp:drawing`.
- **Пресет-геометрия (`a:prstGeom`)** — ECMA-376 Annex D; машинная копия таблицы пресетов — `wordpdf-core/src/test/resources/geom/presetShapeDefinitions.xml` (синхрон пинит `PresetGeometryTest#tableMatchesEcmaXml`).
- **Chart Drawings (`c:drawing`)** — ECMA-376 §21.3.
- **Поведение Word (что он реально пишет в `w:r`/`w:t`/`lastRenderedPageBreak`, текстбоксы, чарты)** — `ms-oi29500.md` (указатели на секции Part 1, напр. §2.17.3.3.13 → Part 1 §17.3.3.13).
### Регенерация
```bash
# ecma376-part1-5th.md — из PDF в репозитории (постобработка: выбросить строки
# `^\s*\d{1,4}\s*$` (номера страниц), `^ECMA-376 Part 1\s*$` (колонтитул),
# строки с `.....` (точки оглавления); остальной текст — как есть)
pdftotext -layout docs/standards/docx/ECMA-376-1_5th_edition_december_2016.pdf /tmp/p1.txt
# ms-oi29500.md / ms-odrawxml.md — свежие dated-.docx с learn.microsoft.com
# (при 404 — самый свежий .docx со страниц лендингов:
# https://learn.microsoft.com/en-us/openspecs/office_standards/ms-oi29500/1fd4a662-8623-49c0-82f0-18fa91b413b8
# https://learn.microsoft.com/en-us/openspecs/office_standards/ms-odrawxml/06cff208-c6e1-4db7-bb68-665135e5f0de)
curl -sSL -o /tmp/oi29500.docx "https://officeprotocoldocs-f5hpbjgea6b8gneq.b02.azurefd.net/files/MS-OI29500/%5bMS-OI29500%5d-260818.docx"
curl -sSL -o /tmp/odrawxml.docx "https://officeprotocoldocs-f5hpbjgea6b8gneq.b02.azurefd.net/files/MS-ODRAWXML/%5bMS-ODRAWXML%5d-261006.docx"
pandoc /tmp/oi29500.docx -t gfm-raw_html --wrap=none -o docs/standards/docx/ms-oi29500.md
pandoc /tmp/odrawxml.docx -t gfm-raw_html --wrap=none -o docs/standards/docx/ms-odrawxml.md
# schema/strict/ и schema/transitional/ — полные наборы из официальных ECMA-архивов
curl -sSL -o /tmp/p1.zip "https://ecma-international.org/wp-content/uploads/ECMA-376-1_5th_edition_december_2016.zip"
unzip -o /tmp/p1.zip "OfficeOpenXML-XMLSchema-Strict.zip" -d /tmp/
unzip -o -d docs/standards/docx/schema/strict /tmp/OfficeOpenXML-XMLSchema-Strict.zip "*.xsd"
curl -sSL -o /tmp/p4.zip "https://ecma-international.org/wp-content/uploads/ECMA-376-4_5th_edition_december_2016.zip"
unzip -o /tmp/p4.zip "OfficeOpenXML-XMLSchema-Transitional.zip" -d /tmp/
unzip -o -d docs/standards/docx/schema/transitional /tmp/OfficeOpenXML-XMLSchema-Transitional.zip "*.xsd"
```
### Валидация фикстур
`samples/*.docx` обязаны быть ECMA-conformant (фикстуры — источник истины по входу,
код под них не подгоняется). Проверка — `docx/validate-fixtures.py` (lxml + схемы
`docx/schema/transitional/`):
```bash
python3 docs/standards/docx/validate-fixtures.py wordpdf-core/src/test/resources/samples/*.docx
```
Допущения валидатора (оба по Part 1): `xml:space` — предопределённый атрибут
§5.1.2, схемам подмешивается импорт XML-namespace; `mc:AlternateContent`/
`mc:Ignorable` (§15.2.15) — валидируется Fallback-ветка, атрибуты и элементы
ignorable-namespace'ов снимаются. Не маппятся (вне ECMA, осознанно):
`word/charts/style*.xml`/`colors*.xml` (c14/chartStyle, MS-расширение),
`word/diagrams/drawing*.xml` (`dsp:`, [MS-ODRAWXML]).