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 :

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 :
 

 
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 :
 

 
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 :
 

 
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.
 

 
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é :
 

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

 
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 commente
quelques lignes et c'est reparti pour un test. pdflatex m'en veut :
 

 
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 :
 

 
en :
 

 
Ç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 :
 

 
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 :
 

 
Ç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 :
 

 
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 :
 

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

 
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 :
 

 
Cela ne fonctionne plus !
J'ai un :
 

 
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 :
 

 
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.

oula  
pour ne pas perdre du temps, ecris dans un vrai format, le .doc par exemple
bonne chance

Hmm non, je l'ai utilisé de 1995 à 1998 (avant je faisais des .wks) et j'étais très content de passer à LaTeX.

En tout cas, sur les 3 heures, y'a quelques minutes a écrire le post

C'était quoi la question ?

je connais un mec qui aurait pu écrire la phrase citée !!

 
Inutile de te rassurer, je pense que tu connais la réponse à ta question.
Enfin j'espère