Artículo técnico

PDF a Markdown y DOCX en Delphi con PDF Library for Delphi

Medio punto lo decide. En un informe con texto de cuerpo de 10 puntos, un título de sección en negrita de 11 puntos se convierte a Markdown como un párrafo corriente, mientras que una leyenda de portada de 12 puntos, en peso normal, regresa como ### Quarterly figures. Parece al revés hasta que recuerdas lo que una página PDF guarda de verdad: glifos en coordenadas, un nombre de fuente y un tamaño. Nada en la página dice "encabezado". Cada encabezado que emite un conversor es una conjetura construida a partir de esos tres hechos, y la conjetura tiene umbrales

Por qué una página PDF no tiene párrafos que exportar

Una página PDF contiene operadores que muestran texto, no párrafos. Cada operador coloca una corrida de glifos en una posición, en el orden que la aplicación productora le viniera en gana emitir, e ISO 32000-1 no obliga al productor a decir que dos corridas pertenecen a la misma frase, y menos aún al mismo elemento de lista o celda de tabla. El formato describe una página impresa con exactitud, y lo consigue tirando la estructura que produjo la página

Así que cada conversor reconstruye lo que el generador descartó. Las líneas salen de líneas base compartidas y del espaciado vertical. Los saltos de párrafo salen de cambios de espaciado y sangría. Una lista es una corrida de bloques que empiezan con un carácter de viñeta o un patrón numérico. Una tabla es una cuadrícula de bloques de texto cuyos bordes se alinean a lo largo de filas y columnas. En documentos que siguen hábitos tipográficos corrientes esto funciona bien; en un folleto maquetado por efecto visual tiene muy poco de lo que agarrarse

Diagrama de PDF Library for Delphi del pipeline de inferencia que convierte corridas de glifos PDF en bruto en líneas agrupadas, párrafos, encabezados, listas y tablas exportados como Markdown o DOCX
Cada encabezado, lista y tabla de la exportación se infiere del espaciado, las fuentes y los bordes alineados, porque el propio formato PDF no registra ninguno

Los PDF etiquetados son la gran excepción. Cuando un documento lleva un árbol de estructura, los roles de párrafo, encabezado, lista y tabla quedan registrados por el productor en lugar de adivinarse después, razón por la que el trabajo descrito en estructura de accesibilidad de PDF etiquetado también se paga en calidad de conversión. Si controlas al productor, etiquetar la salida es lo más barato que puedes hacer por quien la convierta después

De dónde salen los niveles de encabezado

PDF Library for Delphi decide los niveles de encabezado de dos maneras, según la entrada. En una página etiquetada, un bloque cuyo rol de estructura es H1 a H6 conserva ese nivel, y H o Title pasa a nivel 1. En una página sin etiquetas la exportación recurre al tamaño de fuente relativo al texto de cuerpo de la página, y solo considera párrafos de una sola línea de 200 caracteres o menos

La regla de tamaño necesita a la vez una razón y un hueco absoluto, medidos contra el tamaño de cuerpo dominante:

Salida MarkdownTexto mayor de la líneaCon cuerpo de 10 pt
#al menos 1.6 veces el tamaño del cuerpo y al menos 4 pt mayor16 pt en adelante
##al menos 1.35 veces y al menos 2.5 pt mayor13.5 pt en adelante
###al menos 1.15 veces y al menos 1.25 pt mayor11.5 pt en adelante

Eso explica el ejemplo inicial. Un título en negrita de 11 puntos sobre texto de 10 puntos falla el tercer escalón por medio punto, y el peso no juega ningún papel en el nivel. La leyenda de portada a 12 puntos lo supera. El hueco absoluto existe para tamaños de cuerpo pequeños: sobre texto de 6 puntos, tamaño de nota al pie, una razón sola ascendería una línea de 7 puntos a encabezado, y el requisito extra de 1.25 pt lo evita

Nos parece el intercambio correcto. La negrita es demasiado común dentro del texto de cuerpo (frases de entrada, términos definidos, totales en una línea de resumen) para ser por sí sola una señal fiable de encabezado, y un conversor que ascienda cada línea en negrita produce Markdown con docenas de secciones espurias. Perder unos pocos encabezados de solo-negrita cuesta menos. Si tus documentos dependen de títulos en negrita a tamaño de cuerpo, el arreglo fiable está aguas arriba: etiquétalos, o sube el tamaño del título un punto y medio

La negrita y la cursiva de la salida se leen del nombre de la fuente. Una corrida cuyo nombre de fuente contiene Bold, Black o Demi pasa a **bold**; Italic o Oblique pasa a *italic*. Los productores que hacen subset de fuentes bajo nombres opacos como F3, o que falsifican la negrita trazando glifos regulares, no dan nada que leer a la exportación, y ese texto llega sin estilo

Exportación Markdown para pipelines de recuperación

