Comment insérer une image dans un linuxdoc

ou comment perdre 3h avec linuxdoc

Choisir un format de documentation sous linux est un sujet délicat dans une entreprise. D'aucun pourront argumenter que tel ou tel format n'est pas assez ouvert, pas assez répandu, trop difficile à convertir, trop compliqué à apprendre...

Après avoir longtemps utilisé LaTeX et texinfo, je décidais de me tourner vers le sgml. Ici, linudoc avait ses adeptes. Pourquoi pas me dis-je ? Au moins je n'aurais pas à me soucier de la présentation.

Pour commencer, je m'inspire d'un document écrit par un collègue. Tout se passe bien jusqu'au moment où j'essaie d'intégrer des schémas. Je tente bêtement un :

[img src="exploit.png"]

J'obtiens un message d'erreur lors de la conversion en HTML mais l'image s'affiche quand même.

Je consulte donc la documentation de linuxdoc, au format info. Rien. Pas la moindre trace du quart du commencement de l'insertion d'une image. Je tente une petite recherche sur google. Peine perdue, je tombe au mieux sur des astuces pour docbook (un autre format de documentation sgml). J'essaie de regarder un peu ce que j'ai à ma disposition en local :

$ dpkg -L linuxdoc-tools
[...]
/usr/share/doc/linuxdoc-tools/
[...]

Je décide d'aller faire un tour dans ce répertoire. Là je découvre un fichier "example.sgml". Je l'ouvre. Oh joie, oh bonheur, une section "Tables and Figures" se tiens juste devant mes yeux ! Pour inclure une figure, il faut donc faire :

<figure>
<eps file="logo.eps">
<img src="logo.png">
<caption>The Penguin Logo of the Linux</caption>
</figure>

linuxdoc se chargera tout seul de choisir le format eps ou png selon le format de sortie choisi. L'auteur nous met cependant en garde :
"One more point. Please remember that text only documents can be listened by a blind person, while the heavy graphical documents can't."
C'est vrai, pensons un peu à tous les aveugles qui lisent les documentations linux et privons nous de schéma pour eux ! Ensuite on pourra penser un peu à tous les dyslexiques, beaucoup plus nombreux, et on créera un document avec des mots sans b ni d, ou alors avec uniquement des b ou uniquement des d. On précisera au début du document, "attention, ce document contient des 'd'". Comme ça tout le monde sera à égalité devant la documentation.

