В Prince можно превратить HTML, XHTML или XML в готовый PDF с управляемой печатной вёрсткой: подключить CSS и JavaScript, задать размер и поля страниц, собрать колонтитулы, нумерацию, сноски, перекрёстные ссылки и закладки, встроить шрифты и изображения, а затем выпустить обычный, архивный, полиграфический или доступный документ с нужными параметрами защиты.

Основное окно на Windows строится вокруг очереди исходных документов: кнопки Add File(s) и Add URL добавляют локальные страницы или сетевые адреса, соседние списки принимают пользовательские таблицы стилей и сценарии, вкладка PDF Settings собирает параметры результата, а нижний журнал показывает предупреждения и ошибки. После нажатия Convert каждый источник проходит один и тот же предсказуемый цикл загрузки ресурсов, выполнения разрешённых сценариев, расчёта страниц и записи PDF.

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

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

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

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

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

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

Подготовка HTML, XHTML и XML

Наиболее предсказуемый исходный материал — корректно структурированный HTML или XHTML. Заголовки следует размечать элементами h1–h6, списки — ul, ol и li, таблицы — table, thead, tbody и th, а смысловые области — section, article, nav, header и footer. Такая разметка одновременно помогает печатной вёрстке, созданию закладок и выпуску доступного PDF. Когда роль элемента понятна из структуры, для неё проще написать устойчивое CSS-правило, чем привязываться к случайному набору классов.

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

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

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

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

Каскад стилей и печатные правила

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

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

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

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

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

Размер страницы, поля и ориентация

Размер листа задаётся в @page через стандартное имя или точные размеры. Для деловых документов обычно выбирают A4 или Letter, для книг — фактический обрезной формат, для этикеток и билетов — ширину и высоту в миллиметрах. Точный формат важен не только визуально: типография и архивная система читают геометрию страницы из PDF и могут отклонить файл с лишним полем или неверной ориентацией.

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

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

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

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

Колонтитулы, бегущие заголовки и нумерация

Области полей страницы принимают generated content. В верхнюю или нижнюю область можно вывести название документа, текущую главу, дату выпуска и номер листа. Номер строится счётчиками page и pages: первый даёт текущую страницу, второй — общее количество. Поскольку общее число известно только после расчёта всего документа, движок разрешает эту зависимость во время вёрстки, а не требует заранее вычислять значение в шаблоне.

Бегущий заголовок обычно формируется из содержимого последнего встретившегося заголовка раздела. Для этого текст сохраняют через string-set, а в @page извлекают функцией string(). Можно выбрать первое или последнее значение на странице. В книгах удобно показывать название главы на левой странице, а подраздела — на правой. На первой странице главы верхний колонтитул часто скрывают отдельным правилом.

Другой механизм — running elements. Он переносит в область поля не только строку, но и оформленный фрагмент: логотип, несколько строк, границу или компактную таблицу. Исходный элемент объявляется running, затем вставляется в margin box через element(). При таком подходе нужно следить за высотой: крупный колонтитул уменьшает полезную область и может неожиданно добавить страницы.

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

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

Разрывы страниц и управление фрагментацией

Главная задача печатной вёрстки — указать, где элемент можно делить, а где следует сохранить целиком. Свойства break-before, break-after и break-inside управляют разрывами перед блоком, после него и внутри него. Заголовок обычно запрещают оставлять внизу страницы без следующего абзаца, подпись держат вместе с рисунком, а короткую таблицу стараются не разрывать. Слишком много запретов приводит к большим пустым областям, поэтому ограничения назначают только действительно связанным фрагментам.

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

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

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

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

Таблицы на нескольких страницах

Prince повторяет группу thead на каждой странице длинной таблицы, если структура размечена корректно. Это делает столбцы понятными без ручного копирования заголовков. Группа tfoot может использоваться для итогов или служебной строки. Если шапка не повторяется, проверяют display у thead и отсутствие преобразований, которые превратили табличные элементы в обычные блоки.

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

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

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

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

Колонки, плавающие элементы, Flexbox и Grid

Многоколоночная вёрстка подходит для словарей, указателей, газетных блоков и компактных приложений. CSS Columns задаёт число или желаемую ширину колонок, промежуток и разделительную линию. Движок распределяет поток между колонками и страницами. Заголовок, который должен перекрывать все колонки, оформляют через column-span. Перед выпуском проверяют баланс последней страницы: короткая последняя колонка может потребовать ручного разрыва или изменения высоты раздела.

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

