Ecrire ses epubs  Introduction

Introduction

Pourquoi

Au moins pour deux raisons:

1. Voici quelques mois, j'ai développé une petite application appelée "Lecture audio". Son principe: afficher un contenu (page de livre) et restituer la narration associée. En cliquant sur des sections du texte, cela repositionnait la lecture audio. On peut aussi identifier le texte en cours de lecture. J'ai passé beaucoup de temps à développer cette application. Le résultat est satisfaisant et réponds bien à mon besoin de l'époque.
Par la suite, j'ai découvert que cette fonction, que j'avais imaginée et mise en application, existait déjà dans les epub v3.0. J'avais donc réinventé la roue. C'est la raison pour laquelle je me suis intéressé à la spécification des epub v3.0, bien que très jeune et encore peu supportée.

2. J'ai longtemps recherché une méthode simple pour écrire des epubs pour mes liseuses (dans mon mobile et une liseuse kobo WiFi, une version non tactile, qui n'est pas un Fnac book). D'Adobe InDesign (à partir de CS4), aux générateurs online en passant par Open-Office, les moyens ne manquent pas, il y en a pour tous les gouts, tous les prix.

Détaillons un peu les différentes solutions existantes (cette liste non exhaustive) :

Application Niveau de l'utilisateur Simplicité d'utilisation Maitrise du contenu Cout
Adobe InDesign professionnel de l'édition C'est certainement très simple à utiliser lorsque l'on sait quoi faire, mais ce n'est pas un logiciel "intuitif". Une très bonne gestion du contenu et de la mise en forme, mais au prix d'efforts assez conséquents pour les néofites. La génération d'un epub v3.0 n'est possible qu'à partir du CS6. Plus de 1000€
Libre Office - Write + write2epub Une connaissance du traitement de texte Plus intuitif qu'InDesign, mais nécessite la compréhension des styles pour obtenir un résultat correct. Médiocre: Comme Word, un document bien construit est facile à modifier. Encore faut-il qu'il soit bien construit. La génération d'un epub v3.0 n'est pas prise en charge actuellement. Gratuit
Sigil Une bonne sensibilité informatique Assez intuitif, nécessite la compréhension du HTML et du CSS Plutôt bonne, même si la structure du package n'est pas modifiable de prime abord. Sigil ne permet pas de créer des epubs v3.0 actuellement (version 0.5.3). Gratuit
Générateurs on-line Débutant Nécessite d'être toujours connecté, pas toujours simple à mettre en page Peu de maitrise du contenu, ce que vous écrivez est stocké en ligne, on ne sait trop où, on ne sait trop comment. Ces générateurs ne permettent pas de générer des epub v3.0 . quelques euros la publication

Ce petit descriptif nous montre qu'il n'existe pas de solution "abordable" permettant de générer des epub v3.0
Pour ma part, je préfère utiliser un éditeur de texte évolué et bien comprendre les mécanismes, afin de mieux utiliser des outils tels que Sigil.

Contenu d'un epub

Qu'est-ce qu'un epub? Un epub est un fichier compressé par une méthode zip. L'extension du fichier est remplacée par ".epub".

Le contenu du zip s'articule autour d'un "dossier de référence" qui contient:

Il serait simple de mettre quelques fichiers ensemble dans un fichier zip, et de le lire directement sur une liseuse. Malheureusement, ce n'est pas possible. En effet, il existe des règles pour ajouter des informations et fichiers. Ces règles sont regroupées dans une spécification qui peut être obtenue à cette adresse: http://www.idpf.org.


Dans cet ouvrage, je vais essayer de vous expliquer :

Les techniques et connaissances nécessaires à la bonne compréhension de cet ouvrage

  1. Une connaissance du HTML5 et de CSS.
  2. La compréhension de la structure des fichiers XML.
  3. De la rigueur dans la rédaction, du bon sens et l'envie d'apprendre.

Simple en apparence, non? Les apparences sont souvent trompeuses, et nous verrons que la génération d'epubs peut se révéler subtile.

Si vous estimez, comme moi, que vous n'avez pas le niveau dans ces domaines, n'hésitez pas à lire l'ouvrage et à vous référer aux cours qui m'ont permis d'écrire cet ouvrage.

Glossaire

Dans la suite de cet ouvrage, j'essayerai de n'utiliser que les termes suivants:

Points importants et invariables

Les fichiers du package sont codés en UTF-8, pas en ANSI.

La casse des lettres est importante. "Toto.png" n'est pas "Toto.PNG", ni "toto.png".

Les balises XML sont toujours écrites en minuscule.

Les fichiers contenus dans un package sont presque tous composés de balises. Ces balises sont imbriquées les unes dans les autres, mais ne peuvent en aucun cas se chevaucher :
<balise1><balise2></balise1></balise2> : valide!
<balise1><balise2></balise2></balise1> : invalide!!

Il faut absolument que les documents soient well-formed pour pouvoir être intégrés dans un epub.

 Table des matières

Table des matières

  1. Introduction
  2. Chapitre 1 - Configurer un environnement de travail
  3. Chapitre 2 - Les fichiers de configuration
  4. Chapitre 3 - Le document de contenu
  5. Chapitre 4 - Le contenu en HTML5
  6. Chapitre 5 - Mise en forme avec CSS
  7. Chapitre 6 - Générer l'epub
  8. Chapitre 7 - Table des matières
    1. Un premier essai tout simple
    2. Contourner l'obstacle...
    3. Aller plus loin
      1. Développer la table des matières
      2. Les sous-tables
      3. Créer des renvois en cours de page
  9. Chapitre 8 - La couverture
  10. Chapitre 9 - Notes de référence
  11. Chapitre 10 - Aller plus loin
  12. Annexe I - ePubTools
  13. Annexe II - Résoudre les erreurs
 Test ePUB 3.0

Configurer un environnement

Pourquoi

Vaste question, mais au moins pour répondre aux questions suivantes:

Beaucoup de questions, et pour y répondre, des solutions simples.

Comment visualiser nos epub

Il existe des liseuses installables facilement. Citons quelques solutions:

Application Intérêt Limitations
FB Reader Disponible sur toutes plateformes, très pratique d'utilisation. On peut re-générer un epub, ouvrir FBreader, le contenu s'est mis à jour! Ne supporte pas intégralement les epub v3.0.
Adobe Digital Éditions Disponible sur la plupart des plateformes PC et Mac. Assez pratique d'utilisation, le rendu est très agréable. Ne supporte pas intégralement les epub v3.0.
Azardi Disponible sous Windows, MacOS et aussi online. Supporte intégralement les epub v3.0. Difficile à télécharger. Ne charge pas les epubs, même Well-formed...
Les plug-ins navigateurs Disponible sous toutes plateformes. Affichage souvent dégradé, lent, nécessite d'être connecté, ne supporte pas intégralement les epub v3.0.

Pour une compatibilité maximale, j'utilise Adobe Digital Éditions. Pour un rendu conforme à la version 3.0 de la spécification, on m'avait conseillé d'utiliser Azardi, sans succès! Ce logiciel refuse d'ouvrir un quelconque epub v3.0 généré par mes soins!

