TeXPNG, la documentation

Jean-Michel Sarlat (jm-sarlat@melusine.eu.org) - 7 février 2003

TeXPNG désigne une méthode utilisée sur Syracuse pour mettre en place une prévisualisation des pages d'un document composé avec (La)TeX sous forme d'images au format PNG. Dans le même temps, les fichiers terminaux sont rendus accessibles aux formats PostScript et PDF. Ansi par l'intermédiaire d'une seule page, on accède à la fois aux sources et aux documents finaux en pouvant avoir une idée précise du contenu.


Pour les utilisateurs de Syracuse, la publication dans cet environnement revient à déposer dans un des répertoires de Syracuse le document initial fichier.tex, le fichier d'appel fichier.xml et, éventuellement, tous les fichiers associés, nécessaires à la compilation du fichier initial. Pour que les compilations puissent être exécutées par les robots, le répertoire de dépôt doit appartenir au groupe syracuse avec le droit d'écriture pour ce dernier.

Le fichier d'appel


Il est au format XML (son nom est celui du fichier (La)TeX qu'il est censé indexer avec l'extension .xml), son élément racine est plain. Il contient la définition d'un hachage (Infos) et la référence à un module (texpngpdf.pl).

Fichier : doc1.xml

<plain>
    <hachage nom="Infos">
        <!-- clés -->
    </hachage>
    <module>texpngpdf.pl</module>
</plain>

Le hachage Infos


C'est une succession de clés, présentées sous la forme : <cle nom="une clé">sa valeur</cle>. Voici la liste des clés.

Le module texpngpdf.pl


texpngpdf.pl est un module d'appui de petitParseur, c'est un script perl qui est invoqué au moment de la requête sur le fichier XML par le navigateur client. Il accède au hachage Infos, lis le premier fichier de configuration qu'il trouve éventuellement en remontant vers la racine du serveur à partir de l'endroit ou se trouve le fichier d'appel et fait ce qu'il a à faire ...

Le fichier texpng.cnf


Pour éviter la saisie répétitive de clés, un utilisateur peut, en des endroits bien choisis de l'arborescence qu'il gère, placer un fichier texpng.cnf renfermant les valeurs de ses clés courantes. Ces valeurs seront les valeurs considérées par défaut par le système lorsqu'il traitera un fichier se trouvant sous le répertoire contenant le fichier de configuration. C'est dans ce dernier que l'on peut déclarer une licence en indiquant le nom du fichier qui la renferme.
Le fichier de configuration se construit de la façon suivante : chaque ligne est de la forme nom de la clé = valeur de la clé, cela suppose que la valeur d'une clé ne peut s'écrire sur plusieurs lignes et qu'elle ne peut contenir le signe =. Pour la déclaration d'une licence cela se fait suivant la forme : licence:[nom]=[fichier.txt], où [nom] sera le nom affecté à la licence et [fichier.txt] le nom du fichier contenant le texte de la licence. La recherche de ce fichier est faite avec le même mécanisme, en remontant à partir du répertoire du fichier traité, ce qui laisse un bon nombre de variations possibles.


Exemple de fichier de configuration

Fichier : texpng.cnf

auteur=Jean-Michel Sarlat
licence=ljms
licence:ljms=licence.txt

Exemple de licence

Fichier : licence.txt

<b>Licence de Libre Diffusion de Documents</b> -- LLDD version 1<br />
Ce document peut être librement lu, stocké, reproduit, diffusé, traduit et cité par
tous les moyens et sur tous supports aux conditions suivantes :
<ul>
    <li> tout lecteur ou utilisateur de ce document reconnaît avoir pris connaissance
    de qu'aucune garantie n'est donnée quant à son contenu, à tout point de vue,
    notamment véracité, précision et adéquation pour toute utilisation;</li>
    <li>il n'est procédé à aucune modification autre que cosmétique, changement de
    format de présentation, traduction, correction d'une erreur de syntaxe évidente,
    ou en accord avec les clauses ci-dessous;</li>
    <li>des commentaires ou additions peuvent être insérés à condition d'apparaître
    clairement comme tels; les traductions ou fragments doivent faire référence à
    une copie originale complète, si possible à une copie facilement accessible.</li>
    <li>les traductions et les commentaires ou ajouts insérés doivent être datés et
    leur(s) auteur(s) doi(ven)t être identifiable(s) (éventuellement au travers
    d'un alias);</li>
    <li>cette licence est préservée et s'applique à l'ensemble du document et des
    modifications et ajouts éventuels (sauf en cas de citation courte), quelque soit
    le format de représentation;</li>
    <li>quel que soit le mode de stockage, reproduction ou diffusion, toute personne
    ayant accès à une version numérisée de ce document doit pouvoir en faire une copie
    numérisée dans un format directement utilisable et si possible éditable, suivant
    les standards publics, et publiquement documentés, en usage.</li>
    <li>la transmission de ce document à un tiers se fait avec transmission de cette
    licence, sans modification, et en particulier sans addition de clause ou
    contrainte nouvelle, explicite ou implicite, liée ou non à cette transmission.
    En particulier, en cas d'inclusion dans une base de donnée ou une collection,
    le propriétaire ou l'exploitant de la base ou de la collection s'interdit tout
    droit de regard lié à ce stockage et concernant l'utilisation qui pourrait être
    faite du document après extraction de la base ou de la collection, seul ou en
    relation avec d'autres documents.</li>
</ul>
Toute incompatibilité des clauses ci-dessus avec des dispositions ou contraintes légales,
contractuelles ou judiciaires implique une limitation correspondante du droit de lecture,
utilisation ou redistribution verbatim ou modifiée du document.

Exemple de fichier d'appel

Fichier : reels.xml

<plain>
    <hachage nom="Infos">
        <cle nom="sty">macros.sty</cle>
        <cle nom="texpng">-L -p 3 -t 1.2</cle>
        <cle nom="texpdf">-L -p 3 -D '-Pec -Pamz -Pcmz -ta4'</cle>
        <cle nom="date">7 février</cle>
    </hachage>
    <module>texpngpdf.pl</module>
</plain>

Ce fichier est déplacé dans le répertoire exemple, le lien suivant pointe sur lui.
reels.xml

Le fonctionnement


Les fichiers étant en place, la première requête sur le fichier d'appel va provoquer la compilation donc la création des images PNG et des fichiers PS et PDF. En fin de compilation les logs vont s'afficher à la suite, c'est donc l'occasion de vérifier que tout est correct. Un point important à noter est que c'est l'user du serveur qui est propriétaire des fichiers résultants de la compilation, aussi il peut rencontrer des difficultés s'il doit écraser des fichiers dont il ne serait pas propriétaire. Pour éviter cela il vaut mieux effacer les fichiers que l'on aurait pu produire directement sur le serveur, suite à une compilation.
S'il est nécessaire de forcer une recompilation, suite à une modification par exemple, alors il suffit de rajouter ?rm=ok après le nom du fichier au niveau de la ligne d'appel du navigateur.

Source doc.txt mouliné par petitParseur(Z+B) le mercredi 19 février 2003.