%FSTYLE{/syracuse/fabrique/styles/docsyracuse.css}
%TITRE{TeXPNG, la documentation}
%AUTEUR{Jean-Michel Sarlat}
%MAIL{jm-sarlat@melusine.eu.org}
%DATE{7 février 2003}

%P{§gTeXPNG§ désigne une méthode utilisée sur §gSyracuse§ 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 §iterminaux§ 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.}
%P{Pour les utilisateurs de Syracuse, la publication dans cet environnement
revient à déposer dans un des répertoires de Syracuse le document initial
§vfichier.tex§, le fichier d'appel §vfichier.xml§ et, éventuellement, tous
les fichiers §iassociés§, nécessaires à la compilation du fichier initial.
Pour que les compilations puissent être exécutées par les §irobots§, le 
répertoire de dépôt doit appartenir au groupe §vsyracuse§ avec le droit 
d'écriture pour ce dernier.}

%S{Le fichier d'appel}

%P{Il est au format XML (son nom est celui du fichier (La)TeX qu'il est censé 
indexer avec l'extension §v.xml§), son élément racine est §vplain§. Il contient 
la définition d'un hachage (§vInfos§) et la référence à un module (§vtexpngpdf.pl§).}

FICHIER:doc1.xml:
<plain>
    <hachage nom="Infos">
        <!-- clés -->
    </hachage>
    <module>texpngpdf.pl</module>
</plain>
§ 
M:text: text="doc1.xml" html="doc1.thtm"
SH:rm -f doc1.xml doc1.thtm

%SS{Le hachage Infos}
%P{C'est une succession de clés, présentées sous la forme&nbsp;:
§v&lt;cle nom="une clé"&gt;sa valeur&lt;/cle&gt;§. Voici la liste des
clés.
%L{
- §gauteur§ (facultative) -- auteur du fichier présenté.
- §gcommentaire§ (facultative) -- texte d'un commentaire qui sera inscrit à l'intérieur mais
en bas du cadre de présentation.
- §gconfig§ (facultative) -- par défaut, un fichier de configuration sera recherché en amont, il
est possible de désactiver cela en affectant la valeur §vnon§ à cette clé. L'usage, futur, de cette
clé sera de faire référence à un fichier de configuration déclaré au niveau de TeXPNG (donc sans
notion de localisation relative).
- §gdate§ (facultative) -- date de la mise en place.
- §glicence§ (facultative) -- inscription d'une licence sous le cadre de présentation. Par défaut
un petit texte est présenté, la valeur §vnon§ attribuée à cette clé évite l'inscription. Il 
est possible de déclarer une licence par l'intermédiaire du fichier de configuration. Il suffit
d'invoquer le nom de cette licence ici pour qu'elle soit affichée.
- §gtexpng§ (obligatoire) -- arguments passés à l'application §vtexpng§ pour la réalisation des
images PNG. Voici les options importantes (les seules nécessaires)&nbsp;:
%L{
 - §g-T§ -- la composition utilise le format §vplain TeX§,
 - §g-L§ -- la composition utilise le format §vLaTeX§,
 - §g-p n§ -- le nombre de passes est §vn§ (utile pour générer une table des matières, n=3),
 - §g-t facteur§ -- le facteur d'agrandissement des pages (à l'usage, facteur = 1.2|1.3 se trouvent
 être les plus adaptés).
}
- §gtexpdf§ (obligatoire) -- arguments passés à l'application §vtexpdf§ pour la réalisation des
fichiers PS et PDF. Voici les options importantes&nbsp;:
%L{
 - §g-T§ -- la composition utilise le format §vplain TeX§,
 - §g-L§ -- la composition utilise le format §vLaTeX§,
 - §g-p n§ -- le nombre de passes est §vn§ (utile pour générer une table des matières, n=3),
 - §g-D 'options pour DVIPS'§ -- Les quotes simples sont très importantes ici, elles délimitent
 les arguments passés à DVIPS, en particulier pour le chargement des polices vectorielles et la
 déclaration du format de page PDF.
}
- §gtitre§ (obligatoire) -- titre de la page de présentation.
- §gcls§, §gsty§, §ginc§, §geps§, §gpro§, §gmp§, §gtex§, §gjps§ -- clés permettant la déclaration des
fichiers associés (classes latex, packages latex, inclusions, fichiers eps, prologues postscript,
fichiers metapost, fichiers tex et fichiers jps). Une même clé peut référencer plusieurs fichiers,
il suffit pour cela de séparer leurs noms par §v:§ (deux points),
- §garc§ -- (19/02/2003) -- clé à utiliser comme les précédentes pour présenter des archives.
}
}

%SS{Le module texpngpdf.pl}

%P{§vtexpngpdf.pl§ est un module d'appui de §gpetitParseur§, c'est un script §gperl§ qui est invoqué
au moment de la requête sur le fichier XML par le navigateur client. Il accède au hachage §vInfos§, 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 ...} 

%SS{Le fichier texpng.cnf}
%P{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 §vtexpng.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&nbsp;: chaque ligne est de la forme
§vnom 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 §v=§. Pour la déclaration d'une licence cela se fait suivant la
forme&nbsp;: §vlicence:[nom]=[fichier.txt]§, où §v[nom]§ sera le nom affecté à la licence et §v[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.
}

%P{§gExemple de fichier de configuration§}

FICHIER:texpng.cnf:
auteur=Jean-Michel Sarlat
licence=ljms
licence:ljms=licence.txt
§
M:text: text="texpng.cnf" html="texpng.html"
SH:rm -f texpng.html

%P{§gExemple 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&nbsp;:
<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.
§
M:text: text="licence.txt" html="licence.html"
SH:rm -f licence.html

%P{§gExemple 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>
§
M:text: text="reels.xml" html ="reels.html"
SH:rm -f reels.html
SH:mv reels.xml exemple/

%P{Ce fichier est déplacé dans le répertoire §vexemple§, le lien suivant pointe sur lui.§§
§lexemple/reels.xml§reels.xml§
}

%S{Le fonctionnement}

%P{Les fichiers étant en place, la première requête sur le §ifichier 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'§iuser§ 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 §v?rm=ok§ après le nom du fichier au niveau de la ligne d'appel du navigateur.}