EpubChek: La convalida dei file ePub

IDPF [International Digital Publishing Forum] è l’organismo ufficiale preposto alla stesura delle caratteristiche ‘standard’ del formato ePub. Licenziata recentemente la versione 3.0 l’istituto prosegue nel suo lavoro di definizione di standard.

La questione è molto importante perché pone l’obiettivo di definire in modo assolutamente traversale, un formato che possa ‘girare’ senza problemi su tutti i readers o tablet. La partita in gioco è enorme e non sempre fila tutto liscio, ma gli sviluppi sono costanti e di interesse (recentissimo il lancio del progetto READIUM).

IDPF fornisce un comodissimo strumento per verificare quanto un ePub risponda alle specifiche standard: EpubCheck

EpubCheck non compie nessun controllo sulla correttezza del codice interno (per questo esistono altri sistemi di convalida e controllo), ma solo una profondissima verifica sulla correttezza della struttura interna del file; sulla correttezza nell’espressione dei nomi dei file e della loro gerarchia, sul fatto che tutte le componenti siano dichiarate e che tutte le componenti dichiarate siano effettivamente esistenti … in soldoni una verifica completa che tutte le specifiche standard dettate da IDPF siano rispettate.

EpubCheck può essere utilizzato anche on-line da questa pagina (che oggi pare non funzionare) a patto di non verificare materiale commerciale e che il ‘peso’ del file ePub non superi i 10 Mb, ma consiglio vivamente il download del tool in locale per avere libertà assoluta sul materiale da convalidare. Le informazioni seguenti riguardano proprio la convalida di un file ePub in locale.

Come si utilizza EpubCheck.

Il tool funziona su qualsiasi sistema operativo che monti Java 1.5 o superiore. Si lancia da linea di comando e può essere utilizzato in due modalità: standard o avanzata.

Modalità ‘standard’ (da usare per la verifica del file .epub già creato)

java -jar epubcheck.jar file.epub

banalizzando la stringa può essere letta così: chiediamo a Java di lanciare il tool epubcheck.jar incaricato di verificare il file.epub

il nome del tool e quello del file devono essere espressi in modo corretto e completo di percorso

Modalità ‘avanzata’ (da usare per la verifica del singoli file interni o sulla cartella completa, ma non ancora compressa, del libro)

java -jar epubcheck.jar file -mode MODE -v VERSION

Stiamo come prima chiedendo a Java di lanciare il tool epubcheck.jar incaricato di verificare la validità, però questa volta la verifica avviene secondo modalità leggermente diverse e non sul file epub compresso. Vediamo nel dettaglio le specifiche:

– Il parametro MODE può assumere i seguenti valori:

• opf verifica il solo file opf specificato;
• nav per convalidare la sola navigabilità del documento (esclusivamente per la versione 3.0);
• mo per convalidare la sovrapposizione tra componenti meglio detto ‘media overlay’ (esclusivamente per la versione 3.0) Un esempio di media overlay è presente in questa pagina;
• xhtml per convalidare i soli file .xhtml;
• svg per convalidare le componenti di codice per le rappresentazioni vettoriali;
• exp per convalidare la cartella del libro non compressa.

Non mi soffermo sui primi 5 parametri (a mio parere poco utili perché danno solo indicazioni parziali e a volte contraddittorie), quello che invece è importante tenere presente è il sesto.

Permette di compiere la verifica/convalida anche solo della cartella non compressa e, con l’aggiunta dell’opzione -save in caso di esito positivo, di generare il file epub convalidato.

In quest’ultimo caso la sintassi corretta è la seguente:

java -jar epubcheck.jar dir -mode exp -save

dove dir è il nome (completo di path) della cartella che contiene gli elementi del libro

– Il parametro VERSION può assumere esclusivamente i valori 2.0 e 3.0

– L’utilizzo del parametro -help (o abbreviato -h) visualizza il seguente breve messaggio di aiuto:

When running this tool, the first argument should be the name (with the path) of the file to check.
If checking a non-epub file, the epub version of the file must be specified using -v and the type of the file using -mode.
The default version is: 3.0.
Modes and versions supported:
-mode opf -v 2.0
-mode opf -v 3.0
-mode xhtml -v 2.0
-mode xhtml -v 3.0
-mode svg -v 2.0
-mode svg -v 3.0
-mode nav -v 3.0
-mode mo -v 3.0 // For Media Overlays validation
-mode exp // For expanded EPUB archives
This tool also accepts the following flags:
-save = saves the epub created from the expended epub
-? or -help = displays this help message

Se il nostro file non supera la convalida, il tool restituisce l’elenco degli errori riscontrati. È necessario intervenire sui singoli file operando le opportune correzioni e procedere con un nuovo tentativo di convalida, fino al successo definitivo.

Come già detto, viene segnalato anche dalla pagina ufficiale di info su ePUBCheck 3.0 che:

• qualsiasi verifica sui singoli file interni è necessariamente parziale perché vengono effettuati solo una parte dei test-check complessivi.
• quando si verifica un file completo (.epub) i parametri MODE e VERSION sono ignorati

Consiglio di mantenere l’attenzione sulle pagine ufficiali di aggiornamento e sviluppo:

• Version history e release attuale disponibile al download;
• Forum ufficiale;
• Segnalazione di problemi o richieste/suggerimenti di nuove funzioni.

Buon (e valido  🙂 ) lavoro.