Structuration d'un document

Liminaire

L'idée principale de la structuration d'un document complexe se résume en deux points :

• découpage du source en petits fichiers
• formatage du document final dans un dossier à part.

Le premier point est important pour aider le travail collaboratif (risque de conflit moindre), simplifier le travail du gestionnaire de code source (subversion...). L'ensemble des fichiers peuvent être distribués dans des sous dossiers ou positionné en vrac. Tout dépend de leur nombre et de la manière de chacun.

Cependant, le nom de chaque fichier doit être unique. En effet, lors du formatage dans un dossier temporaire, des fichiers temporaires mis en vrac soit créés, aucune arborescence correspondant à l'arborescence initiale est reconstruite. C'est à la fois plus simple à faire et avoir deux fichiers ayant le même nom est toujours une très mauvaise idée en programmation et finit toujours un jour ou l'autre par poser de gros soucis.

Par ailleurs, il est fondamental lorsqu'on travaille sur un gros projet de séparer le code source, gérer par un gestionnaire de code source, des fichiers temporaires ainsi que des fichiers finaux. Ainsi, seul les fichiers sources sont importants à sauver, à archiver, à transmettre...

Par défaut, les compilateurs travaillent dans le dossier courant. LaTeX ne fait pas exception. Ce comportement, réaliste pour des petits projets, présente trop de risque pour les gros projets. Ainsi, avec un paramétrage adéquate, le code source peut être mis en lecture seule lors du formatage. Il y a de nombreuse manière de faire cela et dans la solution proposée, un simple changement des droits sur les fichiers assure une protection efficace. Cependant, celle-ci est facultative...

Arborescence

Il est hors de question que l'utilisateur se souvienne de commande complexe et effectue des manipulations fastidieuses, répétitives donc avec des risques d'erreurs importants.

Un très bon outil fait cela depuis des années : make. Un Makefile est donc proposé qui se charge de tout le travail. Pour que celui-ci fonctionne, il faut que la structure du projet soit la suivante :

/chemin/du/projet/src/code/source

Le code source doit être dans un sous dossier d'un dossier src. Il peut y avoir autant de sous dossier que l'on souhaite. Le document peut être dans un sous dossier /tex/ par exemple, mais celui-ci doit être placer sous le dossier /src/.

Il ne doit y avoir qu'un seul dossier /src/ dans le chemin global. Un sous dossier ne peut donc prendre le nom de /src/. C'est voulu car faire cela est une mauvaise idée.

Le Makefile crée alors deux dossiers ou il placera ses fichiers :

• /chemin/du/projet/tmp : dossier temporaire qui sers de cache à toutes les étapes intermédiaires ;
• /chemin/du/projet/doc : dossier où seront placés les documents finis.

On remarque que tous ces fichiers sont placés dans des sous dossiers qui sont au même niveau que le dossier /src/. C'est une bonne manière de procéder.

Makefile

La commande make interprète par défaut le fichier Makefile du dossier courant. Ce programme est un moteur d'inférence qui applique les règles selon les contraintes les liants. Il faut savoir qu'il y a une règle de base implicite qui se base sur la date de chaque fichier. Ainsi, la modification d'un fichier, d'une figure... entraîne la reconstruction du document final mais aussi des figures intermédiaires si nécessaire...

Cependant, la compilation d'un document TeX peut être long. Il faut compiler plusieurs fois,lancer le gestionnaire de bibliographie BibTeX, recompiler... Il est le plus souvent inutile de refaire tous ses étapes pour le moindre changement, il y a donc dans le Makefile des cibles pour gagner du temps et ne faire que des compilations partielles.

Attention cependant pour la version finale de bien compiler suffisamment ! Il y un cible touch qui modifie la date du document principal et permet de relancer la compilation de celui-ci par make même sans modification de celui-ci (make fonctionne par défaut sur la date des fichiers et non sur un système de checksum type md5sum).

Après cette longue introduction, voici les cibles utiles (make help):

• all -> compilation complète
• dossier -> création des dossiers du projet
• clean -> nettoyage partiel
• pdf -> compilation simple avec dépendance -> pdf
• dvi -> compilation simple avec dépendance -> dvi
• xpdf -> visualisation du résultat pdf
• xdvi -> visualisation du résultat dvi
• gv -> visualisation du résultat ps
• warning -> liste de tous les warnings
• review -> liste de toutes les remarques
• pdflatex -> compilation du source tex -> pdf
• latex -> compilation du source tex -> dvi
• bibtex -> compilation du source bibtex
• protect -> protection du dossier source
• unprotect -> suppression de la protection

Ce Makefile a été conçu il y de nombreuses années (début 2000). De nombreux logiciels sont apparus ou ont subis de fortes modifications et une mise à jour de celui-ci peut s'avérer nécessaire dans le détail.

De nos jours, on n'utilise quasiment plus latex sauf dans des cas spécifiques. Le plus souvent, on compile directement avec pdflatex. Les cibles les plus utiles au début sont donc pdflatex et xpdf. On se place donc dans le dossier src contenant le Makefile, il suffit alors de faire

make pdflatex
make xpdf

La cible review est particulière puisque lié au paquetage review décrit sur ce même site.

Configuration

Il faut préciser dans le Makefile dans quel dossier LaTeX va trouver les fichiers sources ainsi que les figures. Afin d'éviter de modifier ce fichier, on peut créer un fichier config.mk qui sera chargé s'il existe par le makefile principal.

Par défaut, LaTeX va rechercher ses petits dans le seul dossier courant. Pour ajouter des sous dossiers, par exemple Figure et Partie_n, créer puis mettre dans le fichier config.mk les lignes suivantes :

ARBO_FIG += Figures

ARBO_TEX += Introduction
ARBO_TEX += Partie_1
ARBO_TEX += Partie_2
ARBO_TEX += Conclusion

Le fichier principal est donné par la variable DOCUMENT ayant par défaut la valeur document. Elle est aussi modifiable dans le config.mk, par exemple si votre document principal s'appelle these.tex :

DOCUMENT := these

D'autres variables peuvent être surchargés dans ce fichier, il suffit d'éditer le Makefile pour en comprendre facilement le sens.

Téléchargemet

La dernière version du ​Makefile est accessible directement :

wget http://servforge.legi.grenoble-inp.fr/svn/soft-latex-review/trunk/Makefile