Files
java-word-pdf/docs/standards/README.md
T
Pjandro fbdada1fda
PR checks / web (pull_request) Successful in 55s
PR checks / java (pull_request) Successful in 1m6s
Main: tests, deploy, autotests / web (push) Successful in 32s
Main: tests, deploy, autotests / images-web (push) Successful in 35s
Main: tests, deploy, autotests / java (push) Successful in 2m17s
Main: tests, deploy, autotests / images-app (push) Successful in 31s
Main: tests, deploy, autotests / deploy (push) Successful in 1m46s
Main: tests, deploy, autotests / autotests (push) Successful in 52s
Main: tests, deploy, autotests / rollback (push) Has been skipped
chart: 9 новых типов диаграмм (scatter/bubble/radar/stock/ofPie/surface2D/bar3D/area3D/line3D)
- ChartSpec: enum +9 типов, readGroup 9 веток, два c:valAx для scatter/bubble
  (X — первый), автозаголовок OF_PIE как у круговых
- ChartRenderer: диспетчер + легенда высотных полос для SURFACE
- Пейнтеры: ScatterPainter, RadarPainter, StockPainter, OfPiePainter,
  Surface2dPainter, Cartesian3dPainter (камера Surface3dPainter.project)
- Фикстура samples/chart-types.docx (ChartTypesDocxGenerator, chart-XML
  литералами) + регрессия WordPdfConverterTest#chartTypes_allTypesRenderAsImages
- docs/standards: полные наборы XSD strict/transitional + validate-fixtures.py;
  все 13 фикстур валидны по ECMA-376 (битые атрибуты в старых фикстурах
  исправлены в генераторе и пересозданных .docx)
- AGENTS.md/README обновлены
2026-10-25 02:13:28 +00:00

68 lines
7.1 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.
# Нормативная документация OOXML
Источник истины для chart-движка (`wordpdf-core/.../internal/chart/`) и нормализаторов: любые правки диаграмм/SmartArt/представления docx — по документам ниже, а не по догадкам. Правило закреплено в `AGENTS.md` (секция «Chart-движок»).
## Источники
|Файл|Документ|Редакция/дата|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)|
SHA-256 `.md`-файлов — справочные: они производные от инструментов извлечения (poppler/pandoc), при регенерации другим инструментом могут измениться; первичен PDF/docx выше.
## Что где искать
- **Диаграммы (`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/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/ms-oi29500.md
pandoc /tmp/odrawxml.docx -t gfm-raw_html --wrap=none -o docs/standards/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/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/schema/transitional /tmp/OfficeOpenXML-XMLSchema-Transitional.zip "*.xsd"
```
## Валидация фикстур
`samples/*.docx` обязаны быть ECMA-conformant (фикстуры — источник истины по входу,
код под них не подгоняется). Проверка — `validate-fixtures.py` (lxml + схемы
`schema/transitional/`):
```bash
python3 docs/standards/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]).