Création du fichier epub

Manuellement, lorsque l'on a un dossier contenant un package, il faut:

Je me suis développé une petite application qui me permet de faire ces étapes automatiquement et de m'aider pour certaines tâches fastidieuses. Il suffit de déplacer le répertoire dans la fenêtre de l'application.

Cette application se trouve à cette adresse: ePubTools. N'hésitez pas à vous référer à l'annexe 1.

Contrôle des fichiers epub

Comme évoqué dans l'introduction, les epubs sont sensibles à la casse, et comme nous le verrons un peu plus loin, à la syntaxe des balises XML et HTML. Il existe un outil de vérification des epubs: epub Check. Cette application, développée en java, permet de s'assurer qu'un epub est conforme à la spécification.

Attention, ce n'est pas parce qu'un epub est conforme à la spécification epub qu'il peut s'afficher parfaitement sur une liseuse.

Comment éditer nos fichiers

Techniquement, le bloc note (Notepad) est suffisant. Cependant, pour être plus performant, je recommande Notepad++ qui est vraiment beaucoup plus pratique... Et permets de compléter certaines syntaxes automatiquement.

Ergonomie

Pour me simplifier la vie (eh oui, encore une fois!), je vais créer des raccourcis vers fbreader, ePub_Creator et Notepad++ dans le répertoire contenant mon répertoire de base. Cela me permettra, une fois FBreader fermé, de regénérer l'ePub, et de le tester directement!

Photo de mon interface  Fichiers de configuration

Les fichiers de configuration du package

mimetype

Ce fichier très simple est placé dans le dossier de base.

Il ne contient qu'une seule ligne:
application/epub+zip

Ce fichier est destiné aux liseuses, pour s'assurer qu'elles lisent bien un fichier epub. Il ne faut pas le modifier...

META-INF

Ce dossier contient les fichiers de configuration du package. Il peut contenir plusieurs fichiers.

container.xml

Ce fichier est obligatoire! Il sert à retrouver le contenu du package.

Exemple:

<?xml version='1.0' encoding='utf-8'?>
<container xmlns="urn:oasis:names:tc:opendocument:xmlns:container" version="1.0">
   <rootfiles>
      <rootfile media-type="application/oebps-package+xml" full-path="content/content.opf"/>
   </rootfiles>
</container>
		

Ce fichier est bien un fichier XML. Il garde une structure de balise habituelle.

La balise rootfile contient une propriété "full-path". Cette propriété donne l'emplacement de l'index du contenu (le fichier .opf). Ce path est donné, relativement au dossier de base.

encryption.xml

Ce fichier est facultatif, il sert à encrypter le package.

Plus d'informations: Spec originale

manifest.xml

Ce fichier est facultatif, je ne connais pas son utilité.

Plus d'informations: Spec originale

metadata.xml

Ce fichier est facultatif, je ne connais pas son utilité.

Plus d'informations: Spec originale

rights.xml

Ce fichier est facultatif, il sert à définir des DRM.

Plus d'informations: Spec originale

signatures.xml

Ce fichier est facultatif, il sert à signer le package.

Plus d'informations: Spec originale

Content

Ce dossier contient les fichiers de contenu du package.

Le contenu de ce dossier n'est pas obligatoirement plat: on peut tout à fait garder une arborescence bien organisée.

Ce dossier doit contenir obligatoirement certains fichiers:

content.opf

Ce fichier est obligatoire! Il sert à comprendre le contenu du package, et à indiquer à la liseuse les fichiers à charger.

Ce fichier fait l'objet du chapitre suivant.

"contenu.html"

Le contenu décrypté par la liseuse est du code HTML, un peu comme une page internet. Il est nécessaire d'avoir au moins un fichier HTML à lire. Ce fichier doit d'ailleurs disposer au moins d'un titre!

La spécification recommande de coder les fichiers de contenu en HTML5. Facile à dire, mais la spécification du HTML5 n'est pas encore terminée... Si vous êtes comme moi, vous coderez certainement comme vous le pourrez...

Le codage des pages de contenu fera l'objet d'un chapitre spécifique.

 Content Document

Le fichier Content Document

Ce fichier est primordial dans le package! Sans lui, même si des centaines de milliers de mots sont contenus dans le package, rien ne s'affichera dans une liseuse.

Prenons par exemple le contenu de ce fichier (chez moi, "content.opf") au moment de l'écriture de ces lignes:

<?xml version='1.0' encoding='UTF-8'?>
<opt:package xmlns:opf="http://www.idpf.org/2007/opf" 
   version="3.0"
   unique-identifier="test2">
   <opt:metadata xmlns:dc="http://purl.org/dc/elements/1.1/" >
      <dc:title>test epub v3.0</dc:title>
      <dc:identifier id="test2">urn:uuid:12345678-1234-1234-1234-123456789012</dc:identifier>
      <dc:language>fr</dc:language>
   </opt:metadata>
   <opt:manifest>
      <opt:item properties="nav" id="intro" href="intro.html" media-type="application/xhtml+xml" />
      <opt:item id="Ch1" href="chap1-Config.html" media-type="application/xhtml+xml" />
      <opt:item id="Ch2" href="chap2-Fichiers-Config.html" media-type="application/xhtml+xml" />
      <opt:item id="Ch3" href="chap3-content_document.html" media-type="application/xhtml+xml" />
   </opt:manifest>
   <opt:spine>
      <opt:itemref idref="intro" />
      <opt:itemref idref="Ch1" />
      <opt:itemref idref="Ch2" />
      <opt:itemref idref="Ch3" />
   </opt:spine>
</opt:package>
		

Une bonne surprise, il s'agit d'un document XML. A ce titre, il s'articule donc autour de balises. Certaines de ces balises sont obligatoires, et certaines sont facultatives. Contrairement à beaucoup de fichiers XML, l'ordre des balises a une importance!

La première balise du document : <opt:package> présente une propriété "xmlns" (XML namespace) qui définie pour l'ensemble du document un préfixe: "opf". On retrouvera ce suffixe tout au long des balises de ce document.

La balise <opt:package>

Cette balise est la balise root du document. C'est donc la première balise du document, après la déclaration XML. Toutes les balises sont censées être incluses dans cette balise package.

Cette balise contient des propriétés obligatoires, et d'autres facultatives.

xmlns: espace de nom

Cette déclaration est obligatoire. Le préfixe n'est pas obligatoire, mais simplifie la lecture du document: xmlns:opf="http://www.idpf.org/2007/opf"

version

La déclaration de cette propriété est obligatoire. Cette propriété est d'ailleurs non modifiable pour la version 3.0 des fichiers epub. Cet ouvrage est écrit pour la version 3.0 de la spécification. La déclaration de la propriété version="3.0" est donc obligatoire.

unique-identifier

La déclaration de cette propriété est obligatoire. Cette propriété permet d'identifier l'ouvrage.

La spécification est assez large: il faut que cet identifiant unique fasse au moins un caractère.

prefix, xml:lang, dir, id

La déclaration de ces propriétés est facultative.

