Preflight Cookbook

This cookbook groups the preflight APIs and demos into task-oriented recipes. Use the API reference when you need exact signatures; use this page when you need a working path for an application, build script, or CI job.

Choose an output format

var
  PDF: THotPDF;
begin
  PDF := THotPDF.Create(nil);
  try
    PDF.SavePreflightReport('Input.pdf', 'Input.preflight.txt');
    PDF.SavePreflightReport('Input.pdf', 'Input.preflight.json', '', pfJSON);
    PDF.SavePreflightReport('Input.pdf', 'Input.preflight.html', '', pfHTML);
  finally
    PDF.Free;
  end;
end;

Text output is byte-stable and diff-friendly. JSON is suitable for pipeline ingestion. HTML is self-contained and can be opened directly or saved as a CI artifact.

Validate PDF/VT documents

var
  PDF: THotPDF;
  Report: AnsiString;
begin
  PDF := THotPDF.Create(nil);
  try
    if not PDF.ValidatePDFVT('Input.pdf', Report) then
      WriteLn(string(Report));
  finally
    PDF.Free;
  end;
end;

The PDF/VT report focuses on the ISO 16612-2 identification and document-part structure: XMP GTS_PDFVTVersion in element text or RDF attribute form, modification-date matching, PDF/X base marker, output intent, DPartRoot, DPartRootNode, NodeNameList, and page-level DPart coverage.

Apply a profile

var
  PDF: THotPDF;
  Report: AnsiString;
begin
  PDF := THotPDF.Create(nil);
  try
    Report := PDF.CreatePreflightReportWithProfile(
      'Input.pdf', '', 'project-preflight.ini', pfJSON);
  finally
    PDF.Free;
  end;
end;

Profiles suppress named checks, warnings, or all hints. Use ValidatePreflightProfile before applying a user-authored profile when failing closed is more important than silently ignoring an obsolete name.

Create a reusable profile from a preset

var
  PDF: THotPDF;
  Profile: THPDFPreflightProfile;
begin
  PDF := THotPDF.Create(nil);
  try
    Profile := PDF.GetBuiltInPreflightProfile('compact');
    Profile.DisableWarnings := 'OpenAction,JavaScript,URIAction';
    PDF.SavePreflightProfile(Profile, 'compact-no-actions.ini');
  finally
    PDF.Free;
  end;
end;

Use MergePreflightProfiles to combine a preset with project-specific names. Use DiffPreflightProfiles to review profile drift before updating a shared configuration file.

Archive the report with the PDF

PDF.EmbedPreflightReportInPDF('Input.pdf', 'Input-with-report.pdf');
PDF.EmbedPreflightReportAsXMP('Input.pdf', 'Input-with-xmp-report.pdf');

The text embedding path appends a readable comment block after the final EOF marker. The XMP path appends an RDF-shaped payload for archive workflows that scan metadata packets.

Validate an embedded report

var
  OriginalReport: AnsiString;
  CurrentReport: AnsiString;
begin
  if not PDF.LoadAndValidatePreflightReport(
    'Input-with-report.pdf', OriginalReport, CurrentReport) then
    WriteLn(string(PDF.ComparePreflightReports(OriginalReport, CurrentReport)));
end;

The validation path compares the embedded fingerprint with a fresh preflight run over the source bytes. The diff helper is line-oriented and tuned for HotPDF preflight reports.

Run a conservative repair pass

var
  RepairsApplied: AnsiString;
begin
  if PDF.RepairPDFFromPreflightReport(
    'Broken.pdf', 'Broken-repaired.pdf', RepairsApplied) then
    WriteLn(string(RepairsApplied));
end;

The repair helper intentionally stays narrow. It handles trailing bytes after the final EOF marker and missing EOF markers, but does not rebuild cross-reference tables or rewrite streams.

Aggregate many reports

Reports[0] := PDF.CreatePreflightReport('A.pdf');
Reports[1] := PDF.CreatePreflightReport('B.pdf');
Summary := PDF.AggregatePreflightReports(Reports);

The aggregate output lists one status line per PDF and totals for processed reports, failures, and warnings. It is useful when a pipeline needs one summary even though detailed reports are kept per input file.

Use the command-line tool

HotPDFPreflight Input.pdf -f json -o reports
HotPDFPreflight Input.pdf --pdfvt -o reports
HotPDFPreflight C:\Archive -r --preset compact -f text -o reports --aggregate reports\Aggregate.txt
HotPDFPreflight C:\Archive -r --profile project-preflight.ini -f html -o reports

The CLI mirrors the library workflow: one file or recursive directory input, text / JSON / HTML output, optional password, optional profile, built-in preset, verbose progress, and aggregate summary.

Build a static dashboard

PreflightDashboard C:\Archive C:\Archive\preflight-dashboard

The dashboard demo writes an index.html plus per-file HTML reports. No web server is required, so the output can be published as a static artifact.

Adapt to veraPDF-style JSON consumers

Report := PDF.CreatePreflightReport('Input.pdf');
JSON := PDF.ConvertPreflightReportToVeraPDFStyle(Report);

The adapter keeps HotPDF semantics while reshaping failures into a familiar validation-result structure for tooling that already consumes veraPDF-like JSON.

Related Topics