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

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

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

Как устроено преобразование PDF в HTML

pdf2htmlEX не пытается заново сочинить документ из распознанных абзацев. Сначала движок Poppler разбирает геометрию страницы, команды рисования, текстовые операторы, шрифтовые таблицы, ссылки и структуру оглавления. Затем программа формирует HTML-контейнеры страниц, CSS-классы с координатами и размерами, веб-шрифты и растровые либо векторные фоны. Благодаря этому заголовок, стоявший в PDF на определенном расстоянии от края, получает эквивалентное положение в веб-представлении. Координатная модель объясняет высокую визуальную точность и одновременно ограничивает адаптивность результата.

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

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

Первый запуск и управление именами файлов

Минимальная команда содержит только путь к PDF. Если выходное имя не задано, программа берет основу имени входного файла и добавляет расширение HTML: report.pdf превращается в report.html в рабочем каталоге. Явное второе имя удобно в пакетных сценариях, когда входные документы поступают из одной папки, а публикуемые страницы должны называться по идентификатору заказа, выпуску журнала или коду документа.

pdf2htmlEX documents/report.pdf
pdf2htmlEX documents/report.pdf public/manual.html

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

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

Выбор страниц и проверка диапазона

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

pdf2htmlEX -f 3 -l 5 handbook.pdf handbook-chapter.html

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

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

Масштаб, ширина, высота и границы листа

Параметр --zoom умножает все размеры. Значение 1,3 делает лист и текст на 30 процентов крупнее относительно базового масштаба. Это не увеличение сохранённого растра: координаты, размеры шрифтов и фон рассчитываются сразу в выбранном масштабе. Настройка полезна, когда PDF рассчитан на печать и при коэффициенте 1 дает слишком мелкий текст на мониторе.

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

pdf2htmlEX --fit-width 1024 --bg-format jpg brochure.pdf

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

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

Один HTML или каталог ресурсов

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

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

pdf2htmlEX --embed cfijo --dest-dir public handbook.pdf

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

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

Разбиение документа на отдельные страницы

--split-pages 1 создает основной HTML-контейнер и отдельный файл для каждой страницы. Шаблон --page-filename определяет имена фрагментов; знак процента с числовым спецификатором заменяется порядковым номером. Основной документ загружает фрагменты через JavaScript по мере необходимости. Такой режим особенно полезен для книг и руководств на сотни листов, где единый HTML становится тяжелым для разбора и удержания в памяти.

pdf2htmlEX --embed cfijo --split-pages 1 --dest-dir public --page-filename manual-%d.page manual.pdf

Файлы с расширением .page не являются самостоятельными веб-страницами: в них хранится разметка одного листа, рассчитанная на загрузчик pdf2htmlEX. Открытие такого фрагмента напрямую покажет неполный результат без общих стилей и навигации. Точкой входа остается основной HTML. Сервер должен отдавать фрагменты с приемлемым текстовым MIME-типом и разрешать запросы из каталога документа.

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

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

Текстовый слой: выделение, поиск и копирование

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

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

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

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

Карты ToUnicode и нечитаемый буфер обмена

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

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

Лигатуры и соединенные глифы

В типографских шрифтах сочетания fi, fl и другие пары могут храниться одним глифом. --decompose-ligature пытается разложить их на отдельные символы, что улучшает поиск и копирование. Параметр --turn-off-ligatures добавляет указание браузеру не создавать лигатуры заново. Это полезно, когда внедренное подмножество шрифта не содержит соответствующего глифа и браузер иначе оставляет пустое место или подменяет сочетание.

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

Шрифты, подмножества и точность метрик

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

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

Метрики символов в PDF и веб-движке могут различаться. pdf2htmlEX компенсирует расхождение масштабированием и позиционированием. Параметры --stretch-narrow-glyph и --squeeze-wide-glyph разрешают растягивать слишком узкие или сжимать широкие глифы. Коррекции полезны, когда строки постепенно уходят относительно фона, но чрезмерные значения заметно искажают буквы. Оценивать нужно длинные строки: на коротком заголовке ошибка ширины почти незаметна.

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

