Files
java-word-pdf/AGENTS.md
T
Pjandro ae31f27a27 Экзотические глифы: решётка «#» вместо .notdef
Знак без глифа в шрифте ранa FOP рисовал .notdef — в эталонном
references/word.docx таких оставалось 28.

- Noto Naskh Arabic и Noto Sans Armenian (SIL OFL, 278 КБ) в бандле:
  FontFallback.selectCovering перебирает весь реестр PhysicalFonts и
  находит их сам — арабские дополнения и армянские Unicode 16 рисуются
  без нашего кода.
- GlyphCoverageNormalizer режет ран по покрытию глифов и пишет семейство
  в w:rFonts. Нужен из-за двух дыр docx4j: needsCoverage=false для
  «латинской» группы (римские цифры U+2150–U+218F) и кэш fallbackByScript
  на всю группу Юникода (армянские U+058D/U+058E получали DejaVu Serif).
- FopFallbackFonts.declare декларирует все бандл-семейства: FOP встраивает
  только задекларированные, а font-family в FO может запросить любое.

В эталоне осталось 2 решёток: U+2188 и U+218A есть только в GNU FreeSerif
(GPL-3+ с Font Exception), которого в бандле нет намеренно.
2026-10-05 22:29:10 +00:00

21 KiB
Raw Blame History

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/).

Шрифты (важно при изменениях)

  • 30 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.
  • Noto Naskh Arabic и Noto Sans Armenian (OFL, 278 КБ) добавлены ради глифов, которых нет больше ни в одном шрифте бандла (арабские дополнения U+07B1–U+08FF, армянские U+058D/U+058E). Регистрировать их в BundledFontMapper не требуется: FontFallback.selectCovering перебирает весь реестр PhysicalFonts и находит их сам — достаточно BundledFonts.ENTRIES. У них только regular-начертание (BundledFonts.families() это учитывает, allFamiliesHaveAllVariants их не проверяет).
  • FopFallbackFonts.declare декларирует в FOP-конфиге все бандл-семейства, а не один fallback: FOP умеет встраивать только задекларированные, а font-family в FO может запросить любой из них.
  • 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 → GlyphCoverageNormalizer → 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.
  • Покрытие глифов: знак без глифа в шрифте ранa FOP рисует .notdef («#»). Docx4j 17.x сам ищет покрывающий шрифт (FontFallback.selectCovering по реестру PhysicalFonts), но с двумя дырами: needsCoverage возвращает false для «латинской» группы (поэтому U+2150–U+218F — римские цифры и дроби — остаются на Tinos навсегда), а RunFontSelector.fallbackByScript кэширует фолбэк на всю группу Юникода (обычные армянские «ՊՌՋտ» покрываются DejaVu Serif, и найденный DejaVu Serif подставляется следующим за ними U+058D/U+058E). GlyphCoverageNormalizer (шаг 2.4, тоже байты до JAXB) режет ран по покрытию и пишет семейство в w:rFonts (имя — BundledFontMapper.documentFontName, обратное к bundledFamily). Покрытие меряется java.awt.Font.canDisplay через BundledFonts.awtFont (не GlyphCheck — тот логирует INFO на каждый отсутствующий глиф). Трогаются только раны с одним w:t и с явным w:rFonts; если знака нет ни в одном бандл-шрифте, ран не меняется. Регрессия — WordPdfConverterTest#exoticGlyphs_drawnNotHash, unit — GlyphCoverageNormalizerTest, фикстура samples/exotic-glyphs.docx.
  • Известный остаток эталона: U+2188 (ↈ) и U+218A (↊) — есть только в GNU FreeSerif (GPL-3+ с Font Exception), которого в бандле нет намеренно (весь бандл — SIL OFL). В references/word.pdf на их месте у нас две решётки; ради них OFL не меняют.
  • Символьные шрифты: 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 не конвертирован хотя бы один файл.