Articolo tecnico

Sillabazione e colonne bilanciate nei PDF con Delphi

Versa una scheda prodotto tedesca in tre colonne da 148 punti e due cose vanno storte in una volta. La riga davanti a una parola come Rechnungsprüfungsausschuss può chiudersi con un terzo di vuoto, perché lo spazio prima di quel composto di 26 lettere era l'unico punto dove spezzare. E sull'ultima pagina il testo residuo riempie una colonna, parte di una seconda, e lascia la terza vuota. Un breaker che conosce solo gli spazi, e non conta mai ciò che resta, produce esattamente quella pagina

La correzione ha due metà: spezzare dentro le parole usando regole per la lingua del testo, e dimensionare le colonne finali dal numero di righe ancora da piazzare. Entrambe le metà funzionano solo se il conteggio di righe usato per la decisione arriva dalle stesse interruzioni che verranno disegnate, sillabazione inclusa, a una larghezza di colonna di 148 punti anziché alla regione da 480 punti

Un flusso a tre colonne con sillabazione in PDF Library for Delphi

PDF Library for Delphi tiene un passaggio come flusso di testo: NewTextFlow restituisce un handle, SetTextFlowLanguage e SetTextFlowHyphenation controllano dove le parole si possono spezzare, e DrawTextFlowColumns versa quanto testo resta in una fino a 64 colonne di uguale larghezza e fa avanzare il flusso. La larghezza di colonna è la larghezza della regione meno i gutter, divisa per il numero di colonne, così una regione da 480 punti con tre colonne e gutter da 18 punti dà (480 − 2 × 18) / 3 = 148 punti per colonna

La chiamata restituisce il numero totale di righe che ha disegnato. Zero significa che niente è entrato, e in quel caso il flusso sta dov'era, così nessun testo va perso; la trappola è un ciclo di pagine che continua a chiamare NewPage mentre la chiamata continua a restituire zero. Accade quando la regione è più corta di una riga, o quando un'impostazione di righe minime non può essere soddisfatta nello spazio offerto. Il ciclo qui sotto tratta zero come un errore invece di girare a vuoto

var
  Lib: TPDFlib;
  FontID, Flow, Drawn: Integer;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetDocumentLanguage('de-DE');      // prima di NewTextFlow, vedi sotto
    FontID := Lib.AddTrueTypeFont('Georgia', 1);
    Lib.SetTextSize(10.5);

    Flow := Lib.NewTextFlow(ArticleBody);
    try
      Lib.SetTextFlowHyphenation(Flow, 1, 3, 3);
      Lib.SetTextFlowMinLines(Flow, 2);   // nessuna singola riga isolata a piede di colonna

      repeat
        // Sinistra 66, Top 72, regione di 480 x 620 pt, 3 colonne, gutter da 18 pt, bilanciata
        Drawn := Lib.DrawTextFlowColumns(Flow, 66, 72, 480, 620, 3, 18, 1);
        if Lib.TextFlowFinished(Flow) = 1 then
          Break;
        if Drawn = 0 then
          raise Exception.Create('Column region cannot take the next lines');
        Lib.NewPage;
        Lib.SelectFont(FontID);
        Lib.SetTextSize(10.5);            // NewPage riporta il font a 12 pt
      until False;
    finally
      Lib.ReleaseTextFlow(Flow);
    end;

    Lib.SaveToFile('newsletter.pdf');
  finally
    Lib.Free;
  end;
end;

Le coordinate si misurano dall'angolo in alto a sinistra della pagina qualunque origine tu abbia impostato, perché la chiamata di colonna dispone le sue righe verso il basso da Top. Con l'allineamento a sinistra predefinito, ogni riga parte dal bordo sinistro della propria colonna, così il gioco di un'interruzione sbagliata compare come bordo destro a dente di sega; nel testo giustificato lo stesso gioco diventa fiumi