Хинтинг и четкость мелкого текста

Хинтинг привязывает контуры букв к пиксельной сетке. После извлечения и изменения шрифта исходные инструкции могут стать недействительными. Практический путь — использовать ttfautohint через --external-hint-tool=ttfautohint. Это особенно заметно на мелком тексте и дисплеях с невысокой плотностью, где без хинтинга вертикальные штрихи выглядят размыто или имеют разную толщину.

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

Ограничения на встраивание гарнитур

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

--embed-external-font относится к шрифтам, найденным вне PDF. Это помогает, когда документ ссылается на системную гарнитуру без полного встраивания. Результат зависит от доступности той же гарнитуры во время преобразования. Чтобы пакетная обработка была повторяемой, серверу задают фиксированный набор шрифтов. Иначе два узла с разным окружением создадут визуально разные страницы из одного PDF.

Изображения, векторная графика и фон страницы

Не все графические объекты становятся отдельными тегами img. pdf2htmlEX может собрать линии, заливки, прозрачности и изображения в единый фон страницы. Это гарантирует порядок наложения и снижает риск расхождения между браузерами. Параметр --process-nontext управляет обработкой нетекстовых объектов. Если он выключен, схема, рамка таблицы или фотография может исчезнуть, хотя текст останется на месте.

--bg-format выбирает формат фона. PNG сохраняет четкие линии, прозрачность и мелкий текст без артефактов, но на цветных сканах получается большим. JPEG экономит место на фотографиях и журнальных разворотах, однако вокруг букв и тонких линий появляются ореолы. SVG способен сохранить векторную природу части графики, но сложные эффекты и совместимость требуют проверки. Универсального лучшего формата нет.

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

pdf2htmlEX --process-nontext 1 --bg-format png --hdpi 288 --vdpi 288 atlas.pdf

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

Закладки, ссылки и переходы

Дерево Outline в PDF преобразуется в боковое оглавление, если включена обработка структуры. Параметр --process-outline позволяет оставить или исключить этот блок, а --outline-filename задает имя отдельного файла при внешнем хранении. Многоуровневые разделы сохраняют вложенность. Если у PDF нет настоящих закладок, визуальное содержание на первой странице не превращается в навигацию автоматически: программа не распознает заголовки по размеру шрифта.

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

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

Режим fallback для трудных документов

--fallback 1 формирует страницу как изображение с наложенным скрытым текстом. Внешний вид максимально близок к PDF, потому что вся печатная композиция попадает в растр. Скрытый слой сохраняет поиск и приблизительное выделение. Режим помогает с Type 3-шрифтами, необычными прозрачностями, масками, сложными паттернами и файлами, где обычное разделение текста и фона дает заметные дефекты.

Цена fallback — объем и качество взаимодействия. Каждая страница содержит крупное изображение, поэтому длинное руководство загружается медленнее. Выделение может не совпадать с видимыми буквами, а копирование наследует проблемы текстового слоя PDF. Масштабирование сверх подготовленного разрешения выявляет пиксели. Поэтому fallback применяют точечно после проверки обычного режима, а не как универсальный пресет.

pdf2htmlEX --fallback 1 difficult-document.pdf

Сравнивать режимы лучше при одинаковом масштабе и в нескольких браузерах. Обычный вывод оценивают по совпадению шрифтов, линий и рисунков; fallback — по четкости растра, размеру и точности скрытого текста. Если дефект встречается на одной странице, ее можно преобразовать отдельно, но объединение потребует ручной работы с навигацией. Проще сначала попробовать другой формат фона, DPI и обработку Type 3.

Type 3, символьные и чертежные шрифты

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

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

Многоязычные документы и данные Poppler

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

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

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

