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
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 Markdown | Texto mayor de la línea | Con cuerpo de 10 pt |
|---|---|---|
# | al menos 1.6 veces el tamaño del cuerpo y al menos 4 pt mayor | 16 pt en adelante |
## | al menos 1.35 veces y al menos 2.5 pt mayor | 13.5 pt en adelante |
### | al menos 1.15 veces y al menos 1.25 pt mayor | 11.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
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
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