Follow me
RSS feed
My sources
My Viadeo

algorithmique.net au format epub (ou Jekyll-epub)

Greg | 22 Apr 2010

Projets Depuis que j'ai acquis un iPad, j'ai redécouvert la joie de lire sur un support électronique. J'y goutais déjà via les quelques livres que j'ai achetés ici ou , mais il s'agissait principalement de lecture de PDF sur mon portable ou, à de très rares occasions, de la lecture d'eBook via Stanza. A mon avis, l'eBook n'a d'intérêt que si le support est suffisamment grand. Et pour cela le choix est vaste. En ce qui me concerne, iBooks était la solution idéale.

En fouillant un peu sur le net afin de découvrir l'offre disponible, je suis tombé sur l'excellent article d'Aaron Patterson expliquant comment transformer la documentation Ruby pour la lire sur un lecteur d'eBook. Pour cela il suffit d'utiliser le gem paddle qui permet de passer du format RDoc au format epub.

A partir de là, ce qui va suivre m'est paru évident : "Pourquoi ne pas proposer le contenu de mon Blog au format epub ?"

Le format epub

epub est un format ouvert standardisé pour les livres électroniques pour lequel il est donc facile de trouver les spécifications. En cherchant sur internet, vous trouverez de nombreux articles sur le sujet. Personnellement je me suis appuyé sur un article d'HXA7241 décrivant succinctement, mais clairement, comment créer un epub en respectant le standard OPS/OPF.

Les règles à respecter sont très simples. Tout d'abord, il y a la structure du fichier. Un epub n'est rien d'autre qu'une archive zip. Dans cette archive nous trouverons des fichiers XHTML (un par chapitre) et quelques fichiers spécifiques au standard. Bien entendu, nous trouverons aussi des fichiers CSS et des images, en fonction du contenu du livre.

En ce qui concerne les fichiers spécifiques, nous en trouverons 5 :

Comme je l'ai indiqué plus haut, chaque chapitre de notre livre est rédigé dans un fichier XHTML. Il est très important de bien respecter le standard, au risque de ne pas voir s'afficher les pages. Dans mon application de lecture, il arrive que je me retrouve avec des messages de ce type :

epub error

Il faut également faire attention aux fichiers CSS pour lesquels il existe quelques restrictions. Dans les faits, il faut savoir que seule une sous-partie de la norme CSS 2.1 est supportée.

Pour les images enfin, il faudra vous restreindre au JPEG, GIF, PNG et SVG.

Une fois que vous avez l'ensemble de vos fichiers, il faut les organiser en suivant la structure suivante :

.
|-- mimetype
|-- META-INF
|   `-- container.xml
|-- content.opf
|-- toc.ncx
|-- page-template.xpgt
|-- chapitre01.xhtml
|-- chapitre02.xhtml
|-- ...
|-- display.css
|-- ...
|-- image01.png
|-- image02.png
`-- ...

Bien entendu, vous pouvez disposer librement vos fichiers dans des répertoires, sous répertoires, ..., tant que le fichier content.opf est bien référencé dans le container.xml et que les fichiers composant le livre sont eux-même correctement pointés dans le fichier content.opf, vous pouvez organiser cela à votre guise.

Pour créer votre fichier epub, il suffit maintenant de créer l'archive zip. Pour cela, placez-vous à la racine de votre livre et utilisez la commande suivante :

zip -Xr9D MonLivre.epub mimetype *

Jekyll

Pour ceux qui ne connaissent pas Jekyll, il s'agit d'un outil développé en Ruby, permettant de générer un site statique blog-aware. C'est l'outil utilisé pour propulser ce site.

Dans le cas d'algorithmique.net, les sources du site sont organisées de la façon suivante :

