Техническая статья

PDF Library for Delphi: PDF в Markdown и DOCX в Delphi

Решают полпункта. В отчёте с основным текстом 10 пунктов заголовок раздела, набранный 11-пунктовым жирным, конвертируется в Markdown как обычный абзац, а 12-пунктовая подпись на обложке обычного начертания возвращается как ### Quarterly figures. Это выглядит навыворот, пока не вспомнишь, что страница PDF на самом деле хранит: глифы на координатах, имя шрифта и размер. Ничто на странице не говорит "заголовок". Каждый заголовок, который выдаёт конвертер, — догадка, построенная из тех трёх фактов, и у догадки есть пороги

Почему на странице PDF нет абзацев для экспорта

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

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

Диаграмма PDF Library for Delphi: конвейер логического вывода, превращающий сырые прогоны глифов PDF в сгруппированные строки, абзацы, заголовки, списки и таблицы, экспортируемые как Markdown или DOCX
Каждый заголовок, список и таблица в экспорте выводятся из отступов, шрифтов и выровненных краёв, ведь сам формат PDF не записывает ни одного из них

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

Откуда берутся уровни заголовков

PDF Library for Delphi решает уровни заголовков двумя способами, в зависимости от входа. На тегированной странице блок, чья структурная роль — H1–H6, сохраняет тот уровень, а H или Title становится уровнем 1. На нетегированной странице экспорт откатывается к размеру шрифта относительно основного текста страницы и рассматривает только однострочные абзацы в 200 символов или меньше

Правилу размера нужны и отношение, и абсолютный зазор, отсчитанные от доминирующего размера основного текста:

Вывод MarkdownКрупнейший текст в строкеПри основном тексте 10 pt
#не менее 1.6 размера основного текста и не менее чем на 4 pt крупнее16 pt и выше
##не менее 1.35 и не менее чем на 2.5 pt крупнее13.5 pt и выше
###не менее 1.15 и не менее чем на 1.25 pt крупнее11.5 pt и выше

Это объясняет пример из начала. 11-пунктовый жирный заголовок над текстом 10 пунктов не дотягивает до третьей ступени полпункта, и начертание в уровне не участвует. Подпись на обложке в 12 пунктов проходит. Абсолютный зазор существует ради мелких основных размеров: на тексте 6 пунктов, размера сноски, одно отношение повысило бы строку в 7 пунктов до заголовка, и требование дополнительных 1.25 pt это останавливает

Мы считаем этот размен правильным. Жирное слишком часто встречается внутри основного текста (вводные фразы, определяемые термины, итоги в строке сводки), чтобы быть надёжным сигналом заголовка само по себе, и конвертер, повышающий каждую жирную строку, производит Markdown с десятками ложных разделов. Пропустить несколько заголовков только из жирного стоит дешевле. Если ваши документы опираются на заголовки жирным основного размера, надёжный фикс — выше по потоку: тегируйте их или поднимите размер заголовка на полтора пункта

Жирное и курсивное в выводе читаются из имени шрифта. Прогон, чьё имя шрифта содержит Bold, Black или Demi, становится **bold**; Italic или Oblique становится *italic*. Производители, режущие шрифты под непрозрачными именами вроде F3 или имитирующие жирное обводкой обычных глифов, не дают экспорту ничего читать, и тот текст приходит неоформленным

Экспорт Markdown для конвейеров поиска

Путь Markdown — то, к чему тянуться, когда назначение — текстовый конвейер: сайт документации, поисковый индекс, нарезанный корпус для ассистента. ExportPageMarkdown возвращает одну страницу как WideString, ExportDocumentMarkdown возвращает диапазон страниц, а SaveMarkdownToFile и SaveMarkdownToStream пишут тот же текст как UTF-8 без метки порядка байтов. Отсутствие BOM намеренно: немало генераторов статических сайтов и diff-инструментов трактуют его как содержимое

Диаграмма PDF Library for Delphi: потоковый экспорт Markdown — битовая маска опций выбирает маркеры страниц, обнаружение заголовков и сохранение стилей до постраничной записи UTF-8
Опции комбинируются как битовая маска, а писатель выдаёт UTF-8 без BOM; маркеры страниц оставляют каждому извлечённому чанку цитируемый номер страницы

