Articolo tecnico

Le pagine PDF unite alzano la versione nel catalogo

Un contratto scansito nel 2004 comincia con %PDF-1.3, e dopo che un merge ingenuo aggiunge due pagine di brochure con un font OpenType incorporato e una foto a 16 bit, pdfinfo continua a riportare PDF 1.3. La versione giusta va nel catalogo della revisione aggiunta come /Version /1.6, cosa che ISO 32000-1 §7.5.6 permette e che la page import di HotPDF scrive dagli oggetti che copia

Perché un salvataggio incrementale non può riscrivere %PDF-1.3?

Perché i vecchi byte restano un prefisso del nuovo file. Un incremental update aggiunge un nuovo body, una nuova sezione di cross-reference e un nuovo trailer dopo l'ultimo %%EOF, e lascia stare ogni byte precedente. I validatori di firme ci contano, dato che il /ByteRange di una firma esistente copre il vecchio header. Gli strumenti di revision-diff vanno oltre e trattano "il file originale è un prefisso del nuovo" come la definizione stessa di un salvataggio incrementale. Patchare otto byte all'offset zero manterrebbe validi tutti gli offset di cross-reference e romperebbe comunque il prefisso. La specifica l'aveva previsto. Dal PDF 1.4 uno writer può scavalcare l'header con la voce Version del catalogo, e la NOTE 4 di §7.5.6 dice che la voce esiste proprio perché la versione possa cambiare durante un incremental update. La Table 28 aggiunge le regole di lettura. Il valore è un name object (/1.6, non il numero 1.6); si applica solo quando è più avanti dell'header; quando l'header è più avanti o la voce manca, vince l'header. La versione effettiva è la maggiore delle due. Un reader che controlla solo la prima riga del file dichiara meno di quanto sia per ogni documento aggiornato incrementalmente

Layout dell'incremental update di un PDF unito in Delphi con HotPDF: l'header 1.3 intatto resta un prefisso mentre il catalogo aggiunto porta Version 1.6
La riga di header non può cambiare durante un incremental update, quindi il catalogo aggiunto porta il nome Version necessario e i reader prendono la più avanti delle due

Gli oggetti copiati che alzano la versione richiesta

La versione richiesta viene dalle funzionalità, non dall'header del file sorgente. THPDFHeadlessDocument.AppendImportedPages percorre i dizionari di pagina e le risorse che clona e registra la versione più alta che qualunque voce copiata, non nulla, richiede. I tag sono gli stessi usati quando si salva verso una versione PDF esatta con controlli di funzionalità; qui girano verso l'alto, alzando il livello dichiarato. Ogni riga accoppia un controllo che l'import applica con la versione che ISO 32000-1 stampa accanto alla voce:

Contenuto copiatoRichiedeDove lo dice la specifica
Transparency group, soft mask (/SMask) o parametri ExtGState trasparentiPDF 1.4Modello di trasparenza, §11
Stream di metadati XMP (/Type /Metadata /Subtype /XML)PDF 1.4§14.3.2
Dati immagine compressi con JBIG2DecodePDF 1.4§7.4.7
Dati immagine compressi con JPXDecodePDF 1.5§7.4.9
Immagine a 16 bit, che sia un image XObject o un'immagine inline nel content streamPDF 1.5Table 89, §8.9.7
/PresSteps non nullo, oppure una /Trans di stile Fly, Push, Cover, Uncover o Fade, o una con /SS o /BPDF 1.5Table 30, Table 162
Optional content portato dietro dalle paginePDF 1.5§8.11
/FontFile3 con /Subtype /OpenTypePDF 1.6Table 126
/UserUnit di pagina, layer bloccati, o un'espressione di visibilità OCMD /VEPDF 1.6Table 30, §8.11

Gli stili di transizione più vecchi come Dissolve, Wipe o Split risalgono al PDF 1.1 e non alzano nulla, quindi l'import legge il valore /S di un dizionario di transizione; la sola presenza di /Trans non prova nulla. La scrittura arriva dopo il giro. Un name /Version va nella nuova revisione quando esiste una versione richiesta ed è maggiore sia della versione di header del target sia di qualunque /Version che il catalogo porta già; altrimenti il catalogo non prende alcuna voce /Version. L'header non viene mai modificato. Lo stesso paragrafo di §7.5.6 chiede a uno writer di aggiornare il dizionario /Extensions del catalogo quando un aggiornamento aggiunge o toglie developer extensions. La page import copia solo oggetti a livello di pagina, quindi /Extensions resta come lo aveva il target

Gradino delle versioni della page import di HotPDF in Delphi: font OpenType, immagini a 16 bit e trasparenza alzano il requisito da 1.3 a 1.6 nel catalogo aggiunto
Il giro dell'import registra la versione più alta che qualunque voce copiata richiede, e il nome Version atterra nel nuovo catalogo solo quando supera sia l'header sia qualunque override precedente
uses
  SysUtils, HPDFHeadlessDocument;

