SILE превращает размеченный текст и структурированные XML-данные в аккуратно сверстанные PDF: позволяет задавать страницы и колонки через фреймы, управлять шрифтами OpenType, переносами, формулами, сносками, оглавлением, библиографией и индексом, а при необходимости расширять обработку командами и модулями Lua.

Работа строится вокруг исходного файла: текст набирают в любом редакторе кода, сохраняют с разметкой SIL или XML, затем передают команде sile. Движок читает структуру документа, выбирает класс оформления, формирует строки и страницы, записывает PDF рядом с исходником и выводит в терминал номера обработанных страниц, предупреждения и точное место ошибки.

Вместо перетаскивания объектов мышью пользователь описывает смысл и геометрию макета: где расположен основной поток, какие поля и колонки нужны, каким шрифтом набраны заголовки, как ведут себя сноски и что делать при переходе на следующую страницу. Такой подход особенно полезен для книг, технической документации, многоязычных изданий, каталогов из XML и серийных документов, которые требуется собирать одинаково при каждом запуске.

Как устроен рабочий процесс в SILE

Минимальный проект состоит из текстового файла и ресурсов, на которые он ссылается: шрифтов, растровых изображений, SVG, библиографической базы и подключаемых модулей. Исходник удобно хранить вместе с ресурсами в отдельной папке. Тогда относительные пути остаются переносимыми, а сборка не зависит от текущего каталога пользователя. Результирующее имя по умолчанию строится из имени первого входного файла: например, book.sil превращается в book.pdf.

Запуск sile book.sil выполняет полный цикл: синтаксический разбор, загрузку класса, преобразование текста в узлы, формирование строк, распределение вертикального материала по фреймам и запись страниц. Если нужно другое имя, применяют параметр --output. Вывод в стандартный поток через дефис полезен в конвейерах, но для обычной работы проще сохранять PDF в файл и открывать его отдельным просмотрщиком.

Интерфейс терминала не показывает полосу инструментов или макет страницы. Вместо этого он сообщает, какой класс загружен, какие файлы прочитаны и какие страницы построены. Редактирование происходит в исходнике, поэтому практичный цикл выглядит так: изменить несколько строк, сохранить, повторить команду, обновить PDF в просмотрщике. Редакторы, умеющие запускать задачи по горячей клавише, сокращают этот цикл до одного действия.

\begin{document}
Hello SILE!
\end{document}

$ sile hello.sil

Этот пример создаёт страницу формата A4 с текстом в верхней части и номером страницы внизу. Он полезен не как шаблон полноценного издания, а как проверка трёх вещей: команда доступна в терминале, движок видит базовый шрифт и каталог проекта допускает запись выходного файла. Если простой документ собирается, дальнейшие ошибки обычно связаны уже с разметкой, классом или ресурсами конкретного проекта.

Исходный файл и синтаксис SIL

Основной формат разметки сочетает обычный текст и команды с обратной косой чертой. Команда без содержимого меняет состояние или выполняет действие, а команда с фигурными скобками применяет оформление к вложенному фрагменту. Опции записываются в квадратных скобках перед содержимым. Внешне синтаксис напоминает TeX, однако имена команд, система настроек и правила расширения у SILE собственные; механически переносить команды LaTeX нельзя.

Документ ограничивается парой \begin{document} и \end{document}. Обычные пустые строки разделяют абзацы. Специальные символы, которые участвуют в разметке, приходится экранировать либо выводить через подходящие команды. При большой вложенности полезно выравнивать блоки отступами: движку пробелы в начале строк обычно не нужны, но человеку так легче заметить пропущенную скобку или неправильно закрытое окружение.

Опции документа позволяют задать размер бумаги и ориентацию до начала набора. Класс может установить собственные значения, поэтому при неожиданном формате страницы сначала проверяют объявление документа и параметры класса. Для нестандартного листа важна единица измерения: SILE понимает типографские пункты и распространённые физические единицы, а сложные размеры допускают растяжимость и сжимаемость по модели типографского клея.

\begin[papersize=a5]{document}
\font[family=Gentium Plus,size=11pt]{
  Текст документа
}
\end{document}

Команды можно вкладывать, но лучше не превращать каждую строку в длинную цепочку ручного форматирования. Повторяющееся оформление выносят в макрос, пакет или класс. Тогда смысловая команда вроде \warning{...} остаётся стабильной, а внешний вид меняется в одном месте. Это особенно важно для документации и книг, где одинаковые элементы встречаются сотни раз.

В SIL есть окружения, удобные для блоков с собственной логикой: списков, формул, фрагментов кода и пользовательских конструкций. Окружение получает параметры при открытии, обрабатывает вложенное содержимое и корректно восстанавливает настройки после закрытия. Если шрифт или цвет неожиданно распространяется дальше нужного места, следует проверить, не была ли настройка изменена глобально вместо ограничения содержимым команды.

XML как входной формат

SILE способен читать XML непосредственно, если выбран класс или входной обработчик, который знает значения элементов. Это не простое превращение тегов в одноимённые команды: обработчик сопоставляет структуру данных с типографскими действиями. Например, заголовок XML может вызвать команду раздела, абзац — обычный набор, а элемент предупреждения — рамку, фон и специальный отступ.

В поставке есть класс для подмножества DocBook. Команда с параметром --class docbook нужна потому, что корневой тег чужой XML-схемы сам по себе не сообщает SILE, какой документный класс использовать. После выбора класса движок проходит дерево, обрабатывает поддерживаемые элементы и формирует PDF. Неподдерживаемый тег требует дополнительного правила, а не угадывается автоматически.

$ sile --class docbook manual.xml

XML удобен, когда содержимое уже поступает из базы, системы управления контентом или экспортера. Автору не приходится преобразовывать данные через XSL-FO либо генерировать промежуточный TeX. При этом сложность перемещается в класс: именно там описываются соответствия между элементами, стилями, фреймами и служебными действиями. Один хорошо продуманный класс затем обслуживает тысячи однотипных записей.

Проверять XML лучше до запуска набора. Невалидный документ с незакрытым элементом остановит разбор ещё до типографики, а формально валидный, но неизвестный классу тег может потерять смысл или вызвать ошибку обработчика. Для производственного конвейера полезно разделить проверки: сначала валидатор схемы, затем SILE, затем автоматический контроль числа страниц, наличия PDF и сообщений в журнале.

Классы документов и разделение содержания с оформлением

Класс задаёт основу издания: размер и геометрию страницы, обязательные фреймы, стандартный шрифт, расположение колонтитулов, нумерацию, команды заголовков и процедуру перехода между страницами. В простом документе подходит базовый класс, а книга нуждается в логике глав, разворотов, оглавления и разных шаблонов для начальной и обычной страницы.

Класс выбирается в разметке либо параметром командной строки. Второй способ нужен для входных форматов, у которых нет собственного объявления SILE. Если команда существует в одном классе и отсутствует в другом, документ, собранный с неверным классом, завершится сообщением о неизвестной команде. Поэтому класс следует считать частью проекта и фиксировать в сценарии сборки.

Настраивать книгу исключительно командами внутри текста неудобно: содержание начинает зависеть от размеров полей и координат. Класс позволяет хранить геометрию отдельно. Автор отмечает главу, раздел, эпиграф, подпись или основной текст, а класс решает, какой гарнитурой это вывести, где открыть новую страницу и как обновить оглавление. Изменение формата A5 на другой книжный формат тогда затрагивает преимущественно файл класса.