Опции — битовая маска: PDF_MARKDOWN_INCLUDE_PAGE_MARKERS (1), PDF_MARKDOWN_DETECT_HEADINGS (2) и PDF_MARKDOWN_PRESERVE_STYLES (4), где PDF_MARKDOWN_DEFAULT объединяет все три. Вторая, документная настройка управляет самим анализом: SetStructuredTextOptions принимает флаги PDF_STRUCTURED_*, и её умолчание детектирует колонки, детектирует бегущие колонтитулы и соединяет таблицы, продолжающиеся через разрыв страницы

uses

SysUtils, PDFlibrary; var Pdf: TPDFlib; Exported: Integer; begin Pdf := TPDFlib.Create; try if Pdf.LoadFromFile('handbook.pdf', '') = 0 then raise Exception.Create('Cannot open handbook.pdf'); // Детекция бегущих колонтитулов включена по умолчанию; // добавление EXCLUDE_FURNITURE также убирает их из вывода Pdf.SetStructuredTextOptions(PDF_STRUCTURED_ADVANCED_DEFAULT or PDF_STRUCTURED_EXCLUDE_FURNITURE); // Маркеры страниц и заголовки, но без выделения ** и * Exported := Pdf.SaveMarkdownToFile('1-40', PDF_MARKDOWN_INCLUDE_PAGE_MARKERS or PDF_MARKDOWN_DETECT_HEADINGS, 'handbook.md'); if Exported = 0 then raise Exception.CreateFmt('Markdown export failed, error %d', [Pdf.LastErrorCode]); // JSON с записью на страницу: readingSource — tagged, mixed, // geometric или geometric-columns Writeln(Pdf.GetLastStructuredTextDiagnostics); finally Pdf.Free; end; end;

Для корпуса поиска мы отбрасываем PDF_MARKDOWN_PRESERVE_STYLES. Выделение применяется прогон за прогоном, поэтому жирная фраза, набранная несколькими прогонами, выходит как **Net** **revenue** — на экране читается нормально, а в каждое вложение добавляет шум. Маркеры страниц — обратный случай: оставляйте. Каждый маркер — HTML-комментарий, <!-- page: 12 -->, невидимый при рендеринге Markdown и тривиально разбираемый при нарезке на чанки, поэтому извлечённый отрывок может процитировать страницу, откуда пришёл. Когда таблица продолжается с предыдущей страницы, маркер новой страницы опускается, чтобы pipe-таблица осталась одной таблицей