Confronto PDF Library for Delphi di colonne strette giustificate con e senza sillabazione, che mostra come abilitare la sillabazione spezza la parola lunga ed elimina i fiumi di spazio bianco
La sillabazione consapevole della lingua mette l'interruzione dentro la parola, così il gioco della giustificazione non si raccoglie mai in fiumi

Da dove arriva la lingua della sillabazione?

Un flusso nuovo prende la propria lingua dalla voce /Lang del Catalog del documento nel momento in cui NewTextFlow gira. È lo stesso valore che leggono screen reader e indicizzatori di ricerca, quindi un documento che già dichiara la propria lingua, come fa l'output taggato della tagging automatica per PDF accessibili, si prende la sillabazione gratis. Il momento conta, però. Chiami SetDocumentLanguage dopo che il flusso esiste e quel flusso non la vede mai; il primo esempio imposta la lingua prima per esattamente quella ragione

Quando il tag nomina una lingua supportata, la sillabazione automatica si accende da sola. Le regole coprono inglese, tedesco, olandese, francese, spagnolo, italiano, portoghese, russo, turco, danese, svedese, finlandese, polacco, ceco e ungherese. I sottotag di regione vengono tolti prima della ricerca, così de-CH, de-AT e de sillabano tutti come tedesco. Un tag che le regole non coprono, come ja, viene accettato, e l'interruzione automatica semplicemente si spegne per quel flusso

Tre valori di ritorno ti dicono cosa è successo, e in un codice che riceve la lingua da dati utente vale la pena controllarli:

  • SetTextFlowLanguage restituisce 0 solo per un tag malformato; un tag ben formato per una lingua non coperta restituisce 1 e lascia la sillabazione automatica spenta
  • SetTextFlowHyphenation con Enable = 1 restituisce 0 quando la lingua del flusso non ha regole, così un breaker non può inventarsi punti di interruzione senza una lingua alle spalle
  • GetTextFlowHyphenation riporta se l'interruzione automatica è attiva in questo momento, che è il valore da loggare quando un layout sembra sbagliato

Anche qui l'ordine conta. SetTextFlowLanguage ricalcola lo stato on/off dalla nuova lingua, quindi chiamarla dopo SetTextFlowHyphenation(Flow, 0, …) riaccende la sillabazione per una lingua supportata. Imposta la lingua, poi le opzioni di sillabazione

MinPrefix e MinSuffix sono un'impostazione di stile editoriale

I due interi dopo il flag di attivazione sono il numero minimo di lettere che devono restare sulla riga prima di un'interruzione e passare alla riga successiva dopo di essa. Entrambi accettano da 1 a 16. Quando la sillabazione si accende per la sola lingua, entrambi valgono 2, e una parola viene presa in considerazione per lo spezzamento solo quando ha almeno MinPrefix + MinSuffix + 1 lettere

Due e due è l'impostazione che cambieremmo in quasi ogni documento. Produce più opportunità di interruzione, ma un frammento di due lettere in fondo a una riga si legge come un refuso, e in tedesco o olandese stacca cose come un prefisso di due lettere che il lettore deve poi riattaccare. Tre e tre costa qualcuna riga a dente di sega in più e sembra tipografia. Alza ulteriormente i minimi per i corpi grandi, dove ogni frammento è prominente; scendi a due solo per una colonna davvero stretta in cui hai deciso che una misura fitta batte una pulita

Quali parole si possono spezzare, e che fine fa un URL

Le righe si spezzano agli spazi e ai tab, e un line feed forza una riga nuova. Dentro una parola, la sillabazione automatica guarda solo parole fatte interamente di lettere (latino, comprese le gamme Latin Extended accentate, e cirillico), con ogni punteggiatura iniziale o finale messa da parte. Le regole sono combinazioni prudenti di vocali, gruppi consonantici legali e affissi comuni, quindi piazzano meno punti di interruzione di quanto farebbe un sillabatore a dizionario. Le parole con cifre o punteggiatura interna, come ISO-32000 o v2Beta, e le parole più lunghe di 128 lettere non ricevono punti automatici