При разработке класса сначала создают минимальный вариант с одним фреймом и корректным переходом страниц, затем добавляют колонтитулы, сноски и особые шаблоны. Попытка сразу построить сложный разворот затрудняет диагностику: ошибка может находиться и в геометрии фреймов, и в коде переключения мастера, и в процедуре вывода. Пошаговое усложнение оставляет рабочую контрольную точку.

Фреймы, колонки и геометрия страницы

Фрейм — прямоугольная область, в которую поступает текстовый поток или служебный материал. Его границы можно выразить относительно страницы либо другого фрейма. Такой способ удобнее абсолютных координат: изменение поля автоматически сдвигает зависимую колонку, а ширина правой области может вычисляться от правого края листа. Связи между фреймами образуют геометрию макета.

Основной поток обычно направляется в один фрейм или последовательность колонок. Когда вертикальное место заканчивается, выходная процедура класса выбирает следующий фрейм либо создаёт страницу по мастер-шаблону. Для двух колонок важно определить не только ширину каждой области, но и порядок течения: первая колонка должна передавать материал второй, а вторая — инициировать следующую страницу.

Отдельные фреймы применяют для номера страницы, верхнего колонтитула, поля с примечаниями, сносок и иллюстраций. Служебный фрейм не обязан принимать обычный поток; класс может заполнить его в момент вывода страницы. Это позволяет менять колонтитул в зависимости от главы и не вставлять его вручную в текст каждой страницы.

Ошибки геометрии часто проявляются как нулевая или отрицательная ширина, текст за пределами листа либо бесконечная попытка найти следующий фрейм. Проверять нужно исходные зависимости: левый край должен находиться левее правого, верхний — выше нижнего в принятой системе координат, а цепочка переходов не должна замыкаться сама на себя без создания новой страницы.

Пакеты для мастер-страниц и двусторонней вёрстки помогают различать левую и правую сторону разворота. На зеркальных страницах внутреннее и внешнее поле меняются местами, а номер страницы может переходить к внешнему краю. Для первой страницы главы нередко выбирают отдельный мастер без верхнего колонтитула и с увеличенным отступом перед заголовком.

Переносы, выравнивание и алгоритм разбиения строк

SILE формирует абзац не по одному слову, а оценивает возможные точки разрыва и качество строки в контексте всего абзаца. Основа близка к алгоритму Кнута—Пласса: ширина пробелов может растягиваться или сжиматься, переносы получают штрафы, а движок ищет последовательность строк с приемлемой суммарной плохостью. Поэтому небольшое изменение шрифта способно перестроить весь абзац, а не только последнюю строку.

Пользователь может выбрать выключку по ширине, по левому или правому краю и центрирование. Для основного книжного текста обычно оставляют полную выключку и включают переносы. В узких колонках без переносов возникают чрезмерные межсловные пробелы; в коротких подписях, наоборот, перенос может выглядеть хуже неровного правого края. Настройку следует выбирать по типу блока, а не глобально для всех элементов.

Штрафы контролируют нежелательные разрывы: одиночную строку абзаца внизу страницы, одну строку наверху следующей страницы, перенос перед переходом страницы и другие ситуации. Слишком жёсткие запреты могут привести к большим пустотам или отсутствию допустимого решения. Практичнее назначать высокий, но конечный штраф, а абсолютный запрет оставлять для действительно недопустимых мест.

Межбуквенное пространство и переменные пробелы дают дополнительный резерв для подгонки. Эти настройки требуют осторожности: заметный трекинг разрушает рисунок текста, а чрезмерное растяжение пробелов делает реки. Начинать следует с корректного размера шрифта, ширины строки и словаря переносов; микротипографику подключают после того, как базовая геометрия уже разумна.

Если одна строка выглядит явно хуже соседних, сначала проверяют язык абзаца и наличие шаблонов переносов. Затем смотрят на неразрывные фрагменты, длинные адреса, числа и команды, создающие цельный бокс. Ручной разрыв строки решает единичный случай, но в серийных документах лучше исправить правило, иначе следующая редакция текста снова нарушит макет.

Вертикальный ритм и набор по базовой сетке

Вертикальные интервалы в SILE представлены не только фиксированной высотой, но и клеем с допустимым растяжением и сжатием. Благодаря этому страница может распределять небольшую разницу между несколькими промежутками, сохраняя нижнюю границу фрейма. Если разрешённый диапазон слишком велик, расстояния между абзацами становятся неодинаковыми; если слишком мал, появляются переполнения и пустоты.

Пакет сетки привязывает базовые линии к регулярному шагу. Такой режим нужен для параллельных колонок, библейских изданий и макетов, где строки на соседних страницах должны совпадать. Сетка предъявляет требования к высоте заголовков, иллюстраций и вставок: каждый элемент должен возвращать поток к допустимой базовой линии, иначе накопится смещение.

Интерлиньяж настраивают в связи с кеглем и метриками гарнитуры. Одинаковая числовая величина выглядит по-разному у шрифтов с большой и малой высотой строчных. После смены гарнитуры следует проверить плотные абзацы, строки с диакритикой, верхние и нижние выносные элементы, а также математические формулы, которые могут требовать дополнительной высоты.

При неожиданной пустой полосе перед абзацем полезно включить отладочную визуализацию боксов и клея либо временно убрать пакет, который вмешивается в вертикальное размещение. Причиной бывает накопленный отступ, запрет разрыва, вставка с минимальной высотой или переход на следующую точку сетки. Последовательное отключение компонентов быстрее случайной правки чисел.

Шрифты, OpenType и резервные гарнитуры

SILE работает с установленными шрифтами и обращается к ним по семейству, начертанию, насыщенности и другим параметрам. Для предсказуемой сборки лучше перечислить необходимые гарнитуры в документации проекта и установить их на всех машинах и CI-агентах. Если семейство не найдено, движок не может гарантировать тот же размер строк и страниц даже при автоматической подстановке.

Базовый текст обычно набирается Gentium Plus, моноширинные фрагменты часто рассчитывают на Hack, а математический пакет — на Libertinus Math. Эти гарнитуры не всегда устанавливаются вместе с программой. Сообщение об отсутствующем шрифте устраняют установкой нужного семейства либо явной заменой в классе; копирование TTF или OTF в папку без регистрации не всегда делает файл видимым менеджеру шрифтов.

Поддержка OpenType позволяет включать лигатуры, стилистические наборы, старостильные цифры, дроби и другие таблицы, если они действительно присутствуют в выбранном шрифте. Неизвестная функция не создаёт соответствующие глифы из воздуха. Перед использованием редкой возможности полезно проверить гарнитуру в тестовом документе и убедиться, что включение не меняет символы там, где оно не планировалось.

Пакет резервных шрифтов подбирает другую гарнитуру для символов, отсутствующих в основной. Это важно для многоязычных документов, специальных знаков и ограниченных декоративных семейств. Резерв должен быть согласован по размеру и пропорциям: слишком крупные глифы нарушают интерлиньяж, а отличающаяся толщина выделяет отдельные символы внутри слова.