procedure AppendBrochurePages(const ContractFile, BrochureFile, OutputFile: string);
var
  Target, Source: THPDFHeadlessDocument;
  Options: THPDFHeadlessPageImportOptions;
  Outcome: THPDFHeadlessPageImportResult;
begin
  Target := THPDFHeadlessDocument.Create;
  Source := THPDFHeadlessDocument.Create;
  try
    Target.LoadFromFile(ContractFile);   // intestazione: %PDF-1.3
    Source.LoadFromFile(BrochureFile);   // esportazione PDF 1.7: /FontFile3 /OpenType + foto a 16 bit

    Options := THPDFHeadlessPageImportOptions.Default;
    // Gli indici di pagina sono zero-based: copiate la copertina e la scheda tecnica
    Outcome := Target.AppendImportedPages(Source, [0, 2], Options);

    // Salvato come incremental update: i vecchi byte restano un prefisso.
    // Atteso: la nuova revisione del catalogo porta /Version /1.6,
    // e la prima riga del file continua a leggere %PDF-1.3
    Target.SaveToFile(OutputFile);
    WriteLn(Format('%d pages added, %d annotations flattened',
      [Outcome.AddedPages, Outcome.FlattenedAnnotations]));
  finally
    Source.Free;
    Target.Free;
  end;
end;

Per questa coppia il font program OpenType fissa il requisito a 1.6, e la foto a 16 bit da sola si sarebbe fermata a 1.5. Sorgente e target devono essere due documenti caricati distinti. Un target già firmato o certificato viene rifiutato, perché aggiungere pagine cambia ciò che la firma attesta

Le immagini inline vivono dentro il content stream

Un'immagine inline non è mai un oggetto. ISO 32000-1 §8.9.7 la definisce come una sequenza BI … ID … EI scritta direttamente in un content stream, con chiavi abbreviate come /BPC per /BitsPerComponent, e raccomanda la forma solo per immagini piccole, 4 KB o meno. Una profondità a 16 bit lì vuole PDF 1.5 esattamente come su un image XObject, ma un giro per gli oggetti non la incontra mai, perché quei byte viaggiano dentro il /Contents copiato. Così l'import decodifica anche i content stream di ogni pagina copiata, e di ogni Form XObject e tiling pattern che clona, e li scansisce una volta cercando un header BI la cui profondità sia 16. Una ricerca testuale sparerebbe nel vuoto. L'operando di un operatore show-text può contenere il letterale (BI /BPC 16 ID), e una riga di commento può leggere % BI /BPC 16. Dopo ID, un singolo byte di white space lascia il posto a campioni binari grezzi che corrono fino a un token EI con white space da entrambi i lati — e quei byte di campioni possono comporre BI per caso. Lo scanner quindi salta oltre letterali e stringhe esadecimali, commenti e dati di campioni inline, e si ferma al primo header a 16 bit autentico. Un'immagine inline a 8 bit, o una stringa che menziona solo /BPC 16, lascia la versione dov'era

Flusso di scansione del content stream usato dalla page import di HotPDF in Delphi per trovare un'immagine inline a 16 bit saltando oltre commenti, stringhe e sosia binari
Le immagini inline si nascondono dentro i content stream copiati, così lo scanner salta oltre commenti, stringhe e byte di campioni finché non compare un header a 16 bit autentico

È l'header del file sorgente a decidere la versione?

No. La decidono le pagine scelte. Timbrare il 1.7 della brochure sul merge sovrastima il risultato ogni volta che quelle pagine non usano nulla oltre gli operatori di disegno del PDF 1.3. Una versione sovrastata può mandare un documento qualunque per la strada sbagliata in un workflow di stampa o in un gateway di archivio che ordina i file per versione. Abbinare le chiavi ignorandone i valori sbaglia nella stessa direzione. /Mask null, /PresSteps null e un dizionario /Trans con /S /Dissolve contengono tutti la chiave interessante, nessuno di loro vuole una versione più nuova, e uno scanner che reagisce ai nomi delle chiavi alza la versione per file che non ne avevano bisogno

Una funzionalità PDF 1.3 in un file PDF 1.2 si dichiara come 1.4

Il caso sottile sta in fondo alla gamma delle versioni. Le image mask esplicite e color-key (/Mask nella Table 89) sono etichettate PDF 1.3. Copiate una simile immagine in un documento %PDF-1.2 e il requisito rigoroso è 1.3. Ma /Version nasce con il PDF 1.4. Scrivere /Version /1.3 in un file 1.2 usa un meccanismo che il livello dichiarato non ha, quindi un reader rigoroso non ha motivo di onorarlo. HotPDF dichiara 1.4 in quel caso: una image mask che entra in un documento il cui header è sotto 1.3 alza il requisito dritto a 1.4, la prima versione in cui l'override è legale. Un target già a 1.3 per la stessa immagine non vuole alcun override