.
|-- 404.html
|-- Rakefile
|-- _config.yml
|-- _includes
|-- _layouts
|   |-- default.html
|   `-- post.html
|-- _posts
|   |-- 2009-02-13-bonjour-tout-le-monde.html
|   |-- ...
|   `-- 2010-04-22-algorithmiquenet-au-format-epub-ou-jekyll-epub.html
|-- about.html
|-- atom.xml
|-- capcode.html
|-- css
|   |-- ldd.css
|   |-- quote.gif
|   |-- resume.css
|   |-- screen.css
|   |-- syntax.css
|   `-- video.css
|-- files
|   |-- CARB.zip
|   |-- CV-Gregoire_Lejeune.pdf
|   |-- MyWriteRoom.zip
|   `-- QTRuby.zip
|-- gemmenu.html
|-- images
|   |-- 404.gif
|   |-- ...
|   |-- pages
|   |   |-- gemmenu-download.png
|   |   `-- ...
|   |-- posts
|   |   |-- AJAXHTTP.png
|   |   `-- ...
|   `-- ...
|-- index.html
|-- np
|-- README.textile
`-- video
    |-- binding
    |   |-- binding001.f4v
    |   `-- ...
    `-- ...

Ce qu'il est important de noter dans cette organisation, qui n'a rien de spécifique à ce site, c'est que l'on retrouve tous les posts dans le répertoire _posts, que les pages statiques sont à la racine, les CSS dans le répertoire css et les images dans le dossier images.

Les posts et les pages peuvent bénéficier de l'utilisation de layouts. Dans mon cas, chaque post contient un entête ayant la forme suivante :

---
layout: post
title: Titre du post
author: Greg
category: Site
---

<p>... contenu du post...</p>

Dans cet entête, nous indiquons à Jekyll que lors de la génération du site, il faudra appliquer le layout post au fichier. Pour votre information, le layout post utilise lui même un layout (default)...

Les autres informations contenues dans l'entête peuvent être utilisées comme variables dans le corps du post. Ainsi dans mon layout post nous trouvons ceci :

...
<h1><a href="{ { page.url } }">{ { page.title } }</a></h1>
<div id="meta">By { { page.author } } | { { page.date | date_to_string } }</div>
...

Bon, je pense que vous avez compris le principe...

Pour générer le site, Jekyll a besoin d'un fichier de configuration. Dans mon cas, ce fichier contient les informations suivantes :

markdown: rdiscount
pygments: true
lsi: false
exclude: 
- Rakefile
- np
- README.textile

En exécutant la commande jekyll à la racine, j'obtiens, dans un répertoire _site, le contenu de mon site, qu'il ne me reste plus qu'à uploader sur mon serveur.

Je ne rentrerai pas plus dans les détails, mais sachez qu'il s'agit d'une solution extrêmement simple à utiliser. Et qui couvre largement les besoins de 90% des blogs que l'on trouve sur internet.

Jekyll-epub

Comme nous l'avons vu, le format epub est relativement simple, d'autant plus qu'il utilise des solutions que nous avons l'habitude de manipuler quand nous travaillons sur internet. Je me suis donc penché dessus avec comme objectif de fournir un gem permettant aux utilisateurs de Jekyll de fournir le contenu de leur site sous forme d'eBook.

La première chose à prendre en compte c'est qu'un site web (blog ou pas) n'a pas forcement la même organisation qu'un livre. Ce site par exemple, vous propose sur la page d'accueil le dernier post mis en ligne. En bas de page vous pouvez accéder aux pages statiques et quelques liens externes, à la liste des 8 derniers posts mis en ligne, et à un historique organisé par catégorie. Vous en conviendrez, si cette présentation va sur du Web, elle n'a rien de classique dans le monde du livre. Pour générer un eBook, il va donc falloir revoir un peu l'organisation.

La solution la plus simple serait de proposer une organisation avec un post par chapitre, du plus ancien au plus récent. Nous n'avons donc pas besoin de la page d'accueil. De même, il semble inutile d'ajouter la page d'erreur 404 de même que le fichier de fil atom ne nous servira à rien.

Pour exclure une page, nous utilisons l'entrée exclude: dans le fichier de configuration de Jekyll. Le problème est que nous ne pouvons pas ajouter les pages à exclure de notre eBook dans le fichier _config.yml parce que dans ce cas là, elle seront également exclues de la version Web... Pour contourner cela, j'ai adopté la solution qui consiste à créer un fichier de configuration alternatif _epub.yml. Voici à quoi il ressemble pour ce site :

