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
+62
View File
@@ -0,0 +1,62 @@
# Диаграммы, SmartArt, формулы
XSLT-экспорт docx4j диаграммы не умеет, поэтому `DrawingPreRenderer` (шаг 3.5
конвейера) **до** генерации XSL-FO заменяет `c:chart` / `dgm:relIds` / `m:oMath`
на PNG-картинки (`pic:pic`). Рендер — собственный Java2D-движок (`internal/chart`,
21 класс), без Word/LibreOffice/JEuclid; текст рисуется глифами fontbox (`GlyphFont`),
поэтому fontconfig серверу не нужен.
## Диаграммы
- Выход: PNG **300 dpi** (`ChartRenderer.DPI = 300`), размеры из `wp:extent` (EMU→pt).
- Поддерживаемые типы (`ChartSpec.Type`): `PIE`, `PIE3D`, `DOUGHNUT`, `BAR`,
`BAR_HORIZONTAL`, `LINE`, `AREA`, `SURFACE3D`, `AREA3D`, `BAR3D`, `LINE3D`,
`RADAR`, `SCATTER`, `BUBBLE`, `STOCK`, `OF_PIE`, `SURFACE` (+ `UNSUPPORTED`).
- **Combo** («Комбинированная», §21.2.2.145): несколько групп в одном plotArea
(bar+line/area), привязка по `c:axId`, вторичная ось значений справа; серии
масштабируются по своей оси.
- Стекинг `stacked`/`percentStacked` — ряды накопленной суммой.
- Геометрия/камера 3-D и пропорции откалиброваны по эталонным экспортам Word
(пиксельные тесты с допусками).
## Умные границы (враждебный XML)
|Бюджет|Значение|Поведение при превышении|
|---|---|---|
|`ChartRenderer.MAX_PIXELS`|16 777 216 (4096², 64 МБ ARGB)|`fitDpi` понижает эффективный dpi (24″-график: 300→≈171 dpi), геометрия не меняется|
|`ChartSpec.MAX_POINTS`|100 000|отказ **до** предвыделения списка|
|`ChartRenderer.MAX_TICKS`|1000|безумный шаг оси заменяется «красивым» 1/2/5·10ⁿ|
|`DrawingPreRenderer.MAX_EXTENT_EMU`|22 000 000 (≈24″)|объект **остаётся как есть** + warn (не удаляется)|
|бюджет chart/math-PNG на документ|128 MiB|объект удаляется + warn|
## Модель деградации
Битая/неподдерживаемая часть роняет не конвертацию, а объект:
|Ситуация|Исход|
|---|---|
|битая chart-часть / превышение бюджета PNG|объект удалён + warn|
|неподдерживаемая/битая OMML-формула|**текст** (конкатенация `m:t`) + warn — текст терять хуже|
|`wp:extent` вне диапазона/ноль|объект остаётся + warn (FOP молча потеряет)|
|`OutOfMemoryError`|не деградация — `ConversionException` (REST 500)|
## SmartArt
`SmartArtRenderer` рисует диаграмму по разметке [MS-ODRAWXML]/§21.4: узлы, макет,
связи; тот же DPI/`fitDpi`.
## Формулы OMML
Собственный растер: `MathModel` разбирает OMML (§22.1) в дерево боксов,
`MathRenderer` рисует его только бандл-шрифтами. Конструкции вне списка `SUPPORTED`
деградируют в текст ещё на шаге нормализации (правило 6). Inline-формула опускается
на нижний запас рана — FOP ставит инлайн-графику нижним краем на базу строки.
## Контрафт media-частей
PNG-части получают имена `/word/media/chart-N.png` (константа
`CHART_MEDIA_URI_PREFIX`); по этому префиксу `ChartImageHandler` отключает
пересжатие картинок в FOP — переименование молча вернёт «мыльный» ресемпл.
Глубина (пейнтеры, калибровки, спецификационные секции) —
[chart.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/chart.md).