I soft hyphen (U+00AD) sono l'override. Se una parola ne contiene almeno uno, quelle posizioni diventano i suoi unici punti di interruzione: le regole automatiche vengono saltate per quella parola, e i soft hyphen funzionano anche quando la sillabazione automatica è spenta o la lingua non ha regole. Usali per nomi di marca, codici prodotto e termini che le regole spezzano male; nell'esempio successivo, Rechnungs e prüfungs sono gli unici due punti in cui il composto può spezzarsi

var
  Flow: Integer;
  Body, Rest: WideString;
begin
  // U+00AD segna gli unici posti in cui questo composto può spezzarsi
  Body := 'Die Pr' + #$00FC + 'fung erfolgt durch den Rechnungs' + #$00AD +
    'pr' + #$00FC + 'fungs' + #$00AD + 'ausschuss der Gesellschaft';
  Flow := Lib.NewTextFlow(Body);
  try
    if Lib.SetTextFlowLanguage(Flow, CustomerLanguageTag) = 0 then
      raise Exception.Create('Malformed language tag: ' + CustomerLanguageTag);
    if Lib.SetTextFlowHyphenation(Flow, 1, 3, 3) = 0 then
      LogWarning('No hyphenation rules; only soft hyphens will break words');
      // LogWarning è una tua routine di logging

    Lib.DrawTextFlow(Flow, 72, 72, 148, 240);

    // Tutto ciò che non è entrato torna esattamente come passato,
    // soft hyphen inclusi
    Rest := Lib.GetTextFlowRemaining(Flow);
  finally
    Lib.ReleaseTextFlow(Flow);
  end;
end;

Un hyphen-minus viene disegnato solo all'interruzione effettivamente scelta. I soft hyphen non scelti sono invisibili sia in misurazione sia in disegno, e l'interruzione viene registrata rispetto al testo originale, che è perché GetTextFlowRemaining restituisce i soft hyphen intatti. Il design ingenuo sbaglia in modo riconoscibile: scrive il trattino nella stringa mentre prova un candidato, l'interruzione poi si sposta, e un trattino vagante finisce in mezzo a una riga

Un token che non entra in nessuna riga, un URL lungo o un numero di accesso senza interruzioni legali, viene tagliato al prefisso più lungo che entra, senza aggiungere trattini. Il taglio non atterra mai tra le due metà di una surrogate pair né davanti a un segno combinante, così un'emoji o una lettera accentata non vengono mai divise tra due righe

Cosa cambia Balance=1 sull'ultima pagina

L'argomento Balance conta solo quando tutto ciò che resta entra nella regione. In quel caso DrawTextFlowColumns divide il numero di righe rimaste per il numero di colonne, arrotonda per eccesso, e usa quello come altezza di ogni colonna. Ventidue righe rimaste in tre colonne escono come 8, 8 e 6. Quando il residuo non entra, ogni colonna tiene la propria altezza piena, così la pagina porta quanto può e il resto continua nella pagina successiva

Un'impostazione di righe minime può alzare l'altezza bilanciata. Con SetTextFlowMinLines(Flow, 3) e quattro righe rimaste, l'altezza bilanciata di due sta sotto il minimo, quindi le colonne si riempiono in ordine: tre righe nella prima colonna, una nella seconda, la terza vuota. Una coda corta proprio alla fine del passaggio viene comunque piazzata, dato che non ha nessun altro posto dove andare. Per tenere insieme almeno due righe anche in cima alla colonna successiva, SetTextFlowPaginationLines prende i minimi di orfana e vedova in una chiamata sola

Diagramma PDF Library for Delphi del parametro Balance che mantiene piene le regioni di colonna precedenti mentre accorcia la regione finale a un numero uguale di righe in ogni colonna
Il bilanciamento si applica solo alla fine di un passaggio, dove riporta ogni colonna allo stesso numero di righe

Per gli articoli continui, passa 1 ogni volta. A metà passaggio non cambia niente. Le colonne sono piene comunque. Passeremmo 0 solo quando la regione di colonna è un box fisso in un layout tipo form, dove un residuo di 52 righe in colonne da 43 dovrebbe atterrare come 43, 9 e 0 anziché 18, 18 e 16