Настройки высоты строчной и прописной помогают визуально согласовать моноширинный код или запасной шрифт с основным текстом. Масштабирование по метрикам предпочтительнее случайного уменьшения кегля, но после него всё равно проверяют знаки пунктуации и цифры. Некоторые шрифты содержат необычные метрики, и автоматическая коррекция может потребовать ручного ограничения.

Юникод, языки и направление письма

Язык в SILE влияет не только на подписи вроде названия оглавления. Он выбирает шаблоны переносов, минимальное число букв до и после переноса, правила локализации и иногда обработку пунктуации. Если русский текст размечен как английский, переносы будут отсутствовать или окажутся неверными. Язык следует задавать на уровне документа и менять для отдельных фрагментов.

Движок использует современные библиотеки формирования глифов и способен работать со сложными письменностями, но наличие кода символа ещё не означает полноценный результат. Нужен шрифт с соответствующими глифами и OpenType-таблицами, корректное направление и языковой модуль. Проверка должна включать реальные сочетания букв, диакритику, цифры и пунктуацию, а не одну демонстрационную строку.

Для письма справа налево подключается двунаправленная обработка. Смешение арабского или иврита с латиницей и числами создаёт участки разного направления; порядок символов на экране исходника и визуальный порядок в PDF не совпадают. Ошибки часто вызваны не самим шейпером, а неверно установленным направлением контейнера или нейтральной пунктуацией на границе фрагментов.

Китайский и японский текст требуют правил разрыва между знаками, отличных от европейской модели слов и пробелов. Для слоговых письменностей и языков со специальной сегментацией используются отдельные обработчики. При подготовке многоязычной книги разумно собрать тестовую страницу для каждого языка, включая заголовок, основной абзац, курсив, цифры, сноску и перенос страницы.

Локализация системных подписей зависит от класса и пакетов. Если оглавление или служебный заголовок остаётся на другом языке, проверяют, когда установлен язык: до загрузки соответствующего пакета или после. Некоторые команды считывают локализованную строку в момент инициализации, поэтому позднее переключение влияет только на последующий текст.

Изображения, SVG, цвет и фон

Растровое изображение вставляется с указанием файла и размеров. Если задать только одну сторону, пропорции можно сохранить автоматически; при одновременном принудительном выборе ширины и высоты картинка способна исказиться. Для печати важна не только геометрия на странице, но и исходное разрешение: увеличение маленького файла делает пиксели заметными, хотя PDF формально создаётся без ошибки.

SVG полезен для схем, логотипов и линейной графики. Относительные пути разрешаются относительно документа, что упрощает перенос проекта. Поддержка конкретных элементов SVG зависит от используемого обработчика; сложные фильтры, внешние шрифты и скрипты лучше заранее преобразовать в более простой векторный файл. При проблемах сначала проверяют SVG в независимом валидаторе.

Цвет можно задавать для текста и графических элементов, а пакет фона заполняет область за содержимым. Цветовая модель и ожидания типографии должны быть согласованы заранее: экранный RGB не равен готовому печатному процессу. SILE формирует PDF, но не заменяет профессиональную допечатную проверку профилей, суммарного красочного слоя, вылетов и прозрачностей.

Для обрезных меток и вылетов предусмотрены инструменты макета. Полный вылет требует, чтобы фон или изображение выходили за финальный размер страницы, а метки располагались вне линии реза. Если просто увеличить картинку до края A4, после резки может появиться белая полоса. Геометрию следует строить от обрезного формата и отдельно учитывать служебную область.

Поворот и масштабирование выполняются пакетами эффектов. Вращаемый объект остаётся боксом, поэтому важно понимать, как вычисляется занимаемая область после трансформации. Большая подпись, повернутая на девяносто градусов, может визуально помещаться сбоку, но её исходный бокс вытеснит основной текст. В таких случаях объект размещают в специально рассчитанном фрейме.

Списки, правила, лидеры и специальные блоки

Пакет списков строит маркированные и нумерованные уровни, управляет меткой, отступом и расстоянием между пунктами. Вложенные списки лучше оформлять структурно, а не вручную вводить цифры и табуляцию: автоматическая нумерация корректно обновляется после вставки нового пункта, а класс может изменить вид всех уровней сразу.

Длинная метка требует достаточной ширины левой области. Если номер или символ сталкивается с текстом, увеличивают отступ либо меняют формат метки. Табуляция пробелами ненадёжна, потому что ширина пробела зависит от шрифта, а выключка по ширине может его растянуть. Отдельный бокс для метки обеспечивает стабильное выравнивание.

Лидеры заполняют промежуток повторяющимся знаком или линией, например между названием и номером страницы в оглавлении. Заполнитель должен уметь растягиваться до доступной ширины, не создавая лишнего переноса. Если точки заканчиваются слишком близко к номеру, проверяют минимальный пробел вокруг лидера и ширину неразрывного блока с номером.

Правила создают горизонтальные и вертикальные линии заданной толщины. Их используют как разделители, элементы таблиц и декоративные акценты. Слишком тонкая линия может исчезнуть при растеризации или печати, а линия нулевой высоты не всегда занимает ожидаемое место. Толщину и вертикальное положение лучше проверять на целевом масштабе PDF.

Специализированные окружения включают блоки кода, цитатные врезки, образцы шрифтов, аккорды и экспериментальные направления набора. Их назначение различается, поэтому пакет подключают только при реальной необходимости. Чем меньше неиспользуемых модулей загружает документ, тем проще понять, какая команда изменила настройки или выходную процедуру.

Математические формулы

Математический пакет принимает формулы и формирует специальные боксы с учётом базовой линии, операторов, индексов, дробей, корней и растягиваемых символов. Для качественного результата нужен математический OpenType-шрифт; обычная текстовая гарнитура не содержит всех метрик и вариантов скобок. При отсутствии подходящего шрифта формула может собраться с пропусками или остановить обработку.

Строчная формула должна согласовываться с высотой текста и не увеличивать интерлиньяж без необходимости. Выключная формула размещается отдельным блоком, может иметь номер и собственные интервалы. Когда крупная дробь или матрица оказывается слишком близко к соседней строке, корректируют вертикальные параметры математического блока, а не добавляют случайные пустые строки в исходник.

Поддерживаются команды, похожие на привычную математическую запись, и элементы MathML, однако соответствие стандарту не исчерпывающее. Табличные конструкции MathML работают в пределах реализованных атрибутов. При переносе сложной формулы из другой системы следует проверить каждый оператор, акцент, предел и выравнивание, а не считать одинаковое имя команды гарантией идентичного результата.

Многострочные выкладки строятся через таблицу или специализированное окружение с точками выравнивания. Для цепочки равенств обычно выравнивают знаки, а поясняющий текст помещают в отдельную колонку. Ручные пробелы дают нестабильный результат и меняются вместе со шрифтом. Структурное выравнивание сохраняется при редактировании членов формулы.

Нумерацию формул и ссылки на них лучше централизовать в макросе или классе. Ручной номер справа легко конфликтует с широкой формулой и не обновляется при перестановке. Система счётчиков позволяет присваивать последовательные значения и форматировать их в соответствии с главой, а механизм ссылок — выводить актуальное значение в тексте.

Сноски, оглавление и нумерация страниц

