docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
This commit is contained in:
@@ -0,0 +1,61 @@
|
||||
# Мост .doc → .docx
|
||||
|
||||
Бинарный формат Word 97–2003 читается **собственным мостом** без внешних
|
||||
зависимостей (POI остаётся test-scope): байты `.doc` парсятся по спецификациям
|
||||
**[MS-DOC]** (сам документ) и **[MS-CFB]** (OLE2-контейнер), собираются in-memory
|
||||
`.docx` — и дальше идут тем же конвейером, что и обычные docx.
|
||||
|
||||
## Точка входа
|
||||
|
||||
```java
|
||||
DocToDocx.convert(byte[] docBytes, long maxMb) // → байты .docx (вызывает WordPdfConverter)
|
||||
DocToDocx.countPages(byte[] docBytes) // → страницы по сырым байтам (вызывает валидатор)
|
||||
```
|
||||
|
||||
Страницы `.doc` считаются **по сырым байтам до конвертации** (PageCount из
|
||||
SummaryInformation, разрывы 0x0C, межсекционные разрывы, `pageBreakBefore`) —
|
||||
тот же скан используется валидатором лимита страниц. Любой брак (не-CFB, шифрованный
|
||||
документ, Word 6–95) → `ConversionException` (в REST — 400).
|
||||
|
||||
## Классы пакета `internal/doc` (18 top-level)
|
||||
|
||||
|Класс|Спецификация|Что делает|
|
||||
|---|---|---|
|
||||
|`CfbReader`|[MS-CFB] §2.2–2.6|FAT/DIFAT/miniFAT, directory; бюджеты против враждебного FAT, любой брак → `ConversionException`|
|
||||
|`FibHeader`|[MS-DOC] §2.5.1|заголовок FIB: потоки 1Table/0Table, пары fc/lcb нужных индексов, сверка раскладок по nFib|
|
||||
|`PieceTable`|§2.9.135|текст: куски CP1252/UTF-16LE, клампинг к `cbMac`, проверка aCP|
|
||||
|`Grpprl`|§2.6.2|свойства форматирования (sprm'ы): bold/italic/шрифт/цвет/подсветка/заливка/отступы/табуляции|
|
||||
|`ChpxIndex` / `PapxIndex`|§2.4.6|FKP-страницы символьных/абзацных свойств|
|
||||
|`Styles`|§2.9.271|STSH: стилевые цепочки абзацев и символов (stk=1/2)|
|
||||
|`Tables`|§2.6.3|TAP TTP-абзаца → сетка, границы, выравнивание таблицы|
|
||||
|`Lists`|§2.9.200/.201|PlfLst/PlfLfo → `word/numbering.xml`|
|
||||
|`Sections`|§2.8.26|PlcfSed → геометрия секций, ориентация, нумерация страниц, `titlePg`|
|
||||
|`FontTable`|§2.9.286|SttbfFfn: индекс ftc → имя семейства|
|
||||
|`SummaryInfo`|[MS-OLEPS]|`\x01SummaryInformation`: в т.ч. PageCount|
|
||||
|`Headers`|§2.4.1|Plcfhdd: 6 колонтитуков на секцию → `headerN.xml`/`footerN.xml`|
|
||||
|`OfficeArt`|[MS-ODRAW]|картинки: BLIP-хранилище (JPEG/PNG/TIFF/DIB/EMF/WMF/PICT)|
|
||||
|`PrcData`|§2.9.210|разворачивание «огромных» grpprl, вынесенных за FKP-страницу|
|
||||
|`DocToDocx`|—|оркестратор + вложенный `DocxBody` (сборка document.xml)|
|
||||
|`DocxWriter`|—|мульти-частный zip: content-types, rels, numbering, headers, media|
|
||||
|
||||
17 из 18 классов package-private; наружу — только `DocToDocx`.
|
||||
|
||||
## Модель деградации (не падение)
|
||||
|
||||
|Объект в .doc|Поведение|
|
||||
|---|---|
|
||||
|OLE-внедрения (U+0001 в тексте)|плейсхолдер заменяется его же BLIP-картинкой|
|
||||
|картинки JPEG/PNG/TIFF/DIB|переносятся дословно / через ImageIO в PNG|
|
||||
|EMF/WMF/PICT|пропуск с warn (векторные растеризаторы не в контуре)|
|
||||
|битые/неподдерживаемые конструкции|снисходительный разбор, объект исчезает или упрощается — текст не теряется|
|
||||
|
||||
Поэтому **error-флаги (`errorOnCharts`/`errorOnSmartArt`/`errorOnOle`) на `.doc` не
|
||||
срабатывают**: OLE-вложения бинарного формата — это U+0001 с BLIP-плейсхолдером,
|
||||
мост деградирует их в картинки, «OLE-объектов» в смысле docx-пути в результате нет.
|
||||
|
||||
## Сознательный остаток
|
||||
|
||||
Семантика рестартов списков (`fNoRestart`/`ilvlRestartLim`), `fLegal`,
|
||||
AUTONUM-поля (трактуются как обычные списки), часть тонкостей объединённых ячеек —
|
||||
осознанные упрощения вне контура; полный перечень —
|
||||
[doc-bridge.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/doc-bridge.md).
|
||||
Reference in New Issue
Block a user