Files
java-word-pdf/AGENTS.md
T
Pjandro 0c10bae3cf docx4j 11.5.3 -> 17.3.0: формулы OMML, колонки и постобработка XSL-FO
17.x приносит WordLayoutFixups (постобработка DOM XSL-FO: columnBreaks,
lineBoxAttributes, stripHints и др.) и jeuclid-fop, поэтому начинают
работать две вещи, которых не было: формулы m:oMath (на стр. 4 эталона
формула молча исчезала) и w:cols/@w:num (две колонки на стр. 9-11).
Сходимость текста references/word.docx с экспортом Word 0,848 -> 0,981,
средний постраничный пиксельный diff 10,5% -> 7,4%.

Что пришлось починить по пути:

* docx4j навешивает на fo:inline fox:gsub-features, не объявляя префикс
  fox. FO становится некорректным XML, WordLayoutFixups не парсит его и
  молча отказывается от всех фикс, а оставленный хинт docx4j-baseline
  отвергает уже FOP. Отключаем генерацию через
  docx4j.convert.out.fo.gsubFeatures=false.

* FOP теперь форк org.docx4j:docx4j-fo-renderer*, и его
  META-INF/services/org.apache.fop.fo.ElementMapping лежит ещё и в
  docx4j-export-fo: в fat-jar без ServicesResourceTransformer второй файл
  перезаписывает первый, FOP не узнаёт namespace fo: и падает на
  UnknownXMLObj. Тесты этого не видят — они идут по classpath.

* addPhysicalFont не перезаписывает занятый ключ реестра: системный
  DejaVuSerif.ttf занимает «dejavu serif» и наш DejaVuSerif-Regular.ttf
  не регистрировался. BundledFonts.init() чистит реестр до регистрации.

* Fop.Renderers.getRenderer() теперь список w:renderer по mime —
  FopFallbackFonts ищет application/pdf.

Em-dash (U+2000-U+2EFF) остался на шрифте ранa, если в нём есть глиф —
так же делает Word (в references/word.pdf em-dash нарисован Calibri/Times,
DejaVu нет вообще), поэтому тест проверяет «вшитый шрифт, не Helvetica»,
а не конкретное семейство.
2026-10-05 21:48:23 +00:00