Flexbox удобен для строк карточек, шапок и небольших панелей, где элементы должны делить ширину. При печати важно не задавать всем дочерним блокам минимальную ширину, которая в сумме превышает страницу. Свойства flex-basis, grow и shrink следует проверять на длинных названиях и локализованном тексте. Если один элемент неожиданно вытесняет другой, часто виноваты min-width или неразрывное содержимое.

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

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

Сноски и примечания

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

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

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

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

Шрифты, Unicode и переносы слов

Prince использует системные и подключённые веб-шрифты, а при создании PDF встраивает необходимые данные в соответствии с возможностями файла и лицензией шрифта. Для устойчивой сборки лучше поставлять конкретные семейства вместе с проектом и подключать их через @font-face. Иначе документ на другом компьютере может получить замену с иной шириной знаков, что изменит переносы, высоту абзацев и количество страниц.

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

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

Автоматическая расстановка переносов зависит от языка элемента. Атрибут lang в HTML или xml:lang в XML сообщает, какой словарь применять. Без языка русские слова могут не переноситься, а с неверным языком появятся неправильные точки деления. Для заголовков переносы обычно отключают, для узких колонок включают и задают разумные ограничения по числу подряд идущих переносов.

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

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

Изображения, SVG и графика

Растровые изображения можно подключать обычным img или фоном CSS. Для печати важны не только размеры в пикселях, но и фактический размер на странице. Картинка шириной 1200 пикселей, растянутая на 200 миллиметров, даст заметно меньшую детализацию, чем та же картинка в колонке 80 миллиметров. Перед выпуском полезно вычислить эффективное разрешение и заменить слишком маленькие файлы.

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

Размеры изображения лучше задавать через max-width и автоматическую высоту, чтобы оно не выходило за область текста. Для иллюстрации, которая должна занять всю доступную ширину, используют width: 100% внутри ограниченного контейнера. Одновременное указание независимых width и height способно исказить пропорции. Объектные свойства помогают кадрировать фотографии, но для технических схем обрезание обычно недопустимо.

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

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

JavaScript перед формированием PDF

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

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

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

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

После изменения DOM пагинация пересчитывается. Поэтому сценарий не должен полагаться на окончательные координаты элементов до завершения вёрстки. Задачи, связанные с номером страницы, оглавлением и ссылками, лучше решать встроенными механизмами CSS и generated content: они учитывают всю цепочку зависимостей автоматически.

Закладки, ссылки, оглавление и перекрёстные ссылки

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

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

Номер страницы цели извлекается функцией target-counter, а текст цели — target-content. Благодаря этому строка оглавления может содержать название раздела, лидеры и фактический номер после пагинации. При добавлении главы номера обновляются без ручной правки. Ссылку следует строить на стабильный идентификатор, а не на номер, потому что нумерация меняется вместе с документом.

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

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

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

Метаданные и поведение при открытии

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

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

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

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

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

PDF/A, PDF/X и PDF/UA

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

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

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

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

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

Цвет, ICC-профили и подготовка к печати

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

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

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

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

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

Интерактивные формы и поля подписи

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

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

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

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

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

Шифрование, разрешения и вложения

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

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

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

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

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

Практика командной строки

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

prince report.html -s print.css -o report.pdf

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

prince cover.html contents.html chapters.html appendices.html -s book.css -o book.pdf

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

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

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

Пакетный выпуск и воспроизводимость

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

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

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

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

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

Сетевые ресурсы и загрузка веб-страниц

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

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

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

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

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

Интеграция с серверным приложением

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

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

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

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

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

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

Безопасная обработка недоверенного HTML

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

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

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

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

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

Установка и первый запуск в Windows

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

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

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

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

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

Работа на macOS, Linux и FreeBSD

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

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

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

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

Различие платформ не должно влиять на макет, если ресурсы одинаковы. На практике чаще всего расходятся шрифты, правила поиска файлов и регистр имён. Linux различает Logo.svg и logo.svg, тогда как некоторые файловые системы могут скрыть ошибку. Все пути в шаблоне лучше писать с точным регистром и проверять в чистой среде.

Лицензирование и служебная отметка

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

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

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

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

Диагностика сообщений и журнал

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

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

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

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

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

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

Типичные ошибки и способы исправления

PDF создаётся пустым

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

Изображения и стили не найдены

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

Текст выходит за край страницы

Ищут неразрывные строки, фиксированную ширину, большой min-width и таблицу с суммарной шириной столбцов больше области. Для кодов и адресов включают перенос, для изображения — max-width, для Flexbox — разрешают сжатие. Масштабирование всего документа используют только как крайнюю меру, потому что оно ухудшает читаемость.