Quando il layout dipende da quanto è lungo il passaggio, misura prima di disegnare. MeasureTextFlow restituisce quante righe il resto del flusso richiede a una data larghezza, usando lo stesso spezzamento, sillabazione inclusa, senza muovere il flusso

var
  Flow, Needed, LinesPerColumn: Integer;
  LinePitch: Double;
begin
  Flow := Lib.NewTextFlow(ArticleBody);
  try
    Lib.SetTextFlowLanguage(Flow, 'fr');
    Lib.SetTextFlowHyphenation(Flow, 1, 3, 3);

    Lib.SelectFont(FontID);
    Lib.SetTextSize(10.5);
    // Interlinea che usa la chiamata di colonna: 1.2 x l'altezza del testo selezionato
    LinePitch := Lib.GetTextHeight * 1.2;
    LinesPerColumn := Trunc(620 / LinePitch);

    Needed := Lib.MeasureTextFlow(Flow, (480 - 2 * 18) / 3);
    if Needed > 3 * LinesPerColumn then
      UseTwoPageSpread      // la tua scelta di layout
    else
      UseSinglePage;        // Balance=1 pareggerà le colonne

    Lib.DrawTextFlowColumns(Flow, 66, 72, 480, 620, 3, 18, 1);
    if Lib.TextFlowFinished(Flow) <> 1 then
      CarryOver(Lib.GetTextFlowRemaining(Flow));   // anche questo è tuo
  finally
    Lib.ReleaseTextFlow(Flow);
  end;
end;

Tieni font e dimensione identici da box a box

DrawTextFlow, DrawTextFlowColumns e MeasureTextFlow spezzano tutti le righe con il font e la dimensione selezionati nel momento in cui vengono chiamati. Cambia uno dei due tra due box dello stesso flusso e il secondo box spezza diversamente da ciò che il primo ha misurato. L'interlinea si muove con esso, dato che vale 1,2 volte l'altezza del testo selezionato. Supponi che GetTextHeight riporti 12 punti per il tuo font: l'interlinea è di 14,4 punti e una colonna da 620 punti tiene 43 righe

Il modo facile per inciampare è una pagina nuova. NewPage riseleziona il font corrente, ma a 12 punti, e SelectFont fa lo stesso. Un flusso impostato a 10,5 punti a pagina uno quindi gira a 12 punti dalla pagina due in poi, a meno che il ciclo non richiami SetTextSize: parole più larghe, interlinea più alta, meno righe per colonna, e un risultato di MeasureTextFlow di pagina uno che non corrisponde più. Il sintomo sembra intermittente perché pagina uno ha sempre ragione. Riseleziona il font e poi la dimensione dopo ogni NewPage, in quest'ordine, come fa il primo esempio

PDF Library for Delphi: diagramma di avviso delle interruzioni di riga che deviano dopo un cambio di font tra box, in contrapposizione al ciclo stabile di riselezione del font dopo ogni nuova pagina
Tutti e tre i metodi di flusso spezzano le righe con il font attualmente selezionato, così il font deve sopravvivere attraverso le pagine invariato

I passaggi che mescolano scritture passano per lo stesso percorso del font selezionato in misurazione e disegno, così le face sostitutive scelte dal fallback automatico dei font per testo CJK ed emoji non aprono nessun divario tra le due. Nei layout di report dove il flusso condivide la pagina con intestazioni, piè di pagina e blocchi guidati dai dati, l'ordine di il motore di report basato su dataset resta valido: misura prima, piazza gli elementi fissi, poi affida al flusso la regione che resta

Le chiamate di flusso di testo coperte qui, dalla creazione e misurazione al rewind e al rilascio, fanno parte di PDF Library for Delphi per Delphi, C++Builder e Lazarus. Il riferimento delle funzioni e il download sono sulla pagina prodotto di PDF Library for Delphi