markdown: rdiscount
pygments: true
lsi: false
exclude: 
- Rakefile
- np
- README.textile
- .htaccess
- 404.html
- video
- atom.xml
- files
- index.html
- tags
epub:
  validate: true
  name: algorithmique_net.epub
  title: Algorithmique.net
  lang: fr
  subject: Informatique
  description: "Retouvez l'ensemble des articles publiés sur algorithmique.net..."
  relation: http://algorithmique.net
  creator: Grégoire Lejeune
  publisher: Grégoire Lejeune
  date: 2010-12-31
  rights: "Copyright (c) 2009, 2010 Grégoire Lejeune. All documents licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 2.5 License, except ones with specified licence."

Comme vous pouvez le voir, je ne me suis pas contenté d'allonger la liste des fichiers à exclure. J'ai également ajouté le support d'entrées spécifiques à la création de notre eBook. En voici la liste exhaustive :

Autre élément à prendre en compte : les layouts. En effet, si dans sa version Web, algorithmique.net se présente très bien avec un entête et un pied de page, il n'en sera pas de même en version livre électronique. Pour cela il faudrait donc pouvoir avoir un layout spécifique pour la version epub.

Je permets cela en ajoutant la possibilité de spécifier un layout alternatif dans le cas de la génération de l'eBook. Pour cela j'ai ajouté une entrée epub: dans les données d'entête des fichiers (posts, pages et layouts). Ainsi, mes pages qui avaient un entête de la forme :

---
layout: default
title: A propos...
---

Ont maintenant la forme suivante :

---
epub: epub
layout: default
title: A propos...
---

Ce qui indique que dans le cas de la création du fichier epub, ce n'est pas le layout default qui sera utilisé, mais epub.

Pour les posts, ils utilisent tous le layout post qui utilise lui même me layout default. J'ai donc simplement modifié l'entête du layout post de ceci :

---
layout: default
---

A cela :

---
epub: epub
layout: default
---

Pour que tout cela soit pris en charge, j'ai créé une petite extension Jekyll::Epub dans laquelle je me suis permis d'étendre certaines classes de Jekyll. Les sources de ce petit travail sont disponibles sur Github.

Voilà, il ne reste plus qu'à lancer la génération. Ceci se fait très simplement en utilisant la méthode create de Jekyll::Epub

Personnellement j'utilise un fichier Rakefile pour gérer ce site. J'ai donc tout simplement ajouté la tache suivante :

desc 'Create epub...'
task :epub do
  Jekyll::Epub.new().create
end

Et voila le travail...

Jekyll-epub

TODO

Jekyll-epub est encore un cours de développement, et je ne garantis pas du tout que cela fonctionne chez vous. Je vais le stabiliser en le testant via les nombres sites utilisant Jekyll.

Avant de livrer un premier gem, j'aimerai ajouter quelques options telles que la possibilité de forcer l'ordre des pages. Ceci afin de permettre d'ajouter un sommaire, des mentions, ... en début ou fin de livre. Si vous regardez les sources, vous verrez que certaines parties demandent une évidente réécriture. Enfin, je souhaiterais étendre un peu les filtres et surtout permettre l'utilisation de filtres définis spécifiquement par l'utilisateur. La création de l'archive est également à revoir. Il serait également bien de créer une extension Liquid permettant d'isoler des spécificités d'une page entre sa version Web et sa version epub. Quelque chose du genre :

<html> 
...

{ % epub % }
<!-- ceci n'est visible dans las la version epub -->
{ % endepub % }

{ % noepub % }
<!-- ceci n'est visible dans las la version Web -->
{ % endnoepub % }

...
</html>

Bref, pas mal de choses avant de pouvoir l'utiliser réellement.

Pour ceux qui souhaitent voir plus précisement le rendu obtenu, vous pouvez télécharger la version epub d'algorithmique.net.

Copyright © 2009 - 2011 Grégoire Lejeune.
All documents licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 2.5 License, except ones with specified licence.
Powered by Jekyll.