Справочник
Справочные материалы отвечают на точечные вопросы: какой символ, какое значение, какой уровень поддержки, какой пункт спецификации. В этом разделе описана проверенная поверхность NextPDF: справочник по модулям, матрицы поддержки, поверхность API, справочник по ошибкам, соответствие стандартам и публикуемые проектом политики. Справочник не предназначен для пошагового решения задач: если нужно достичь цели, а не найти отдельный факт, используйте Руководства или Сборник рецептов.
Карта справочника
Заголовок раздела «Карта справочника»Движок Core
Заголовок раздела «Движок Core»Движок nextpdf/core, описанный по отдельным модулям.
| Страница | Для чего использовать |
|---|---|
| Справочник по ядру движка | Карта пространства имён: страницы модулей и четыре подсемейства. |
| Контракты: 41 публичный интерфейс (SPI) | Публичные интерфейсы и перечисления, для которых отслеживается стабильность. |
| Core: фасад Document и трейты-составляющие | Фасад Document и семейство трейтов Has*. |
| HTML: подсистема отрисовки HTML+CSS в PDF | Однопроходный потоковый отрисовщик HTML. |
| Безопасность: шифрование, криптополитика и поверхность подписания | Шифрование, разрешения и точки интеграции для подписания. |
Поддержка рендеринга
Заголовок раздела «Поддержка рендеринга»Какие возможности отрисовщик проверяет, декларирует, частично поддерживает или не поддерживает.
| Страница | Для чего использовать |
|---|---|
| Матрица поддержки CSS | Уровни поддержки Cascading Style Sheets (CSS) по каждой возможности в конвейере HTML. |
| Неподдерживаемые возможности CSS и обходные пути | Что не входит в область поддержки и что делать вместо этого. |
| Матрица поддержки шрифтов и письменностей | Технологии шрифтов и поддержка систем письма. |
| Поддержка вертикального письма CJK | Поддержка вертикального writing-mode для китайского, японского и корейского текста. |
| Поддержка компоновки сложных письменностей | Поддержка компоновки (shaping) для письменностей, которым она нужна. |
Поверхность API
Заголовок раздела «Поверхность API»Точные имена символов, допустимые значения и контракты сервисов.
| Страница | Для чего использовать |
|---|---|
| Справочник перечислений | Все публичные перечисления и допустимые для них значения. |
| Настройка TSA | Служба меток времени (TSA) по умолчанию и как её изменить. |
| Справочник по REST API Connect | Конечные точки REST для NextPDF Connect на основе документа OpenAPI 3.1. |
| Обозреватель API Connect | Интерактивный обозреватель того же контракта. |
Справочники API уровня пакетов размещены рядом с соответствующими пакетами: Справочник по API Connect, Указатель API для интеграций и Справочник по API Python SDK в разделе “Руководства”.
Справочник по ошибкам
Заголовок раздела «Справочник по ошибкам»Исключения, выбрасываемые движком, сгруппированы по доменам и снабжены структурированным контекстом и рекомендациями по восстановлению.
| Страница | Для чего использовать |
|---|---|
| Справочник по ошибкам | Модель исключений: базовый класс NextPdfException и контракт контекста. |
| Основные и общие ошибки | Ошибки жизненного цикла документа и общие сбои движка. |
| Ошибки рендеринга и ввода-вывода | Сбои HTML, шрифтов, писателя и читателя. |
| Ошибки безопасности и подписания | Сбои шифрования, подписания и PKI. |
| Ошибки среды выполнения и поддержки | Сбои HTTP, отказоустойчивости и наблюдаемости. |
| Ошибки Accelerator | Сбои опционального сайдкара для ускорения. |
| Ошибки соответствия | Сбои валидации и инструментов проверки соответствия. |
Соответствие стандартам
Заголовок раздела «Соответствие стандартам»Профили стандартов, на которые ориентируется NextPDF Core; для каждого явно обозначена граница: движок формирует вывод, рассчитанный на соответствие, а само соответствие определяет внешний валидатор.
| Страница | Для чего использовать |
|---|---|
| Соответствие стандартам | Позиция проекта по соответствию и указатель профилей. |
| Соответствие PDF 2.0 | Базовый уровень ISO 32000-2, на который ориентирован движок. |
| Соответствие PDF/A-4 | Соответствие для архивирования и Карта пунктов PDF/A-4. |
| Соответствие PDF/UA-2 | Соответствие для доступности и Карта пунктов PDF/UA-2. |
| Соответствие PDF/X | Соответствие для печатного производства. |
| Карта пунктов PAdES | Сопоставление базовых профилей ETSI EN 319 142 для подписей PDF. |
| Соответствие ZUGFeRD / Factur-X | Соответствие для гибридных электронных счетов. |
Центр доверия
Заголовок раздела «Центр доверия»Инженерная позиция по движку Core и границы каждого утверждения.
| Страница | Для чего использовать |
|---|---|
| Центр доверия | Указатель позиций. |
| Лицензирование продукта | Условия лицензирования открытого ядра и коммерческих редакций. |
| Товарный знак и использование бренда | Как можно использовать имя и знаки NextPDF. |
| Обработка данных, PII и телеметрия | Что движок читает, хранит и передаёт. |
| Модель безопасности для подписи и шифрования | Криптографическая модель и её ограничения. |
| Модель угроз для движка | От чего движок защищает, а от чего нет. |
| Политика раскрытия уязвимостей | Как сообщить об уязвимости. |
Проект и релизы
Заголовок раздела «Проект и релизы»| Страница | Для чего использовать |
|---|---|
| Список изменений | Что изменилось в каждом релизе. |
| Соглашения для журнала изменений | Как оформляются и классифицируются записи журнала изменений. |
| Версионирование, стабильность, объявление устаревшим и политика поддержки | Гарантии совместимости между релизами. |
| Как устроена документация NextPDF | Структура этого набора документации и управление им. |
Глоссарий
Заголовок раздела «Глоссарий»Глоссарий — термины этой документации, определённые один раз для повторного использования во всём наборе.
Контракт справочной статьи
Заголовок раздела «Контракт справочной статьи»Каждая статья об API должна отвечать на один и тот же набор вопросов:
| Вопрос | Обязательный ответ |
|---|---|
| Что вызывать? | Полностью квалифицированное имя символа, конечная точка, команда интерфейса командной строки (CLI) или ключ конфигурации. |
| Какие входные данные принимаются? | Таблица параметров с типом, обязательностью, значением по умолчанию и допустимыми значениями. |
| Что происходит по умолчанию? | Поведение, если необязательные входные данные не указаны. |
| Что возвращается? | Тип возвращаемого значения, тело ответа, выходной файл, поток или побочный эффект. |
| Что может пойти не так? | Исключение, ошибка проверки, статус HTTP или режим отказа во время эксплуатации. |
| Как использовать это безопасно? | Замечания о безопасности, безопасной работе в воркерах, ограничениях размера, путях, тайм-аутах и обработке секретов. |
Политика охвата
Заголовок раздела «Политика охвата»Справочные страницы по API и поведению опираются на исходный код. Публичные API документируются на основе исходного кода пакета, файлов конфигурации, тестов и примеров. Внутренние вспомогательные классы документируются только тогда, когда разработчикам приложений нужно понимать их поведение для настройки или эксплуатации пакета.
Готовность к переводу
Заголовок раздела «Готовность к переводу»На справочных страницах предпочтительны таблицы, а не плотные абзацы. Каждая строка должна быть самодостаточной: при последующей сегментации в формате Extensible Localization Interchange File Format (XLIFF) содержимое будет разбито на блоки.