Introduction

Il y a plusieurs jours j’ai voulu lire la documentation de postgreSQL. Naïvement je pensais pouvoir la lire au format ePub, tout comme je le ferais avec la documentation de Django, disponible sur le site Readthedocs.

Je me rends donc sur la page de la liste des manuels postgreSQL. Et là, c’est le drame : pas de version ePub !

J’ai donc - comme souvent en informatique - dû improviser. Pour ArchLinux, je précise.

Que dit la documentation ?

Je regarde dans la documentation en ligne de postgreSQL pour produire une documentation soi-même mais il s’avère qu’il n’y a pas de méthode pour générer de version ePub.

Pourtant, quand on regarde le fichier Makefile de la documentation postgreSQL sur le dépôt git, il semble qu’une règle permette de générer un fichier ePub. Cf. les sources du fichier Makefile pour la documentation postgreSQL dans le dépôt Git, l.288.

Le problème

La génération du ePub dépend du script Ruby dbtoepub qui n’est pas présent dans ArchLinux. Théoriquement c’est le paquet docbook-xml qui devrait fournir ce script, mais la recette (fichier PKGBUILD) d’ArchLinux omet tout un tas de fichiers lors de la création du paquet, y compris notre fameux dbtoepub.

J’ai bien tenté de l’installer manuellement, mais cela dépend d’une version de Ruby antérieure à celle présente dans ArchLinux. Probablement que sous Debian aucun souci n’apparaît puisqu’un paquet dbtoepub existe.

Ma solution

Relativisons et utilisons les outils à notre disposition sous ArchLinux :

  • le Makefile de la documentation postgreSQL qui demande un fichier postgres.xml en dépendance
  • et qui permet justement de générer ce postgres.xml
  • pandoc qui transforme certains documents en d’autres documents

J’ai donc procédé ainsi pour générer la documentation postgreSQL 9.5.5 en ePub :

sudo pacman -S openjade docbook-xml docbook-sgml pandoc
git clone --depth=1 git://git.postgresql.org/git/postgresql.git -b REL9_5_5
cd postgresql
./configure
cd doc/src/sgml
make postgres.xml
pandoc -f docbook -t epub -o postgres.epub postgres.xml

Ce qui m’a fournit un fichier postgres.epub que j’ai pu insérer dans ma bibliothèque numérique Calibre.

Conclusion

Je suis heureux de pouvoir lire ma documentation sur ma liseuse et espère ne pas avoir de mauvaise surprise lors de ma lecture.