Seule la propriété xml:lang me semble importante. On la déclare donc: xml:lang="fr" (fr pour français).


La balise <opt:metadata>

Cette balise est obligatoire. Elle est obligatoirement la première balise enfant de <opt:package>.

Cette balise n'a aucune propriété obligatoire, mais tout comme la balise <opt:package>, elle doit présenter des balises enfants obligatoires et facultatives, sans ordre pré-établi.

La spécification présente dans ses exemples une propriété que je vais reproduire malgré tout: xmlns:dc="http://purl.org/dc/elements/1.1/" .

La balise <dc:identifier>

Cette balise est obligatoire. Elle présente la propriété "id" correspondante (ou plutôt complétant) la propriété unique-identifier de la balise <opt:package>.

Il est conseillé de remplir cette balise avec un uid. L'utilitaire que je propose vous fournit un générateur d'uid. Il suffit ensuite de compléter la balise:
<dc:identifier id="test2">urn:uuid:12345678-1234-1234-1234-123456789012</dc:identifier>

La spécification n'impose pas l'utilisation d'uuid, et il est même possible d'utiliser un seul caractère comme identifiant...

Une fonctionnalité intéressante est l'ajout d'une balise <meta property="dcterms:modified"> qui va permettre d'ajouter la date de la version et donc de faire plusieurs éditions, tout en gardant le même uid. Le format de la date est obligatoirement: aaaa-mm-jjThh:mm:sZ

Une bonne pratique consiste donc à utiliser ce jeu de balises:

<dc:identifier id="test2">urn:uuid:12345678-1234-1234-1234-123456789012</dc:identifier>
<meta property="dcterms:modified">2012-10-10T12:00:00Z</meta>
		

l'uid résultant sera: urn:uuid:12345678-1234-1234-1234-123456789012@2012-10-10T12:00:00Z

La balise <dc:title>

Cette balise est obligatoire. Elle définit le titre de la publication. Ce titre sera affiché par la liseuse dans la liste d'ouvrages.

Il est possible de créer un titre sur plusieurs lignes, en ajoutant plusieurs balises <dc:title> . il faudra alors ajouter la propriété "id" à chaque balise, ainsi qu'une balise supplémentaire <opt:meta refines="#titre1" property="title-type">main / subtitle </opt:meta>

Exemple:

<dc:title id="titre1">Mon titre à moi</dc:title> 
<meta refines="#titre1" property="title-type">main</meta>

<dc:title id="titre2">Mon sous-titre</dc:title>
<meta refines="#titre1" property="title-type">subtitle</meta>
		

La balise <dc:language>

Cette balise est obligatoire. Elle ne présente pas de propriété.

Si j'écris en français, je choisis "fr":
<dc:language>fr</dc:language>

Les balises facultatives

Ces balises permettent de mieux identifier la publication. Bien que facultatives, certaines méritent d'être remplies.

<dc:contributor> permet d'indiquer une personne ayant aidé à l'écriture de la publication.
<dc:creator> Permet d'indiquer l'auteur.
<dc:date> Permet d'indiquer la date de la publication. Le format est particulier:
<dc:date>aaaa-mm-jjThh:mm:ssZ</dc:date>
<dc:source> Ne doit être utilisé que si l'ouvrage dérive d'un autre ouvrage. Il s'agit souvent d'un numéro ISBN.
<dc:description> Contient une description de la publication.
<dc:publisher> Contient l'éditeur.
<dc:subject> Une description du sujet de la publication.

La balise <opt:manifest>

Cette balise est obligatoire. Elle est obligatoirement la seconde balise enfant de <opt:package>. Elle suit donc obligatoirement la balise </opt:metadata>.

Cette balise n'a aucune propriété obligatoire. L'ordre de déclaration des balises enfants n'a pas d'importance.

Les balises <opt:item>

Ces balises sont obligatoires dans le sens où elles déclarent le contenu de la publication. Une image non déclarée dans ces balises ne peut en aucun cas être utilisée par la liseuse.

Chaque contenu est déclaré, une balise par contenu. Il peut donc y avoir de nombreuses lignes d'item.

Chaque balise peut, et doit présenter certaines propriétés:

"id"obligatoireUn identifiant unique pour chaque balise.
"href"obligatoirele chemin relatif au fichier de contenu déclaré.
"media-type"obligatoireLe type de contenu déclaré. Il peut s'agir d'une page de contenu: "application/xhtml+xml",
d'une image: "image/jpeg" ou "image/gif" ou "image/png",
ou d'une feuille de style: "text/css"
"fallback"facultatifl'identifiant d'un média non pris en charge (à confirmer).
"properties"facultatif/obligatoireUne propriété particulière.
Attention, il faut obligatoirement déclarer dans une seule balise, une seule propriété "nav" qui définira la table des matières.
"media-overlay"facultatifUtilisé pour les livres audio (à confirmer).

Il est assez fastidieux de remplir cette section à chaque fois que l'on ajoute un fichier au package. C'est particulièrement vrai pour les images et fichiers que l'on ne compose pas soi-même. Pour éviter cette tâche, mon application de génération possède une option permettant d'ajouter automatiquement une balise item pour les fichiers présents dans le package mais pas défini dans cette section. Ces fichiers seront référencés avec un id du type "autores" + numéro. Cette option ne modifie que le content.opf de l'epub, pas la version originale.


La balise <opt:spine>

Cette balise est obligatoire. Elle est obligatoirement la troisième balise enfant de <opt:package>. Elle suit donc obligatoirement la balise </opt:manifest>.

Cette balise n'a aucune propriété obligatoire. L'ordre de déclaration des balises enfants définit l'ordre d'affichage des ressources. Il convient donc de le faire correctement.

La propriété "toc" contient la référence vers la table des matières (toc = table of content) déclarée à l'étape précédente.

La propriété "page-progression-direction" indique le sens de lecture de la publication: "ltr" (de gauche à droite) ou "rtl" (de droite à gauche).

Les balises <opt:itemref>

Au moins une balise <itemref> est obligatoire, car ces balises déclarent le contenu de la publication à afficher.

Chaque contenu est déclaré, une balise par contenu. Il peut donc y avoir de nombreuses lignes d'item.

Chaque balise peut, et doit présenter certaines propriétés:

"idref"obligatoireL'id de la ressource à afficher, définie dans la balise <opf:manifest>.
"linear"facultatifPermets de définir si les différents contenus s'enchainent les uns par rapport aux autres. La valeur est "yes" si le contenu est enchainé, "no" si le contenu n'est pas enchainé. Si la propriété n'est pas mentionnée, la valeur "yes" est utilisée.

La balise <opt:bindings>

Cette balise est facultative. Elle définit ce qu'il faut faire du contenu non supporté par la spécification epub v3.0.

Cette balise permet de réaliser des animations, et plus encore...

 Contenu

Le contenu

Un epub sert à exposer un contenu (écris, images, films, etc.) sur différents dispositifs appelés liseuses.

Nous allons voir dans ce chapitre comment le contenu est créé.

Format