Сноска состоит из маркера в основном тексте и вставки, которая должна попасть в область сносок на той же странице. Если сносок много, выходная процедура перераспределяет доступную высоту основного фрейма. Ручное размещение внизу страницы не подходит: изменение абзаца выше сдвинет маркер, а примечание останется на прежней странице.

Слишком длинная сноска может потребовать переноса или специального решения класса. Нельзя рассчитывать, что любой объём автоматически поместится под коротким текстом страницы. Для академических документов проверяют страницы с несколькими примечаниями, длинными адресами и формулами внутри сносок; именно они выявляют граничные ошибки макета.

Оглавление собирается из зарегистрированных заголовков и обычно требует как минимум двух проходов. На первом проходе SILE узнаёт номера страниц и записывает служебные данные, на следующем — вставляет их в оглавление. После серьёзной правки документ запускают повторно до стабилизации; старое оглавление после одного прохода не означает, что команда неисправна.

Номер страницы выводится пакетом folio и классом. Титульные листы, римская нумерация введения и арабская нумерация основной части требуют явного управления счётчиком и форматом. Скрытие напечатанного номера не всегда означает исключение страницы из счёта: это два разных действия, которые класс должен различать.

Колонтитулы часто зависят от текущей главы или раздела. Значение сохраняют при обработке заголовка, а выводят в момент завершения страницы. Если в колонтитуле появляется заголовок со следующей страницы, значит переменная обновляется слишком рано либо выходная процедура берёт текущее состояние вместо отметки, связанной с материалом данной страницы.

Библиография по BibTeX и CSL

Библиографический пакет читает базу записей, связывает ключи цитирования с источниками и формирует список литературы. Стиль CSL определяет порядок авторов, года, названия, знаки препинания и вид повторных ссылок. Один и тот же набор данных можно оформить по разным правилам без ручного переписывания каждой записи.

Команда цитирования должна получать существующий ключ. Опечатка в ключе, неверная кодировка базы или отсутствующий обязательный параметр проявляются предупреждением либо незаполненной ссылкой. Перед финальной сборкой полезно отдельно проверить список неизвестных ключей и записи без автора, даты или названия, потому что стиль может обрабатывать их по-разному.

Групповые цитаты объединяют несколько источников в один блок и соблюдают разделители стиля. Локатор указывает страницу, главу или другой фрагмент. Если знаки препинания дублируются, не следует вручную добавлять скобки вокруг результата: оформление аффиксов и разделителей должно оставаться в библиографическом механизме.

Список литературы может сортироваться по языковым правилам, автору, году и другим полям. Для смешанных алфавитов результат зависит от колляции и локали. В издании с русскими и латинскими авторами заранее определяют требуемый порядок и проверяют реальные фамилии с диакритикой, дефисами и частицами.

Ссылки DOI и другие идентификаторы могут превращаться в PDF-ссылки при подключённой поддержке. Для печатной версии длинный адрес иногда создаёт плохую строку, поэтому стиль должен выбирать компактное представление. В цифровом PDF важно проверить кликабельную область и отсутствие лишней пунктуации внутри цели ссылки.

Предметный указатель

Индексатор регистрирует термин в точке его появления, сохраняет номер страницы и затем печатает отсортированный указатель. Разметка должна отделять отображаемый термин от ключа сортировки: имя с частицей, число или слово с диакритикой может печататься одним образом, но сортироваться по нормализованной форме.

Последовательные страницы можно сворачивать в диапазон. Это уменьшает объём указателя, но требует точного определения, когда страницы считаются смежными и как оформляется тире. Повторные отметки на одной странице должны объединяться, иначе строка заполняется одинаковыми номерами. Эти операции выполняются генератором, а не вручную после экспорта PDF.

Многоуровневый термин состоит из основной рубрики и подрубрики. Непоследовательное написание создаёт две разные ветви, поэтому в большом проекте полезны макросы или словарь ключей. Исправление названия в одном месте тогда меняет все вхождения и сохраняет общий ключ сортировки.

Указатель, как и оглавление, зависит от служебных данных предыдущего прохода. После удаления большого раздела старые номера могут сохраняться до повторной сборки. В автоматическом сценарии запускают SILE несколько раз либо сравнивают служебные файлы и останавливаются, когда они перестают меняться.

Макросы и настройки

Макрос в SIL заменяет повторяющуюся последовательность команд именованной конструкцией. Простой макрос выводит фиксированное содержимое, а макрос с аргументами принимает параметры и вложенный текст. Его задача — выражать смысл документа, а не только экономить символы. Команда \productname{...} понятнее цепочки выбора шрифта, регистра и цвета.

Вложенные макросы должны аккуратно управлять областью настроек. Изменение шрифта, языка, цвета или интервалов внутри одного вызова не должно протекать наружу. Для этого содержимое обрабатывают в локальном контексте и восстанавливают состояние после завершения. Симптом утечки — все последующие абзацы неожиданно получают оформление последнего элемента.

Настройки типизированы: длина, целое число, логическое значение и другие варианты проверяются при установке. Ошибка единицы измерения или лишний текст должны быть исправлены в исходнике, а не молча превращены в ноль. Это снижает риск получить формально созданный, но геометрически неверный документ.

Система настроек поддерживает временную установку на период обработки содержимого. Такой способ предпочтительнее пары изменить — вернуть, потому что возврат выполнится корректно и при вложенных вызовах. Когда два пакета используют одну настройку, стек контекстов предотвращает случайное восстановление чужого значения.

Отладка настроек начинается с определения уровня: значение класса, документа, пакета или конкретной команды. Если ручная установка не действует, возможно, класс меняет параметр позже либо пакет читает его один раз при загрузке. Перенос команды в правильное место часто решает проблему без модификации внутреннего кода.

Пакеты и расширение на Lua

Основное ядро SILE сравнительно компактно, а значительная часть возможностей реализована пакетами. Пакет регистрирует команды, настройки, обработчики сырого содержимого и хуки класса. Он может изменить разбиение строк, добавить новый тип вставки или построить специализированный элемент вроде декоративного инициала. Подключать пакет следует до первого использования его команд.

Сторонние модули распространяются через LuaRocks или вместе с проектом. Важна совместимость с той реализацией Lua, которую использует SILE. Если пакет установлен в дерево другой версии Lua, команда его не найдёт, хотя LuaRocks сообщит об успешной установке. Путь можно передать параметром --luarocks-tree либо настроить окружение.

Проектное дерево lua_modules удобно для воспроизводимой сборки: зависимости находятся рядом с исходниками и не требуют глобальной установки. В репозитории обычно фиксируют описание зависимостей, а не случайно собранные бинарные файлы для чужой платформы. На CI дерево восстанавливают перед запуском SILE.

Пакет на Lua способен выполнять произвольный код, поэтому устанавливать следует только модули из доверенного источника и просматривать их зависимости. Документ, загружающий неизвестный пакет, нельзя считать пассивным текстом. В изолированном сборочном окружении ограничивают доступ к секретам и не запускают непроверенные исходники от имени привилегированного пользователя.

Для собственного пакета сначала создают минимальный класс-наследник, регистрируют одну команду и проверяют загрузку. Затем добавляют параметры, настройки и тестовый документ. Регрессионные PDF или снимки страниц помогают заметить, что изменение алгоритма неожиданно сдвинуло строки в других сценариях.

Пользовательские входные и выходные обработчики