Trêve de plaisanterie, il me faut mon document dans plusieurs formats et au minimum le HTML et le PDF (ici c'est comme ça !). Je lance la génération du PDF. Damned ! l'image est trop grosse. Je décide donc de la réduire un peu et édite mon makefile :

exploit.eps: exploit.fig
	fig2dev -L ps -m 0.8 $< $@

re-damned ! Après re-génération du PDF, elle n'a pas bougée. Je re-vérifie tout. Bizarre. Commence à m'énerver ce truc ! Je m'étonne qu'il n'y ait pas d'option pour préciser la taille de la figure. Je décide de chercher un peu plus de documentation pour avoir une liste complète des tags linuxdoc disponibles.

$ locate linuxdoc | grep dtd
[...]
/usr/share/sgml/dtd/linuxdoc.dtd
[...]

Après visualisation du fichier et recherche de "figure", il s'avère qu'un attribut "height" est disponible. Après quelques essais infructueux, je me décide à chercher de nouveau un peu de documentation sur google. Je fini par trouver un Linuxdoc-Reference.pdf. Enfin une référence complète avec tous les tags. Enfin presque complète, je ne suis visiblement pas le seul à avoir du mal avec linuxdoc et on trouve dans ce document beaucoup de :
"Again I can't explain this one. If you can, please mail."
Rassurant.

Quelques tests plus tard, je m'aperçois finalement que linuxdoc utilise le .png et non le .eps pour générer mon PDF. J'essaie de créer un PS au lieu d'un PDF pour voir. C'est bien le schéma au format .eps qui est utilisé. Par contre si je veux créer un PDF à partir du PS, je n'ai pas d'index (normal). Cette solution ne me convient donc pas.

Je décide de mettre un peu à jour ma debian, on ne sait jamais, dès fois qu'un bug quelconque soit corrigé :

apt-get update
apt-get -y upgrade

Mal m'en a prit, dia est maintenant incapable de générer des schémas en noir et blanc :

$ dia -e bdd.png bdd.dia
** (dia-python:1452): WARNING **: Can't color_convert in \
non-interactive app (w/o color_init())
[...]

Je me retrouve avec un schéma vert sur fond noir qui sera du plus bel effet sur mon document HTML. Pour l'instant il défigure également mon PDF car ce dernier intègre toujours le .png et non le .eps. Note pour plus tard : mettre à jour sa debian le moins souvent possible.

Bien décider à résoudre le problème, je vais regarder les sources de linuxdoc. Par chance c'est du perl, ça ira vite. Il suffit d'éditer LinuxDocTools.pm. Je rajoute quelques "print STDERR" bien placés pour avoir les différentes commandes lancés. Je commente la suppression des fichiers temporaires. Trois fichiers temporaires sont utilisés à chaque fois. Et je n'ai pas compté les différentes commandes...

J'arrive assez vite à identifier le problème en lançant les commandes à la main. C'est dans le dernier fichier temporaire que je me retrouve avec un .png au lieu de mon .eps. Le fichier "linuxdoc/latex2e/mapping" est utilisé. Je l'ouvre. Bingo c'est là que sont insérés les commandes latex destinées à pdflatex, utilisé pour la création du PDF, qui permettent de créer les figures. Je modifie quelques lignes et c'est reparti pour un test. pdflatex m'en veut :

$ linuxdoc --language=fr --charset=latin -B latex --output=pdf admin.sgml
[...]
! LaTeX Error: Unknown graphics extension: .eps.
[...]

Nouvelle recherche sur google. pdflatex ne sait pas inclure de schéma au format .eps (rha pourquoi ils ne le disent pas dans la doc de linuxdoc ?). Il faut les convertir en .pdf avant. On se croirait encore en 1980. Pourquoi chercher à inventer des machines à voyager dans le temps alors qu'il suffit d'installer linux sur un PC ? Je rajoute vite fait une règle au Makefile. Allélouia ! ça marche ! J'ai enfin mon schéma dans le PDF. Le titre de la figure n'apparaît pas (alors que dans le .ps c'était bon) mais je laisse ce détail de coté pour l'instant.

Ce qui m'intéresse pour le moment c'est que linuxdoc prenne le .png pour générer la sortie HTML et le .pdf pour la sortie PDF. Par chance, linuxdoc utilise un préprocesseur et dispose d'un "<#if>". J'avais remarqué lors de mes pérégrinations précédentes que l'option "pdflatex=yes" était passé au préprocesseur et je modifie donc la ligne :

<img src="exploit.pdf">

en :

<!--
<img src="exploit.pdf">
-->
<img
src="exploit.<#if pdflatex=yes>pdf</#if><#unless pdflatex=yes>png</#unless>">

Ça semble fonctionner : j'ai bien l'image .pdf dans mon PDF. Par contre je l'ai aussi dans mon HTML... Vérifications faites, il s'avère que le préprocesseur considère que "pdflatex=yes" est vrai si "pdflatex" n'est pas défini :

$ cat admin.sgml | sgmlpre | grep exploit.pdf 
<img src="exploit.pdf">
src="exploit.pdf">

Notons la section "SEE ALSO" du man de sgmlpre que je trouve très explicite :
"For a complete description, see the header in the source archive."
J'opte pour le passage d'une option "-D png=no" à linuxdoc lors de la création du PDF et change la ligne du .sgml en :

<img
src="exploit.<#if png=yes>png</#if><#unless png=yes>pdf</#unless>">

Ça fonctionne.
Fort de ce succès, je supprime la ligne que j'avais commenté et poursuis l'écriture de mon document. Mal m'en a pris. Quelques minutes plus tard, j'essaie de recompiler. Pas moyen :

$ linuxdoc --language=fr --charset=latin -B latex --output=pdf admin.sgml
[...]
LaTeX Warning: File `exploit.pdf' not found on input line 51.
[...]

Je n'y comprends plus rien. J'annule mes récentes modification avec quelques "undo" Emacs. Je relance la compilation : ça fonctionne ! Après plusieurs minutes d'essai, je comprends que c'est la ligne en commentaire qui change tout ! Petit test :

mkdir zyz
touch zyz/toto

Rajout de la ligne '<img src="zyz/toto">' en commentaire uniquement. Recompilation :

$ ltrace make admin.pdf 2>&1 | grep zyz
strlen("zyz")                                    = 3
memcpy(0x8071623, "zyz", 4)                      = 0x8071623

Super !
Quand on crée un PDF, linuxdoc recherche apparemment les 'img src="X"' et teste l'existence des fichier "X" ("apparemment" car je n'ai pas poussé plus loin mes investigations, il était déjà tard). Je me dis qu'il ne doit pas prendre en compte les sauts de ligne et que c'est pour cela que mon fichier n'est pas trouvé. J'essaie donc :

<img src="exploit.<#if png=yes>png</#if><#unless png=yes>pdf</#unless>">

Cela ne fonctionne plus !
J'ai un :

$ make admin.pdf 
[...]
can not copy graphics
[...]

Linuxdoc effectue donc cette recherche avant l'appel au préprocesseur ! J'en entend déjà certains me dire que c'est du logiciel libre, que les développeurs ne sont payés, que je râle et que je ne fait rien... Qu'ils aillent au diable.

J'ai finalement dans mon fichier :

<figure loc="p">
<eps file="exploit.eps" height="25cm">
<!--
Ne pas supprimer ce commentaire !!!
<img src="exploit.pdf">
Ne pas supprimer le saut de ligne après "img" !
-->
<img
src="exploit.<#if png=yes>png</#if><#unless png=yes>pdf</#unless>">
<caption>Environnement de production</caption>
</figure>

Et voilà, 3 heures pour insérer une image dans un linuxdoc à l'aide d'une bidouille digne d'un programmeur visual basic. Et encore, je n'ai toujours pas de titre pour les figures du PDF...

Ne perdons pas espoir, la prochaine fois j'essaie le docbook.