Скрытый, перекрытый и дублированный текст

Некоторые PDF содержат невидимый OCR-слой под сканом, повторяющиеся символы для имитации жирности или текст, перекрытый белым прямоугольником. Если все объекты безусловно перенести в HTML, скрытые фрагменты могут стать видимыми или попадать в выделение дважды. --correct-text-visibility включает анализ видимости, а --covered-text-dpi задает разрешение, с которым оценивается перекрытие.

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

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

Пароли, ограничения и шифрование

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

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

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

Печать HTML-результата

Параметр --printing добавляет стили, рассчитанные на печать из браузера. Однако путь PDF → HTML → печать не гарантирует получение исходного PDF байт в байт. Браузер применяет собственные поля, масштаб, разбиение и цветовые правила. Если цель — просто напечатать документ, надежнее печатать PDF. Печатные стили нужны, когда HTML уже встроен в издательскую оболочку и требуется приемлемая бумажная копия.

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

Размер файлов и скорость первой загрузки

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

Для PNG-фонов сравнивают переход на JPEG на страницах с фотографиями, но оставляют PNG для схем и текста. Для шрифтов проверяют, не повторяются ли почти одинаковые подмножества. Для разметки применяют HTTP-сжатие gzip или Brotli: позиционные классы и повторяющиеся числа сжимаются особенно хорошо. Серверное сжатие уменьшает передачу, не меняя файлы и визуальный результат.

--tmp-file-size-limit ограничивает объем временных данных. Слишком малое значение приводит к ошибкам на больших страницах; слишком большое позволяет одному заданию занять весь диск. В пакетной системе лимит согласуют со свободным местом и параллелизмом. После аварийного завершения проверяют временный каталог и применяют --clean-tmp, если остались промежуточные файлы.

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

Пакетная обработка и повторяемые сценарии

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