Bonne nouvelle, les epub sont constitués principalement de code HTML! La spécification epub v3.0 stipule même que le contenu doit être codé en HTML5 (dont la spécification n'est pas figée à ce jour...).

La base du HTML5

Sous ce titre très présomptueux: une simple présentation du HTML5 afin de pouvoir écrire un petit peu de contenu.

Le contenu minimum d'un fichier HTML5

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
   <head>
   </head>
   <body>
      <p>Ceci est du contenu!</p>
   </body>
</html>
		

Les balises textes

Sous ce titre énigmatique, les balises que j'utilise le plus et que vous devrez utiliser le plus vous aussi...

<h1> à <h6> Ces balises servent à définir des titres. h1 étant le titre le plus "important", h6 le moins "important". Cette balise est toujours suivie d'un retour à la ligne.
<p> Le texte contenu dans la balise p forme un paragraphe. Cette balise est toujours suivie d'un retour à la ligne.
<em> Cette balise s'utilise au sein d'une balise p ou h1, h2, etc. Elle permet de mettre l'accent sur un passage (emphase).
<strong> Cette balise s'utilise au sein d'une balise p ou h1, h2, etc. Elle indique un passage important.
<mark> Cette balise s'utilise au sein d'une balise p ou h1, h2, etc. Elle permet de "souligner" une portion du texte.
<cite> Cette balise s'utilise au sein d'une balise p ou h1, h2, etc. Elle permet de mettre définir du texte en tant que citation.
<br /> Cette balise s'utilise au sein d'une balise p ou h1, h2, etc. Elle force un retour à la ligne.

Il est important de bien comprendre qu'une balise <strong> n'a pas pour objectif de mettre un texte en gras, mais de faire "ressortir" ce texte. Il existe différentes façons de faire ressortir un texte: mettre en gras, augmenter la taille de la police, changer la police, etc.

Ces balises servent à bien structurer le texte et de définir et d'appliquer, par la suite, un style.

Les balises spécifiques

Des balises importantes pour la mise en forme ou la navigation...

<a href=""> Cette balise permet de définir un lien (au sein du document ou vers une autre page). Elle s'utilise au sein d'une autre balise (h1, h2, h3, etc. et p); exemple:
<a href="http://www.google.fr">Unlien vers le site Google</a>
<table> Cette balise permets de définir un tableau. Attention, dans une liseuse, les tables sont souvent mises en forme comme des listes.
<tr> Cette sous-balise de <table> permet de définir une ligne d'un tableau.
<td> Cette sous-balise de <tr> permet de définir une cellule d'un tableau.
<th> Cette sous-balise de <tr> permet de définir une cellule "en-tête" d'un tableau.
<ul> Cette balise permet de définir une liste non ordonnée "unordonned list" en anglais): une liste à puce.
<ol> Cette balise permet de définir une liste ordonnée ("ordonned list" en anglais): une liste numérotée.
<il> Cette balise permet de définir une ligne dans une liste (ordonnée ou non).
<img src"" alt=""> Cette balise permet d'insérer une image dans du texte. Après l'ajout d'une image, il ne faut pas oublier de déclarer la nouvelle ressource dans le fichier content.opf. Ne pas oublier la propriété "alt" qui affiche un texte lorsque l'image n'est pas trouvée.

Aller plus loin...

Il existe une foultitude de cours et de tutoriaux sur le HTML5.
Mon préféré, c'est le cours de Mathieu Nébra, disponible sur le site du zéro. Simple et bien mieux structuré que cet ouvrage...

Vérifier un contenu HTML5

Le HTML, c'est comme une boite de chocolats, on ne sait jamais sur quoi on va tomber.

Je ne sais pas si vous êtes comme moi, mais lorsqu'il faut respecter à la lettre un format, on commence par faire très attention, on va écrire quelques lignes, vérifier 15 fois ce que l'on a écrit, et sauvegarder le fichier. Puis, en ouvrant un navigateur (Chrome ou IE ou autre), on va regarder le résultat. Et on est super content de soi, ce n'est pas si compliqué que cela , etc.

La déconvenue viendra de la génération de l'epub. Après création, une vérification est automatiquement lancée, pour détecter les non-conformités. Et soudain, c'est le drame, des pages et des pages d'avertissements et d'erreurs! C'est tellement énervant, que l'on se dit que l'on n'y arrivera jamais. Rassurez-vous, on y arrive toujours!

Pour nous aider, il existe un outil en ligne, disponible à cette adresse: http://validator.w3.org/check qui nous permet de valider la page que l'on vient d'écrire. Les messages ne sont pas toujours explicites, mais permettent de corriger les erreurs plus facilement.

Bonne pratique pour se simplifier la vie

Nous l'avons vu, un document HTML5 est plutôt simple à créer, mais si nous voulons utiliser les fonctionnalités avancées des epub, il faut ajouter en tête du document un lien vers la spécification: xmlns:epub="http://www.idpf.org/2007/ops". Grâce à cet espace de nom, il sera possible d'utiliser les mots-clefs epub v3.0 très simplement!

 Mise en forme

La mise en forme

Au chapitre précédent, nous avons écrit un contenu. Ce contenu est agrémenté de balises de mise en forme. Ce chapitre a pour but de présenter la base de la mise en forme des epubs.

La philosophie des epubs, c'est que le contenu doit s'adapter au lecteur, et non le lecteur s'adapter au contenu.

C'est certainement ce point précis qui fera le succès des livres numériques dans les années à venir. En effet, qui n'a jamais été exaspéré par la lecture d'un livre mal imprimé, ou écrit trop petit? Mes parents n'ont pas mes yeux et auront tendance à privilégier des polices plus grosses, alors que je privilégierai plutôt des polices plus petites. Cette personnalisation est offerte dans les epubs, notament grâce aux feuilles de style.

Les feuilles de style

Si, comme moi il y a 6 mois, vous ne connaissez pas l'usage des feuilles de style, reportez-vous au cours HTML5+CSS évoqué au précédent chapitre.

Créons le fichier style.css uniquement pour mettre en forme les paragraphes

p
{
   color: blue;
}
		

La déclaration dans content.opf

Comme toute ressource, il faut la déclarer comme contenu. Pour ce faire, on ajoute la ligne suivante: <opf:item id="css" href="css/epub-spec.css" media-type="text/css" /> dans la balise <manifest> du fichier content.opf.

Une autre déclaration?

Si vous avez bien intégré le fonctionnement HTML + CSS, vous savez qu'il faut aussi ajouter la ligne suivante dans le header des pages de contenu: <link rel="Stylesheet" href="style.css" type="text/css" /> .

Si vous voulez vous simplifier la vie, ajoutez dès à présent cette nouvelle ligne à tous vos fichiers HTML. Cela va vous permettre de donner une unité de mise en page et de modifier complètement l'aspect de votre ouvrage en ne modifiant qu'un seul fichier!

Allez, si on faisait un essai pour voir ce qui se passe?
Sur un navigateur (Chrome, IE, etc.), aucun souci, la couleur du texte des paragraphes est bien bleue.