Входной обработчик превращает содержимое в абстрактное дерево, понятное SILE. Поэтому формат не ограничен SIL и XML: модуль может разобрать Markdown, Djot или специализированный язык данных. Качественный обработчик сохраняет структуру — заголовки, списки, ссылки, атрибуты — вместо преждевременного превращения всего в оформленный текст.

Разбор должен сообщать ошибку с именем файла и позицией. Сообщение не удалось обработать документ без строки мало помогает автору. При проектировании собственного входного формата полезно хранить сведения о происхождении каждого узла, чтобы последующая ошибка команды могла указать на исходный фрагмент, а не на внутреннее дерево.

Выходной обработчик получает страницы и рисует их в целевом формате. Основным результатом служит PDF, но архитектура допускает другие выходы, включая текстовый backend. Возможности зависят от backend: цвет, ссылки, векторные операции и шрифты могут поддерживаться не одинаково. Документ, рассчитанный на PDF, нужно отдельно тестировать при смене выходного формата.

Параметр имени результата позволяет отделить исходную структуру проекта от каталога публикации. В пакетной сборке выходные файлы направляют в отдельную папку, а временные служебные данные очищают только после успешного завершения. Это предотвращает ситуацию, когда неудачный запуск оставляет новый неполный PDF поверх проверенного файла.

Автоматическая сборка и CI

Текстовый исходник хорошо подходит для системы контроля версий: изменения видны построчно, классы и пакеты проходят совместное рецензирование, а PDF можно пересобирать на сервере. Сценарий CI должен устанавливать одинаковые шрифты и зависимости, иначе число строк и страниц различается между разработчиком и сервером даже при идентичном исходнике.

Готовый контейнер упрощает запуск, но каталог проекта необходимо подключить внутрь контейнера, чтобы движок видел исходники и мог записать PDF. Системные шрифты хоста также не появляются автоматически. Их монтируют отдельной папкой или включают в образ. Пропущенный шрифт — самая частая причина различий между контейнерной и обычной сборкой.

В GitHub Actions доступно действие SILE, которому передают имя исходника. Для регулярных сборок быстрее использовать заранее собранный контейнер, чем заново строить его при каждом запуске. Версию образа фиксируют тегом, чтобы обновление окружения не изменило макет в произвольный момент. Переход на другой тег проводят отдельной задачей с визуальным сравнением.

name: Build PDF
on: [push, pull_request]
jobs:
  typeset:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: sile-typesetter/sile@v0
        with:
          args: book.sil

После сборки проверяют код возврата, существование файла, ненулевой размер и отсутствие критических сообщений. Для важных изданий дополнительно рендерят контрольные страницы в PNG и сравнивают их с эталоном. Пиксельное отличие не всегда означает ошибку, но оно указывает, где требуется ручная проверка после обновления шрифта, библиотеки или класса.

Многопроходные документы CI должен собирать столько раз, сколько нужно оглавлению, ссылкам и индексу. Фиксированное число проходов проще, но может быть избыточным; более точный сценарий сравнивает служебные файлы между запусками. Если данные продолжают меняться бесконечно, сборку останавливают и сообщают о нестабильной ссылке или счётчике.

Установка и совместимость

На macOS рекомендуемый путь проходит через Homebrew: команда устанавливает SILE и библиотечные зависимости, но базовые шрифты могут потребовать отдельной установки. После завершения проверяют sile --help, затем собирают минимальный документ. Если терминал не видит команду, проблема обычно в пути Homebrew, а не в разметке.

В Linux доступны пакеты Arch Linux, Fedora, OpenSUSE, Ubuntu через PPA, NixOS, Void Linux и некоторых BSD-систем. Пакет дистрибутива удобен тем, что зависимости оформлены средствами системы. Однако набор установленных шрифтов различается: даже при наличии команды sile математический или демонстрационный документ может требовать дополнительных пакетов шрифтов.

Nix позволяет запускать пакет в временном окружении и закреплять состав зависимостей. Это удобно для воспроизводимых проектов и серверов, где нежелательна глобальная установка. В конфигурации фиксируют не только SILE, но и семейства шрифтов, Lua-модули и инструменты, которые генерируют входные данные.

В Windows готового обычного установщика нет. Практический путь — WSL с пакетом выбранного Linux-дистрибутива, Docker или удалённая сборка. Нативные экспериментальные сборки не следует считать равнозначной заменой без проверки: состояние зависимостей и доступность шрифтов могут отличаться. Для пользователя, которому нужен привычный графический редактор PDF, такой процесс будет неоправданно сложным.

Сборка из исходников требует компилятора Rust, исходников Lua или совместимой среды, HarfBuzz, fontconfig, ICU и библиотек для создания PDF. Этот вариант выбирают разработчики, сопровождающие пакеты, либо пользователи платформ без готового пакета. Перед компиляцией полезно прочитать перечень зависимостей именно для своей системы и не смешивать заголовки одной версии Lua с библиотекой другой.

Работа через Docker

Контейнер запускают с подключением текущего каталога в рабочую папку внутри образа. Тогда исходник, изображения и готовый PDF остаются на хосте. Без тома команда может успешно создать файл внутри временного контейнера, после чего результат исчезнет. Права пользователя контейнера должны позволять запись в подключённый каталог.

docker run --rm -it \
  --volume "$PWD:/data" \
  siletypesetter/sile:latest book.sil

Для доступа к системным шрифтам подключают каталог fontconfig в отдельную точку. Конкретный путь зависит от платформы. После подключения полезно выполнить список шрифтов внутри контейнера и убедиться, что семейства называются так же, как в документе. Имя файла шрифта и имя семейства в метаданных могут не совпадать.

Контейнерный тег latest удобен для эксперимента, но в производственном проекте его заменяют конкретным тегом. Тогда повторная сборка через месяц использует тот же набор. Обновление проводят осознанно: собирают обе версии, сравнивают число страниц, оглавление, переносы и контрольные изображения.

Скорость контейнера близка к обычному запуску после загрузки слоёв. Главные накладные расходы приходятся на получение образа и подключение ресурсов. В CI кэширование образа и зависимостей заметно ускоряет работу, особенно если PDF небольшой, а набор шрифтов велик.

Диагностика ошибок разметки

Первая категория ошибок возникает до набора: незакрытая фигурная скобка, неверное окружение, лишний символ в параметре или повреждённый XML. Сообщение обычно содержит файл и позицию. Исправлять следует самое первое диагностическое сообщение: последующие часто являются следствием нарушенной структуры и исчезают после одной правки.

Неизвестная команда означает, что в имени есть опечатка, нужный пакет не загружен либо выбран класс без этой команды. Сначала ищут команду в документации подключённого пакета, затем проверяют порядок загрузки. Создавать пустую заглушку опасно: документ соберётся, но смысловой элемент пропадёт из PDF.

Ошибка разбора длины появляется при неизвестной единице, неверном десятичном разделителе или лишнем тексте. В разметке используют точку как десятичный знак и поддерживаемые единицы. Отрицательная длина допустима не везде; если она приводит к геометрии с отрицательной шириной, нужно пересмотреть зависимость фрейма, а не подавлять проверку.

