ePUB: scrivere codice ‘in bella’ è solo una questione di forma?

Modelli di calligrafia – Carola Bruno – Padova – Gennaio 2012

Nessuna regola scritta vincola chi scrive il codice di un eBooks a farlo in bella forma e ordinando i file secondo chissà quale ordinamento gerarchico. Però aiuta.

Sollecitato a scrivere qualcosa su questo tema, e spinto ulteriormente dopo aver notato come sempre più spesso alcune regole fondamentali di ordine e pulizia vengono disattese anche negli eBook di blasonati editori 😦  scrivo due righe sull’argomento.

Non dico nulla di nuovo o di particolare e i più ‘addentro’ possono tranquillamente leggere altro.

Come sappiamo un ePub non è altro che un guscio compresso che contiene tre componenti fondamentali:
– il file mime-type
– la cartella META-INF
– la cartella OEBPS.

Mentre le prime due fungono sostanzialmente da ‘marcatori’ (il primo per dire all’hardware ‘io sono un ePub’ e il secondo per fare sapere dove poterne trovare le varie parti), la cartella OEBPS di fatto contiene il libro vero e proprio (capitoli, contributi, apparati, stili, scripts …).
Più un libro è articolato e complesso, e più aumenta il numero di file in gioco. Va da se che alcune regole di ordine, gerarchia e pulizia aiutano la programmazione e gli eventuali successivi interventi di modifica.

Il file più importante di un eBook dal punto di vista strutturale è il file content.opf.

Contiene innanzitutto i metadata che riguardano il libro, espressi secondo le specifiche dettate da DCMI ( Dublin Core Metadata Iniziative )

ma è sulla parte che segue che voglio concentrare l’attenzione: l’elemento <manifest>

Il suo scopo è quello di elencare e descrivere tutti i file che concorrono alla pubblicazione.
La sintassi esprime ogni elemento mediante tre ‘indicatori’:

• un id che ‘denomina’ in modo univoco l’elemento in questione;
• l’indirizzamento href che ne ‘esprime’ la posizione all’interno del file epub;
• la componente media-type che ne ‘caratterizza’ la funzionalità.

Quest’ultima componente si esprime seconde le specifiche dettate da IANA (Internet Assigned Numbers Authority) nella sezione MIME (Multipurpose Internet Mail Extensions)

Banalizzando e giusto per fare un esempio, faccio la parafrasi di una espressione tipo reperibile all’interno di un file content:

<item id=”img_001_01″ href=”immagini/riomaggiore.jpg” media-type=”image/jpeg” />

In un libro ci sono moltissime di queste espressioni e mi è capitato spesso di prendere in mano content.opf creati senza nessun criterio; un guazzabuglio di definizioni ed elementi senza alcun ordine. E di impazzire per metterci le mani.
E gli stessi file (se un programmatore è disordinato nel content,opf probabilmente lo è anche nel creare la gerarchia dei file) liberi e mescolati tra di loro all’interno della cartella OEPBS.

Meglio un buon ordine che aiuta la stesura e soprattutto le fasi di revisione: ogni file di una certa tipologia va posto in una cartella assieme agli altri file suoi omologhi, e le relative ‘chiamate’ nel file content raggruppate in modo analogo.
La simbologia <!– xxxxx –> esprime un commento di programmazione all’interno del codice e può essere usata per marcare le varie parti:

<!– immagini –>
<item id=”img_001_01″ href=”immagini/riomaggiore.jpg” media-type=”image/jpeg” />
<item id=”img_002_01″ href=”immagini/manarola.jpg” media-type=”image/jpeg” />
<item id=”img_003_01″ href=”immagini/corniglia.jpg” media-type=”image/jpeg” />
<item id=”img_004_01″ href=”immagini/vernazza.jpg” media-type=”image/jpeg” />
<item id=”img_005_01″ href=”immagini/monterosso.jpg” media-type=”image/jpeg” />
<item id=”img_006_01″ href=”immagini/cinqueterre.png” media-type=”image/png” />

