Files
java-word-pdf/AGENTS.md
T
Pjandro 2d446d783c Шрифты: restrictToBundled() чистит реестр PhysicalFonts от системных перед load()
Конструктор BundledFontMapper каждый раз заново обнаруживает системные
шрифты; на Windows найденный Calibri покрывает U+2000-U+2EFF, и
RunFontSelector оставляет em-dash на Carlito вместо fallback-DejaVu
(красный ruPlain_emDashEmbeddedNotHelvetica). Очистка реестра после
init() и до load() делает вывод одинаковым на любой ОС; шрифты,
встроенные в docx, регистрируются при load() и остаются в реестре.
2026-10-02 19:51:24 +00:00

4.1 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, иначе тест красный.

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

  • 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, кавычки, многоточие) рендерятся DejaVu Sans, а не шрифтом ранa — по дизайну; виртуальный «Segoe UI Symbol» мапится на fallback.

Архитектура (неочевидное)

  • Пайплайн: байты docx → DocxOnOffNormalizer → docx4j → XSL-FO (XSLT) → FOP → PDF.
  • Порядок инициализации в WordPdfConverter.convertToStream важен: сначала new BundledFontMapper(), потом BundledFonts.init() (бандл-шрифты регистрируются поверх системных), затем BundledFonts.restrictToBundled() (чистит реестр PhysicalFonts от системных шрифтов до load(); конструктор маппера каждый раз заново добавляет их, и GlyphCheck на Windows находит системный Calibri — em-dash остаётся на Carlito, красный ruPlain_emDashEmbeddedNotHelvetica). Не менять местами.
  • docx4j 11.x теряет атрибуты w:val="off"/"on" при JAXB-разборе — поэтому нужна нормализация байтов до загрузки (регрессионный тест ruPlain_regularRunsUseRegularFont).
  • Не убирать 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 не конвертирован хотя бы один файл.