Passons sur FBReader... Enfer et damnation, le texte ne change pas de couleur! Le CSS ne fonctionne pas! Language injuste, pourquoi tant de haine?

Les limites

En fait, le CSS fonctionne, mais certaines liseuses ne l'appliquent pas intégralement. Le même contenu sous Adobe Digital Éditions est... bleu. Les liseuses ne comprennent pas toutes les balises, et omettent celles qu'elles ne comprennent pas ou ne veulent pas appliquer.

Conclusion:

Compliqué? Non, mais tâchons de rester compatible avec le plus grand nombre de liseuses.

La spécification v3.0

La spécification précise que les balises doivent se conformer à la spécification CSS2.1
Le positionnement absolu est à bannir car la mise en forme peut être changée par les réglages utilisateurs.

Les balises les plus utilisées

Sans ordre de priorité:
margin, padding, border, font, text, table, em, strong, cite, quote, et bien d'autres encore.
Le mieux est de vous reporter au site http://www.w3schools.com/css/ pour une liste exhaustive des balises CSS.

N'oubliez pas : les liseuses omettent certaines balises. Regénérez régulièrement votre epub pour vérifier que votre mise en page est adaptée aux liseuses. C'est extrêmement flagrant si vous utilisez des tables:

Sous Chrome:

Une table sous Chrome

Sous FBReader:

Une table sous FBReader  Du Package à l'epub

Du Package à l'epub

Dans les premières pages de cet ouvrage, je vous proposais d'utiliser un petit utilitaire de mon cru. Seulement vous n'aimez pas les utilitaires, on ne sait jamais, il pourrait y avoir un virus? Et vous avez raison d'être suspicieux... Rien ne vous permet, à partir de l'exécutable que je propose, d'être certain que je n'ai pas inclus des virus, trojan ou que sais-je encore. En fait, si: j'ai décidé de publier les sources de l'utilitaire, donc vous pourriez vérifier, puis regénerer l'utilitaire mais c'est une autre histoire.

Si vous refusez d'utiliser l'utilitaire, vous pouvez essayer de zipper manuellement votre package.

Quelques règles pour un epub Well-formed

Un epub est un fichier zip, contenant des fichiers obligatoires. Les quelques règles à suivre:

Facile? Allez-y, cela va vous prendre moins de 2 minutes, faites le test!

  1. On zip le contenu du répertoire en utilisant winzip ou 7Zip
  2. On renomme le fichier en ligne de commande:
    ren "fichier.zip" "fichier.epub"
  3. On passe ce fichier dans l'epubchecker tool:
    java.exe -jar "Path d'epubcheck-3.0b5\epubcheck-3.0b5.jar" "Path vers l'epub.epub".

Si vous avez autant de chance que moi, vous vous rendez-compte que ce n'est pas toujours simple. 2 cas de figure se présentent habituellement:

Les 2 cas d'erreurs courantes

Conclusion

Avec tous les essais que je fais, bien régulièrement, pour m'assurer du bon rendu du contenu, je préfère utiliser mon petit utilitaire. Qui génère un epub en quelques secondes, sans aucune manipulation supplémentaire. Mais, "c'est vous qui voyez!"

 La table des matières

Mais où est donc la table des matières?

Souvenez vous, au chapitre 4, nous avons définit ; dans la balise "manifest" ; une propriété "nav".

Nav, cela ressemble à navigation, donc table pour naviguer d'un chapitre à un autre, où d'un paragraphe à un autre. Nous allons tenter de comprendre comment cela se passe.

Un premier essai tout simple

La spécification nous propose une structure minimale pour un fichier nav.html, que je modifie en fonction des différents chapitres de cet ouvrage:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops">
   <head>
      <title>Test ePUB 3.0</title>
   </head>
   <body>
      <nav epub:type='toc' >
         <h1>Table des matières</h1>
         <ol>
            <li><a href="intro.html">Introduction</a></li>
            <li><a href="chap1-Config.html">Chapitre 1 - Configurer un environement de travail</a></li>
            <li><a href="chap2-Fichiers-Config.html">Chapitre 2 - Les fichiers de configuration</a></li>
            <li><a href="chap3-content_document.html">Chapitre 3 - Le document de contenu</a></li>
            <li><a href="chap4-Contenu.html">Chapitre 4 - Le contenu en HTML5</a></li>
            <li><a href="chap5-Mise_en_forme.html">Chapitre 5 - Mise en forme avec CSS</a></li>
            <li><a href="chap6-Packaging.html">Chapitre 6 - Générer l'epub</a></li>
            <li><a href="chap7-toc.html">Chapitre 7 - Table des matières</a></li>
         </ol>
      </nav>
   </body>
</html>
		

D'après la spécification, les liseuses devraient présenter une table des matières, même en ne mettant pas ce fichier nav.html dans la balise spine. Allons, faisons une petite vérification

Sous FBReader: pas de table des matières.
Sous Adobe Digital Éditions: pas de table des matières.
Sous Azardi: je ne peux pas ouvrir le fichier.
Et oui, comme vous êtes en train de le comprendre, les liseuses actuelles ne savent pas lire les fichiers de navigation des epub v3.0!

Contourner l'obstacle...

Comme il me semble difficile de publier un livre sans une table des matières, je vais me référer à la spécification : The NCX feature defined in [OPF2] is superseded by the EPUB Navigation Document [ContentDocs30]. EPUB 3 Publications may include an NCX (as defined in OPF 2.0.1) for EPUB 2 Reading System forwards compatibility purposes, but EPUB 3 Reading Systems must ignore the NCX in favor of the EPUB Navigation Document..

On peut donc faire cohabiter au sein d'un epub v3.0 une table des matières NCX (epub v2.0.1) et un document de navigation v3.0!

Ce document étant dédié aux epub v3.0, j'ai développé un convertisseur automatique d'un navigation document vers une table NCX. Une option est disponible dans mon utilitaire. L'emploi de cette option modifie automatiquement le content-document généré (et uniquement le content document généré) pour ajouter une référence à la table des matières v2.0.1 .

Aller plus loin

Développer la table des matières

La table des matières présentée plus haut est très simple, et renvoie au début des chapitres. C'est très bien pour des petits chapitres comme dans cet ouvrage, mais si nos chapitres faisaient 50 pages, il serait judicieux de créer des renvois intermédiaires, et ainsi faciliter la vie du lecteur.

La table des matières d'un epub est complètement paramétrable. Il est possible de créer des sous-tables, de n'afficher que certains titres, et même de faire des renvois au sein de paragraphes!

Une table sobre est souvent plus élégante qu'une table très détaillée. Tout dépends de l'ouvrage, mais tachez de faire aussi simple que possible.

Créer des renvois en cours de page

Si vous avez bien intégré le cours HTML5, vous savez que nous pouvons utiliser le mécanisme des ancres afin de créer des renvois au sein d'une page. La syntaxe est la suivante:
Dans la définition de la page, on ajoutera la propriété id="ancre" à une seule balise contenue dans ce fichier.
Dans la table de navigation, on ajoutera <a href="cible.html#ancre>.

Les sous-tables

