- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
4.7 KiB
Мост .doc → .docx
Бинарный формат Word 97–2003 читается собственным мостом без внешних
зависимостей (POI остаётся test-scope): байты .doc парсятся по спецификациям
[MS-DOC] (сам документ) и [MS-CFB] (OLE2-контейнер), собираются in-memory
.docx — и дальше идут тем же конвейером, что и обычные docx.
Точка входа
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 (репозиторий).