Два поведения подлавливают тех, кто экспортирует страницу за страницей в цикле. Во-первых, бегущие колонтитулы распознаются по повторению: абзац в верхней или нижней 12 процентах страницы считается мебелью, когда совпадающий текст сидит в той же полосе на другой странице того же экспорта, причём цифры нормализуются, так что "Page 3 of 40" совпадает с "Page 4 of 40". Одностраничный вызов не имеет другой страницы для сравнения, поэтому нетегированный колонтитул остаётся в тексте. Во-вторых, картинки в Markdown встроены инлайн как data: URI, что держит файл самодостаточным и означает, что страница с большой фотографией может добавить сотни килобайтов base64. Если у вашего чанкера есть лимит размера, срезайте строки, начинающиеся с ![PDF image, до нарезки

Держите флаги опций Markdown и DOCX порознь

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

var

Md: WideString; begin // Компилируется и работает: 1 читается как PDF_MARKDOWN_INCLUDE_PAGE_MARKERS Md := Pdf.ExportDocumentMarkdown('', PDF_DOCX_INCLUDE_IMAGES); // PDF_DOCX_PRESERVE_PAGE_BREAKS — это 8, вне маски Markdown: // Md возвращается пустым, а LastErrorCode — 113 Md := Pdf.ExportDocumentMarkdown('', PDF_MARKDOWN_DEFAULT or PDF_DOCX_PRESERVE_PAGE_BREAKS); if (Md = '') and (Pdf.LastErrorCode = PDFLIB_ERROR_MARKDOWN_EXPORT_INVALID) then Writeln('Unknown Markdown option bit'); end;

Пустая строка — также легитимный результат для страницы вовсе без текста, поэтому проверяйте LastErrorCode, прежде чем считать '' ошибкой. Отказы извлечения сообщают 517 (PDFLIB_ERROR_MARKDOWN_EXPORT); плохие аргументы, включая диапазон страниц, разрешающийся в ноль страниц, сообщают 113

DOCX без Office на машине

SaveDOCXToFile и SaveDOCXToStream пишут пакет WordprocessingML сами: ZIP-контейнер, части документа, нумерации и отношений, а также PNG-медиа. Ничто не зовёт Word или COM, поэтому конвертация работает на безголовом сервере, под служебной учётной записью или в контейнере — во всех местах, где автоматизация Office нелицензирована, нестабильна или не установлена

uses

Classes, SysUtils, PDFlibrary; var Pdf: TPDFlib; Target: TFileStream; Written: Integer; begin Pdf := TPDFlib.Create; try if Pdf.LoadFromFile('handbook.pdf', '') = 0 then raise Exception.Create('Cannot open handbook.pdf'); Target := TFileStream.Create('handbook.docx', fmCreate); try Written := Pdf.SaveDOCXToStream('1-40', PDF_DOCX_INCLUDE_IMAGES or PDF_DOCX_DETECT_HEADINGS or PDF_DOCX_PRESERVE_STYLES or PDF_DOCX_PRESERVE_PAGE_BREAKS, Target); finally Target.Free; end; // При успехе Written равен числу страниц в диапазоне if Written <> 40 then raise Exception.CreateFmt('DOCX export stopped after %d pages, error %d', [Written, Pdf.LastErrorCode]); finally Pdf.Free; end; end;

Списки пишутся собственными определениями нумерации Word, а не впечатанными префиксами "1.", поэтому вставка пункта в Word перенумерует остальные. Детектированные таблицы становятся настоящими таблицами Word с ширинами столбцов из измеренных краёв столбцов и затенённой строкой заголовка. С установленным PDF_DOCX_PRESERVE_PAGE_BREAKS каждая страница-источник начинается с новой страницы Word, кроме случаев, когда таблица продолжается с предыдущей; тот разрыв опускается, чтобы таблица осталась одной таблицей. Оставляйте флаг выключенным, когда пользователи всё равно будут перелистывать текст — жёсткий разрыв каждые 40 строк им мешает

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

Детерминированная упаковка DOCX

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

Диаграмма PDF Library for Delphi: детерминированная упаковка DOCX, собираемая запись за записью на чистом Pascal, рядом с автоматизацией Office, чьи встроенные метаданные меняются при каждом преобразовании
Два одинаковых преобразования дают одинаковый хеш для diff и кэширования — свойство, которое автоматизация Office теряет в момент встраивания свежих меток времени

Этот результат держится на двух решениях. Каждая запись ZIP несёт одну и ту же фиксированную DOS-дату, 1 января 1980 года, вместо времени прогона, а часть core properties не имеет дат создания или изменения. Каждая запись сжимается сырым Deflate, только когда это реально делает её меньше, поэтому PNG-медиа, уже сжатая, хранится как есть. Первый пункт можно подтвердить через unzip -v handbook.docx: каждая строка показывает одну и ту же дату

Автоматизация Office такого не даст. Сохранение через Word штампует текущее время в метаданные пакета и заголовки ZIP, поэтому один документ, конвертированный дважды, различается так, что хеш бессмыслен. За тем же рассуждением стоят стабильные файловые идентификаторы из статьи детерминированные PDF ID для воспроизводимых сборок: когда вывод воспроизводим, проверка становится сравнением

Какие входы конвертируются хорошо, а какие не будут никогда

Качество конвертации сильнее зависит от входа, чем от конвертера, и стоит сказать пользователям об этом заранее. Тегированные PDF и чисто сгенерированные деловые документы (счета, отчёты, договоры) конвертируются хорошо: заголовки приземляются заголовками, таблицы выживают, списки перенумеровываются в Word. Двухколоночные академические вёрстки проходят в правильном порядке чтения, когда геометрия колонок регулярна, и диагностика сообщит для тех страниц geometric-columns. Таблицы, разрывающиеся между страницами, сшиваются выводом — проверяйте их выборочно. Тяжело свёрстанный маркетинговый материал, где текст размещён ради эффекта, а не в порядке чтения, оставляет любому конвертеру мало что восстановить; рассчитывайте дорабатывать результат руками

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

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

PDF Library for Delphi поставляется для Delphi, C++Builder и Lazarus, с редакциями DLL и ActiveX, открывающими те же вызовы экспорта Markdown и DOCX хостам C#, C++ и скриптов. Справочник по каждому флагу опций и пробная загрузка — на странице продукта PDF Library for Delphi