La ruta Markdown es la que hay que coger cuando el destino es un pipeline de texto: un sitio de documentación, un índice de búsqueda, un corpus troceado para un asistente. ExportPageMarkdown devuelve una página como WideString, ExportDocumentMarkdown devuelve un rango de páginas, y SaveMarkdownToFile y SaveMarkdownToStream escriben el mismo texto como UTF-8 sin marca de orden de bytes. El BOM ausente es deliberado; un buen número de generadores de sitios estáticos y herramientas de diff lo tratan como contenido

Diagrama de PDF Library for Delphi de la exportación Markdown en streaming donde la máscara de bits de opciones selecciona marcadores de página, detección de encabezados y conservación de estilos antes de escrituras UTF-8 página a página
Las opciones se combinan como máscara de bits y el escritor emite UTF-8 sin BOM, mientras que los marcadores de página dejan cada fragmento recuperado con un número de página citable

Las opciones son una máscara de bits: PDF_MARKDOWN_INCLUDE_PAGE_MARKERS (1), PDF_MARKDOWN_DETECT_HEADINGS (2) y PDF_MARKDOWN_PRESERVE_STYLES (4), con PDF_MARKDOWN_DEFAULT combinando las tres. Un segundo ajuste, de documento entero, controla el análisis mismo: SetStructuredTextOptions recibe los flags PDF_STRUCTURED_*, y su valor por defecto detecta columnas, detecta cabeceras y pies recurrentes, y une tablas que continúan tras un salto de página

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');

    // La detección de cabeceras y pies de página recurrentes viene activada
    // por defecto; añadir EXCLUDE_FURNITURE también los suelta de la salida
    Pdf.SetStructuredTextOptions(PDF_STRUCTURED_ADVANCED_DEFAULT or
      PDF_STRUCTURED_EXCLUDE_FURNITURE);

    // Marcadores de página y encabezados, pero sin énfasis ** y *
    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 con una entrada por página: readingSource es tagged, mixed,
    // geometric o geometric-columns
    Writeln(Pdf.GetLastStructuredTextDiagnostics);
  finally
    Pdf.Free;
  end;
end;

Para un corpus de recuperación dejamos fuera PDF_MARKDOWN_PRESERVE_STYLES. El énfasis se aplica corrida a corrida, así que una frase en negrita compuesta por varias corridas sale como **Net** **revenue**, que se lee bien en pantalla y añade ruido a cada embedding. Los marcadores de página son el caso contrario: consérvalos. Cada marcador es un comentario HTML, <!-- page: 12 -->, invisible cuando el Markdown se renderiza y trivial de parsear cuando troceas, así que un pasaje recuperado puede citar la página de la que vino. Cuando una tabla continúa de la página anterior, el marcador de la página nueva se omite para que la tabla de tuberías se quede en una pieza