Come si rilegge la versione effettiva?

Prendete la versione di header, cercate il nome /Version nel catalogo, e usate la più avanti delle due. Un parser completo raggiunge il catalogo attraverso il /Root del trailer. Per un controllo rapido in un job batch spesso basta una scansione dei byte, con una avvertenza detta subito: trova la voce solo quando la revisione del catalogo più recente è scritta come oggetto semplice, fuori da qualunque object stream compresso. Cercate dal fondo. Un file aggiornato incrementalmente può tenere un catalogo per revisione: l'originale, poi una copia sostitutiva completa in ogni aggiornamento. I reader usano la copia più recente di ogni oggetto (§7.5.6), quindi l'ultimo /Version del file appartiene di norma al catalogo vivo. Un risultato vuoto significa che questa scansione non ha trovato override in testo semplice; un parser può trovarne ancora uno dentro un object stream. La funzione ritorna la versione effettiva come stringa tipo 1.6, e la barriera che la segue protegge un canale PDF/A-1, il cui standard di base ISO 19005-1 è costruito sul PDF 1.4:

uses
  SysUtils, IOUtils;

function EffectivePdfVersion(const FileName: string): string;
const
  Key: RawByteString = '/Version';
var
  Bytes: TBytes;
  Text: RawByteString;
  P, Q: Integer;
  Declared: string;
begin
  Result := '';
  Bytes := TFile.ReadAllBytes(FileName);
  if Length(Bytes) < 8 then
    Exit;                                     // troppo corto per '%PDF-1.x'
  SetString(Text, PAnsiChar(@Bytes[0]), Length(Bytes));
  if Copy(Text, 1, 5) <> '%PDF-' then
    Exit;
  Result := string(Copy(Text, 6, 3));        // '%PDF-1.3' -> '1.3'

  // La revisione più recente sta in fondo, quindi cercate all'indietro
  P := Length(Text) - Length(Key) + 1;
  while (P > 0) and (Copy(Text, P, Length(Key)) <> Key) do
    Dec(P);
  if P = 0 then
    Exit;                                     // nessun override in testo semplice trovato

  Q := P + Length(Key);
  while (Q <= Length(Text)) and (Text[Q] in [#0, #9, #10, #12, #13, #32]) do
    Inc(Q);
  if (Q < Length(Text)) and (Text[Q] = '/') then
  begin
    Declared := string(Copy(Text, Q + 1, 3)); // name object: /1.6
    if Declared > Result then                 // l'header vince quando è più avanti
      Result := Declared;
  end;
end;

procedure RequirePdfA1Channel(const FileName: string);
var
  Version: string;
begin
  Version := EffectivePdfVersion(FileName);
  if Version > '1.4' then
    raise Exception.CreateFmt(
      '%s declares PDF %s; the PDF/A-1 channel takes PDF 1.4 at most',
      [ExtractFileName(FileName), Version]);
end;

Il confronto tra stringhe funziona perché ogni versione PDF pubblicata ha un numero minore a una cifra, e 2.0 ordina comunque sopra ogni valore 1.x. Notate cosa la barriera lascia stare. Non rimuove /Version per far passare il file di nascosto, e non si fida mai del solo header. Un controllo solo-header farebbe passare il contratto unito. Il file porta ancora un formato font PDF 1.6

Rifiutare o degradare per una pipeline limitata al 1.4

Cancellare l'override è la riparazione sbagliata. Gli oggetti che richiedevano 1.6 sono ancora nel file, quindi un reader attento alla versione vedrebbe un documento 1.3 con un formato font 1.6, e i tool di preflight riportano quel disallineamento. Un canale davvero limitato al 1.4 ha due opzioni sane. Rifiutare il merge prima che venga salvato, con la versione effettiva come test, oppure riportare prima le pagine sorgente al livello del target — convertite il contenuto di font e immagini nello strumento di authoring, poi importate il risultato. Rifiutare presto è il migliore dei predefiniti. L'errore nomina il file e la versione mentre il job gira ancora, cosa che costa molto meno da supportare di un fallimento di validazione che nessuno sa spiegare una settimana dopo. Un requisito si può togliere al momento dell'import: con Options.RemovePresentationSteps := True le pagine copiate lasciano fuori /PresSteps, così la navigazione tra sottopagine non aggiunge nulla alla versione richiesta. Quando la decisione spetta al salvataggio, un pre-controllo della versione prima del salvataggio ferma il job prima che venga scritto qualunque byte

Per il contratto del 2004 il numero da cercare è 1.6. Chiamate EffectivePdfVersion sull'output unito nello stesso servizio che ha fatto girare AppendImportedPages del componente PDF HotPDF per Delphi. Un canale limitato al 1.4 può così mandare via il job mentre l'errore nomina ancora le pagine di brochure che l'hanno alzato