При внутренней трассировке Lua полезно отделить пользовательскую часть от стека библиотек. Верхняя строка, указывающая на исходник или пользовательский пакет, обычно важнее десятков вызовов ядра. Минимальный пример из нескольких строк помогает понять, вызывает ли ошибку конкретная команда или взаимодействие нескольких пакетов.

Флаг подробного вывода и отладочные пакеты применяют временно. Постоянный поток сотен сообщений скрывает значимое предупреждение. В сценарии сборки обычный режим сохраняют кратким, а расширенный журнал включают при падении или по отдельной переменной окружения.

Проблемы со шрифтами и символами

Сообщение шрифт не найден проверяют командой системного менеджера шрифтов, а не только просмотром папки. После установки кэш fontconfig может потребовать обновления. В контейнере проверка выполняется внутри контейнера: наличие гарнитуры на хосте ничего не гарантирует без подключённого каталога.

Квадрат вместо символа означает отсутствие глифа в выбранной гарнитуре либо неработающий резерв. Нужно определить кодовую точку, проверить её в таблице шрифта и добавить подходящий fallback. Замена символа похожим знаком скрывает проблему и может исказить данные, особенно в научном или лингвистическом тексте.

Неверное соединение букв сложного письма указывает на шрифт без нужных таблиц, неправильный язык или направление. Простой Unicode-шрифт с отдельными глифами не обязательно умеет корректно формировать арабское слово или индийский слог. Для проверки используют заведомо подходящую гарнитуру и минимальный текст без дополнительных пакетов.

Если после замены шрифта изменилась нумерация страниц, это ожидаемое следствие других метрик. Нельзя вернуть прежний объём одной настройкой межстрочного интервала без визуальной проверки. Сравнивают ширину строки, высоту строчных, межсловные пробелы и число переносов, затем корректируют стиль целиком.

Встроение шрифтов в PDF проверяют отдельным анализатором перед распространением. Наличие текста на экране не доказывает, что получатель увидит то же самое. Лицензия шрифта также может ограничивать встраивание; для публикуемого документа выбирают гарнитуры с разрешённым режимом и проверяют свойства итогового PDF.

Переполнение, пустые страницы и нестабильная вёрстка

Переполненный горизонтальный бокс появляется, когда неразрывный фрагмент шире строки. Причиной бывают длинный адрес, код, формула, изображение или слово без допустимого переноса. Решение выбирают по смыслу: разрешить перенос адреса, уменьшить изображение, разбить формулу, сменить колонку или задать корректный язык. Уменьшать весь основной шрифт ради одного фрагмента нерационально.

Вертикальное переполнение означает, что материал не удалось разместить в доступных фреймах. Проверяют цепочку переходов, высоту вставок, сносок и запреты разрыва. Если класс не создаёт следующую страницу, поток может остановиться даже при небольшом тексте. Минимальный документ с тем же классом показывает, работает ли базовая выходная процедура.

Неожиданная пустая страница часто создаётся правилом начала главы с правой стороны. В двустороннем издании пустой левый оборот может быть намеренным. Если он не нужен, изменяют политику класса. Удалять страницу из готового PDF плохо: нумерация, оглавление и развороты останутся рассчитанными с её учётом.

Нестабильное оглавление между проходами бывает при содержимом, которое меняет собственный размер в зависимости от номера страницы. Например, более длинный номер сдвигает текст и снова меняет пагинацию. Для устранения фиксируют ширину поля номера, сокращают заголовок в оглавлении или меняют макет, чтобы служебные данные не создавали обратную связь.

Различия между машинами обычно связаны со шрифтами, версиями библиотек и локалью. Репозиторий исходников сам по себе не обеспечивает воспроизводимость. Необходимо фиксировать окружение, хранить контрольные суммы ресурсов и сравнивать PDF или рендеры после обновлений.

Практический сценарий: книга

Для книги создают класс с титульными страницами, мастер-шаблонами левого и правого разворота, командами главы и раздела, оглавлением, сносками и колонтитулами. Текст делят на файлы по главам и подключают из основного документа. Это ускоряет навигацию и уменьшает риск конфликта при совместной работе.

На раннем этапе собирают несколько характерных страниц: начало главы, плотный основной текст, страницу со сносками, иллюстрацию, длинный заголовок и последнюю страницу главы. Полный роман не нужен для настройки геометрии. Когда тестовый набор устойчив, добавляют остальное содержимое и проверяют редкие комбинации.

Оглавление и ссылки требуют повторных проходов. В редакторе удобно назначить задачу, которая запускает команду несколько раз и открывает итоговый PDF. Служебные файлы не удаляют между проходами, но очищают при изменении структуры класса, если старые данные вызывают странные ссылки.

Перед публикацией проверяют развороты, висячие строки, пустые полосы, совпадение колонтитула с главой, номера в оглавлении и встроенные шрифты. Автоматическая проверка числа страниц ловит крупные изменения, но не замечает плохой перенос или потерянный инициал; контрольные страницы необходимо осмотреть визуально.

Практический сценарий: каталог из XML

Каталог удобно хранить как структурированные записи: товар, группа, артикул, характеристики, цена, изображения и примечания. Класс или пакет связывает каждый элемент XML с командой SILE. Если поле отсутствует, обработчик решает, скрыть строку, вывести заглушку или остановить сборку. Такое правило должно быть единообразным для всех записей.

Страница каталога часто содержит несколько фреймов и повторяемые карточки. Перед размещением карточки полезно оценить её высоту; если она не помещается в остаток страницы, начать новую колонку или страницу. Разрыв карточки посередине допустим не всегда. Запрет разрыва улучшает целостность, но может оставлять большие пустоты при очень высокой записи.

Изображения проверяют до набора: путь, формат, размеры и разрешение. Отсутствующий файл лучше считать ошибкой, чем тихо выпускать пустую рамку. Для тысяч картинок предварительный скрипт способен составить отчёт быстрее, чем последовательные падения SILE на каждой проблемной записи.

Единый класс гарантирует одинаковую типографику всех выпусков. Изменение поля или шрифта применяется ко всему каталогу при следующей сборке. При этом пагинация изменится, поэтому внешние ссылки на номера страниц нельзя хранить как постоянные данные; их следует генерировать из актуального PDF или структуры выпуска.

Практический сценарий: техническая документация

Техническое руководство содержит иерархию разделов, код, предупреждения, таблицы, перекрёстные ссылки и индекс. Смысловые макросы отделяют тип блока от оформления. Предупреждение может получить рамку и значок в печатном PDF, но исходник остаётся понятным и пригодным для другого выходного обработчика.

Код набирают моноширинным шрифтом с контролируемым переносом. Автоматический перенос длинной команды способен изменить смысл при копировании, поэтому визуальный знак продолжения должен отличаться от реального символа. Для листингов с важными пробелами используют окружение verbatim и проверяют табуляцию.

Ссылки на разделы строят через метки и счётчики, а не ручные номера. После перестановки главы текст ссылки обновляется при повторной сборке. Неразрешённая метка должна оставлять заметное предупреждение; выпуск документа с пустыми ссылками блокируют в CI.

Индекс полезен для терминов, которые встречаются в разных разделах. Метки индекса добавляют в исходник рядом с содержанием, а не после набора по готовому PDF. Тогда изменение пагинации автоматически отражается в указателе и не требует ручной сверки сотен номеров.

Практический сценарий: параллельные тексты и сложный макет