Dos comportamientos cazan a quien exporta página a página en un bucle. Primero, las cabeceras recurrentes se reconocen por repetición: un párrafo en el 12 por ciento superior o inferior de la página cuenta como mobiliario cuando un texto coincidente se sienta en la misma banda en otra página de la misma exportación, con los dígitos normalizados para que "Page 3 of 40" coincida con "Page 4 of 40". Una llamada de una sola página no tiene otra página con la que comparar, así que una cabecera recurrente sin etiquetas se queda en el texto. Segundo, las imágenes en Markdown van incrustadas inline como URIs data:, lo que mantiene el archivo autosuficiente y significa que una página con una fotografía grande puede añadir cientos de kilobytes de base64 al archivo. Si tu troceador tiene un límite de tamaño, elimina las líneas que empiezan con ![PDF image antes de trocear

Mantener separados los flags de opción de Markdown y DOCX

Las constantes de Markdown y DOCX comparten los bits bajos pero significan cosas distintas. PDF_DOCX_INCLUDE_IMAGES es 1, el mismo valor que PDF_MARKDOWN_INCLUDE_PAGE_MARKERS. Pásale la constante DOCX a una llamada Markdown y el compilador es feliz, la llamada tiene éxito, y recibes marcadores de página. Solo un bit fuera del rango Markdown se rechaza:

var
  Md: WideString;
begin
  // Compila y se ejecuta: 1 se lee como PDF_MARKDOWN_INCLUDE_PAGE_MARKERS
  Md := Pdf.ExportDocumentMarkdown('', PDF_DOCX_INCLUDE_IMAGES);

  // PDF_DOCX_PRESERVE_PAGE_BREAKS es 8, fuera de la máscara Markdown:
  // Md regresa vacío y LastErrorCode es 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;

Una cadena vacía también es un resultado legítimo para una página sin texto alguno, así que mira LastErrorCode antes de tratar '' como error. Los fallos de extracción reportan 517 (PDFLIB_ERROR_MARKDOWN_EXPORT); los argumentos malos, incluido un rango de páginas que no resuelve a ninguna página, reportan 113

DOCX sin Office en la máquina

SaveDOCXToFile y SaveDOCXToStream escriben el paquete WordprocessingML ellos mismos: el contenedor ZIP, las partes de documento, numeración y relaciones, y el media PNG. Nada llama a Word ni a COM, así que la conversión corre en un servidor sin cabeza, bajo una cuenta de servicio o en un contenedor, todos sitios donde la automatización de Office o no tiene licencia, o es inestable, o no está instalada

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 iguala el número de páginas del rango si todo va bien
    if Written <> 40 then
      raise Exception.CreateFmt('DOCX export stopped after %d pages, error %d',
        [Written, Pdf.LastErrorCode]);
  finally
    Pdf.Free;
  end;
end;

Las listas se escriben con las definiciones de numeración propias de Word en lugar de prefijos "1." tecleados, de modo que insertar un elemento en Word renumera el resto. Las tablas detectadas se convierten en tablas Word de verdad con anchos de columna tomados de los bordes de columna medidos y una fila de cabecera sombreada. Con PDF_DOCX_PRESERVE_PAGE_BREAKS activado, cada página fuente empieza en una página Word nueva, excepto donde una tabla continúa de la página anterior; ese salto se suelta para que la tabla siga siendo una tabla. Deja el flag apagado cuando quien vaya a usar el archivo va a refluir el texto de todos modos, porque un salto duro cada 40 líneas le estorba

El valor de retorno es el recuento de páginas escritas. Una exportación a stream que devuelve menos páginas de las que pediste falló a mitad de camino, y el stream sostiene un paquete incompleto, así que descártalo en lugar de entregarlo a Word

Empaquetado DOCX determinista

Dos conversiones del mismo PDF con las mismas opciones producen un archivo DOCX idéntico byte por byte, así que puedes hashear la salida para detectar cambios, comparar dos builds de un documento generado, y cachear resultados sin preocuparte de que una entrada idéntica produzca un artefacto distinto

Diagrama de PDF Library for Delphi del empaquetado DOCX determinista construido entrada a entrada en Pascal puro, junto a la automatización de Office cuyos metadatos incrustados cambian en cada conversión
Dos conversiones idénticas producen hashes idénticos para diff y caché, una propiedad que la automatización de Office pierde en cuanto incrusta marcas de tiempo nuevas

Dos decisiones sostienen eso. Cada entrada ZIP lleva la misma fecha DOS fija, 1 de enero de 1980, en lugar de la hora de la ejecución, y la parte de propiedades core no tiene fechas de creación ni modificación. Cada entrada se comprime con Deflate en crudo solo cuando realmente la hace más pequeña, así que el media PNG, que ya viene comprimido, se almacena tal cual. Puedes confirmar el primer punto con unzip -v handbook.docx: cada fila muestra la misma fecha

La automatización de Office no puede darte eso. Guardar a través de Word estampa la hora actual en los metadatos del paquete y en las cabeceras ZIP, así que el mismo documento convertido dos veces difiere en formas que derrotan a un hash. El mismo razonamiento hay detrás de los identificadores de archivo estables de IDs de PDF deterministas para builds reproducibles: cuando la salida es reproducible, la verificación se convierte en una comparación

Qué entradas convierten bien, y cuáles nunca lo harán

La calidad de conversión varía más con la entrada que con el conversor, y merece la pena decírselo a tus usuarios de frente. Los PDF etiquetados y los documentos de negocio limpiamente generados (facturas, informes, contratos) convierten bien: los encabezados aterrizan como encabezados, las tablas sobreviven, las listas se renumeran en Word. Las maquetaciones académicas a dos columnas atraviesan en el orden de lectura correcto cuando la geometría de columnas es regular, y los diagnósticos reportarán geometric-columns para esas páginas. Las tablas que se parten entre páginas se reunen por inferencia, así que dales un vistazo. El material de marketing fuertemente diseñado, donde el texto se coloca por efecto y no en orden de lectura, deja a cualquier conversor poco que recuperar; espera retocar el resultado a mano

Los documentos escaneados son un caso aparte. Una página que es una sola imagen grande no contiene objetos de texto, así que no hay nada que exportar hasta que exista una capa de texto, y ejecutar OCR es un prerrequisito para ambos formatos. Antes de comprometerte con un lote grande, muestrea una docena de archivos representativos y enumera lo que contienen sus páginas, como se describe en búsqueda de texto y enumeración de elementos de página; una página con imágenes y sin corridas de texto te dice más en un segundo que leer la salida convertida

Elige el formato por lo que pasa después. Markdown va con máquinas y pipelines: los encabezados se vuelven fronteras de fragmentos, las tablas siguen legibles como tablas de tuberías, y los marcadores de página dan a cada fragmento una cita. DOCX va con personas que necesitan cambiar el documento, porque lo que quieren de vuelta es un archivo editable en Word, con listas de verdad y tablas de verdad, y el texto solo no les da eso

PDF Library for Delphi se publica para Delphi, C++Builder y Lazarus, con ediciones DLL y ActiveX que exponen las mismas llamadas de exportación Markdown y DOCX a hosts de C#, C++ y scripting. La referencia de cada flag de opción y una descarga de prueba están en la página del producto PDF Library for Delphi