set -euo pipefail
mkdir -p public
for pdf in incoming/*.pdf; do
  base=$(basename "$pdf" .pdf)
  mkdir -p "public/$base"
  pdf2htmlEX --split-pages 1 --dest-dir "public/$base" "$pdf" "$base.html"
done

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

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

Повторяемость требует фиксированного контейнера или образа окружения с Poppler, FontForge, poppler-data и шрифтами. Иначе изменение системной библиотеки способно изменить метрики и фон. Контрольный набор PDF прогоняют после любого изменения, сравнивают размеры, снимки и извлеченный текст. Хеш HTML слишком чувствителен к служебным различиям, поэтому его дополняют визуальным сравнением ключевых страниц.

Встраивание в серверный процесс

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

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

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

Кеширование результата привязывают к хешу входного PDF и точному набору параметров. Один файл с --fit-width 1024 и --zoom 1.3 дает разные наборы, поэтому хеш только PDF недостаточен. В ключ включают формат фона, DPI, режим внедрения, диапазон страниц и параметры текста. Такой кеш экономит ресурсы и не смешивает публикации с разным качеством.

Научные статьи, формулы и технические таблицы

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

Таблицы сохраняют линии и расположение ячеек, как видно в технической документации. При этом DOM не обязан содержать элемент table, строки и ячейки. Экранный считыватель не получит структурные связи заголовков, а данные нельзя надежно выгрузить в CSV простым разбором HTML. Для аналитического извлечения используют специализированный инструмент; pdf2htmlEX выбирают для публикации визуальной страницы.

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

Журналы, каталоги и сложная композиция

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

Формат фона выбирают по содержимому выпуска. Фотографический журнал выигрывает от JPEG, технический каталог с мелкими чертежами — от PNG или SVG. Разделение страниц снижает время открытия обложки. Оглавление PDF становится основной навигацией, поэтому его качество исправляют до преобразования: короткие осмысленные заголовки удобнее длинных автоматически созданных строк.

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

Сканы и необходимость OCR

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

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

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

Проверка результата перед публикацией

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

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

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

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

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

Программа	Лучше подходит для	Главное ограничение
pdf2htmlEX	Публикации PDF с близкой геометрией, выделяемым текстом и встроенными шрифтами	Фиксированные координаты плохо перестраиваются под узкий экран
Poppler pdftohtml	Извлечения текста, простого HTML и XML для последующей обработки	Сложные журнальные и технические страницы воспроизводятся менее точно
MuPDF mutool convert	Быстрой конвертации и извлечения в нескольких текстовых и графических форматах	HTML ориентирован на текст, а не на копию каждого элемента макета
Mozilla PDF.js	Встраивания полноценного просмотрщика исходного PDF в веб-приложение	Документ остается PDF и требует интерфейса просмотрщика
Apryse PDF2HTML	Коммерческих конвейеров и интеграции через поддерживаемый SDK	Проприетарная лицензия и зависимость от коммерческого комплекта
PyMuPDF	Программного извлечения текста и HTML из Python с доступом к объектам страниц	Для точной издательской оболочки требуется собственный код

pdf2htmlEX выбирают, когда HTML должен выглядеть как печатный оригинал и сохранить текстовый слой. pdftohtml и PyMuPDF удобнее, если данные будут разбираться и перестраиваться программно. MuPDF подходит для быстрого многоформатного конвейера. PDF.js предпочтителен, когда нужно показать сам PDF с привычной панелью, не превращая его в набор веб-страниц. Apryse оправдан там, где важны коммерческая поддержка и интеграция с корпоративным SDK. PDF Commander правит содержимое PDF до публикации, но не заменяет конвертер в HTML.

Практические пресеты

Один файл для передачи

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

pdf2htmlEX --zoom 1.2 short-document.pdf short-document.html

Большое руководство на сайте

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

pdf2htmlEX --embed cfijo --split-pages 1 --fit-width 1200 --dest-dir manual --page-filename page-%d.page manual.pdf index.html

Фотографический каталог

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

pdf2htmlEX --bg-format jpg --fit-width 1400 catalog.pdf

Проблемная страница

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

pdf2htmlEX -f 27 -l 27 --process-nontext 1 --hdpi 288 --vdpi 288 manual.pdf page-27.html
pdf2htmlEX -f 27 -l 27 --fallback 1 manual.pdf page-27-fallback.html

Запуск AppImage, DEB и Alpine-пакета

AppImage рассчитан на запуск одного файла в 64-разрядной Linux-среде. После загрузки ему дают право исполнения и вызывают с параметрами pdf2htmlEX. Если система запрещает FUSE, образ распаковывают штатным механизмом AppImage либо используют окружение, где FUSE разрешен. Ошибка Permission denied обычно означает отсутствие исполняемого бита или запрет монтирования, а не повреждение PDF.

chmod +x pdf2htmlEX-*.AppImage
./pdf2htmlEX-*.AppImage --help
./pdf2htmlEX-*.AppImage input.pdf output.html

DEB передают менеджеру пакетов с указанием пути к файлу. Такой способ регистрирует пакет и зависимости в системе. Если менеджер сообщает о несовместимой архитектуре, проверяют x86-64. Если не хватает библиотек, нельзя бездумно скачивать отдельные .so с посторонних сайтов; безопаснее использовать совместимый контейнер, AppImage или пакеты своего дистрибутива.

sudo apt install ./pdf2htmlEX-*.deb
pdf2htmlEX --help

Alpine-пакет предназначен для среды musl и часто используется при построении контейнера. Его содержимое размещают по путям, ожидаемым сборкой, и добавляют необходимые библиотеки. Копирование двоичного файла из Alpine в Ubuntu или наоборот не гарантирует запуск из-за различий libc. Архитектура и базовая система должны совпадать с именем пакета.

Для Windows не предоставлена сопоставимая официальная готовая сборка. Практический путь — WSL2 или Linux-контейнер. Сторонние Win32-пакеты связаны с иным набором Poppler и FontForge, могут распознавать не все описанные параметры и не подходят как надежная основа. Синтаксис команды остаётся полезным, но исполняемый файл следует получать со страницы официальных пакетов.

Проверка окружения перед большой конвертацией

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

pdf2htmlEX --help
pdf2htmlEX --version
mkdir -p test-out
pdf2htmlEX --dest-dir test-out --embed cfijo sample.pdf sample.html

Ключ --embed cfijo оставляет CSS, шрифты, изображения, JavaScript и оглавление отдельными файлами. Нижний регистр отключает встраивание соответствующего ресурса, верхний включает его. Такой тест удобнее монолитного HTML: по содержимому каталога видно, на каком этапе пропал объект. Если не создан шрифт, проверяют сообщения FontForge и права на запись; если отсутствуют фоны, смотрят --process-nontext и формат изображений; если оболочка страницы открывается без содержимого, проверяют JavaScript и шаблон манифеста.

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

pdf2htmlEX --data-dir /usr/local/share/pdf2htmlEX input.pdf output.html
pdf2htmlEX --debug 1 --clean-tmp 0 input.pdf output.html

Для документов с китайскими, японскими и корейскими шрифтами проверяют наличие таблиц Poppler. В сборках, где предусмотрен --poppler-data-dir, путь задают явно. Признак проблемы — квадраты, пустые места или предупреждения о недоступной CMap при том, что сам PDF отображается в обычном просмотрщике. Установка соответствующего набора данных и повторная конвертация обычно полезнее замены шрифта в созданном HTML, потому что неверное сопоставление возникает до создания текстового слоя.

Дополнительное хинтование шрифтов проверяют отдельно. В документации для него предлагается внешний инструмент ttfautohint. Его подключают через --external-hint-tool, а затем сравнивают мелкий текст при масштабе 100% в нескольких браузерах. Хинтование влияет на четкость и посадку глифов, но не исправляет неверную кодировку, отсутствующий ToUnicode или ошибочную геометрию исходного PDF.

pdf2htmlEX --external-hint-tool ttfautohint --font-format woff input.pdf output.html

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

HTML открывается пустым

Пустая страница не всегда означает, что конвертация ничего не создала. Сначала проверяют размер HTML и наличие элементов страниц в исходном коде. При раздельных ресурсах открытие файла напрямую через протокол file: может блокировать загрузку страниц или сценариев; результат размещают на тестовом HTTP-сервере и повторяют проверку. Если контейнеры страниц есть, но их высота равна нулю, ищут недоступный CSS. Если HTML почти пуст, включают --debug 1 и проверяют манифест, пароль, диапазон страниц и сообщения Poppler.

cd test-out
python3 -m http.server 8080

Текст виден, а рисунки и линии исчезли

Такой результат характерен для отключённой обработки нетекстовых объектов или для неверного ожидания от векторного слоя. Устанавливают --process-nontext 1, возвращают --embed-image 1 либо убеждаются, что вынесенные изображения действительно скопированы рядом с HTML. Для сложной векторной страницы пробуют PNG-фон и повышенный DPI. Если SVG превышает допустимое число узлов, параметр --svg-node-count-limit позволяет перевести слишком сложный фон в растр вместо создания тяжёлого SVG.

pdf2htmlEX --process-nontext 1 --bg-format png --hdpi 216 --vdpi 216 input.pdf output.html
pdf2htmlEX --bg-format svg --svg-node-count-limit 5000 input.pdf output.html

Шрифт заменён, строки съехали

Сначала определяют, был ли шрифт встроен в PDF. Для встроенного шрифта проверяют, создан ли WOFF и загружается ли он без ошибки. Для невстроенного — параметр --embed-external-font: при значении 1 найденный системный шрифт можно включить в результат, при 0 браузер ищет гарнитуру самостоятельно. Второй вариант экономит место, но метрики локальной замены могут отличаться, из-за чего строки становятся длиннее или короче. Подмена семейства в CSS на визуально похожее не гарантирует совпадения ширины глифов.

Когда отдельные символы слишком узкие или широкие относительно метрик PDF, используют --stretch-narrow-glyph и --squeeze-wide-glyph. Эти параметры не являются универсальным улучшением: один растягивает узкие глифы, другой сжимает широкие. Их проверяют на странице с проблемной строкой, а не включают сразу для всей библиотеки. Для мелкого текста дополнительно уменьшают чрезмерный --font-size-multiplier, если браузер зависает или округляет размеры не так, как ожидается.

Копирование даёт неверные символы

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

pdf2htmlEX -f 1 -l 1 --tounicode -1 input.pdf visual.html
pdf2htmlEX -f 1 -l 1 --tounicode 0 input.pdf balanced.html
pdf2htmlEX -f 1 -l 1 --tounicode 1 input.pdf unicode.html

Слитные слова или лишние пробелы регулируют через --space-threshold. Порог задаётся как доля размера шрифта: слишком малое значение создаёт пробелы внутри слова, слишком большое склеивает соседние слова. Параметр --space-as-offset 1 может уменьшить число текстовых элементов, но при плохой кодировке способен потерять символы. Любое изменение проверяют на строках с узкими буквами, цифрами, кернингом и несколькими пробелами.

Страница обрезана или получила лишние поля

По умолчанию используется CropBox. Некоторые PDF содержат MediaBox большего размера, а видимая область определена CropBox; другие, наоборот, имеют ошибочно заданный CropBox. Переключение --use-cropbox 0 показывает полный MediaBox. Если после этого появляются метки реза и служебные поля, исходный выбор был верным. Если возвращается потерянный фрагмент схемы, проблема находилась в границах страницы, а не в масштабе.

Результат слишком большой

Сначала выясняют, что занимает место: встроенные фоновые изображения, шрифты, CSS или повторяющиеся данные URI. Команда с раздельными ресурсами делает структуру измеримой. Для фотографических фонов применяют JPEG, для текста и тонких линий обычно оставляют PNG или SVG. Уменьшение DPI снижает вес растра, но может сделать формулы и мелкие подписи нечёткими. Отключение поддержки печати через --printing 0 сокращает CSS, однако после этого нельзя ожидать точного печатного представления.

pdf2htmlEX --embed cfijo --printing 0 --bg-format jpg --hdpi 144 --vdpi 144 --dest-dir web input.pdf output.html
du -ah web | sort -h | tail

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

Процесс расходует слишком много памяти или долго не заканчивается

Большие планы, чертежи и страницы с тысячами векторных объектов проверяют по одной. Высокие --hdpi и --vdpi, SVG без лимита узлов, встроенные фоновые данные и параллельный запуск нескольких заданий резко повышают нагрузку. Практическое решение — ограничить число одновременных процессов, задать отдельный временный каталог с достаточным местом, использовать диапазоны страниц и собрать результат после успешных частей. Убийство процесса по одному только времени без сохранения журнала затрудняет диагностику.

mkdir -p /var/tmp/pdf2htmlex-job
TMPDIR=/var/tmp/pdf2htmlex-job pdf2htmlEX -f 40 -l 60 --tmp-dir /var/tmp/pdf2htmlex-job input.pdf part.html

Оглавление или ссылки отсутствуют

Для закладок должны быть включены --process-outline 1 и встраивание оглавления либо отдельный файл, заданный через --outline-filename. Если исходный PDF не содержит структуры закладок, программа не создаёт её по крупным заголовкам. Аннотации обрабатываются отдельно параметром --process-annotation; формы — --process-form. Поэтому наличие кликабельного URL, закладки и поля формы проверяют как три разные функции.

pdf2htmlEX --process-outline 1 --embed-outline 0 --outline-filename outline.html input.pdf output.html
pdf2htmlEX --process-annotation 1 --process-form 1 input.pdf interactive.html

Firefox тормозит на странице с мелким текстом

pdf2htmlEX применяет множитель размера шрифта, чтобы обойти округление очень маленьких значений в браузерах. Слишком большой --font-size-multiplier способен ухудшить работу некоторых версий Firefox. Для проблемной страницы пробуют меньшее значение, например 2, и проверяют совпадение строк. Нельзя компенсировать зависание простым удалением трансформаций из CSS: это разрушает рассчитанные координаты текста.

Диагностика по слоям

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

Режим доказательства --proof помогает сопоставить текстовый слой с фоном. При положительном значении текст рисуется и в текстовом слое, и на фоне; при значении 2 варианты различаются цветом. Для растрового фона полезен повышенный DPI, иначе контрольные надписи сами становятся нечёткими. Такой HTML предназначен для диагностики и не публикуется как конечный результат.

pdf2htmlEX -f 12 -l 12 --proof 2 --hdpi 288 --vdpi 288 input.pdf proof.html

Если видимые буквы совпадают, но выделение проходит на несколько пикселей выше или ниже, исследуют вертикальную погрешность --veps. Горизонтальные сдвиги связаны с --heps, метриками шрифта и пробелами. Эти значения задают допустимую величину перемещения при оптимизации HTML. Слишком свободный допуск уменьшает число элементов, но может ухудшить точность; слишком строгий сохраняет больше позиционных фрагментов и увеличивает разметку.

Параметр --optimize-text 1 пытается сократить количество HTML-элементов для текста. Он полезен, когда документ состоит из обычных строк и результат прошёл визуальное сравнение. При нарушении расположения букв оптимизацию отключают первой. Исправлять последствия десятками ручных CSS-правок нерационально: повторная конвертация с --optimize-text 0 сохраняет воспроизводимость.

Что можно менять в созданном HTML

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

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

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

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

Адаптация результата к небольшому экрану

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

Для каталога страниц можно показывать миниатюры и загружать выбранный лист отдельно. Режим --split-pages 1 помогает не помещать весь документ в память браузера сразу. Шаблон --page-filename page-%04d.page создаёт предсказуемые имена, а оболочка или собственный загрузчик запрашивает нужные фрагменты. При таком размещении обязательно тестируют переходы из оглавления и прямое открытие страницы.

pdf2htmlEX --split-pages 1 --page-filename page-%04d.page --embed cfijo --dest-dir publication input.pdf index.html

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

Доступность, поиск и смысловая структура

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

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

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

Безопасность обработки и публикации

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

Пароль нельзя помещать в общий журнал команд или URL задания. Параметры --owner-password и --user-password могут оказаться в истории оболочки и списке процессов. Для контролируемой системы используют временный закрытый сценарий, минимизируют время жизни секрета и очищают журнал. --no-drm 1 применяют только при наличии законного разрешения; техническая возможность не отменяет ограничений документа.

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

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

Как подобрать параметры без бесконечных проб

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

Первая группа — геометрия: CropBox, масштаб, ширина и высота. Вторая — текст: ToUnicode, пробелы, лигатуры, оптимизация и видимость. Третья — шрифты: внешние гарнитуры, формат, хинтование и коррекция ширины глифов. Четвёртая — фон: формат, DPI, SVG и обработка нетекстовых объектов. Пятая — упаковка: встраивание, раздельные ресурсы, страницы и печать. Такой порядок не смешивает причины.

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

Практический рабочий процесс от PDF до публикации

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

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

На третьем этапе решают, нужен один переносимый HTML или каталог с кешируемыми ресурсами. Для короткой инструкции удобен монолитный файл; для книги или каталога — раздельные шрифты, фоны и страницы. Результат открывают через тот же HTTP-сервер и с теми же заголовками, которые будут использоваться после размещения. Проверяют Chrome, Firefox и хотя бы один мобильный браузер.

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

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