67 lines
18 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.
# AGENTS.md
Конвертер docx → PDF на чистом Java (docx4j + Apache FOP, без LibreOffice/Aspose). Java 17, только Maven. Модули: `wordpdf-core` (библиотека), `wordpdf-cli` (fat-jar через maven-shade).
## Сборка
- `mvn clean verify` — все модули + тесты; единственный гейт перед `git push` (lint/typecheck/CI в репозитории нет).
- `mvn -pl wordpdf-cli package` — только fat-jar `wordpdf-cli/target/wordpdf-cli-1.0.0.jar`.
- `dependency-reduced-pom.xml` — артефакт shade, уже в .gitignore, не коммитить.
## Тесты
- JUnit 5, без внешних сервисов, headless (surefire уже задаёт `-Djava.awt.headless=true`).
- Один тест: `mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#ruPlain_regularRunsUseRegularFont`.
- Тесты `wordpdf-cli` зависят от test-jar `wordpdf-core` (classifier `tests`): сборка `-pl wordpdf-cli` без `-am` не пройдёт — либо строить из корня, либо `-am`.
- Тестовые `.docx` коммитятся в `wordpdf-core/src/test/resources/samples/`; тесты их не генерируют.
Пересоздать — одноразовой утилитой `SampleDocxGenerator` (команда в javadoc класса); POI — только test scope.
- `BundledFontsTest` проверяет синхронность списка `ENTRIES` с реальными TTF в `resources/fonts/`: новый шрифт = файл + `Entry`, иначе тест красный.
## Эталон в references/
- 11-страничный документ (текст, таблицы, колонтитулы, 3 диаграммы + SmartArt, формулы) со своим эталонным PDF, экспортированным из Word 365:
`word.docx` + `word.pdf` — Transitional OOXML (`schemas.openxmlformats.org/.../2006/...`).
- `references/` — материалы для ручного сравнения с Word, не тестовые фикстуры: в тесты и в jar их не подключать (фикстуры — `wordpdf-core/src/test/resources/samples/`).
## Шрифты (важно при изменениях)
- 28 TTF в `wordpdf-core/src/main/resources/fonts/` — бинарные фикстуры, часть jar; не удалять/переименовывать без обновления маппинга.
- Алиасы MS→open-source: Calibri→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; fallback — DejaVu Sans.
- `slf4j-simple` обязателен: без него docx4j печатает предупреждение прямо в выходной PDF (регрессионный тест `noLoggingWarningInPdf`).
- Символы U+2000–U+2EFF (em-dash, кавычки, многоточие): `RunFontSelector.symbolBlockFont` оставляет шрифт ранa, если в нём есть этот глиф, и только иначе подставляет виртуальный «Segoe UI Symbol» (маппится на fallback DejaVu Sans, см. `BundledFontMapper`). Так же делает Word: в `references/word.pdf` em-dash нарисован Calibri/Times, DejaVu там нет вообще. Регрессия — `ruPlain_emDashEmbeddedNotHelvetica` (проверяет, что глиф рисует **вшитый** шрифт, а не базовый Helvetica).
## Архитектура (неочевидное)
- Пайплайн: байты docx → `DocxOnOffNormalizer` → `SymbolFontNormalizer` → `FieldNormalizer` → docx4j → XSL-FO (XSLT) → FOP → PDF.
- Поля страниц: Word пишет `PAGE`/`NUMPAGES` сложным полем (`fldChar begin` → `instrText` → `separate` → кэш → `end`). Экспорт docx4j в FO `w:instrText` внутри такого поля игнорирует и печатает кэш docx — во всех колонтитулах одно число (в эталоне «2» вместо 1, 2, 3 …). `FieldNormalizer` разворачивает поле в `w:fldSimple` (его обрабатывает `FldSimpleWriter` из docx4j-export-fo: PAGE → `fo:page-number`, есть также NUMPAGES/SECTIONPAGES/PAGEREF), сохраняя внутри закэшированные ран — они дают шрифт/размер. Штатный `FieldsCombiner` docx4j делает то же, но не заходит внутрь `w:sdt`, а Word держит нумерацию именно в контентном контроле («Page Numbers (Top of Page)»). Трогаются только инструкции, для которых есть обработчик; вложенные поля пропускаются. Регрессия — `WordPdfConverterTest#pageNumbers_recomputedNotCached`, фикстура `samples/page-numbers.docx`.
- Символьные шрифты: Word хранит маркеры списков и спецсимволы кодами из PUA (U+F0xx), глиф выбирается по имени шрифта (`Symbol`, `Wingdings`, `Webdings`). Экспорт docx4j в FO этих шрифтов не знает: код уходит в fallback, глифа нет, FOP рисует `.notdef` — в PDF решётка «#». `SymbolFontNormalizer` (шаг 1.6, тоже правит байты до JAXB) меняет код на Unicode, а имя шрифта — на `DejaVu Sans`. Таблица кодов — `SymbolMapper` из docx4j 17.x, отфильтрована по наличию глифа в DejaVu; константы сгенерированы, менять руками нельзя. Обрабатываются `w:lvl` (numbering.xml), `w:r` и `w:sym`; ран с `w:sym` разрезается, т.к. у символа собственный `w:font`. Регрессия — `WordPdfConverterTest#symbolFonts_bulletsAreNotHash`, фикстура `samples/symbol-bullets.docx`.
- Порядок инициализации в `WordPdfConverter.convertToStream` важен: сначала `new BundledFontMapper()`, потом `BundledFonts.init()`, затем `BundledFonts.restrictToBundled()` (чистит реестр `PhysicalFonts` от системных шрифтов до `load()`; конструктор маппера каждый раз заново добавляет их). Не менять местами.
- docx4j 17.x по-прежнему теряет атрибуты `w:val="off"/"on"` при JAXB-разборе — нормализация байтов до загрузки (`DocxOnOffNormalizer`) нужна и на 17.x (проверялось отключением: красный `ruPlain_regularRunsUseRegularFont`).
- Ключ реестра `PhysicalFonts` — имя шрифта, и `addPhysicalFont(URI)` **не перезаписывает** занятый ключ. Системный `DejaVuSerif.ttf` занимает «dejavu serif», и наш `DejaVuSerif-Regular.ttf` (то же имя) не добавился бы — `BundledFonts.init()` перед регистрацией вызывает `dropNonBundled()`.
- **`docx4j.convert.out.fo.gsubFeatures=false`** ставится в статическом блоке `WordPdfConverter` — критично. Иначе docx4j навешивает на `fo:inline` атрибут `fox:gsub-features`, не объявляя префикс `fox`; FO становится некорректным XML, `WordLayoutFixups` не может его разобрать, молча отказывается от всех фикс и оставляет хинты `docx4j-baseline`, которые FOP отвергает (`Invalid property encountered on "fo:block": docx4j-baseline`). Без фиксов нет ни колонок, ни колонок таблиц.
- `WordLayoutFixups` (включён по умолчанию в 17.x) — постобработка DOM XSL-FO: `columnBreaks` (реально работают `w:cols/@w:num`, 2 колонки на стр. 9–11 эталона), `disregardBaselineShifts`, `lineBoxAttributes`, `stripHints` и др. Побочный эффект: авто-ширины колонок таблиц без `tblGrid`/`tcW` стали уже (слово может перенестись внутри ячейки) — в `tableImage_tableAndImage` сравнение нормализовано по пробелам.
- Формулы OMML (`m:oMath`) рисует `jeuclid-fop`, который в 17.x пришёл вместе с `docx4j-export-fo` — отдельного кода не требуется (в 11.5.3 формула молча исчезала).
- **`ServicesResourceTransformer` в maven-shade (`wordpdf-cli`) обязателен**: `META-INF/services/org.apache.fop.fo.ElementMapping` лежит и в `docx4j-fo-renderer-core`, и в `docx4j-export-fo`; без слияния второй перезаписывает первый, FOP не узнаёт namespace `fo:` и падает на `UnknownXMLObj cannot be cast to Root`. В fat-jar это не видно из тестов — тесты идут по classpath, проверять `java -jar`.
- FOP в 17.x — форк `org.docx4j:docx4j-fo-renderer*` (пакеты `org.apache.fop.*`), он знает хинты `docx4j:baseline`/`docx4j:line-box` через `WordLayoutElementMapping`. `Fop.Renderers.getRenderer()` теперь возвращает **список** `w:renderer` (по mime) — `FopFallbackFonts.rendererFonts` ищет `application/pdf`.
- Диаграммы: `docx2fo.xslt` умеет только `a:graphicData/pic:pic`, для `c:chart` и `dgm:relIds` там `notImplemented` (объект молча исчезает). Поэтому `DrawingPreRenderer.run(pkg)` (шаг 3.5 в `convertToStream`, после `setFontMapper` и до `FOSettings`) рендерит их своим Java2D-движком в PNG 300 dpi (`internal/chart/*`) и подменяет на `pic:pic`. Тест `chartsSmartArt_drawingsBecomeImages`, фикстура `samples/charts-smartart.docx`.
- В `DrawingPreRenderer` нужны собственные rels части — `part.getRelationshipsPart()` (`Base`), а **не** `getOwningRelationshipPart()`: у `document.xml` последнее указывает на пакетный `.rels`. Обход `pkg.getParts()` — только по снимку списка: `createImagePart` докидывает части в тот же реестр.
- SmartArt рисуется из `word/diagrams/drawing1.xml` (кэш разложенной Word-ом схемы: абсолютные позиции + `prstGeom`); текст-заполнители (`[Текст]`) лежат в `data1.xml` на `dgm:pt type="node"`, а формы ссылаются на `dgm:pt type="pres"` — связь через `dgm:cxn type="presOf"`.
- `surface3D` (`Surface3dPainter`): перспективная проекция (`c:view3D/perspective`, по умолчанию 30°, и `depth`), грани — ровно ячейки сетки по 2 треугольника без передискретизации, цвет из `c:bandFmts` затемняется по нормали грани (Lambert). Грани рисуются в модельно-экранных координатах уже умноженными на `scale/off` — забыть масштаб значит нарисовать поверхность в субпиксельный ноль.
- Знак `rotY` в DrawingML обратный правому правилу вокруг вертикали: в `Surface3dPainter.paint` он берётся как `-Math.toRadians(spec.rotY)`. Иначе передняя кромка категорий идёт вверх вправо, а ось рядов — вниз вправо (зеркально Word).
- `c:view3D/perspective` — НЕ угол обзора камеры. Расстояние камеры в `Surface3dPainter` = `CAMERA_DISTANCE * (30/perspective)`, где `CAMERA_DISTANCE = 2.36` (эффективный `fov ≈ 49°`, подобран фитом по эталону Word). При наивном `fov = perspective` перспектива слишком слабая: ось рядов уходит вправо вместо почти вертикального ухода в глубину, лента выглядит плоской, а левый край схлопывается в точку.
- Пропорции «коробки» surface3D (`DEPTH_RATIO = 0.705`, `HEIGHT_RATIO = 0.664`): глубина = 0.705 ширины (от неё `c:view3D/depth`), высота значений = `0.664 * availH/availW`, вписывание в область построения — равномерным масштабом. Раздельный масштаб x/y (или куб 1×1×1) даёт вертикальную гору вместо плоской ленты.
- Поля вокруг коробки — доли области построения `GUTTER_LEFT = GUTTER_RIGHT = 0.1485`, `GUTTER_TOP = 0.116`, `GUTTER_BOTTOM = 0.146`; `offX`/`offY` обязаны включать левое и верхнее поле (без `topGutter` поверхность сидела на 22 pt выше эталона). Коробка занимает ~70% ширины: при полях «на глаз» поверхность растягивалась на 82% и лезла на подписи оси значений.
- Калибровка камеры, коробки и полей зафиксирована тестами `Surface3dPainterTest.cameraMatchesWordReference` и `surfaceSilhouetteMatchesWordPlacement`. Эталон — стр. 3 `word-export.pdf` (экспорт Word), растеризованная `pdftoppm -r 300`; цели замеряются по **связному блоку граней** (серые грани в силуэт входят, по одной лишь насыщенности силуэт недомерен на 7%), пунктиру переднего ребра пола и подписям осей: уклон передней кромки 0,1282, аспект силуэта 0,207, шаг оси значений 0,0504, вертикальный шаг оси рядов 0,1176 (все — относительно ширины силуэта); сам силуэт 314,9×65,3 pt с центром в (227,3; 82,3). Замеры по скриншотам давали вдвое завышенную ось рядов и раздували глубину.
- Нормаль грани считается в той же метрике, что и проекция: `v` умножается на `depthScale`, `w` уже умножен на `hScale`. Без масштаба в нормали поверхность кажется положе и все грани уходят в светлую часть Lambert.
- Затенение граней surface3D — Lambert `0.92 + 0,88·dot` с клампом `[0,80; 1,25]` и боковым светом `LIGHT = (0,83, 0,48, 0,28)`. Дискретные множители эталона (гистограмма цветов граней, 300 dpi) — 0,40 / 0,75 / 0,85 / 1,04 / 1,06 / 1,10; группа 0,40 — узкая полоска underside под передним краем, и разгон Lambert до неё (отрицательные dot) по всем граням ухудшает совпадение с эталоном (17,2 → 17,6 средних расхождений на пиксель), поэтому нижний кламп 0,80. Направление света перебрано по 120 направлениям — текущее лучшее. Тест `shadingMatchesWordRange`.
- Триангуляция ячейки — диагональ с **большей суммой значений** (`z[r][c] + z[r+1][c+1] >= z[r+1][c] + z[r][c+1]` → `w00–w11`, иначе `w01–w10`), то есть верхняя огибающая седла. Фиксированная диагональ невозможна: у седловой ячейки одна вершина попадает внутрь треугольника остальных трёх, и при «не той» диагонали второй треугольник становится невидимой щепкой, а видимая грань окрашивается не той полосой. Проверено по эталону (стр. 3 `word-export.pdf`, 300 dpi, сравнение полос по пикселям; ячейка Ряд 1→2 / Категория 2→3): верхняя огибающая 92,3 % совпадений полос, фиксированная `w00–w11` — 81,6 %, фиксированная `w01–w10` — 57,9 %, окраска целого квада без разрезки — 74,1 %, билинейная tessellation 3×3/6×6 — 67,8 %/66,0 %. Регрессия — `Surface3dPainterTest.saddleCellUsesHigherDiagonal` (нижняя кромка силуэта в окне 0,42…0,55 его ширины обязана быть полосы 3–4). Клиппинг полос — по треугольникам, не по кваду.
- Пустой `c:title` при `c:autoTitleDeleted val="0"` даёт автозаголовок `Chart Title` (`ChartSpec.AUTO_TITLE`); для круговых (`pie`/`pie3D`/`doughnut`) вместо него — имя ряда. Тесты `ChartSpecTest`.
- В кваде ячейки `w01` обязан быть `z[r+1][c]`, а `w10` — `z[r][c+1]` (u=категория, v=ряд). Перестановка закручивает квад в «бабочку»: дыры и самопересечения граней.
- `ChartRenderer.axisBounds` для линейной оси значений без явного `c:min` всегда поднимает нижнюю границу до 0 (как Word); от этого зависит и легенда полос surface3D (`0-1 … 4-5`, а не `1-2 … 4-5`). Юнит-тесты — `Surface3dPainterTest`.
- Не убирать shade-фильтры `META-INF/*.SF|*.DSA|*.RSA` — подписанные jar-файлы зависимостей ломают fat-jar.
## Точка входа
- Библиотека: `WordPdfConverter.convert(Path)` / `convert(Path, Path)` — статический stateless-класс; ошибки — `ConversionException`.
- CLI: `WordPdfCli` (fat-jar, Main-Class в манифесте). Коды возврата: 0 успех, 1 ошибка использования, 2 не конвертирован хотя бы один файл.