Een halve punt bepaalt het. In een rapport met 10-punts brontekst komt een sectietitel in 11-punts vet binnen als gewone alinea in Markdown, terwijl een 12-punts bijschrift op de omslag, in normaal gewicht, terugkomt als ### Quarterly figures. Dat lijkt achterstevoren totdat je bedenkt wat een PDF-pagina werkelijk bewaart: glyphs op coördinaten, een fontnaam en een grootte. Niets op de pagina zegt "kop". Elke kop die een converter uitzendt is een gis gebouwd uit die drie feiten, en de gis heeft drempels
Waarom een PDF-pagina geen alinea's heeft om te exporteren
Een PDF-pagina bevat tekst-tonende operators, geen alinea's. Elke operator zet een run glyphs op een positie, in welke volgorde de producerende toepassing ze ook toevallig uitzond, en ISO 32000-1 legt de producent geen enkele verplichting op om te zeggen dat twee runs bij dezelfde zin horen, laat staan bij hetzelfde lijstitem of dezelfde tabelcel. Het formaat beschrijft een gedrukte pagina exact, en het komt daar door de structuur weg te gooien die de pagina produceerde
Dus elke converter bouwt opnieuw wat de generator wegwierp. Regels komen uit gedeelde baselines en verticale spatiëring. Alineaeinden komen uit veranderingen in spatiëring en inspringing. Een lijst is een reeks blokken die beginnen met een opsommingsteken of een getalpatroon. Een tabel is een raster van tekstblokken waarvan de randen over rijen en kolommen uitlijnen. Op documenten die gewone typografische gewoonten volgen werkt dit goed; op een brochure die op visueel effect is ingedeeld heeft het weinig om vast te houden
Getagde PDF's zijn de grote uitzondering. Draagt een document een structuurboom, dan worden de alinea-, kop-, lijst- en tabelrollen door de producent vastgelegd in plaats van achteraf gegist, wat de reden is dat het werk uit tagged PDF-toegankelijkheidsstructuur ook in conversiekwaliteit terugverdient. Beheer je de producent zelf, dan is de output taggen het goedkoopste wat je kunt doen voor wie hem later converteert
Waar de kopniveaus vandaan komen
PDF Library for Delphi beslist kopniveaus op twee manieren, afhankelijk van de invoer. Op een getagde pagina houdt een blok waarvan de structuurrol H1 tot H6 is dat niveau, en H of Title wordt niveau 1. Op een ongetagde pagina valt de export terug op fontgrootte ten opzichte van de brontekst van de pagina, en hij beschouwt dan alleen eenregelige alinea's van 200 tekens of minder
De grootteregel heeft zowel een verhouding als een absolute afstand nodig, gemeten tegen de dominante bodygrootte:
| Markdown-uitvoer | Grootste tekst op de regel | Bij een body van 10 pt |
|---|---|---|
# | minstens 1,6 keer de bodygrootte en minstens 4 pt groter | 16 pt en omhoog |
## | minstens 1,35 keer en minstens 2,5 pt groter | 13,5 pt en omhoog |
### | minstens 1,15 keer en minstens 1,25 pt groter | 11,5 pt en omhoog |
Daarmee is het openingsvoorbeeld verklaard. Een 11-punts vette titel bovenop 10-punts tekst mist de derde trede op een halve punt na, en gewicht speelt geen rol bij het niveau. Het omslagbijschrift op 12 punten haalt hem wel. De absolute afstand bestaat voor kleine bodygroottes: op 6-punts voetnoottekst zou een verhouding alleen een regel van 7 punten tot kop promoveren, en de extra eis van 1,25 pt houdt dat tegen
We vinden dit de juiste afweging. Vet is veel te gewoon binnen brontekst (inleidende zinnen, begripstermen, totalen in een samenvattingsregel) om op zichzelf een betrouwbaar kopsignaal te zijn, en een converter die elke vette regel promoveert produceert Markdown met tientallen loosde secties. Een paar koppen die alleen op vet leunen missen kost minder. Leunen jouw documenten op titels in vet op bodygrootte, dan zit de betrouwbare fix stroomopwaarts: tag ze, of zet de titelgrootte anderhalve punt hoger
Vet en cursief in de uitvoer worden uit de fontnaam gelezen. Een run waarvan de fontnaam Bold, Black of Demi bevat wordt **vet**; Italic of Oblique wordt *cursief*. Producenten die fonts subsetten onder opaaknamen als F3, of die vet simuleren door gewone glyphs te overtrekken, geven de export niets te lezen, en die tekst komt ongestyled aan
Markdown-export voor retrieval-pijplijnen
De Markdown-route is degene om te pakken wanneer de bestemming een tekstpijplijn is: een documentatiesite, een zoekindex, een gechunkt corpus voor een assistent. ExportPageMarkdown geeft één pagina terug als WideString, ExportDocumentMarkdown geeft een paginabereik terug, en SaveMarkdownToFile en SaveMarkdownToStream schrijven dezelfde tekst als UTF-8 zonder bytevolgordemarkering. De ontbrekende BOM is opzet; een aantal statische sitegeneratoren en diff-gereedschappen behandelen hem als inhoud
Opties zijn een bitmasker: PDF_MARKDOWN_INCLUDE_PAGE_MARKERS (1), PDF_MARKDOWN_DETECT_HEADINGS (2) en PDF_MARKDOWN_PRESERVE_STYLES (4), met PDF_MARKDOWN_DEFAULT dat alle drie combineert. Een tweede, documentbrede instelling stuurt de analyse zelf: SetStructuredTextOptions neemt de PDF_STRUCTURED_*-vlaggen, en zijn default detecteert kolommen, detecteert doorlopende kop- en voetteksten, en voegt tabellen die een paginagrens overschrijden samen
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');
// Detectie van doorlopende kop- en voetteksten staat standaard aan;
// EXCLUDE_FURNITURE toevoegen haalt ze ook uit de uitvoer
Pdf.SetStructuredTextOptions(PDF_STRUCTURED_ADVANCED_DEFAULT or
PDF_STRUCTURED_EXCLUDE_FURNITURE);
// Paginamarkeringen en koppen, maar geen **- en *-nadruk
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 met één invoer per pagina: readingSource is tagged, mixed,
// geometric of geometric-columns
Writeln(Pdf.GetLastStructuredTextDiagnostics);
finally
Pdf.Free;
end;
end;
Voor een retrievalcorpus laten wij PDF_MARKDOWN_PRESERVE_STYLES vallen. Nadruk wordt per run toegepast, dus een vette zin die over meerdere runs loopt komt als **Net** **revenue** uit de bus, wat op het scherm prima leest en ruis toevoegt aan elke embedding. Paginamarkeringen zijn het tegenovergestelde geval: houd ze vast. Elke markering is een HTML-comment, <!-- page: 12 -->, onzichtbaar zodra de Markdown wordt gerenderd en makkelijk te parsen wanneer je chunks splitst, zodat een opgehaalde passage de pagina kan citeren waar hij vandaan komt. Loopt een tabel door vanaf de vorige pagina, dan wordt de markering voor de nieuwe pagina weggelaten zodat de pipe-tabel in één stuk blijft
Twee gedragingen vangen mensen die pagina voor pagina in een lus exporteren. Ten eerste worden doorlopende koppen herkend aan herhaling: een alinea in de bovenste of onderste 12 procent van de pagina geldt als meubilair wanneer matchende tekst in dezelfde band op een andere pagina van dezelfde export zit, met genormaliseerde cijfers zodat "Page 3 of 40" matcht met "Page 4 of 40". Een aanroep voor één pagina heeft geen andere pagina om tegen af te zetten, dus een ongetagde doorlopende kop blijft in de tekst. Ten tweede worden afbeeldingen in Markdown inline ingebed als data:-URI's, wat het bestand zelfstandig houdt en betekent dat een pagina met een grote foto honderden kilobytes base64 aan het bestand kan toevoegen. Heeft je chunker een groottelimiet, dan stript u regels die met ![PDF image beginnen voordat je splitst
Markdown- en DOCX-optievlaggen uit elkaar houden
De Markdown- en DOCX-constanten delen de lage bits maar betekenen verschillende dingen. PDF_DOCX_INCLUDE_IMAGES is 1, dezelfde waarde als PDF_MARKDOWN_INCLUDE_PAGE_MARKERS. Geef de DOCX-constante door aan een Markdown-aanroep en de compiler is tevreden, de aanroep slaagt, en je krijgt paginamarkeringen. Alleen een bit buiten het Markdown-bereik wordt geweigerd:
var
Md: WideString;
begin
// Compileert en draait: 1 wordt gelezen als PDF_MARKDOWN_INCLUDE_PAGE_MARKERS
Md := Pdf.ExportDocumentMarkdown('', PDF_DOCX_INCLUDE_IMAGES);
// PDF_DOCX_PRESERVE_PAGE_BREAKS is 8, buiten het Markdown-masker:
// Md komt leeg terug en LastErrorCode is 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;
Een lege string is ook een legitieme uitkomst voor een pagina zonder enige tekst, dus check LastErrorCode voordat je '' als error behandelt. Extractiefalen meldt 517 (PDFLIB_ERROR_MARKDOWN_EXPORT); slechte argumenten, inclusief een paginabereik dat naar geen enkele pagina resolveert, melden 113
DOCX zonder Office op de machine
SaveDOCXToFile en SaveDOCXToStream schrijven het WordprocessingML-pakket zelf: de ZIP-container, de document-, nummerings- en relatieonderdelen, en PNG-media. Niets roept Word of COM aan, dus de conversie draait op een headless server, onder een serviceaccount of in een container, allemaal plekken waar Office-automatisering niet gelicenseerd, onstabiel of niet geïnstalleerd is
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 is bij succes gelijk aan het aantal pagina's in het bereik
if Written <> 40 then
raise Exception.CreateFmt('DOCX export stopped after %d pages, error %d',
[Written, Pdf.LastErrorCode]);
finally
Pdf.Free;
end;
end;
Lijsten worden geschreven met Word's eigen nummeringsdefinities in plaats van getypte "1."-prefixen, dus het invoegen van een item in Word hernummert de rest. Gedetecteerde tabellen worden echte Word-tabellen met kolombreedtes uit de gemeten kolomranden en een gearceerde koprij. Met PDF_DOCX_PRESERVE_PAGE_BREAKS gezet begint elke bronpagina op een nieuwe Word-pagina, behalve waar een tabel van de vorige pagina doorgaat; die pagina-einde wordt weggelaten zodat de tabel één tabel blijft. Laat de vlag weg wanneer gebruikers de tekst toch gaan omlopen, want een hard pagina-einde elke 40 regels staat hen in de weg
De retourwaarde is het aantal geschreven pagina's. Een streamexport die minder pagina's teruggeeft dan je vroeg is halverwege gefaald, en de stream houdt een incompleet pakket vast, dus gooi hem weg in plaats van hem aan Word te geven
Deterministische DOCX-verpakking
Twee conversies van dezelfde PDF met dezelfde opties produceren een byte-voor-byte identiek DOCX-bestand, dus je kunt de uitvoer hashen om verandering te detecteren, twee builds van een gegenereerd document diffen, en resultaten cachten zonder te vrezen dat een identieke invoer een ander artefact opleverde
Twee keuzes maken dat mogelijk. Elke ZIP-invoer draagt dezelfde vaste DOS-datum, 1 januari 1980, in plaats van de tijd van de run, en het core properties-onderdeel heeft geen aanmaak- of wijzigingsdatums. Elke invoer wordt alleen met ruwe Deflate gecomprimeerd wanneer dat hem werkelijk kleiner maakt, dus PNG-media, al gecomprimeerd, worden ongecomprimeerd opgeslagen. Het eerste punt bevestig je met unzip -v handbook.docx: elke rij toont dezelfde datum
Office-automatisering kan je dat niet geven. Opslaan via Word stempelt de huidige tijd in de pakketmetadata en de ZIP-headers, dus hetzelfde document twee keer geconverteerd verschilt op manieren die een hash slopen. Dezelfde redenering zit achter de stabiele bestandsidentifiers in deterministische PDF-ID's voor reproduceerbare builds: zodra output reproduceerbaar is wordt verificatie een vergelijking
Welke invoer goed convergeert, en welke nooit
Conversiekwaliteit varieert meer met de invoer dan met de converter, en het loont dat je gebruikers dat vooraf vertelt. Getagde PDF's en netjes gegenereerde zakelijke documenten (facturen, rapporten, contracten) converteren goed: koppen landen als koppen, tabellen overleven het, lijsten hernummeren in Word. Tweekoloms academische indelingen komen in de juiste leesvolgorde door wanneer de kolomgeometrie regelmatig is, en de diagnostiek meldt geometric-columns voor die pagina's. Tabellen die over pagina's heen breken worden door inferentie weer samengevoegd, dus steekproef ze na. Zwaar vormgegeven marketingmateriaal, waarin tekst op effect is geplaatst in plaats van in leesvolgorde, geeft elke converter weinig om terug te halen; reken erop het resultaat met de hand bij te werken
Gescande documenten zijn een apart geval. Een pagina die één grote afbeelding is bevat geen tekstobjecten, dus er is niets te exporteren totdat er een tekstlaag bestaat, en OCR draaien is een vereiste voor beide formaten. Leg je je vast op een grote batch, sample dan een dozijn representatieve bestanden en som op wat hun pagina's bevatten, zoals beschreven in tekstzoeken en pagina-elementen opsommen; een pagina met afbeeldingen en geen textruns vertelt je in een seconde meer dan de geconverteerde uitvoer lezen zal
Kies het formaat op wat er daarna gebeurt. Markdown past bij machines en pijplijnen: koppen worden chunkgrenzen, tabellen blijven leesbaar als pipe-tabellen, en paginamarkeringen geven elke chunk een citatie. DOCX past bij mensen die het document moeten wijzigen, want wat ze terugwillen is een bewerkbaar bestand in Word, met echte lijsten en echte tabellen, en alleen de tekst geeft hen dat niet
PDF Library for Delphi verschijnt voor Delphi, C++Builder en Lazarus, met DLL- en ActiveX-edities die dezelfde Markdown- en DOCX-exportaanroepen blootleggen aan C#, C++ en scripting hosts. De referentie voor elke optievlag en een proefdownload staan op de PDF Library for Delphi-productpagina