Появляются большие пустые области

Временно отключают break-inside: avoid, фиксированные высоты, widows, orphans и требования начать раздел с конкретной стороны. Затем возвращают правила по одному. Частая причина — блок, который не помещается в остаток страницы и запрещён к делению; он уходит целиком, оставляя пустоту.

Колонтитул перекрывает текст

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

Номер страницы в оглавлении неверен

Проверяют уникальность id, правильность ссылки и отсутствие копий заголовка. Номер должен извлекаться target-counter после окончательной пагинации, а не быть записан вручную. Если HTML собирается частями, идентификаторы нужно делать уникальными во всём итоговом документе.

Кириллица заменена квадратами

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

Команда работает вручную, но не на сервере

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

PDF не проходит проверку профиля

Читают конкретные сообщения валидатора и журнала. Для PDF/A чаще всего исправляют встраивание шрифтов, метаданные и цветовой профиль; для PDF/X — выходное намерение, геометрию и запрещённые элементы; для PDF/UA — структуру, порядок чтения и альтернативный текст. Переключение на другой профиль без понимания не решает задачу.

Файл слишком большой

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

Рабочие сценарии

Счета и акты

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

Регулярные отчёты

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

Книги и руководства

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

Каталоги товаров

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

Сертификаты и билеты

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

Документы из XML

Семантические элементы XML получают представление через CSS. Атрибуты выводятся псевдоэлементами, разделы нумеруются счётчиками, а повторяющиеся записи превращаются в таблицы или карточки. Такой процесс сохраняет исходные данные независимыми от оформления и позволяет выпускать несколько форматов из одной структуры.

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

Программа	Лучше подходит для	Главное ограничение
Prince	Книги, отчёты и автоматический выпуск PDF из HTML/XML с развитой печатной CSS-вёрсткой	Нет визуального редактирования готового PDF
PDFreactor	Серверные Java- и веб-проекты, которым нужны HTML-to-PDF, профили и программный API	Коммерческая эксплуатация требует лицензирования
Antenna House Formatter	Сложная издательская вёрстка из XML, XSL-FO и CSS для технической документации	Высокий порог настройки профессиональных макетов
WeasyPrint	Проекты Python и открытые конвейеры для отчётов с современной печатной CSS-вёрсткой	Не исполняет JavaScript страницы
Vivliostyle CLI	Открытая веб-издательская сборка книг и публикаций на базе Chromium	Требует среды Node.js и настройки проекта
wkhtmltopdf	Поддержка существующих простых сценариев на старом WebKit	Устаревший движок ограничивает современный CSS

Prince стоит выбирать, когда исходником служит HTML или XML, а результату нужны управляемые страницы, сноски, закладки, перекрёстные ссылки и профили PDF. PDFreactor близок по серверному классу задач и удобен там, где важна его модель интеграции. Antenna House Formatter предпочтителен в издательских системах, уже построенных вокруг XSL-FO или очень сложной технической вёрстки. WeasyPrint подходит Python-проектам, которым не нужен JavaScript, Vivliostyle CLI — открытым веб-издательским процессам, а wkhtmltopdf разумно сохранять прежде всего ради совместимости с давно работающими простыми шаблонами. PDF Commander в эту таблицу не включён: он нужен для ручного изменения уже созданных PDF, тогда как перечисленные решения формируют документ из разметки.

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

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

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

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

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

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

Контроль перед выпуском

• Проверить размер листа, ориентацию, внутренние и внешние поля на первой, левой и правой страницах.
• Просмотреть места разрывов у заголовков, таблиц, рисунков, подписей, сносок и непереносимых блоков.
• Сопоставить оглавление, закладки, видимые номера и метки страниц в просмотрщике.
• Убедиться, что все шрифты и начертания встроены, кириллица отображается, а переносы используют правильный язык.
• Проверить изображения в фактическом размере, SVG, прозрачность, цветовой профиль и область обреза.
• Открыть внутренние и внешние ссылки, проверить уникальность целей и номера перекрёстных ссылок.
• Для доступного PDF пройти структуру с клавиатуры и программой чтения, проверить альтернативный текст и порядок чтения.
• Для PDF/A, PDF/X или PDF/UA выполнить профильную валидацию и разобрать каждое предупреждение.
• Для защищённого файла проверить оба пароля, разрешения, совместимость просмотрщиков и безопасную передачу.
• Сохранить команду, журнал, исходные данные и контрольную сумму результата в записи задания.

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

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