Pour créer une sous-table, il suffit de créer une liste ordonnée contenue dans une balise <li>. Exemple:

<ol>
   <li><a href="#Chap7">Mais où est donc la table des matières?</a>
      <ol>
         <li><a href="#Chap7.1">Un premier essai tout simple</a></li>
         <li><a href="#Chap7.2">Contourner l'obstacle...</a></li>
         <li><a href="#Chap7.3">Aller plus loin</a>
            <ol>
               <li><a href="#Chap7.3.1">Développer la table des matières</a></li>
               <li><a href="#Chap7.3.2">Créer des renvois en cours de page</a></li>
               <li><a href="#Chap7.3.3">Les sous-tables</a></li>
            </ol>
         </li>
      </ol>
   </li>
</ol>
		

Donnera le résultat suivant:

  1. Mais où est donc la table des matières?
    1. Un premier essai tout simple
    2. Contourner l'obstacle...
    3. Aller plus loin
      1. Développer la table des matières
      2. Les sous-tables
      3. Créer des renvois en cours de page

Les limites

Est-ce compliqué? Non, c'est même très simple de prévoir sa table de navigation dès l'écriture du document. Evidemment, tout se complique lorsque l'on modifie la structure d'un document. Si on insère un chapitre dans la structure, ou si l'on change l'ordre des paragraphes, les id des balises ne seront plus ordonnées.

La solution que je préfère consiste à générer manuellement la table des matières au cours de la relecture, après avoir terminé la rédaction de l'ouvrage.

 Couverture

La couverture

Lorsque l'on se ballade dans une librairie, ou chez un marchant de livre, notre regard est souvent attiré par certains ouvrages. Lorsque nous sommes vraiment attirés, nous allons même jusqu'à prendre le livre entre les mains et nous lisons le quatrième de couverture (au dos du livre). C'est à ce moment que nous avons envie d'acheter le livre, voire de le lire sur place.

Pour les epub, c'est un peu la même chose, sauf que dans une librairie en ligne, nous ne voyons que quelques ouvrages mis en avant par le libraire. Exemple: si je me connecte sur le site d'une célèbre librairie en ligne:
Copie d'écran de la page d'accueil.
Sur les 3 livres présentés:
mon regard est instantanément attiré par le premier, certainement à cause de couleurs chatoyantes que je n'ai pas coutume de voir sur mon écran. J'identifie un chat et je me dis qu'il s'agit d'un roman pour femme ;).
Puis mon regard est attiré par cette femme en travers d'un livre, je me dis qu'il s'agit d'un livre pour les hommes ;).
Enfin, mon regard tombe sur ce dernier ouvrage dont je n'ai même pas envie de lire le titre.

Dans nos liseuses, c'est assez similaire, les ouvrages apparaissent avec une miniature de la couverture, et nous pouvons être attirés ou repoussés rien qu'en la regardant.

