Quello che segue è un guest-post di Alberto Pettarin. Una interessante lezione su FlightCrew strumento poco noto ma, come vedremo, fondamentale per una convalida efficace di ePUB.
Innanzitutto ringrazio JeanPaul per l’invito a scrivere questo articolo su
FlightCrew, un validatore di EPUB complementare al piu’ noto EpubCheck.
Introduzione a FlightCrew
FlightCrew (FC) e’ un programma open-source gratuito per la validazione
di file EPUB secondo lo standard 2.0.1.
Il primo rilascio ufficiale di FC si deve Strahinja Markovic (ottobre 2010),
l’autore del noto editor di EPUB Sigil.
Attualmente FC e’ manutenuto da John Schember,
che ha sostituito Strahinja anche nello sviluppo di Sigil.
Il codice e gli eseguibili sono rilasciati sotto licenza
GNU LGPL 3 e CC BY-SA 3.0.
L’idea alla base di FC e’ fornire uno strumento piu’ efficiente e
piu’ efficace del validatore messo a disposizione
da IDPF, EpubCheck (EC).
Nello specifico, FC vuole effettuare un’analisi piu’ approfondita di EC
per quanto riguarda la raggiungibilita’ delle risorse e la loro osservanza
dello standard EPUB e, a cascata, di tutti gli altri standard coinvolti:
XHTML, CSS, NCX, OPF, eccetera.
Nonostante FC effettui controlli piu’ sofisticati di EC,
spesso risulta piu’ veloce perche’ e’ scritto in C++,
a differenza di EC che e’ scritto in Java.
FC e’ utilizzabile in tre modalita’: a linea di comando (CLI), tramite
un’interfaccia grafica (GUI) e all’interno di Sigil, di cui costituisce
il “motore” di validazione attivabile cliccando sull’icona
con la spunta verde (“Validate EPUB”).
Le prime due versioni sono scaricabili dalla pagina
Google Code del progetto,
mentre ovviamente Sigil e’ scaricabile da
questa pagina.
Nel resto dell’articolo descrivero’ l’utilizzo a linea di comando,
secondo me il piu’ efficiente per un uso (semi)professionale.
Rispetto a questa versione a linea di comando,
le versioni grafiche offrono in piu’ solo
il drag-and-drop del file da validare
dentro la finestra dell’applicazione (versione GUI)
e la possibilita’ di scorrere l’elenco dei warning e degli error
in una lista ordinata colorata (versioni GUI e Sigil).
Infine cerchero’ di mostrare le analogie e le differenze
tra FC e EC, su una serie di errori comunemente riscontrati negli EPUB.
Utilizzo da linea di comando
Una volta scaricata la versione CLI (command-line interface),
otteniamo un eseguibile che si chiama flightcrew-cli.
Al momento l’ultima release e’ la 0.7.2,
che usero’ per gli esempi di questo articolo.
Nota per gli utenti Linux:
io ho installato flightcrew in /opt/flightcrew, e
creato il seguente alias nel mio file .bashrc per comodita’:
alias flc='/opt/flightcrew/flightcrew-cli'
Nel seguito usero’ sempre flightcrew-cli per non confondere
gli utenti Windows/Mac, ma ovviamente flc e’ molto piu’ comodo…
Il funzionamento e’ molto semplice, non ci sono opzioni
da specificare come per EC:
$ flightcrew-cli book.epub
Se FC non trova problemi in book.epub, restituira’ il messaggio:
$ flightcrew-cli book.epub
No problems found.
e restituira’ al sistema operativo un return code 0,
caratteristica utile da conoscere se vogliamo creare degli script
per automatizzare il nostro un flusso di lavoro.
Se invece FC individua dei problemi, ne restituira’ l’elenco
e passera’ un return code 1 al sistema operativo.
Nella prossima sezione vedremo alcuni esempi comuni.
Generalmente viene anche restituito il file all’interno dell’EPUB
che ha generato l’errore e, se applicabile, la riga relativa.
Uno dei punti di forza di FC e’ proprio una reportistica degli errori
comprensibile, mentre EC (specie le prime versioni) spesso genera
dei messaggi d’errore di difficile comprensione.
Ma il vero punto di forza di FC e’ l’approfondita analisi
dei singoli file contenuti all’interno dell’EPUB e delle loro relazioni.
Il primo tipo di controlli, ad esempio, include una verifica
della conformita’ delle pagine allo standard W3C XHTML 1.1, del content file
a OPF, della TOC alla specifica NCX e via dicendo.
Ovviamente FC controlla anche che l’EPUB sia zippato correttamente,
che vi sia il mimetype file, e via dicendo:
in sintesi, che il file contenitore sia formalmente ben costruito.
Il secondo tipo di controlli, invece, comprende verifiche
che riguardano la “completezza logica” del file EPUB.
A questo gruppo appartengono il controllo che tutti gli elementi
dichiarati nella guide siano anche dichiarati nella spine,
che tutte le risorse presenti nel manifest siano effettivamente
inclusi nel file EPUB, cosi’ come controlla il viceversa,
cioe’ che tutti gli elementi presenti nel file EPUB siano effettivamente
referenziati da qualche pagina.
Un controllo importante effettuato da FC
e’ la verifica che non sia possibile arrivare ad un elemento
(ad esempio tramite la guide o un link interno)
senza che questo elemento sia elencato nella spine.
Ad onor del vero bisogna dire che FC non controlla alcuni elementi
che invece EC controlla, in particolare la raggiungibilita’
degli elementi di fallback (se presenti) e la sintassi delle risorse
in formato DTBook.
Io consiglio sempre di utilizzare entrambi i validatori!
Esempi d’errori e confronto tra FlightCrew e EpubCheck
Di seguito mostrero’ alcuni esempi di errori tipici trovati da FC,
spesso confrontandoli con quanto segnalato da EC (versione 3.0b5).
Utilizzero’ sempre lo stesso file EPUB (corretto) —
una versione “alleggerita” di
Come non detto,
in cui andro’ a inserire, per maggior chiarezza,
un singolo errore per volta.
EPUB zippato male
Un errore comune fra i neofiti consiste nel comprimere la cartella che contiene
le risorse tramite un programma come zip o WinZip,
che di default applica la compressione a tutti i files.
Ricordo che invece il file mimetype deve essere
aggiunto all’archivio ma non deve essere compresso.
FC ce lo ricorda in termini comprensibili:
$ flightcrew-cli zippatoMale.epub
zippatoMale.epub: error 502: Bytes 30-60 of your epub file are invalid. This means that one or more of the following rules are not satisfied:
1. There needs to be a "mimetype" file in the root folder.
2. Its content needs to be *exactly* the ASCII string "application/epub+zip".
3. It needs to be the first file in the epub zip archive.
4. It needs to be uncompressed.
zippatoMale.epub: error 501: The META-INF/container.xml file was not found.
EC invece restituisce questo messaggio criptico:
$ java -jar epubcheck3.jar zippatoMale.epub
Epubcheck Version 3.0b5
ERROR: zippatoMale.epub: Length of the first filename in archive must be 8, but was 12
ERROR: zippatoMale.epub: Required META-INF/container.xml resource is missing
Check finished with warnings or errors
Analogamente, se il file mimetype e’ errato,
perche’ ad esempio c’e’ un carattere di andata a capo di troppo,
avremo i seguenti errori:
$ flightcrew-cli mimetypeErrato.epub
mimetypeErrato.epub: error 502: Bytes 30-60 of your epub file are invalid. This means that one or more of the following rules are not satisfied:
1. There needs to be a "mimetype" file in the root folder.
2. Its content needs to be *exactly* the ASCII string "application/epub+zip".
3. It needs to be the first file in the epub zip archive.
4. It needs to be uncompressed.
$ java -jar epubcheck3.jar mimetypeErrato.epub
Epubcheck Version 3.0b5
Validating against EPUB version 2.0
ERROR: mimetypeErrato.epub/mimetype: Mimetype file should contain only the string “application/epub+zip”.
Check finished with warnings or errors
EPUB con metadati errati
Altro errore che puo’ capitare soprattutto agli inizi,
specialmente se non si utilizza un EPUB editor come Sigil,
consiste nello scrivere metadati non corretti.
Un esempio? La data deve essere nel formato
“YYYY” oppure “YYYY-MM” oppure “YYYY-MM-DD”.
Quindi “2012-6-3” non e’ un valore valido, infatti FC protesta:
$ flightcrew-cli dataNonValida.epub
dataNonValida.epub/OEBPS/content.opf(8): error 1110: The element's value is "2012-3-2", which is not a valid date format.
Purtroppo EC non rileva questo problema:
$ java -jar epubcheck3.jar dataNonValida.epub
Epubcheck Version 3.0b5
Validating against EPUB version 2.0
No errors or warnings detected.
D’accordo, e’ un errore che non dovrebbe causare gravi imbarazzi
ad un eReader, pero’ e’ bene essere a conoscenza di questo genere di situazioni,
specie perche’ molti addetti ai lavori considerano il responso di EC
(e non l’effettiva conformita’ alla specifica EPUB)
come unico parametro di qualita’ dei propri EPUB…
Pagina XHTML elencata nella spine ma non esistente
Dimenticare di copiare una pagina XHTML nella cartella di “assemblaggio”
e’ un errore che puo’ capitare frequentemente
se si lavora a piu’ mani sullo stesso eBook.
In questo caso, FC ci avvisa che effettivamente la pagina testo.xhtml
e’ elencata nel file OPF e nella TOC, ma non esiste nell’archivio:
$ flightcrew-cli paginaInesistente.epub
paginaInesistente.epub/OEBPS/content.opf(23): error 1115: The element's "href" attribute points to file "Text/testo.xhtml" which does not exist.
paginaInesistente.epub/OEBPS/toc.ncx(48): error 1300: This element's "src" attribute value is "Text/testo.xhtml", but that file does not exist.
Il messaggio di EC e’ simile, ma non ci fa presente che
la pagina e’ referenziata da OPF e TOC:
$ java -jar epubcheck3.jar paginaInesistente.epub
Epubcheck Version 3.0b5
Validating against EPUB version 2.0
ERROR: paginaInesistente.epub: OPS/XHTML file OEBPS/Text/testo.xhtml is missing
Check finished with warnings or errors
Pagina XHTML non valida
Cosa succede se commettiamo un errore nello scrivere una pagina XHTML,
ad esempio inseriamo un tag p all’interno di un tag h1?
Entrambi i validatori si comportano bene:
$ flightcrew-cli paginaNonValida.epub
paginaNonValida.epub/OEBPS/Text/testo.xhtml(11): error 301: element 'p' is not allowed for content model '(a | br | span | bdo | map | object | img | svg | tt | i | b | big | small | em | strong | dfn | code | q | samp | kbd | var | cite | abbr | acronym | sub | sup | input | select | textarea | label | button | ins | del | script)'
$ java -jar epubcheck3.jar paginaNonValida.epub
Epubcheck Version 3.0b5
Validating against EPUB version 2.0
ERROR: paginaNonValida.epub/OEBPS/Text/testo.xhtml(11,12): element “p” not allowed here; expected the element end-tag, text or element “a”, “abbr”, “acronym”, “applet”, “b”, “bdo”, “big”, “br”, “cite”, “code”, “del”, “dfn”, “em”, “i”, “iframe”, “img”, “ins”, “kbd”, “map”, “noscript”, “ns:svg”, “object”, “q”, “samp”, “script”, “small”, “span”, “strong”, “sub”, “sup”, “tt” or “var” (with xmlns:ns=”http://www.w3.org/2000/svg”)
Check finished with warnings or errors
Pagina presente nel manifest ma non nella spine
A mio avviso, EC ha una grossa limitazione:
non effettua alcun controllo di raggiungibilita’ degli elementi dell’EPUB.
Prendiamo il caso in cui una pagina e’ dichiarata nel manifest ma
non e’ inclusa nella spine.
Questo comporta la non visualizzazione della pagina nell’eBook finale!
Sfortunatamente EC non segnala questo genere di problemi:
$ java -jar epubcheck3.jar paginaNonReferenziata.epub
Epubcheck Version 3.0b5
Validating against EPUB version 2.0
No errors or warnings detected.
Viceversa, FC ci segnala il problema:
$ flightcrew-cli paginaNonReferenziata.epub
paginaNonReferenziata.epub/OEBPS/Text/spuria.xhtml: warning 2200: This resource is present in the OPF , but it's not reachable (it's unused).
Un test di velocita’
Infine, ho fatto un rapido test di velocita’,
sulla stessa macchina e sullo steso file EPUB senza errori:
$ time flightcrew-cli book.epub
No problems found.
real 0m2.050s
user 0m1.812s
sys 0m0.148s
$ time java -jar epubcheck2.jar book.epub
Epubcheck Version 1.2
No errors or warnings detected
real 0m5.150s
user 0m7.052s
sys 0m0.168s
$ time java -jar epubcheck3.jar book.epub
Epubcheck Version 3.0b5
Validating against EPUB version 2.0
No errors or warnings detected.
real 0m10.548s
user 0m14.981s
sys 0m0.476s
Altro rapido test, questa volta su un file con gravi errori:
$ time flightcrew-cli book2.epub 2> /dev/null
real 0m8.946s
user 0m8.085s
sys 0m0.560s
$ time java -jar epubcheck2.jar book2.epub 2> /dev/null
Epubcheck Version 1.2
real 0m9.173s
user 0m13.905s
sys 0m0.328s
$ time java -jar epubcheck3.jar book2.epub 2> /dev/null
Epubcheck Version 3.0b5
Validating against EPUB version 2.0
real 0m15.997s
user 0m22.913s
sys 0m0.528s
Come si vede, FC e’ generalmente piu’ veloce di EC:
cio’ e’ vero per la quasi totalita’ dei file EPUB
che mi e’ capitato di controllare.
Viceversa, quando l’EPUB contiene migliaia di pagine
con decine di migliaia di link interni da controllare,
l’analisi piu’ raffinata di FC comporta
un tempo di esecuzione piu’ lungo.
Conclusioni
Concludo questo articolo con due note metodologiche.
Primo, i validatori sono strumenti comodi
per controllare (ancora in fase di lavorazione al PC)
che i propri eBook siano conformi allo standard EPUB,
ma non sostituiscono un test sugli eReader fisici.
Essi sono come i correttori ortografici dei word processors:
sono capaci di trovare gli errori grammaticali in un testo,
ma non garantiscono che esso sia anche “tipograficamente” gradevole
(ne’ che sia semanticamente coerente, ma questa e’ un’altra storia…)!
Inoltre, proprio come i correttori ortografici,
spesso possono non evidenziare tutte le difformita’
rispetto alla specifica di riferimento,
perche’ (a) spesso ne controllano solo un sottoinsieme di criticita’ comuni,
e (b) possono essere affetti da bug essi stessi.
Quindi invito tutti rimanere vigili e non accettare pedissequamente
il responso dei validatori, positivo o negativo che sia,
ma usarlo come uno (tra molti) elementi nel valutare
la qualita’ del proprio eBook.
Secondo, il mio consiglio e’ di utilizzare sempre entrambi
i validatori, non FC in sostituzione di EC o viceversa.
Infatti bisogna ricordare che un validatore produce sempre e solo
veri positivi: dato che EC e FC controllando due sottoinsiemi diversi
della specifica EPUB, usarli entrambi
non puo’ mai essere meno utile che usarne uno solo!
E ora, al lavoro!
Tutti — Autori, Editori, Lettori —
abbiamo voglia di buoni eBook, di eBook di qualita’!
Risorse
1. http://code.google.com/p/flightcrew/
2. http://code.google.com/p/sigil/
3. http://code.google.com/p/epubcheck/
4. http://sigildev.blogspot.it/2010/10/introducing-flightcrew-epub-validator.html
5. http://idpf.org/epub/201
6. http://ebci.it/
Autore
Alberto Pettarin vive a Padova, dove ha recentemente
conseguito il Dottorato di Ricerca in Ingegneria dell’Informazione
e dove sta per concludere un progetto di ricerca post-doc.
Da sempre appassionato di tipografia digitale
(e, quindi, da sempre sfruttato dai suoi colleghi allergici a LaTeX),
da qualche anno si occupa di editoria digitale e di eBook in particolare.
E’ uno dei soci fondatori-coordinatori dell’eBook Club Italia,
per il quale scrive recensioni tecniche di eBook pubblicati in Italia.
Nel suo (pressoche’ inesistente) tempo libero legge,
pedala o gioca a tennis, cucina, guarda i TED Talks
e scrive free software,
quasi sempre con la scusa di fare un favore all’umanita’
(in realta’ gli piace un sacco programmare).
Puo’ essere raggiunto via email (pettarin AT gmail DOT com)
oppure tramite il suo
profilo Linkedin.
Generalmente non parla di se’ in terza persona.