Sigil, gli errori più frequenti in un EPUB

Come abbiamo visto in più occasioni, Sigil presenta al suo interno un test di convalida per EPUB, il FlightCrew. Questo test è complementare (e non alternativo) al test di convalida ufficiale, lo EpubCheck, e proprio la volta scorsa abbiamo visto come e quando utilizzarli, in modo da ottenere da entrambi il miglior risultato: FlightCrew in fase di lavorazione, EpubCheck al termine dei lavori, appena prima di cominciare a distribuire il nostro e-book.

FlightCrew, tra le altre cose, nasce col proposito di correggere ciò che i suoi autori consideravano (e considerano tuttora) un difetto di EpubCheck, ossia la scarsa comprensibilità, agli occhi di un non iniziato, degli errori segnalati da EpubCheck. Il che, oggettivamente, è vero: EpubCheck utilizza spesso una terminologia che è solo leggermente più chiara rispetto a quella della Microsoft, quando si tratta di segnalare un errore. Inoltre, tende a farlo con un lessico e una sintassi ridotti all'osso  non molto lontani da “io Tarzan, tu Jane”. L’errore si capisce, se si ha esperienza nel settore, ma per chi si avventura per la prima volta nel magico mondo degli EPUB la comprensione può non essere così immediata.

FlightCrew propone dunque una forma più chiara e colloquiale nella segnalazione di errori, almeno per quanto sia possibile farlo; diviene così più semplice capire il messaggio di errore, ma ciò non significa automaticamente che si riuscirà anche a capire quale sia l’errore, dove sia e come poterlo correggerlo, soprattutto se la nostra conoscenza dell’inglese e della struttura interna di un EPUB è approssimativa (o assente). Vediamo dunque una breve lista degli errori più comuni, che ci saranno segnalati dal test di convalida FlightCrew all'interno di Sigil. Assieme all'errore, troverete anche due parole su come correggerlo.

Premessa generale, la forma in cui ci sono presentati gli errori da Sigil.  Ogni errore ci apparirà nella finestra “Risultati della validazione” con una struttura tripartita, cioè divisa in tre riquadri.

1. File contiene il nome del file in cui l’errore è stato trovato.
2. Riga contiene il numero della riga in cui l’errore è stato trovato, all'interno del file segnalato prima. Il numero corrisponde a quello che ci appare utilizzando la visuale “codice”, nel riquadro centrale di Sigil; in questa visuale, ogni riga di codice sarà numerata.
3. Messaggio, infine, è una descrizione dell’errore, espressa in termini abbastanza comprensibili.

Detto questo, passiamo ai messaggi di errore più comuni.

This resource is present in the OPF <manifest>, but it's not reachable (it's unused).

Errore estremamente comune, in fase di lavorazione. Significa che il nostro EPUB contiene un file che noi non abbiamo usato, per esempio una immagine che all'inizio avevamo inserito in una pagina, ma poi abbiamo deciso di togliere: se abbiamo solo cancellato il riferimento all'interno della pagina, ma non abbiamo cancellato l’immagine dalla cartella “Images”, Sigil ci segnalerà che quel file non è usato nel nostro documento. In questi casi, possiamo cancellare il file non utilizzato, se davvero non ci serve, oppure dovremo provvedere a inserire da qualche parte nel nostro e-book un riferimento a esso, se intendiamo conservarlo.

This resource is reachable but not present in the OPF <manifest>. "Reachable" means that a reference of some kind that points to this resource exists in the epub.

È il gemello dell’errore precedente e si riferisce al problema opposto: nel nostro e-book è presente il riferimento a un qualche file, che però non esiste. Probabilmente, in questo caso, abbiamo cancellato il file, ma ci siamo dimenticati di cancellare anche i riferimenti a quel file, all'interno di una qualche pagina del nostro EPUB. Si può correggere reinserendo il file latitante, oppure cancellando anche il riferimento a quel file.

ID value 'heading_id_17' is not unique.

Il termine colorato in rosso cambierà a seconda dei casi. L’errore commesso stavolta è l’utilizzo di uno stesso nome, per due o più ID. Lo ID è una specie di targa, che possiamo applicare a un tag, per poterci poi riferire a esso in modo più semplice e diretto in un altro punto del codice; come ogni targa, è necessario che lo ID sia unico. Se assegniamo a due elementi una stessa targa, abbiamo un errore. In questo caso, basterà assegnare uno ID diverso a ogni elemento.

The "profile" attribute is not an allowed attribute of the <package> element.

Anche in questo caso, i nomi colorati in rosso saranno diversi a seconda dei casi. Questa classe di errori ci appare quando abbiamo assegnato a un particolare elemento (il secondo termine in rosso) un attributo (il primo termine in rosso) che non era permesso utilizzare in quel particolare punto. Molti tag possono infatti essere modificati, assegnando loro uno o più attributi, ma non tutti questi attributi sono accettati in uno EPUB: il colore, ad esempio, è bene attribuirlo usando il foglio di stile CSS, invece di appiccicarlo come elemento di un tag. In questo caso, dovremo eliminare l’attributo “illegale”.

attribute 'size' is not declared for element 'font'.

Errore gemello del precedente, i termini colorati in rosso sono quelli che possono cambiare a seconda dei casi. Stavolta abbiamo dimenticato di specificare un attributo (il primo termine in rosso) per un particolare elemento (il secondo termine in rosso), che richiedeva invece una precisazione sul modo in cui utilizzarlo. Per correggere, dovremo aggiungere l’attributo richiesto.

The <language> element is missing.

Come al solito il termine in rosso può cambiare a seconda dei casi. Stavolta l’errore si trova nel file content.opf e si riferisce a un metadato che avremo dovuto inserire, ma non abbiamo inserito: per esempio la lingua in cui è scritto il nostro EPUB (italiano, inglese, eccetera), oppure il titolo del nostro e-book, l’autore, eccetera. Possiamo correggerlo con l’editor dei metadati, aggiungendo gli attributi richiesti.

The <item> element's "media-type" attribute has value "font/truetype", but the file's media type is "application/x-font-ttf".

Questo  non è strettamente un errore, ma una richiesta di stile, o una proposta che non potrete rifiutare, per quanto riguarda il tipo di font che avete utilizzato. In materia di font, al momento non esiste uno standard ufficiale, per gli EPUB, ma di fatto il formato “application/x-font-ttf” agisce come se fosse uno standard; se e quando avremo una standardizzazione di questo elemento, è dunque altamente probabile che sarà scelto questo, dato che in ambito industriale ne fa già le veci. Di conseguenza, Sigil e FlightCrew vi invitano fin da adesso ad adattarvi al sistema.

element 'svg' is not allowed for content model.

A seguire, ci sarà poi una lista di tag abbastanza lunga, che ho tagliato per ragioni di spazio. In questo caso, avete inserito nel vostro EPUB un elemento SVG, che di solito consiste in una immagine vettoriale: una immagine, cioè, che si può allargare o restringere per adattarsi alla dimensione dello schermo, in teoria senza perdita di qualità. Ottima scelta per un e-book, soprattutto nel caso di un fumetto, ma con un problema: non potete utilizzare un elemento <svg> direttamente all'interno del tag <body> di un documento. O meglio, potete, ma vi sarà segnalato come errore, perché non è ammesso in questa posizione. Per risolvere, basterà racchiudere il tag <svg> in un altro elemento, come ad esempio <div>: in questo modo non sarà più attaccato direttamente a <body>, ma sarà diventato un discendente di <div>, e n questa forma non vi darà più problemi.