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:
Pjandro
2026-11-22 21:39:08 +03:00
parent ae7c8b755a
commit b3511f8b74
27 changed files with 1616 additions and 0 deletions
+40
View File
@@ -0,0 +1,40 @@
# Ограничения рендера
Конвертер **не является pixel-perfect рендером Word**: часть расхождений —
неустранимые невозможности связки docx4j + Apache FOP, а не упущения проекта.
## Что конвертируется приближённо
- Раскладка, поля и некоторые эффекты могут отличаться от Word (ограничения
FOP/docx4j по построению).
- Символы U+2000–U+2EFF (тире, кавычки): из шрифта рана, если в нём есть глиф,
иначе — из fallback-семейства DejaVu.
- Знаков, которых нет ни в одном шрифте бандла, это не касается: вместо них
остаётся `.notdef` (пустой бокс). В эталонном наборе таких два: U+2188 (ↈ) и
U+218A (↊) — глифы есть только в GNU FreeSerif под GPL, а бандл держится целиком
на SIL OFL.
- Поддержка таблиц/изображений — базовая (уровень docx4j/FOP).
- На `.doc` error-флаги диаграмм/SmartArt/OLE не срабатывают: BLIP-плейсхолдеры
бинарного формата — уже растры (вставляются картинками), EMF/WMF/PICT пропускаются
с warn — [Мост .doc](doc-bridge.md).
## Стоп-лист «не чинить»
До любой попытки «починить» расхождение с Word — сверьтесь со списком: это
невозможности движка, попытка фикса хуже самого расхождения.
|Конструкция|Что происходит|Почему не чинится|
|---|---|---|
|`w:jc="distribute"`|рендерится как left|межсимвольного распределения в FOP нет; `text-align-last` в форке отсутствует|
|`w:suff="tab"`|игнорируется (label через hanging-tab)|нужна per-item ширина; совпадает с поведением docx4j|
|`w:lvlJc`|игнорируется|—|
|кернинг|не применяется|—|
|`framePr` (обтекание)|не поддерживается|—|
|кэш полей `REF`/`SEQ`/`TOC`|печатается кэш из docx|живой пересчёт вне контура (`PAGE`/`NUMPAGES`/`PAGEREF`/`DATE` — пересчитываются)|
|руби (надстрочница)|надстрочная часть вырезается, база печатается|ruby-разметки в FOP нет; потеря текста хуже потери аннотации|
|`ptab`|не поддерживается|—|
|U+2188/U+218A|`.notdef`|GPL-шрифты не добавляем намеренно|
|`lineRule="auto"`|—|не «чинить»: метрический шаг пинен тестом|
Полный перечень с доказательствами по ECMA-376 —
[render-limitations.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/render-limitations.md).