Параллельный текст размещает две версии материала рядом или в связанных фреймах. Главная задача — синхронизация соответствующих блоков. Простое независимое заполнение колонок быстро рассинхронизируется из-за разной длины языков. Пакет parallel управляет связанными сегментами и помогает начать соответствующий фрагмент на согласованной вертикальной позиции.

Если один сегмент значительно длиннее, возникает пустота в соседней колонке. Это не всегда ошибка: сохранение соответствия важнее плотности. Для уменьшения пустот редактор может делить абзацы на более мелкие логические блоки, но нельзя произвольно переставлять предложения только ради геометрии.

Сетка базовых линий усиливает визуальную связь колонок. Гарнитуры разных письменностей подбирают по оптическому размеру и межстрочному расстоянию. Одинаковый кегль не гарантирует одинаковую высоту; запасной шрифт может потребовать масштабирования по высоте строчных.

Сложные формы абзаца, как набор по окружности или змейкой, демонстрируют программируемость движка. Они подходят для отдельных художественных задач, но усложняют чтение и корректорскую работу. Такой макет следует изолировать в макросе и сопровождать обычным тестом, чтобы изменения алгоритма не повлияли на основной поток.

Что SILE делает с готовым PDF, а чего не делает

SILE создаёт PDF из исходной разметки, но не предназначен для интерактивного исправления уже готовой страницы. Нельзя открыть чужой договор, выделить слово мышью и заменить его как в PDF-редакторе. Для изменения результата возвращаются к SIL, XML или данным, после чего выполняют новую сборку.

Пакет PDF способен добавлять низкоуровневые объекты, закладки, ссылки и служебную структуру, если это предусмотрено документом. Это не равнозначно универсальному редактированию произвольного PDF. Слияние, удаление страниц, распознавание сканов и заполнение существующих форм лучше выполнять специализированными инструментами до или после SILE.

Такое разделение полезно для воспроизводимости: готовый файл считается результатом, а не источником истины. Корректировка в PDF после сборки создаёт расхождение — при следующем запуске она исчезнет. Финальные постобработки допустимы только как зафиксированный этап сценария, который повторяется автоматически и не требует ручной памяти.

Если задача состоит в подготовке нового издания по структурированному тексту, SILE даёт глубокий контроль. Если нужно быстро исправить существующий PDF без исходников, графический редактор будет практичнее. Выбор определяется направлением процесса: данные и разметка → PDF или готовый PDF → ручное изменение.

Мастер-страницы и переключение макетов

Мастер-страница объединяет набор фреймов и правила их использования. Один мастер может описывать обычный книжный разворот, другой — начало главы, третий — страницу с полноформатной иллюстрацией. Класс выбирает мастер перед созданием страницы, поэтому автору не приходится вручную повторять координаты. Важное условие — каждый мастер должен предоставлять фреймы, которые ожидает выходная процедура: основной поток, область сносок и служебные зоны.

Переключение мастера удобно связывать со смысловой командой. Команда главы завершает текущий материал, при необходимости переходит на правую страницу, выбирает шаблон без верхнего колонтитула и только затем выводит заголовок. После завершения стартовой страницы класс возвращается к обычному развороту. Если возврат забыть, все последующие страницы сохранят специальный макет, хотя исходный текст будет выглядеть правильно.

Фреймы разных мастеров могут иметь одинаковые имена, но различную геометрию. Это позволяет выходной процедуре направлять основной текст в content, не зная, одна там колонка или две. Стабильные имена становятся интерфейсом между классом и макетом. Переименование фрейма требует обновить все места, где он выбирается или используется как родитель координат.

Для иллюстрационной страницы иногда нужен мастер без основного потока. В таком случае класс обязан после вывода изображения создать следующую страницу с текстовым мастером и вернуть материал в правильную цепочку. Иначе оставшийся текст попытается попасть в отсутствующий фрейм. Такой сценарий тестируют не отдельной картинкой, а картинкой между двумя абзацами, чтобы проверить вход и выход из специального режима.

Отладку мастер-страниц упрощает временная визуализация границ. Она показывает фактические прямоугольники, зависимости и наложения, которые не заметны в чистом PDF. После исправления рамки отключают: это диагностический слой, а не часть макета. Контрольные страницы сохраняют отдельно, чтобы при следующей правке геометрии быстро сравнить поля и положение колонтитулов.

Размеры, клей, боксы и штрафы

Внутренняя модель SILE строится из боксов, клея, кернов и штрафов. Бокс имеет измеримую ширину и представляет текстовый фрагмент, изображение или другой неделимый объект. Клей заполняет пространство и содержит естественный размер, допустимое растяжение и сжатие. Керн добавляет фиксированное смещение, а штраф обозначает возможность и цену разрыва. Понимание этих четырёх элементов объясняет большинство необычных переносов.

Обычный пробел не является фиксированным пустым прямоугольником. При полной выключке его клей меняет ширину, чтобы строка точно совпала с границами фрейма. Если суммарного растяжения недостаточно, строка получает высокую плохость; если допустимых точек переноса мало, алгоритм всё равно выбирает наименее плохой вариант. Поэтому чрезмерные пробелы указывают на узкую строку, неверный язык или длинные неразрывные боксы.

Длина может включать несколько компонентов, например естественное значение плюс запас растяжения и сжатия. Такой интервал полезен между абзацами и крупными блоками, где небольшое распределение помогает заполнить страницу. Однако суммарная гибкость всех промежутков не должна превращать макет в случайный: для элементов, положение которых определяет дизайн, используют фиксированную или очень ограниченную величину.

Керн перемещает следующий объект без создания обычного разрываемого пространства. Отрицательный керн применяется для точной посадки инициала или декоративного элемента, но легко вызывает наложение. Его следует использовать после измерения конкретной гарнитуры и проверять при смене шрифта. Если отрицательное смещение компенсирует ошибочную геометрию фрейма, правильнее исправить сам фрейм.

Штраф с низкой ценой делает место удобным для разрыва, высокий штраф старается его избежать, а бесконечный запрещает. Разрыв строки, страницы и колонки использует одну идею, но действует на разных стадиях. Накопление абсолютных запретов может оставить движку без решения. Для заголовка практичнее запретить отрыв от следующего короткого абзаца или потребовать минимальное число строк, чем удерживать вместе весь большой раздел.

При диагностике полезно мысленно разложить проблемный фрагмент. Если длинное слово не переносится, это один бокс без допустимого штрафа внутри. Если абзац не помещается на странице, вокруг него может быть запрет разрыва. Если нижний край страницы не совпадает, вертикальному клею не хватает диапазона. Такой анализ даёт конкретную настройку вместо серии случайных изменений полей и кегля.

Обновление зависимостей без потери макета

Обновление движка, системной библиотеки или шрифта способно изменить формирование глифов, переносы и пагинацию. Даже исправление ошибки в алгоритме может сдвинуть номера страниц и оглавление. Поэтому обновление выполняют отдельной веткой проекта, где старое и новое окружение можно собрать параллельно. Сравнивают не только факт успешного запуска, но и контрольные развороты, число страниц, ссылки и служебные файлы.

