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
+63
View File
@@ -0,0 +1,63 @@
# Шрифты
Конвертация не зависит от шрифтов системы: **30 TTF упакованы в jar**
`wordpdf-core/src/main/resources/fonts/`, выгружаются во временный каталог и
регистрируются в docx4j/FOP. Реестр шрифтов после каждой конвертации возвращается
к бандлу — шрифты, встроенные в чужие docx, не влияют на последующие документы.
`java.awt.Font` не используется (метрики и глифы — fontbox напрямую), поэтому
**fontconfig серверу не нужен**.
## Бандл
7 текстовых семейств по 4 начертания + 2 покрывающих (только regular):
|Семейство|Аналог MS-шрифта|Назначение|
|---|---|---|
|Carlito|Calibri|метрически совместимая замена|
|Caladea|Cambria|метрически совместимая замена|
|Arimo|Arial|метрически совместимая замена|
|Tinos|Times New Roman|метрически совместимая замена|
|Cousine|Courier New|метрически совместимая замена|
|DejaVu Sans / DejaVu Serif|—|fallback с гарантированной кириллицей|
|Noto Naskh Arabic|—|арабские дополнения U+07B1–U+08FF|
|Noto Sans Armenian|—|армянские знаки Unicode 16|
## Алиасы (`BundledFontAliases`)
Имена шрифтов из документа подменяются аналогами при конвертации:
|Имя в docx|Физический шрифт|
|---|---|
|Calibri|Carlito|
|Cambria|Caladea|
|Arial|Arimo|
|Times New Roman|Tinos|
|Courier New|Cousine|
## Fallback-цепочка
1. **Ран** идёт своим шрифтом (по `w:rFonts` + алиасам).
2. Знака нет в шрифте рана (тире «—», кавычки, U+2000–U+2EFF) — ран падает в
**DejaVu Sans** (FOP-фолбэк-семейства задекларированы всецело, шаг 4 конвейера).
3. Serif-раны ищут покрытие сначала в serif-семействах (DejaVu Serif, Tinos, Caladea).
4. Знака нет и там — `GlyphCoverageNormalizer` (правило 7) режет ран и каждой части
назначает покрывающее семейство: serif → DejaVu Serif, sans → DejaVu Sans,
экзотика → Noto.
5. Знака нет ни в одном шрифте бандла — остаётся `.notdef` (пустой бокс).
Все шрифты встраиваются в PDF как **подмножества** (кириллица и латиница
воспроизводятся на любом просмотрщике).
## Лицензии
|Шрифты|Лицензия|
|---|---|
|Arimo, Cousine, Tinos, Carlito, Caladea|SIL OFL 1.1 (`fonts/FONT-LICENSE.txt`)|
|DejaVu Sans / DejaVu Serif|SIL OFL 1.1 / Bitstream Vera (`fonts/DejaVu-LICENSE.txt`)|
|Noto Naskh Arabic, Noto Sans Armenian|SIL OFL 1.1 (`fonts/Noto-LICENSE.txt`)|
GPL-шрифты в бандл не добавляем намеренно (из-за этого два символа эталона —
U+2188/U+218A — остаются `.notdef`; см. [Ограничения](limitations.md)).
Новый шрифт = файл в `resources/fonts/` + запись в `BundledFonts.ENTRIES`
(синхронность проверяет `BundledFontsTest`).