Обзор pdf2htmlEX: точное преобразование PDF в HTML из командной строки
pdf2htmlEX — специализированный консольный конвертер, который преобразует PDF в HTML с акцентом на сохранение визуальной геометрии страницы, шрифтов и доступного для выделения текста. Его важно не путать с веб-сервисами «PDF to HTML», библиотеками-обёртками с похожими названиями и отдельным Android-портом: предмет этого обзора — исходный C++-проект, созданный Lu Wang и сегодня развиваемый в общественном репозитории pdf2htmlEX/pdf2htmlEX. У проекта необычный статус: исходный код получал заметные обновления и слияния в 2024–2025 годах, но последняя опубликованная запись GitHub Releases остаётся v0.18.8.rc1 от 30 июня 2020 года, тогда как текущая конфигурация ветки master обозначает версию 0.18.8.rc2. Поэтому pdf2htmlEX разумно рассматривать как технический open-source-инструмент для контролируемых рабочих процессов, а не как обычное настольное приложение с регулярными установщиками и гарантированным циклом релизов.
| Параметр | Актуальное состояние |
|---|---|
| Тип | Консольный конвертер PDF → HTML |
| Разработчик | Создан Lu Wang; текущий репозиторий поддерживается сообществом pdf2htmlEX |
| Последний опубликованный Release | v0.18.8.rc1, 30 июня 2020 года |
| Версия в текущей конфигурации master | 0.18.8.rc2 |
| Основная платформа сборки | Linux с Debian/Ubuntu-подобной системой; также возможна контейнеризация |
| Вход | |
| Выход | HTML, при необходимости с отдельными CSS, шрифтами, изображениями и страницами |
| Лицензия | GPLv3 или более поздняя версия |
| Цена и аккаунт | Бесплатно, без подписки и обязательной регистрации |
| Облачная обработка | Не требуется: стандартный сценарий выполняется локально |
Скачать pdf2htmlEX
Новейшая версия для Виндовс, macOS и Линукс. Удобный редактор PDF под российские реалии.
Безопасная точка получения — официальный репозиторий pdf2htmlEX/pdf2htmlEX и его раздел Releases. Сторонние сайты с готовыми бинарными файлами здесь особенно нежелательны: у проекта давно не было нового формального релиза, поэтому легко встретить сборку с неясным происхождением, старым Poppler или изменёнными зависимостями. На официальной странице релизов последней опубликованной записью остаётся v0.18.8.rc1; она содержит подготовленные артефакты эпохи Ubuntu 18.04/20.04 и Alpine 3.12, а потому сама дата публикации должна восприниматься как важное предупреждение о совместимости.
Текущая ветка master заметно новее релизного пакета. В ней конфигурация сборки задаёт pdf2htmlEX 0.18.8.rc2, Poppler 24.06.1 и FontForge 20230101. В июле 2025 года в репозиторий были слиты изменения для Ubuntu 22.04, обновлённого OpenJPEG2, частичной поддержки Windows в обработчике сигналов и современного контейнерного сценария на Debian Bookworm с multi-arch/ARM64. Эти факты не превращают master в «стабильный релиз», но показывают, что текущий код нельзя оценивать только по дате v0.18.8.rc1.
Какой вариант выбирать
- Для воспроизводимой серверной установки практичнее собирать фиксированный commit из официального репозитория или собственный контейнер, чтобы версия исходников и зависимостей была известна заранее.
- Для разовой проверки на Linux можно использовать официальный старый AppImage или пакет из Releases, но только после оценки совместимости с вашей системой; это не современная универсальная сборка.
- Для Windows и macOS корректнее ориентироваться на OCI-контейнер через Docker/Podman либо отдельную контролируемую сборочную среду. Наличие отдельных изменений для Windows не означает существования актуального официального Windows-инсталлятора.
Что такое pdf2htmlEX
pdf2htmlEX — программа командной строки для преобразования фиксированной PDF-разметки в HTML, CSS, веб-шрифты и изображения. Её ключевая идея отличается от простого извлечения текста: вместо превращения документа в обычную последовательность абзацев конвертер старается воспроизвести координаты, размеры шрифтов, трансформации, изображения и другие элементы страницы так, чтобы результат в браузере визуально был близок к исходному PDF.
Первоначальный проект создал Lu Wang. Репозиторий coolwanglu/pdf2htmlEX был архивирован 9 декабря 2018 года и помечен как прекративший активную разработку. Современный pdf2htmlEX/pdf2htmlEX — общественная линия продолжения, собравшая исправления из форков; её история содержит более поздние изменения. Поэтому архивирование исходного upstream не означает исчезновения проекта целиком.
По назначению это не PDF-редактор, не OCR-пакет, не просмотрщик и не облачный API. Программа получает готовый PDF и создаёт веб-представление. Если задача — просто читать документы, удобнее использовать обычный просмотрщик. Если требуется распознавание сканов, нужен OCR-инструмент, например ABBYY FineReader. pdf2htmlEX наиболее уместен, когда уже существующий PDF нужно опубликовать в браузере с сохранением макета.
Основные функции pdf2htmlEX
Точный HTML-слой текста
Программа извлекает шрифты из PDF, преобразует их в веб-формат и размещает текст в HTML с координатами и стилями. Благодаря этому текст обычно остаётся выделяемым и копируемым, в отличие от сценария «отрендерить каждую страницу одной картинкой». Сохранение копируемости зависит от качества кодировок внутри самого PDF: если ToUnicode-карты повреждены или противоречат данным шрифта, видимый текст может выглядеть правильно, а копирование давать неверные символы.
Параметр —tounicode управляет картой символов: 0 — автоматический режим, 1 — принудительное использование ToUnicode из PDF, -1 — приоритет визуальной карты с риском ухудшить копирование. Это настройка существующего текстового слоя, а не OCR.
Встраивание ресурсов и единый HTML-файл
CSS, шрифты, изображения, JavaScript и оглавление по умолчанию можно встроить в один HTML. Их также разрешено вынести наружу параметрами —embed-css, —embed-font, —embed-image, —embed-javascript, —embed-outline или строкой —embed — например, для отдельного кэширования и аудита ресурсов.
Разделение документа по страницам
Ключ —split-pages 1 сохраняет содержимое отдельных страниц в самостоятельных файлах. С помощью —page-filename задаётся шаблон имени, включая числовой заполнитель вроде page%03d.page. Этот режим рассчитан на ленивую или динамическую загрузку больших документов и обычно требует JavaScript и корректной раздачи файлов веб-сервером. Для полностью автономного статического файла лучше оставить разделение выключенным.
Изображения, фон и сложная графика
Невыражаемые как обычный HTML объекты рендерятся в графический фон. Поддерживаются PNG, JPG и SVG; конкретный набор сообщает pdf2htmlEX -v. Для SVG предусмотрены —svg-node-count-limit и —svg-embed-bitmap.
Ссылки, оглавление, печать и ограниченная обработка форм
Проект поддерживает ссылки и outline/bookmarks. Печать включена по умолчанию и может быть отключена, если соответствующие правила CSS не нужны. Аннотации по умолчанию не обрабатываются (—process-annotation 0). Обработка форм тоже выключена и, согласно справке, ориентирована на текстовые поля и radio buttons, поэтому считать pdf2htmlEX полным переносчиком интерактивных PDF-форм нельзя.
Выбор диапазона и геометрии
Параметры —first-page и —last-page ограничивают диапазон страниц. Масштаб задаётся через —zoom или ограничения —fit-width и —fit-height. По умолчанию используется CropBox, а —use-cropbox 0 переключает расчёт на MediaBox. Для растровых элементов задаются горизонтальное и вертикальное DPI; это влияет на качество и объём фоновых изображений, но не превращает текстовый слой в растр.
Режимы совместимости и диагностики
—fallback 1 увеличивает размер ради совместимости. —proof накладывает текстовый слой на фон для диагностики, —debug выводит служебные данные, а —clean-tmp 0 сохраняет промежуточные файлы. Эти режимы лучше включать только для разбора конкретного дефекта.
Интерфейс и удобство использования
У pdf2htmlEX нет собственного графического окна, панели миниатюр, меню экспорта или мастера настроек. Интерфейс — командная строка и файловая система. Пользователь выбирает входной PDF, параметры и имя результата, после чего проверяет созданный HTML в браузере. Это делает программу неудобной для человека, который ожидает визуальный редактор, но предсказуемой для скриптов, серверных задач и пакетной обработки.
Логика работы
Базовый вызов выглядит как pdf2htmlEX document.pdf. Если выходное имя не указано, программа создаёт document.html в текущем каталоге. Более сложные сценарии наращиваются флагами: диапазон страниц, каталог назначения, встраивание ресурсов, фон, формы, аннотации, кодировки и режим отладки. То есть «навигация» строится не вокруг экранов интерфейса, а вокруг параметров запуска.
Порог освоения выше, чем у Adobe Acrobat Pro или другого GUI-конвертера: необходимо понимать shell, относительные пути, права файлов и устройство HTML-ресурсов. Компенсация — возможность хранить точную команду в системе контроля версий и повторять её на одинаковых документах без ручных кликов.
Язык интерфейса
Отдельной русской локализации командной строки нет: названия параметров и сообщения диагностики англоязычные. Это не мешает обработке русскоязычных PDF, поскольку язык содержимого определяется шрифтами и картами символов исходного документа, а не языком команд.
Поддерживаемые форматы и совместимость
Входной формат основного конвертера — PDF. Он не является универсальным импортёром DOCX, ODT, EPUB, TIFF или офисных файлов. Если исходник существует в редактируемом формате, часто правильнее экспортировать HTML из исходного приложения, чем сначала фиксировать макет в PDF, а затем восстанавливать его координаты.
Основной выход — HTML. В зависимости от настроек рядом могут появляться CSS, JavaScript, WOFF или другой выбранный формат шрифта, изображения и файлы отдельных страниц. Формат шрифта задаётся через —font-format; справка указывает WOFF как значение по умолчанию. Внешние ресурсы можно отключить или встроить, поэтому результат бывает как монолитным, так и многокомпонентным.
Что переносится хорошо
- позиционированный текст и его визуальные параметры;
- встроенные шрифты с преобразованием для веба;
- растровые изображения и значительная часть векторной графики через фоновые слои;
- гиперссылки и outline;
- сложные фиксированные макеты, включая многоколоночные страницы и математические материалы, если исходный PDF корректен.
Где есть ограничения
Type 3 fonts имеют отдельный параметр —process-type3 и в man page названы экспериментальной функцией; без него соответствующий текст рендерится как изображение. Формы и аннотации требуют явного включения и не гарантируют перенос всей интерактивности PDF. Скан без текстового слоя не превратится в распознанный документ: OCR в pdf2htmlEX отсутствует.
Совместимость с браузерами нельзя оценивать одной галочкой. Проект исторически ориентирован на современные браузеры и использует HTML5/CSS/JavaScript, но официальная документация не задаёт актуальную матрицу версий Chrome, Firefox, Safari или Edge. Для производственной публикации итог нужно проверять именно в тех браузерах, которые входят в требования проекта.
Производительность и стабильность
У проекта нет актуальной официальной таблицы производительности, поэтому корректно говорить о механике нагрузки, а не о вымышленных секундах на страницу. pdf2htmlEX анализирует PDF, извлекает и преобразует шрифты, формирует текстовые элементы, а сложные объекты рендерит как фон. На больших документах одновременно растут время CPU, объём временного каталога и размер результата.
Что сильнее всего влияет на ресурсы
- высокое DPI фоновых изображений;
- режим —correct-text-visibility 2, при котором частично перекрытый текст может уходить в фоновый слой с повышенным DPI;
- —fallback 1, увеличивающий итоговый размер ради совместимости;
- встраивание всех ресурсов в один HTML, которое упрощает передачу, но может создавать очень крупный файл;
- сложные SVG-фоны без ограничения числа узлов;
- большое число уникальных встроенных шрифтов и их подмножеств.
Параметр —tmp-file-size-limit ограничивает суммарный размер временных файлов в килобайтах. Значение -1 означает отсутствие лимита и является значением по умолчанию. Для серверной пакетной обработки это важная настройка: ограничение диска лучше задавать явно на уровне контейнера или файловой системы, а не надеяться только на параметры приложения.
README общественной ветки предупреждает о возможных дубликатах шрифтов и фоновых изображений. Для массовой публикации допустима дедупликация, но только с визуальной регрессионной проверкой: «лишние» элементы могут участвовать в точном позиционировании.
Стабильность и жизненный цикл
Главный эксплуатационный риск — не падения как таковые, а разрыв между живущей веткой исходников и редкими релизами. Репозиторий принимал изменения в 2025 году, но готовый Release не обновлялся с 2020-го. Для продакшена разумно закреплять конкретный commit, версию контейнера и контрольные PDF-примеры, а не автоматически тянуть master при каждом развёртывании.
Лицензирование и версии
pdf2htmlEX распространяется бесплатно с открытым исходным кодом. Основной пакет лицензирован по GPLv3 или любой более поздней версии; в отдельных ресурсных каталогах могут применяться более мягкие условия. Подписки, платной редакции, ограниченного бесплатного режима и пробного периода у основного проекта нет. Регистрация аккаунта для локального запуска не требуется.
Последняя формальная запись Releases — v0.18.8.rc1, тогда как текущий buildScripts/versionEnvs задаёт 0.18.8.rc2. Поэтому rc2 — версия нынешней сборочной конфигурации, но не новый опубликованный Release.
Коммерческое использование и шрифты
GPL сама по себе не запрещает коммерческое использование, однако публикация результата может затрагивать отдельные права на содержимое PDF и шрифты. Официальный сайт проекта прямо предупреждает, что извлечение, преобразование или распространение шрифтов может быть незаконным в зависимости от лицензии и законодательства. Если HTML будет размещён публично, нужно проверять права на веб-встраивание каждого коммерческого шрифта, а не считать наличие шрифта внутри PDF автоматическим разрешением на дальнейшее распространение.
Системные требования
Проект не публикует современный минимальный объём RAM, частоту CPU или точный список поддерживаемых версий дистрибутивов. Подтверждённый путь сборки ориентирован на Debian/Apt-среду. Скрипт buildInstallLocallyApt устанавливает инструменты разработки, затем загружает и статически собирает совместимые версии Poppler и FontForge, после чего устанавливает pdf2htmlEX в /usr/local/bin.
Linux и сборка из исходников
Текущий скрипт инструментов использует sudo, wget, git, pkg-config, Ruby, autoconf, libtool, CMake, make, GCC/G++, dpkg/dpkg-dev, gettext, OpenJDK 17 headless и jq. Среди библиотек сборки присутствуют Cairo, PNG, JPEG, libxml2 и OpenJPEG2. В конфигурации master зафиксированы Poppler 24.06.1 и FontForge 20230101. Это объясняет, почему установка заметно тяжелее типичного «apt install программа»: проект тесно связан с конкретными API двух внешних библиотек.
Контейнеры
Текущий Dockerfile основан на Debian Bookworm, запускает официальный мета-скрипт сборки и задаёт pdf2htmlEX как ENTRYPOINT. Изменение 2025 года добавляло multi-arch/ARM64-подход. Нужен Docker/Podman или другой OCI-runtime и место на сборку Poppler/FontForge.
Windows и macOS
Актуальные нативные установщики для Windows и macOS не подтверждены. Патч SignalHandler для Windows улучшает переносимость исходников, но не заменяет поддерживаемый инсталлятор; наиболее воспроизводимым остаётся Linux-контейнер или собственная сборка.
Преимущества и недостатки pdf2htmlEX
Плюсы и минусы
Плюсы ✔️
- Фокус на визуальной точности. Текст сохраняется как HTML-слой с координатами, а сложная графика дополняется фоном.
- Автономный результат. Можно получить один HTML со встроенными стилями, шрифтами, изображениями и JavaScript.
- Гибкое управление ресурсами. Те же компоненты можно вынести во внешние файлы и организовать собственную структуру публикации.
- Поддержка сложных PDF. Проект изначально рассчитан на документы с необычной типографикой, формулами и фиксированной журнальной вёрсткой.
- Автоматизация. CLI удобно встраивается в shell-скрипты, CI и серверные очереди.
- Нет обязательного облака. Конвертация выполняется локально и не требует загрузки документа стороннему сервису.
Минусы ❌
- Редкие официальные релизы. Готовая опубликованная сборка заметно отстаёт от master.
- Сложная сборка. Проект зависит от конкретных версий Poppler и FontForge и собирает их специально.
- Нет GUI. Для единичных офисных задач командная строка менее удобна, чем Sejda PDF или настольный редактор.
- Нет OCR. Сканированные страницы без текстового слоя останутся графикой.
- HTML не становится семантическим документом автоматически. Точная визуальная раскладка часто означает множество позиционированных элементов, а не чистые заголовки и абзацы.
- Нужно учитывать лицензии шрифтов. Встроенный в PDF шрифт не всегда разрешено публиковать как webfont.
Карта критических зависимостей
| Зависимость | Зачем нужна | Что произойдёт при проблеме | Практический контроль |
|---|---|---|---|
| Poppler | Разбор и рендеринг PDF | Несовместимая версия может нарушить сборку или обработку новых PDF | Закреплять версию, сейчас master ориентирован на 24.06.1 |
| FontForge | Извлечение и преобразование шрифтов | Ошибки метрик, конвертации или сборки | Использовать согласованную версию 20230101 из текущей конфигурации |
| Cairo и графические библиотеки | Фоновые изображения и векторные элементы | Проблемы с графическим слоем или сборкой | Не смешивать произвольные системные версии с неподготовленным исходником |
| Шрифты исходного PDF | Внешний вид и копирование текста | Подмена гарнитуры, ошибочные метрики, юридические ограничения | Проверять —version, итоговые webfonts и лицензию шрифта |
| Браузер | Финальное воспроизведение HTML/CSS/JS | Расхождения позиционирования или печати | Тестировать целевые браузеры на эталонных страницах |
| Временный каталог и диск | Промежуточные ресурсы | Остановка обработки крупного файла | Контролировать свободное место, tmp-dir и tmp-file-size-limit |
Аккаунт и облачный API не требуются. Интернет нужен для получения исходников, зависимостей или образа; сама установленная программа может конвертировать локальные файлы офлайн.
Паспорт обратимости операций
pdf2htmlEX не меняет исходный PDF: он создаёт новый набор файлов, поэтому результат легко пересобрать с другими параметрами. Но обратное HTML → исходный PDF без потерь не обещано: HTML является представлением страницы, а не полной реконструкцией PDF-объектов.
| Операция | Что сохраняется | Что может потеряться | Как откатиться |
|---|---|---|---|
| Обычная конвертация | Исходный PDF не изменяется | Часть интерактивности PDF, семантика чтения, нестандартные объекты | Удалить результат и повторить конвертацию |
| Отключение встраивания | Те же визуальные ресурсы, но отдельными файлами | Переносимость одного файла | Вернуться к значениям embed по умолчанию |
| split-pages | Раздельные страницы и основной контейнер | Самодостаточность при копировании одного HTML | Пересобрать без —split-pages |
| tounicode=-1 | Визуальное соответствие может улучшиться | Корректность копирования символов | Вернуть 0 и пересоздать HTML |
| process-type3=1 | Попытка нативного текста для Type 3 | Стабильность экспериментального пути | Отключить и оставить Type 3 в графическом слое |
Для воспроизводимости храните исходный PDF, точную команду и версию бинарного файла.
Хронология развития и поддержки
- 2012–2014. Lu Wang и участники создают исходную кодовую базу; проект позиционируется как PDF-to-HTML конвертер с сохранением текста и макета.
- 2013. Публикуется техническое описание подхода pdf2htmlEX к онлайн-публикации PDF и использованию HTML5/CSS.
- 9 декабря 2018. Оригинальный репозиторий coolwanglu/pdf2htmlEX архивируется и становится read-only.
- 2019–2020. Общественная ветка pdf2htmlEX/pdf2htmlEX объединяет исправления из форков, обновляет обработку перекрытого текста и сборочную систему.
- 30 июня 2020. Публикуется v0.18.8.rc1 — последняя формальная запись Releases, доступная и сегодня.
- 2024. В master обновляется цепочка до Poppler 24.06.1 и более нового FontForge, CI переводится на Ubuntu 22.04.
- 2025. Сливаются исправление OpenJPEG2, изменение SignalHandler для Windows и современный Dockerfile на Debian Bookworm с multi-arch/ARM64-подходом.
Итог хронологии: код продолжил жизнь после архивирования авторского upstream, но регулярный выпуск готовых бинарников так и не восстановился.
Сравнение с аналогами
| Инструмент | Основная задача | PDF → HTML | Сильная сторона | Ограничение относительно pdf2htmlEX |
|---|---|---|---|---|
| pdf2htmlEX | Публикация PDF как HTML с сохранением страницы | Да | Точное позиционирование, webfonts, единый или разделённый вывод | Сложная установка, редкие релизы, нет OCR и GUI |
| Poppler pdftohtml | Конвертация PDF в HTML/XML/изображения | Да | Активно обновляемая утилита в составе Poppler; в сентябре 2026 актуальна линия Poppler 26.09 | Иной баланс между извлечением и визуальным воспроизведением; меньше специализированных настроек публикации pdf2htmlEX |
| PDF.js | Рендеринг исходного PDF в браузере | Нет, это viewer/platform, а не предварительный конвертер в самостоятельный HTML-документ | PDF остаётся источником, современный браузерный просмотрщик и API | Не создаёт статическую HTML-копию страницы заранее |
| Adobe Acrobat Pro | Коммерческое редактирование и экспорт PDF | Да | GUI, экспорт в один или несколько HTML-файлов, настройки изображений и OCR | Платный закрытый продукт; хуже подходит для полностью открытого воспроизводимого server-side pipeline |
| Sumatra PDF | Просмотр документов; в pre-release 3.7 также консольные преобразования | Pre-release 3.7 документирует text output в HTML/XHTML | Современный Windows-инструмент, простой просмотр и широкий набор форматов | Его HTML-конвертация не позиционируется как замена специализированной системе точного веб-воспроизведения pdf2htmlEX |
С Sumatra PDF сравнение корректно только по конкретной задаче. Для чтения и навигации на Windows pdf2htmlEX не конкурент. Pre-release Sumatra PDF 3.7 документирует команду convert с HTML/XHTML среди текстовых выходов, но pdf2htmlEX специализирован на визуально близком fixed-layout HTML. Poppler pdftohtml, напротив, остаётся прямой консольной альтернативой и развивается регулярно: Poppler 26.09.0 от 3 сентября 2026 года включал ускорение pdftohtml. Выбор между ними — это компромисс между свежестью экосистемы Poppler и более узкими средствами веб-воспроизведения pdf2htmlEX.
Инструкция по установке
Сборка на Debian/Ubuntu-подобной системе
- Установите Git и убедитесь, что у пользователя есть право выполнять sudo для установки пакетов.
- Клонируйте официальный репозиторий pdf2htmlEX/pdf2htmlEX в отдельный рабочий каталог.
- Перед запуском просмотрите buildScripts/buildInstallLocallyApt: скрипт не только компилирует программу, но и устанавливает инструменты разработки через apt.
- Из корня репозитория запустите ./buildScripts/buildInstallLocallyApt.
- Дождитесь сборки согласованных Poppler, FontForge и самого pdf2htmlEX. Официальная документация указывает, что результат устанавливается в /usr/local/bin.
- Проверьте установку командой pdf2htmlEX —version и зафиксируйте показанные версии pdf2htmlEX, Poppler и FontForge в журнале развёртывания.
- Для первого запуска используйте небольшой неконфиденциальный PDF и простую команду pdf2htmlEX sample.pdf sample.html. Откройте результат в целевом браузере и сравните несколько характерных страниц.
Локальный контейнер на основе текущего Dockerfile
- Клонируйте официальный репозиторий и перейдите в его корень.
- Соберите образ командой docker build -f docker/Dockerfile.bookworm -t pdf2htmlex-local .
- Создайте отдельный каталог для входных и выходных файлов.
- Запустите контейнер с монтированием этого каталога, рабочей директорией внутри него и аргументами pdf2htmlEX. Поскольку Dockerfile задаёт pdf2htmlEX как ENTRYPOINT, после имени образа передаются только параметры и имя PDF.
- Закрепите digest образа или commit исходников и повторяйте контрольные тесты при обновлении.
Удаление
Универсальная современная процедура uninstall не документирована. Контейнер удаляется средствами Docker/Podman; пакет .deb — пакетным менеджером. После сборки в /usr/local безопаснее опираться на журнал установленных путей, а не удалять один бинарник вслепую.
Практические кейсы
Публикация одного PDF как автономного HTML
Цель: получить автономный файл для статического сайта. Подготовка: проверить текстовый слой и права на шрифты. Шаги: выполнить pdf2htmlEX report.pdf report.html с настройками встраивания по умолчанию. Проверка: открыть результат офлайн и в целевом браузере, проверить текст, ссылки и печать. Ограничение: единый HTML может быть крупным.
Большой документ с раздельной загрузкой страниц
Цель: разделить большой документ. Подготовка: выделить отдельный каталог публикации. Шаги: применить —split-pages 1, —dest-dir и —page-filename page%03d.page. Проверка: открыть результат через HTTP и проверить страницы в начале, середине и конце. Ограничение: передавать нужно весь комплект файлов; динамическая загрузка зависит от JavaScript.
Извлечение ограниченного диапазона для веб-превью
Цель: опубликовать, например, первые десять страниц каталога, не конвертируя весь PDF. Подготовка: определить допустимый диапазон и убедиться, что внутренние ссылки за его пределы не критичны. Шаги: применить —first-page 1 —last-page 10 и отдельный —dest-dir preview. Проверка: сравнить номера страниц и содержание последней страницы результата с PDF. Ограничение: оглавление и ссылки могут ссылаться на страницы, которых в укороченной копии нет.
Разбор неправильного копирования текста
Цель: диагностировать неверное копирование символов. Подготовка: сохранить эталонный фрагмент. Шаги: сравнить —tounicode 0, 1 и -1; для лигатур проверить —decompose-ligature 1. Проверка: сопоставить внешний вид и вставленный plain text. Ограничение: при неверной карте glyph → Unicode гарантированного восстановления смысла нет.
Диагностика перекрытого текста
Цель: исправить текст, видимый поверх перекрывающего объекта. Шаги: проверить —correct-text-visibility: режим 1 учитывает полное, режим 2 — частичное перекрытие; для сравнения использовать —proof 2. Проверка: сопоставить участок с PDF. Ограничение: режим 2 может дать ложные срабатывания и увеличить фоновый рендер.
Навигатор по сбоям
| Симптом | Сначала проверить | Безопасное действие | Контроль результата |
|---|---|---|---|
| Сборка падает на Poppler/FontForge | Используется ли текущий официальный build script и зафиксированные версии | Вернуться к чистому clone и не подмешивать системные заголовки другой версии | pdf2htmlEX —version показывает ожидаемые библиотеки |
| Шрифты отличаются | Встроен ли шрифт в PDF, включён ли embed-external-font | Сравнить результат с внешними шрифтами и без них, не отключая метрики вслепую | Проверить характерные строки и переносы |
| HTML слишком большой | Все ли ресурсы встроены, включён ли fallback, есть ли повторяющиеся фоновые файлы | Вынести изображения/шрифты наружу и проверить дедупликацию | Визуальная сверка после каждого изменения |
| Страница медленно открывается | Размер одного HTML, сложность SVG, число DOM-элементов | Разделить страницы или ограничить SVG; осторожно попробовать optimize-text | Проверить несколько браузеров и отсутствие визуальных регрессий |
| Скан не имеет выделяемого текста | Есть ли текстовый слой в исходном PDF | Выполнить OCR до pdf2htmlEX | Сначала проверить поиск текста в самом PDF |
Контроль перед сохранением и передачей
- Открыть начало, середину и конец документа, а не только титульную страницу.
- Проверить текстовое выделение, копирование кириллицы, цифр, формул и лигатур.
- Проверить внутренние и внешние ссылки.
- Если включались формы или аннотации, проверить именно их, потому что они выключены по умолчанию и поддерживаются ограниченно.
- Убедиться, что все внешние CSS, JS, изображения, webfonts и page-файлы действительно передаются вместе с HTML.
- Проверить права на распространение встроенных шрифтов.
- Открыть результат с теми же Content Security Policy и путями, которые будут на production-сайте.
- Зафиксировать версию pdf2htmlEX, commit и параметры команды рядом с артефактом.
Часто задаваемые вопросы
Создаёт ли pdf2htmlEX «чистый» семантический HTML?
Нет. Его главная цель — визуальная верность фиксированному PDF, поэтому структура часто основана на позиционированных текстовых элементах и слоях. Полученный HTML можно индексировать и в нём часто можно выделять текст, но это не равнозначно корректной структуре article, heading, list и table. Для доступного адаптивного сайта лучше иметь исходный структурированный документ или выполнять дополнительную семантическую переработку.
Можно ли обработать защищённый PDF?
Есть параметры owner-password и user-password. Также существует —no-drm, но официальная справка прямо требует использовать обход ограничений только при наличии разрешения. Техническое наличие флага не отменяет прав владельца документа.
Почему HTML выглядит верно, а поиск и копирование ошибаются?
PDF может хранить glyph-коды и отдельно карту Unicode. Если карта отсутствует или неверна, pdf2htmlEX способен сохранить картинку текста лучше, чем его смысл. Для диагностики используются tounicode и decompose-ligature, но гарантированного восстановления символов без корректных данных в исходнике нет.
Можно ли использовать pdf2htmlEX как OCR?
Нет. Изображение страницы не распознаётся автоматически. Если документ — скан, сначала нужен OCR, после которого в PDF появится текстовый слой. Для такого сценария ближе по назначению ABBYY PDF Transformer или современный OCR-пакет.
Работает ли результат без JavaScript?
Базовый монолитный вывод может быть проще в автономном использовании, но проект использует JavaScript для части поведения, а режим разделённых страниц рассчитан на динамическую загрузку. Есть fallback-режим для большей совместимости ценой размера. Если политика сайта запрещает встроенный JavaScript, ресурсы нужно вынести и проверить результат под реальной CSP.
Можно ли редактировать полученный HTML вручную?
Технически да, но любое изменение позиционирования, CSS-классов или связей с ресурсами способно нарушить точное совпадение с PDF. Если требуется содержательное редактирование текста и структуры, лучше вернуться к исходному DOCX/ODT/LaTeX/HTML, а не использовать сгенерированный слой как удобный редакторский формат.
Подойдёт ли LibreOffice вместо pdf2htmlEX?
LibreOffice удобнее для GUI и исходных офисных форматов. Импорт PDF в редактор и автоматическое воспроизведение fixed-layout PDF в веб-слое — разные задачи.
Вывод
pdf2htmlEX остаётся редким инструментом с очень конкретной сильной стороной: он умеет превращать PDF в веб-представление, сохраняя текстовый слой и внешний вид страницы значительно глубже, чем простое извлечение текста. Он особенно уместен для архивных журналов, технических документов, научных материалов и других fixed-layout PDF, когда исходного HTML нет, а пользователю нужно читать документ в браузере и выделять текст.
Это не универсальная рекомендация: нужны командная строка, сложная сборка и контроль версий, а готовый Release стар по дате. Для OCR и редактирования лучше специализированный редактор, для прямого браузерного просмотра — PDF.js, для активно обновляемой CLI-конвертации — Poppler pdftohtml, для чтения на Windows — Sumatra PDF.
Практически pdf2htmlEX стоит выбирать не потому, что «нужен любой конвертер PDF в HTML», а когда уже доказана необходимость точного fixed-layout результата, локальной обработки и автоматизации. В таком случае наилучшая стратегия — собственная воспроизводимая сборка или контейнер, закреплённый commit, набор эталонных PDF и обязательная проверка шрифтов, копирования текста и браузерной совместимости перед публикацией.