docs(standards): [MS-PPT] для .ppt + навигатор PresentationML для .pptx
PR checks / web (pull_request) Successful in 40s
PR checks / java (pull_request) Successful in 1m35s
Main: tests, deploy, autotests / web (push) Successful in 32s
Main: tests, deploy, autotests / java (push) Successful in 1m9s
Main: tests, deploy, autotests / images-web (push) Successful in 30s
Main: tests, deploy, autotests / images-app (push) Successful in 48s
Main: tests, deploy, autotests / deploy (push) Failing after 2m42s
Main: tests, deploy, autotests / autotests (push) Has been skipped
Main: tests, deploy, autotests / rollback (push) Failing after 2m37s
PR checks / web (pull_request) Successful in 40s
PR checks / java (pull_request) Successful in 1m35s
Main: tests, deploy, autotests / web (push) Successful in 32s
Main: tests, deploy, autotests / java (push) Successful in 1m9s
Main: tests, deploy, autotests / images-web (push) Successful in 30s
Main: tests, deploy, autotests / images-app (push) Successful in 48s
Main: tests, deploy, autotests / deploy (push) Failing after 2m42s
Main: tests, deploy, autotests / autotests (push) Has been skipped
Main: tests, deploy, autotests / rollback (push) Failing after 2m37s
This commit was merged in pull request #90.
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# Нормативная документация форматов Office
|
||||
|
||||
Источник истины по форматам документов, которые принимает конвертер (`.docx`/`.doc`), и по соседним форматам того же семейства (`.xlsx`/`.xls`). Правило репозитория: любое решение про уже существующий формат — по спецификациям отсюда, а не по памяти или догадкам; ссылка на спецификацию — **с номером секции** (см. `AGENTS.md` «Documentation FIRST»).
|
||||
Источник истины по форматам документов, которые принимает конвертер (`.docx`/`.doc`), и по соседним форматам того же семейства (`.xlsx`/`.xls`, `.pptx`/`.ppt`). Правило репозитория: любое решение про уже существующий формат — по спецификациям отсюда, а не по памяти или догадкам; ссылка на спецификацию — **с номером секции** (см. `AGENTS.md` «Documentation FIRST»).
|
||||
|
||||
### Формат → директория
|
||||
|
||||
@@ -10,8 +10,10 @@
|
||||
|`.docx` (Word OOXML)|`docx/` (валидатор фикстур)|`ooxml/` (ECMA-376 Part 1 §17 WordprocessingML + XSD; [MS-OI29500], [MS-ODRAWXML])|
|
||||
|`.xls` (Excel 97–2003, бинарный OLE2)|`xls/` ([MS-XLS])|`binary/` (то же окружение, что у .doc)|
|
||||
|`.xlsx` (Excel OOXML)|`xlsx/` ([MS-XLSX])|`ooxml/` (ECMA-376 Part 1 §18 SpreadsheetML + `sml.xsd`; [MS-OI29500], [MS-ODRAWXML])|
|
||||
|`.ppt` (PowerPoint 97–2003, бинарный OLE2)|`ppt/` ([MS-PPT])|`binary/` (то же окружение, что у .doc)|
|
||||
|`.pptx` (PowerPoint OOXML)|`pptx/` (навигатор: MS-расширения для .pptx не публикуется)|`ooxml/` (ECMA-376 Part 1 §13 — части PresentationML, §19 — Reference Material + `pml.xsd`; [MS-OI29500], [MS-ODRAWXML])|
|
||||
|
||||
Схемы ECMA-376 покрывают и PowerPoint (`pml.xsd`, §19 — в PDF и `ecma376-part1-5th.md` в `ooxml/`); специализированных MS-документов по PowerPoint здесь нет.
|
||||
Схемы ECMA-376 покрывают PowerPoint полностью: части пакета — §13, элементы — §19 (оба в PDF и `ecma376-part1-5th.md` в `ooxml/`), специфика бинарного .ppt — [MS-PPT] в `ppt/`; отдельного MS-документа-расширения для .pptx Microsoft не публикует (`[MS-PPTX]` — 404, `[MS-PPTSB]` снят с публикации).
|
||||
|
||||
### Как искать по номеру секции
|
||||
|
||||
@@ -21,10 +23,11 @@
|
||||
|`ooxml/ecma376-part1-5th.md`|номер вида §18.3.1.53|по нумерованным заголовкам в теле: `grep -n "^18\.3\.1" ooxml/ecma376-part1-5th.md` (пример строки: `18.3.1.53 is (Rich Text Inline)`)|
|
||||
|`ooxml/ms-oi29500.md`|комментарий Office к Part 1|указатели вида `§2.17.3.3.13` (→ Part 1 §17.3.3.13)|
|
||||
|`binary/*.md`, `xlsx/ms-xlsx.md`|номер вида §2.2|тот же приём оглавления: `grep -n "^\[2\.2 " xlsx/ms-xlsx.md`|
|
||||
|`ppt/ms-ppt.md`|номер вида §2.9.42 или имя записи|оглавление даёт пару «номер → якорь»: `grep -n "^\[2\.9\.42 " ppt/ms-ppt.md`; заголовки в теле без номеров, но названы именем типа: `grep -n "^#\+ TextCharsAtom" ppt/ms-ppt.md`|
|
||||
|
||||
### Конвенции
|
||||
|
||||
- Первичен оригинал — `.docx`/`.pdf` в таблицах «Источники»; `.md` — производные извлечения, их SHA-256 справочные (сменишь инструмент — сменится SHA).
|
||||
- Регенерация — dated `.docx` с CDN (два хоста: у office_protocols-документов путь с сегментом `/files/`, у windows_protocols — без) + `pandoc -t gfm-raw_html --wrap=none`; плейсхолдеры `[TABLE]` (packet diagram'ы) и «full»-конверты с HTML-таблицами (`-t gfm`) описаны в README'ах каталогов.
|
||||
- Регенерация — dated `.docx` с CDN (два хоста: у office_protocols-документов путь с сегментом `/files/`, у windows_protocols — без) + `pandoc -t gfm-raw_html --wrap=none`; плейсхолдеры `[TABLE]` (packet diagram'ы) и «full»-конверты с HTML-таблицами (`-t gfm`) описаны в README'ах каталогов. Исключение: `ppt/ms-ppt.md` сразу делается `-t gfm` — packet diagram'ы там сохранены HTML-таблицами, `[TABLE]` нет, «full»-файл не заведён.
|
||||
- ECMA-376 `.md` — из PDF (`pdftotext -layout` + постобработка), XSD — из официальных ECMA-архивов: `ooxml/README.md`.
|
||||
- Валидация `.docx`-фикстур по transitional-XSD — `docx/validate-fixtures.py`, см. `docx/README.md`.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Нормативная документация общего OLE2-окружения (.doc/.xls/.ppt)
|
||||
|
||||
Справочный комплект вокруг бинарных форматов Office 97–2003: контейнер и его служебные потоки (CFB, property sets, OfficeArt-рисунки, шифрование, VBA, метафайлы) общие для Word, Excel и PowerPoint — правки по документам ниже, а не по догадкам. Специфика форматов: Word — `../doc/README.md` ([MS-DOC]), Excel — `../xls/README.md` ([MS-XLS]). Документация OOXML — `../ooxml/README.md`.
|
||||
Справочный комплект вокруг бинарных форматов Office 97–2003: контейнер и его служебные потоки (CFB, property sets, OfficeArt-рисунки, шифрование, VBA, метафайлы) общие для Word, Excel и PowerPoint — правки по документам ниже, а не по догадкам. Специфика форматов: Word — `../doc/README.md` ([MS-DOC]), Excel — `../xls/README.md` ([MS-XLS]), PowerPoint — `../ppt/README.md` ([MS-PPT]). Документация OOXML — `../ooxml/README.md`.
|
||||
|
||||
SHA-256 `.md`-файлов — справочные: они производные от инструментов извлечения (poppler/pandoc), при регенерации другим инструментом могут измениться; первичен docx в таблице «Источники».
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Нормативная документация OOXML (общая для .docx/.xlsx/.pptx)
|
||||
|
||||
Источник истины для chart-движка (`wordpdf-core/.../internal/chart/`), нормализаторов и любого правки OOXML-разметки: любые правки диаграмм/SmartArt/представления docx/xlsx — по документам ниже, а не по догадкам. Правило закреплено в `AGENTS.md` (секции «Chart/SmartArt-движок», «Нормализаторы»). Здесь — только кросс-форматная часть ECMA-376 и Office-комментарии; специфика WordprocessingML-пайплайна и валидация фикстур — `../docx/README.md`, SpreadsheetML-расширения Excel — `../xlsx/README.md`. Документация бинарного .doc — `../doc/README.md`, бинарного .xls — `../xls/README.md`.
|
||||
Источник истины для chart-движка (`wordpdf-core/.../internal/chart/`), нормализаторов и любого правки OOXML-разметки: любые правки диаграмм/SmartArt/представления docx/xlsx — по документам ниже, а не по догадкам. Правило закреплено в `AGENTS.md` (секции «Chart/SmartArt-движок», «Нормализаторы»). Здесь — только кросс-форматная часть ECMA-376 и Office-комментарии; специфика WordprocessingML-пайплайна и валидация фикстур — `../docx/README.md`, SpreadsheetML-расширения Excel — `../xlsx/README.md`, PresentationML (.pptx) — `../pptx/README.md`. Документация бинарного .doc — `../doc/README.md`, бинарного .xls — `../xls/README.md`, бинарного .ppt — `../ppt/README.md`.
|
||||
|
||||
SHA-256 `.md`-файлов — справочные: они производные от инструментов извлечения (poppler/pandoc), при регенерации другим инструментом могут измениться; первичен PDF/docx в таблице «Источники».
|
||||
|
||||
@@ -19,6 +19,7 @@ SHA-256 `.md`-файлов — справочные: они производны
|
||||
|
||||
- **WordprocessingML (.docx)** — ECMA-376 §17 (текст/раны/свойства — §17.3, таблицы — §17.4; например `w:position` — §17.3.2.24) + `schema/transitional/wml.xsd`.
|
||||
- **SpreadsheetML (.xlsx)** — ECMA-376 §18 (§18.2 workbook, §18.3 worksheet, §18.4 styles, §18.5 sharedStrings, §18.6 drawing) + `schema/transitional/sml.xsd`, `dml-spreadsheetDrawing.xsd`; поиск: `grep -n "^18\.3\.1" ecma376-part1-5th.md`. Расширения Excel — `../xlsx/ms-xlsx.md`.
|
||||
- **PresentationML (.pptx)** — части пакета: ECMA-376 §13 (§13.2 Package Structure, §13.3.6 Presentation Part, §13.3.8 Slide Part, §13.3.9 Slide Layout Part, §13.3.10 Slide Master Part…), семантика элементов `p:`: §19 «PresentationML Reference Material» (§19.2 presentation properties, §19.3 slides, §19.5 animation) + `schema/transitional/pml.xsd` (он же в `schema/strict/`); поиск: `grep -n "^13\.3\.[0-9]" ecma376-part1-5th.md`, `grep -n "^19\.3" ecma376-part1-5th.md`. Навигатор по формату — `../pptx/README.md`, бинарный .ppt — `../ppt/README.md`.
|
||||
- **Диаграммы (`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`.
|
||||
- **Chart Drawings (`c:drawing`)** — ECMA-376 §21.3.
|
||||
- **Диаграммы-схемы 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`.
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
# Нормативная документация бинарного .ppt (PowerPoint 97–2003)
|
||||
|
||||
Справочный комплект формата бинарного .ppt: [MS-PPT] — источник истины по потокам CFB-файла и записям `PowerPoint Document`-потока (RecordHeader, persist-объекты, документ/слайды/шейпы/анимация/текст). В конвертере поддержки .ppt нет — комплект справочный (вход конвертера: `.docx`/`.doc`). Общее OLE2-окружение (CFB-контейнер, property sets, OfficeArt, шифрование, VBA, метафайлы, общие типы MS-OSHARED) — `../binary/README.md`; документация OOXML — `../ooxml/README.md`; PresentationML (.pptx) — `../pptx/README.md`.
|
||||
|
||||
SHA-256 `.md`-файлов — справочные: они производные от инструментов извлечения (pandoc), при регенерации другим инструментом могут измениться; первичен docx в таблице «Источники».
|
||||
|
||||
Конверт сделан `-t gfm` (**raw_html включён**): битовые макеты записей (packet diagram'ы — RecordHeader §2.3.1 и т. п.) в [MS-PPT] есть, но здесь они сохранены инлайновыми HTML-таблицами (425 штук), которые GitHub рендерит; при `-t gfm-raw_html` те же 425 таблиц сворачиваются в плейсхолдеры `[TABLE]`, поэтому вариант с выключенным raw_html не используется. Отдельный «full»-файл, как у [MS-DOC]/[MS-XLS], не нужен — поля всех макетов уже в `ms-ppt.md`.
|
||||
|
||||
### Источники
|
||||
|
||||
|Файл|Документ|Редакция/дата|URL|SHA-256|
|
||||
|---|---|---|---|---|
|
||||
|`ms-ppt.md`|[MS-PPT] «PowerPoint (.ppt) Binary File Format» — бинарный формат .ppt PowerPoint 97–2003 (потоки Current User / PowerPoint Document / Pictures; записи: DocumentContainer, persist-объекты, слайды, шейпы, анимация, текст)|10.1 (241112, ноябрь 2024)|https://officeprotocoldocs-f5hpbjgea6b8gneq.b02.azurefd.net/files/MS-PPT/%5bMS-PPT%5d-241112.docx|`32c90b18077b345b8554928290b7d853c05db605c8950e12403afd1f3d5d835d`|
|
||||
|`ms-ppt.docx`|Оригинальный dated-.docx [MS-PPT] 10.1 (первичный источник `.md`-конверта)|10.1 (241112)|тот же URL, что `ms-ppt.md`|`776798ab869049330e625a39a15e2e5cad036149c1bc813673b86be0f5fd7f6c`|
|
||||
|
||||
Недейтед `[MS-PPT].docx` на CDN отсутствует (404, есть только недейтед-PDF на 26 МБ) — брать только dated-.docx из таблицы «Published Version» лендинга. `[MS-PPTSB]` (слайд-деки старых PowerPoint) Microsoft сняла с публикации — лендинг и CDN отдают 404, в комплект не входит.
|
||||
|
||||
### Что где искать
|
||||
|
||||
- **Структура файла** — `ms-ppt.md`: §2.1 File Streams and Storages — потоки и хранилища CFB: §2.1.1 Current User Stream (имя `Current User`, обязательный, единственная запись CurrentUserAtom), §2.1.2 PowerPoint Document Stream (имя `PowerPoint Document`, обязательный — основной поток записей), §2.1.3 Pictures Stream (имя `Pictures`, опциональный — содержимое задаётся записью OfficeArtBStoreDelay, [MS-ODRAW]), §2.1.4 Summary Information Stream (имя `\005SummaryInformation`) и §2.1.5 Document Summary Information Stream (имя `\005DocumentSummaryInformation`) — property sets по [MS-OSHARED] §2.3.3.2.1/§2.3.3.2.2, §2.1.6 Encrypted Summary Information Stream (имя `EncryptedSummary`, только шифрованный документ — [MS-OFFCRYPTO] §2.3.5.4), §2.1.7 Digital Signature Storage. Контейнер — тот же OLE2/CFB, что у .doc/.xls (`../binary/ms-cfb.md` §2.2).
|
||||
- **Типы записей по назначению** — `ms-ppt.md`: §2.2 Basic Types (BlipRef §2.2.1, bool1/char2, PersistIdRef §2.2.21, SlideId/SlideIdRef §2.2.24/.25, PrintableAnsiString/PrintableUnicodeString §2.2.22/.23…), §2.3 File Structure Types (RecordHeader §2.3.1 — `rh.recType`/`rh.recInstance`/`rh.recLen`, CurrentUserAtom §2.3.2, UserEditAtom §2.3.3, persist-таблица PersistDirectoryAtom §2.3.4 с PersistDirectoryEntry §2.3.5 и PersistOffsetEntry §2.3.6, CryptSession10Container §2.3.7), §2.4 Document Types (корень дерева — DocumentContainer §2.4.1), §2.5 Slide Types (SlideContainer §2.5.1, MainMasterContainer §2.5.3, RoundTrip*-записи), §2.6 Slide Show Types, §2.7 Shape Types (шейпы, группы, таблицы), §2.8 Animation Types, §2.9 Text Types (TextHeaderAtom §2.9.41, TextCharsAtom §2.9.42 / TextBytesAtom §2.9.43, StyleTextPropAtom §2.9.44 с TextPFRun §2.9.45 и TextCFRun §2.9.46), §2.10 External Object Types (OLE-объекты, ссылки на картинки), §2.11 Other Types, §2.12 Common Structures, §2.13 Enumerations (в т.ч. §2.13.24 RecordType — полная таблица `RT_*` → имя записи; на неё ссылается каждое поле `rh.recType`).
|
||||
- **Как читается файл на практике** — §3 Structure Examples: §3.2 File Structure (CFB + потоки + persist-разрешение offset'ов), §3.3 Persist Objects, §3.5 Slides, §3.9 Text; §4 Security Considerations; §5 Appendix A: Product Behavior (что пишет PowerPoint разных версий); §6 Change Tracking (история редакций).
|
||||
- **Поиск по номеру секции** — заголовки в теле без номеров, но названы именем типа, а оглавление даёт пару «номер → якорь»: `grep -n "^\[2\.9\.42 " ms-ppt.md` → `[2.9.42 TextCharsAtom [373](#textcharsatom)]`, дальше тело — `grep -n "^#\+ TextCharsAtom" ms-ppt.md` (якорь = lowercase имя типа). По имени записи можно сразу в тело: `grep -n "^#\+ StyleTextPropAtom" ms-ppt.md`. Поля записей — таблицы вида `| **rh.recType** | MUST be an [RT_TextCharsAtom](#recordtype). |`.
|
||||
|
||||
### Регенерация
|
||||
|
||||
```bash
|
||||
# ms-ppt.md — свежий dated-.docx [MS-PPT] с лендинга
|
||||
# https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-ppt/6be79dde-33c1-4c1b-8ccc-4b2301c08662
|
||||
# (самый свежий dated-.docx — в таблице «Published Version»; недейтед .docx на CDN нет)
|
||||
curl -sSL -o /tmp/ms-ppt.docx "https://officeprotocoldocs-f5hpbjgea6b8gneq.b02.azurefd.net/files/MS-PPT/%5bMS-PPT%5d-241112.docx"
|
||||
pandoc /tmp/ms-ppt.docx -t gfm --wrap=none -o docs/standards/ppt/ms-ppt.md
|
||||
|
||||
# Обновлённый dated-.docx при этом перекладывается в ms-ppt.docx (первичный источник).
|
||||
```
|
||||
Binary file not shown.
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,11 @@
|
||||
# Документация формата .pptx в этом репозитории
|
||||
|
||||
Здесь — только навигатор: нормативная база PresentationML живёт в `../ooxml/README.md` (ECMA-376 Part 1 §13 — части пакета и §19 — Reference Material, XSD `pml.xsd`, комментарии Office [MS-OI29500], расширения рисунков [MS-ODRAWXML]) — там же таблицы «Источники» с SHA и команды регенерации. Своего MS-документа-расширения у PowerPoint нет: `[MS-PPTX]` Microsoft не публикует (лендинг 404), `[MS-PPTSB]` снят с публикации (лендинг и CDN 404), поэтому новых файлов в этом каталоге нет — только ссылки. В конвертере поддержки .pptx нет — комплект справочный (вход конвертера: `.docx`/`.doc`). Бинарный .ppt — `../ppt/README.md` ([MS-PPT]), общее OLE2-окружение — `../binary/README.md`.
|
||||
|
||||
### Что где искать
|
||||
|
||||
- **Части пакета .pptx** (`ppt/presentation.xml`, `slides/slideN.xml`, `slideLayouts/`, `slideMasters/`, `notesSlides/`, `handoutMaster`, `commentAuthors`, `presProps`, `viewProps`, `tableStyles`, `theme/`) — ECMA-376 §13 PresentationML в `../ooxml/ecma376-part1-5th.md`: §13.2 Package Structure, §13.3.1 Comment Authors Part, §13.3.2 Comments Part, §13.3.3 Handout Master Part, §13.3.4 Notes Master Part, §13.3.5 Notes Slide Part, §13.3.6 Presentation Part, §13.3.7 Presentation Properties Part, §13.3.8 Slide Part, §13.3.9 Slide Layout Part, §13.3.10 Slide Master Part, §13.3.11 Slide Synchronization Data Part, §13.3.12 User Defined Tags Part, §13.3.13 View Properties Part; поиск: `grep -n "^13\.3\.[0-9]" ../ooxml/ecma376-part1-5th.md`.
|
||||
- **Семантика элементов `p:`** — там же §19 «PresentationML Reference Material» (прямо в начале: «as defined by §13 of this Part»): §19.2 Presentation Properties (19.2.1 Presentation Properties, 19.2.2 View Properties), §19.3 Slides (19.3.1 Slides, 19.3.2 Embedded Objects, 19.3.3 Programmable Tags), §19.4 Comments, §19.5 Animation, §19.6 Slide Synchronization Data, §19.7 Simple Types; поиск: `grep -n "^19\.3" ../ooxml/ecma376-part1-5th.md`. Схема — `../ooxml/schema/transitional/pml.xsd` (она же в `../ooxml/schema/strict/`), общая разметка шейпов/текста — `dml-main.xsd`, `shared-*.xsd`.
|
||||
- **Рисунки/шейпы, чарты, SmartArt, пресет-геометрия** — те же источники, что у chart-движка конвертера: §21.2 (чарты `c:chart`), §21.3 (`c:drawing`), §21.4 (`dgm:`) + `dml-chart.xsd`/`dml-diagram.xsd`, пресеты `a:prstGeom` — Annex D; расширения Office — `../ooxml/ms-odrawxml.md`. Подробности — `../ooxml/README.md`.
|
||||
- **Поведение PowerPoint (что он реально пишет)** — `../ooxml/ms-oi29500.md` §3.3 PowerPoint (бинарные части-наследники: Legacy Diagram Text, SmartTags и т. п.) и §2.1.2 «Part 1 Section 8.6, PresentationML». Внимание: внутренние ссылки MS-OI29500 — по нумерации ISO/IEC-29500-1; она совпадает с репозиторной копией ECMA для частей (§13.3.8 Slide), но ссылки вида «Part 1 Section 8.6» в ECMA-376 5-го издания — это §13 (части) и §19 (элементы).
|
||||
- **Валидация `.pptx`-фикстур** — готового скрипта нет; при необходимости — по образцу `../docx/validate-fixtures.py`, только с корневым элементом `p:presentation`/`p:sld` против `../ooxml/schema/transitional/pml.xsd`.
|
||||
Reference in New Issue
Block a user