Vous l'aurez compris: il vous appartient d'associer une couverture séduisante à votre ouvrage (surtout s'il est mauvais ?).

Ajouter une couverture à sa publication

La couverture d'un epub v3.0 n'est pas obligatoire. Si vous n'en définissez pas, la couverture sera une copie d'écran de la première page affichée. Si vous en définissez, cela ne peut être qu'une image (jpg, png, gif ou svg).

Pas de surprise, tout se passe dans le fichier content document (content.opf).

De la même façon que la table des matières, la page de couverture est définie dans la balise <manifest>.
Dans les ressources, l'image de la couverture va recevoir une propriété supplémentaire: "cover-image". On aura donc, pour une couverture "couverture.jpg" une ligne supplémentaire dans la table des ressources:

<opf:manifest>
   <opf:item id="couverture" href="couverture.jpg" media-type="image/jpg " properties="cover-image" /> 
   ...
</opf:manifest>
		

Cette ligne n'est pas ajoutée automatiquement par mon application.

Bonne pratique

Même s'il n'est pas obligatoire d'ajouter la couverture dans la balise <spine>, il semble intéressant de l'y ajouter en première position. En effet, la miniature qui apparaitra sur une liseuse non compatible v3.0 prendra la première page comme couverture.

Je vous conseille donc d'ajouter une page qui affichera votre image de couverture en "plein écran". Pour afficher une image en plein écran, il va falloir utiliser des balises <svg>.

Le "svg"

Jamais entendu parlé du svg? Moi non plus, jusqu'à ce matin! Bon, pour faire simple, le svg (Scalable Vector Graphics) permet de contrôler dynamiquement le rendu du contenu. C'est un peu comme une fenêtre: il y a la surface affichée, et l'image affichée dans cette surface. Les dimensions de la fenêtre ne sont pas toujours celles des images que l'on y affiche. Le svg permet de contrôler la façon dont seront affichées les images sur différents écrans.

Si vous avez compris à quoi sert le svg, vous devez vous demander : mais pourquoi on ne construit pas un epub uniquement en svg?
Et bien certains epub sont construits uniquement sur les svg. Il s'agit essentiellement des epubs générés depuis des PDF (pdf2epub, etc.). Les images sont ajustées à l'écran et affichées. C'est très pratique pour faire un epub à partir d'un scan. Cependant, si vous avez déjà essayé de lire ce genre d'epub, vous savez que l'interaction est très moyenne, et que l'epub n'est plus du tout lisible sur de nombreuses liseuses. Sans compter le lourdeur du processus de création d'un svg pour chaque page à afficher.

Nous laisserons donc les epubs 100% svg aux éditeurs de bande dessinée. Soit dit en passant, il me semble que la bande dessinée ne devrait pas être transcrite de cette façon, car cela dénature l'œuvre.

Afficher une image en plein écran

Sans rentrer dans les détails, pour une image de couverture "couverture.jpg" nous allons simplement utiliser le code suivant:

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
   <head>
      <title>Couverture</title>
      <link rel="Stylesheet" href="style.css"  type="text/css" />
   </head>
   <body>
        <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="100%" height="100%" viewBox="0 0 283 425" preserveAspectRatio="meet">
            <image width="283" height="425" xlink:href="couverture.jpg"/>
        </svg>
    </body>
</html>
		

Quelques remarques:

Exemples:

Pas de cohérence entre la taille de l'image et le viewbox:

Mauvais rendu

la taille de l'image et celle du viewbox sont cohérentes:

Bon rendu

Une dernière subtilité: lorsqu'un document intègre une zone svg, il faut obligatoirement le déclarer lorsqu'on déclare le fichier dans le content document en ajoutant une propriété "svg" à sa balise item.
Pour intégrer ce fichier "couverture.html" dans l'epub, j'ajouterai donc les lignes suivantes dans le content document:

<opf:manifest>
   <opf:item id="cover" href="couverture.jpg" media-type="image/jpeg" properties="cover-image" />
   <opf:item id="couverture" href="couverture.html" media-type="application/xhtml+xml" properties="svg" />
   ...
</opf:manifest>
<opf:spine>
   <opf:itemref idref="couverture" linear="yes" />
   ...
</opf:spine>
		
 Notes

Notes

Dans certains livres, il est nécessaire d'insérer des notes de référence ou des notes de bas de page. Il existe un mécanisme dans la spécification pour les insérer.

Au niveau de l'insertion d'une note dans un texte: on ajoute un lien:
<a epub:type="noteref" href="#fn1">(1)</a>
Le lien, dans cet exemple, renvoi le lecteur à une note au sein de la page (grâce au #), mais il tout à fait possible de faire un lien dans une autre page.

L'emplacement où pointe ce lien est définit de cette façon:
<aside epub:type="footnote" id ="fn1">1. Ceci est une note de bas de page.</aside>

Qu'est ce qu'une note? C'est essentiellement un envoi vers endroit particulier. Il est donc logique qu'une note soit un lien.

Extraordinairement simple, non? [1]

 Aller plus loin

Aller plus loin

Si, comme moi, vous avez écrit quelques centaines de lignes dans un epub, vous vous heurtez certainement à la douloureuse opération qu'est la relecture. Il n'y a pas de bonne ou de mauvaise méthode. Seul le résultat compte.

Certains préfèreront entrer leurs textes sous un traitement de texte conventionnel, le corriger, puis le copier dans un HTML. C'est assez simple, mais toutes les subtilités de la mise en page, de la mise en exergue, des points importants, etc. disparaissent avec cette opération.

D'autres préféreront imprimer leur epub (depuis Adobe Digital Édition) et corriger manuellement avant d'appliquer les modifications manuellement dans le code des pages.

N'oubliez pas, ce qui compte, c'est que le contenu soit propre, sans fautes, facile à lire et qu'il s'adapte au lecteur.


Ça y est, vous avez toutes les cartes en main pour générer vos epubs, partager vos histoires et vos connaissances.

J'espère qu'en arrivant au bout de ces quelques pages, vous aurez l'impression d'avoir appris quelque chose.

N'hésitez pas à m'envoyer vos commentaires, remarques et questions, soyez-en remercié par avance.

De mon côté, je vais continuer à lire la spécification v3.0, et essayer de transcrire mon "lecteur audio" en générateur d'epub v3.0

 ePubTools

Annexe I - ePubTools

Se procurer ePubTools

La dernière version d'ePubTools est disponible sur sourceforge, à cette adresse: liens vers ePubTools.

Cette application est compatible avec xp, vista, seven. Elle nécessite d'avoir le .net framework installé (version 3.5 minimum).

Installation

L'installation peut faire apparaitre un avertissement sur l'application qui, bien que signée, ne vient pas d'un ordinateur connu (le miens en l'occurrence). Il n'y a pas d'options ou même de difficultés particulières lors de l'installation.

Lancement

Comme je vous l'ai dit pour l'installation, l'application ne vient pas d'un éditeur connu, et Avast peut lancer des avertissements et essayer de lancer l'application dans la sandbox. De par son fonctionnement, cette application ne doit pas s'exécuter dans la sandbox.

Générationd'un epub

L'application est constituée d'une fenêtre très simple, dimensionable, placée au-dessus des autres fenêtres:

copie d'écran de l'interface

Pour générer un epub à partir d'un dossier, il suffit de déplacer le dossier de base de la publication dans la fenêtre. La génération est alors automatique. Le fichier epub généré porte le nom du dossier de base, et est placé dans le dossier parent.

Un exemple avec cet ouvrage:

copie d'écran du dossier conteneur

Pour générer cet ouvrage, j'attrape le dossier "Ecrire ses epubs" et je le déplace dans la fenêtre de l'application (On remarquera au passage que le dossier de base peut contenir des espaces: c'est vrai, mais quand même déconseillé, surtout pour les liseuses embarquées). L'application génère alors le fichier epub, l'écrit sur le disque, puis lance (ou pas) la phase de vérification à l'aide de epubcheck.

Si l'epub est vérifié après génération, et qu'il contient au moins une erreur ou un avertissement, alors le détail du message d'erreur ou d'avertissement s'affiche dans une fenêtre:

Fenetre d'erreurs

Vous n'avez plus qu'à corriger l'erreur!

Si l'epub est Well-Formed, un message s'affiche en bas de la fenêtre:

Génération réussie

Les options de génération

Le menu options compte plusieurs options permettant de modifier la génération de l'epub:

Les différentes options

Les Outils intégrés

Ce menu compte plusieurs fonctions:

Les différents outils

Edition des informations

Edition d'un opf

Cette page permets l'édition des informations de l'epub, la génération d'un nouvel identifiant unique, etc. L'interface ne permets pas d'ajouter et supprimer des rubriques, mais synchronise certaines rubriques dont la modification n'est pas toujours aisée.

 Résoudre les erreurs

Annexe II - Résoudre les erreurs

Vous vous êtes lancés, vous avez écrit des centaines de pages, mais quand vous lancez la génération, vous obtenez des centaines de milliers de lignes d'erreurs? Pas de panique, ce n'est pas toujours si grave.

Il existe différents niveaux d'erreurs, certains sont plus grave que d'autres.

Les erreurs "XML"

Ces erreurs sont liées à la syntaxe XML. Le fait de faire se chevaucher 2 balises, ou d'oublier le "/" de fermeture d'une balise génère vraiment beaucoup d'erreurs.

Omission d'une balise <p>

Je commence par cette erreur, car c'est une erreur vicieuse: vous oubliez d'ouvrir une balise <p> et vous tapez votre texte, en ajoutant une balise </p> en fin de ligne. A la génération, l'erreur n'est pas très explicite:

ERROR: C:/Documents and Settings/xxxxxxxx/Bureau/epub/examples/Ecrire ses epubs.epub/content/Annexe2-Resoudre_les_erreurs.html(18,100): The element type "body" must be terminated by the matching end-tag "</body>".

Dans le fichier "Annexe2-Resoudre_les_erreurs.html", à la ligne 18 et à la position 100, il doit y avoir une erreur. Je la corrige en ajoutant le "<p>" en début de ligne, et hop le document est Well-formed!

Omission de fermeture d'une balise

Exemple avec l'annexe I: j'oublie le "/" de la première balise <p>: j'obtiens 22 erreurs!

La première erreur indique souvent l'emplacement de l'erreur à corriger:

ERROR: C:/Documents and Settings/xxxxxxxx/Bureau/epub/examples/Ecrire ses epubs.epub/content/Annexe1-ePubTools.html(11,169): element "p" not allowed here; expected the element end-tag, text or element "a", "abbr", "area", "audio", "b", "bdi", "bdo", "br", "button", "canvas", "cite", "code", "command", "datalist", "del", "dfn", "em", "embed", "i", "iframe", "img", "input", "ins", "kbd", "keygen", "label", "map", "mark", "meter", "ns1:switch", "ns2:math", "ns3:svg", "object", "output", "progress", "q", "ruby", "s", "samp", "script", "select", "small", "span", "strong", "sub", "sup", "textarea", "time", "u", "var", "video" or "wbr" (with xmlns:ns1="http://www.idpf.org/2007/ops" xmlns:ns2="http://www.w3.org/1998/Math/MathML" xmlns:ns3="http://www.w3.org/2000/svg")

Dans le fichier "Annexe1-ePubTools.html", à la ligne 11 et à la position 169, il doit y avoir une erreur. Je la corrige en ajoutant le "/" et hop, le document est Well-formed!

Chevauchement de balises

Même fichier, même emplacement, je fais se chevaucher une balise p et une balise a : <p><a></p></a>. J'obtiens 2 erreurs, la première indique le problème:

ERROR: C:/Documents and Settings/xxxxxxxx/Bureau/epub/examples/Ecrire ses epubs.epub/content/Annexe1-ePubTools.html(11,163): The element type "a" must be terminated by the matching end-tag "</a>".

Dans le fichier "Annexe1-ePubTools.html", à la ligne 11 et à la position 163, il doit y avoir une erreur. Je la corrige en inversant la balise <p> et la balise </a> et hop, le document est Well-formed!

Mauvaise utilisation de balises

Même fichier, même emplacement, je vais insérer une balise <div> </div> au milieu d'une balise <p>. J'obtiens 1 erreur:

ERROR: C:/Documents and Settings/xxxxxxxx/Bureau/epub/examples/Ecrire ses epubs.epub/content/Annexe1-ePubTools.html(11,23): element "div" not allowed here; expected the element end-tag, text or element "a", "abbr", "area", "audio", "b", "bdi", "bdo", "br", "button", "canvas", "cite", "code", "command", "datalist", "del", "dfn", "em", "embed", "i", "iframe", "img", "input", "ins", "kbd", "keygen", "label", "map", "mark", "meter", "ns1:switch", "ns2:math", "ns3:svg", "object", "output", "progress", "q", "ruby", "s", "samp", "script", "select", "small", "span", "strong", "sub", "sup", "textarea", "time", "u", "var", "video" or "wbr" (with xmlns:ns1="http://www.idpf.org/2007/ops" xmlns:ns2="http://www.w3.org/1998/Math/MathML" xmlns:ns3="http://www.w3.org/2000/svg")

Dans le fichier "Annexe1-ePubTools.html", à la ligne 11 et à la position 23, il doit y avoir une erreur, car div n'est pas autorisé. Je la corrige en changeant la balise <div> par la balise <span> et hop, le document est Well-formed!

Les erreurs de fichiers

Fichier manquant, ou erreur dans le nom ou l'emplacement du fichier

Si vous vous trompez dans le référencement de vos fichiers (une majuscule au lieu d'une minuscule par exemple), vous obtiendrez une erreur de ce type:

ERROR: C:/Documents and Settings/xxxxxxxx/Bureau/epub/examples/Ecrire ses epubs.epub: image file content/Interface.png is missing

Retrouvez le fichier, et corriger l'erreur de frappe.

Erreur dans le type du fichier

Si vous vous trompez dans le référencement de vos fichiers, un png référencé comme un jpeg par exemple: <opf:item id="png6" href="Interface.png" media-type="image/jpeg" />, vous obtiendrez une erreur de ce type:

ERROR: C:/Documents and Settings/xxxxxxxx/Bureau/epub/examples/Ecrire ses epubs.epub: The file content/Interface.jpg does not appear to be of type image/jpeg

La correction est simple: il suffit de référencer correctement le fichier: <opf:item id="png6" href="Interface.png" media-type="image/png" />, et hop, le document est Well-formed.

Les erreurs du svg

Si l'un de vos fichier de contenu utilise du svg, il faut le déclarer. Par exemple le fichier couverture: <opf:item id="couverture" href="couverture.html" media-type="application/xhtml+xml" /> génèrera cette erreur:

ERROR: C:/Documents and Settings/xxxxxxxx/Bureau/epub/examples/Ecrire ses epubs.epub/content/couverture.html: This file should declare in opf the property: svg

Pour corriger ce problème, ouvrir le fichier opf et changer la déclaration du fichier couverture.html: <opf:item id="couverture" href="couverture.html" media-type="application/xhtml+xml" properties="svg" />.

Les erreurs de la table de navigation

Une erreur dans la table de navigation génère très souvent 2 erreurs: une pour la table v3.0 et une pour la table v2.

Erreurs dans le nom du fichier lié

ERROR: C:/Documents and Settings/xxxxxxxx/Bureau/epub/examples/Ecrire ses epubs.epub/content/nav.html(34,43): 'content/Annexe1-ePubTools1.html': referenced resource missing in the package. ERROR: C:/Documents and Settings/xxxxxxxx/Bureau/epub/examples/Ecrire ses epubs.epub/content/toc.ncx(116,52): 'content/Annexe1-ePubTools1.html': referenced resource missing in the package.

Changeons Annexe1-ePubTools1.html par Annexe1-ePubTools.html pour corriger l'erreur.

Erreur dans l'ancre du lien

ERROR: C:/Documents and Settings/xxxxxxxx/Bureau/epub/examples/Ecrire ses epubs.epub/content/nav.html(26,48): 'Chap7.3.8': fragment identifier is not defined in 'content/chap7-toc.html' ERROR: C:/Documents and Settings/xxxxxxxx/Bureau/epub/examples/Ecrire ses epubs.epub/content/toc.ncx(90,57): 'Chap7.3.8': fragment identifier is not defined in 'content/chap7-toc.html'

Pour corriger l'erreur: Définissons l'ancre Chap7.3.8 dans le document chap7-toc.html, ou changeons l'ancre Chap7.3.8 par une ancre définie.

Utilisation d'une balise interdite

Si l'on se sert d'une balise <ul> au lieu d'une <ol>, on obtient cette erreur:

ERROR: C:/Documents and Settings/xxxxxxxx/Bureau/epub/examples/Ecrire ses epubs.epub/content/nav.html(23,12): element "ul" not allowed here; expected the element end-tag or element "ol"

Le fichier ne débute pas par un header

Un fichier de navigation commence obligatoirement par un header.

ERROR: C:/Documents and Settings/xxxxxxxx/Bureau/epub/examples/Ecrire ses epubs.epub/content/nav.html(9,7): element "p" not allowed here; expected element "h1", "h2", "h3", "h4", "h5", "h6", "hgroup" or "ol"

Le fichier référencé dans la table de navigation n'est pas référencé comme contenu

WARNING: C:/Documents and Settings/xxxxxxxx/Bureau/epub/examples/Ecrire ses epubs.epub/content/nav.html(35,53): hyperlink to resource outside spine 'content/Annexe2-Resoudre_les_erreurs.html' WARNING: C:/Documents and Settings/xxxxxxxx/Bureau/epub/examples/Ecrire ses epubs.epub/content/toc.ncx(122,62): hyperlink to resource outside spine 'content/Annexe2-Resoudre_les_erreurs.html'

Pour résoudre cet avertissement, incluez Annexe2-Resoudre_les_erreurs.html dans la balise spine du fichier opf.

Les autres erreurs

Les erreurs les plus fréquentes ont été présentées. Il en existe d'autres, que vous découvrirez au fil des générations d'epub. Le mieux est de bien lire l'erreur (pour les non-anglophones, de la traduire en ligne).