Сначала обновляют один слой. Одновременная замена SILE, набора шрифтов и сторонних пакетов не позволяет определить источник отличия. После каждого шага запускают тестовый набор: минимальный документ, книгу, многоязычную страницу, математику, библиографию и нестандартный макет. Если регрессия появляется, диапазон причин уже ограничен конкретным изменением.

Сторонний пакет может использовать внутренний API, который меняется строже, чем публичные команды документа. Перед обновлением проверяют журнал пакета и запускают его тесты. Временное подавление предупреждения о устаревшем интерфейсе откладывает проблему: следующая несовместимость может стать ошибкой. Лучше заменить вызов и закрепить минимальную поддерживаемую конфигурацию.

Шрифты обновляют особенно осторожно. Новая редакция семейства иногда сохраняет имя, но меняет контуры, кернинг и метрики. Система считает это тем же шрифтом, хотя строки становятся другими. Для критичного издания хранят точные файлы с разрешённой лицензией или фиксируют пакет дистрибутива и его контрольную сумму. В отчёте сборки полезно записывать фактически найденные семейства.

После принятого обновления эталонные изображения меняют осознанно. Нельзя автоматически заменить все контрольные снимки только потому, что тест упал: так легко закрепить пропавший абзац или неверный шрифт. Редактор просматривает различия, подтверждает ожидаемые изменения и лишь затем обновляет эталон. Отклонения без понятной причины требуют дополнительной диагностики.

Финальная проверка выполняется в чистом окружении, а не на машине, где сохранились старые модули и шрифты. Контейнер, Nix-среда или новый CI-агент показывают, достаточно ли декларации проекта для сборки. Если чистая среда не работает, локальный успех объясняется скрытой зависимостью, которую следует добавить в конфигурацию.

Сравнение SILE с аналогами

Программа	Лучше подходит для	Главное ограничение
SILE	Программируемых книг, XML-каталогов, сложных фреймов и многоязычной типографики	Нет визуального конструктора и обычного установщика Windows
Typst	Быстрой разметки научных и технических документов с современным языком и коротким циклом сборки	Меньше возможностей для произвольной Lua-логики и обработки чужих XML-схем
LaTeX	Научных статей, диссертаций и проектов, которым нужна огромная экосистема пакетов и шаблонов	Сложная макропрограммная модель и громоздкая настройка нестандартных макетов
ConTeXt	Книг и издательских макетов с глубокой интеграцией TeX, Lua и собственных модулей	Высокий порог входа и менее привычная документация для пользователей LaTeX
WeasyPrint	Автоматического превращения HTML и CSS в PDF, особенно в веб-проектах	Типографическая логика ограничена моделью HTML/CSS и движком пагинации
Pandoc	Преобразования Markdown и других форматов с выбором внешнего PDF-движка	Сам по себе не является полнофункциональным движком точной страничной вёрстки

SILE стоит выбирать, когда макет требует программируемых фреймов, прямой обработки XML, нестандартной выходной процедуры или расширений на Lua. Typst удобнее для автора, которому важны современный синтаксис и быстрый старт. LaTeX остаётся сильным выбором для научной экосистемы, ConTeXt — для опытной TeX-вёрстки, WeasyPrint — для команд, уже работающих с HTML/CSS, а Pandoc — как конвертер, соединяющий исходный формат с подходящим движком.

PDF Commander не включён в таблицу как прямой аналог: он решает обратную задачу — редактирует и организует существующие PDF через графический интерфейс. Его имеет смысл выбирать вместо SILE, когда исходной разметки нет и требуется изменить готовый документ, переставить страницы, добавить подпись или выполнить другую ручную операцию.

Как выбрать подход к проекту

Для одноразового письма или простого отчёта настройка класса может занять больше времени, чем работа в текстовом процессоре. Преимущество появляется при повторяемости: десятки документов используют один стиль, данные обновляются автоматически, а макет должен собираться без ручного перетаскивания. Чем больше выпусков и структурных правил, тем быстрее окупается программируемая схема.

Перед началом проекта формулируют требования к входным данным, странице, шрифтам, ссылкам и сборочному окружению. Затем создают минимальный вертикальный срез: один заголовок, несколько абзацев, изображение, сноску и страницу оглавления. Если этот набор уверенно собирается на рабочей машине и CI, можно расширять класс и импортировать основной объём данных.

Не следует начинать с украшений. Сначала добиваются правильной структуры, языков, переносов, размеров и переходов страниц. Затем настраивают гарнитуры, интервалы и декоративные элементы. Такой порядок уменьшает число переменных: дизайнерская корректировка не маскирует ошибку класса, а техническая правка не разрушает уже утверждённый стиль.

Ресурсы проекта фиксируют так же тщательно, как исходный текст. Список шрифтов, контрольные суммы изображений, версии сторонних пакетов и команда сборки входят в документацию репозитория. Благодаря этому другой участник может получить тот же PDF, а не приблизительно похожий файл с иной пагинацией.

Контроль качества готового PDF

После успешной команды проверяют не только открытие файла. Анализатор PDF должен показать ожидаемое число страниц, формат листа, встроенные шрифты и отсутствие шифрования, если оно не планировалось. Просмотр нескольких страниц на экране не обнаруживает отсутствующий глиф в конце книги или случайно пустую страницу.

Визуальная проверка охватывает титул, обычный разворот, начало главы, страницу со сносками, таблицу или формулу, страницу с иллюстрацией, оглавление, библиографию и индекс. Эти места используют разные подсистемы и дают более полное покрытие, чем последовательное пролистывание первых десяти страниц.

Для печати рендерят PDF в растровые изображения с разрешением, близким к проверочному, и осматривают тонкие линии, мелкий текст и границы вылета. Дополнительно проверяют свойства шрифтов и цветовые требования типографии. SILE отвечает за построение документа, но параметры конкретного печатного процесса должны быть заданы и проверены отдельно.

Регрессионный контроль сравнивает новые страницы с утверждёнными. Полное побитовое сравнение PDF может реагировать на метаданные, поэтому надёжнее сопоставлять рендеры выбранных страниц и текстовую структуру. Любое отличие после обновления окружения рассматривают осознанно: принимают как улучшение либо исправляют и возвращают прежний результат.

Итоговый рабочий план

1. Подготовить папку проекта, текстовый исходник и минимальный документ, который создаёт PDF без ошибок.
2. Выбрать класс или создать его упрощённую версию с одним основным фреймом и корректным переходом страниц.
3. Установить и зафиксировать шрифты, затем проверить OpenType-функции, языки и переносы на тестовых абзацах.
4. Добавить смысловые команды, изображения, формулы, сноски, оглавление, библиографию и индекс по одному компоненту.
5. Настроить повторную сборку в редакторе или CI, включая нужное число проходов и проверку кода возврата.
6. Собрать контрольный набор страниц, выполнить визуальное сравнение и проверить свойства итогового PDF.
7. Хранить правки в исходниках и классах, не вносить незадокументированные изменения вручную в готовый файл.

SILE наиболее убедителен там, где страница является результатом правил, а не единичной ручной композицией. Он требует освоить разметку, терминал и устройство классов, зато даёт повторяемую сборку, прямую работу со структурированными данными и возможность менять поведение движка на уровне Lua. При аккуратно организованном проекте одна команда воспроизводит книгу, руководство или каталог вместе с переносами, оглавлением, ссылками и типографикой, которые иначе пришлось бы контролировать вручную на каждой странице.