<!– audio –>
<item id=”snd_001″ href=”audio/mareggiata.m4a” media-type=”audio/mpeg” />
<item id=”snd_002″ href=”audio/risacca.m4a” media-type=”audio/mpeg” />

<!– css –>
<item id=”css_base” href=”css/base.css” media-type=”text/css” />
<item id=”css_riom” href=”css/riomaggiore.css” media-type=”text/css” />
<item id=”css_mana” href=”css/manarola.css” media-type=”text/css” />
<item id=”css_corn” href=”css/corniglia.css” media-type=”text/css” />
<item id=”css_vern” href=”css/vernazza.css” media-type=”text/css” />
<item id=”css_mont” href=”css/monterosso.css” media-type=”text/css” />

Secondo le espressioni appena viste, a livello gerarchico esisteranno:

una cartella immagini contenente 5 jpeg e un png:
riomaggiore.jpg
manarola.jpg
corniglia.jpg
vernazza.jpg
monterosso.jpg
cinqueterre.png

una cartella audio contenente due basi sonore:
mareggiata.m4a
risacca.m4a

e una cartella css contenente i fogli stile:
base.css
riomaggiore.css
manarola.css
corniglia.css
vernazza.css
monterosso.css

È importante che anche l’attribuzione degli id segua una certa logica. Nell’esempio appena visto ho utilizzato un criterio di progressione:
riomaggiore.jpg è l’immagine 1 del capitolo 1 e ho scelto di indicarla con id 001_01, mentre manarola.jpg, immagine 2 del capitolo 1, sarà indicata con id 002_01.
Inutile sottolineare che gli ‘zero’ all’interno del nome, consentono ordinamenti più precisi: sia dei file nelle gerarchie sia dei nomi all’interno del file content.

Gli utenti che generano ePub da Indesign, conoscono sicuramente il problema della denominazione dei links immagine. Nomi variegati e variopinti che possono andare bene in un impaginato per stampa, tanto ci pensa Indesign a tenerli fortemente ‘al guinzaglio’ ma non aiutano la successiva revisione del codice nel passaggio ad ePUB.

In questo caso ci vengono in aiuto due scripts. Il primo di Marijan Tompa in arte Tomaxxi. Permette di rinominare tutti i contributi immagine a nostro piacimento. La ri-denominazione avviene link per link uno alla volta. Attenzione che i file vengono rinominati definitivamente, quindi nel caso di future eventuali integrazioni da parte di chi aveva fornito i documenti i nomi non saranno più uguali. Meglio lavorare su una copia. Questo il link al sito di Tomaxxi (consiglio una visita approfondita perché è una miniera per chi usa Indesign) e questo il link diretto per il download dello script

Il secondo è quello che preferisco perché rigenera i nomi in batch. Si tratta di uno script di Kasyan Servetsky (altro sito da ispezionare con cura perché ricchissimo di tools e scripts di cui non è possibile fare a meno). Ci chiede una ‘radice’ comune che applicherà a tutti i nomi aggiungendo poi una numerazione sequenziale legata al numero di pagina. Anche in questo caso l’operazione è ‘distruttiva’ quindi lavoriamo sempre su una copia, ma lo script ci restituisce anche un utile report con indicate tutte le sostituzioni effettuate, da conservare  se prevediamo future integrazioni dall’esterno. Questo il link diretto allo script

Tornando al tema principale chiudo citando un aspetto molto importante: l’accortezza nell’utilizzo dei caratteri nel nome dei file. Il matching tra nome dichiarato nel file content e il nome effettivo del file deve essere perfetto. Meglio abituarsi ad utilizzare esclusivamente caratteri minuscoli, evitando spazi e caratteri speciali ad esclusione dell’underscore  ‘ _ ‘ che è sicuro e affidabile per qualsiasi codifica. Cerchiamo di generare nomi  brevi (nei limiti del possibile) e che siano possibilmente esplicativi dell’immagine o meglio ancora, come visto prima, del suo posizionamento all’interno del file ePub.

E tu? Utilizzi strumenti che possono aiutare la stesura o il controllo in fase di scrittura? Hai altre accortezze da suggerire?