24.2 \include & \includeonly

Synopsis :

\includeonly{  % dans le préambule du document
  ...
  nomfichier,
  ...
  }
  ...
\include{nomfichier}  % dans le corps du document

Apporte de la matière d’un fichier externe nomfichier.tex dans un document LaTeX.

La commande \include fait trois choses : elle exécute \clearpage (voir \clearpage & \cleardoublepage), puis elle insère la matière à partir du fichier nomfichier.tex dans le document, ensuite fait encore un \clearpage. Cette commande ne peut apparaître que dans le corps du document.

La commande \includeonly contrôle quels fichiers seront lus par LaTeX lors des commandes \include suivantes. Sa liste de noms de fichier est séparée par des virgules, et la commande ne peut apparaître que dans le préambule, ou même plus tôt, par ex. dans la ligne de commande : elle ne peut pas apparaître dans le corps du document.

Dans le document racine en exemple ci-dessous, constitution.tex, on inclut trois fichiers, preambule.tex, articles.tex, et amendements.tex.

\documentclass{book}
\includeonly{
  preambule,
  articles,
  amendements
  }
\begin{document}
\include{preambule}
\include{articles}
\include{amendements}
\end{document}

Le fichier preambule.tex ne contient aucun code spécial ; vous avez juste extrait ce chapitre de consitution.tex pour le mettre dans un fichier séparé pour rendre son édition plus commode.

\chapter{Préambule}
Le peuple français proclame solennellement son attachement aux Droits de
l’Homme et aux principes de la souveraineté nationale tels qu’ils ont
été définis par la Déclaration de 1789, ...

Exécuter LaTeX sur constitution.tex fait apparaître la matière issue de ces trois fichiers dans le document mais génère également les fichiers auxiliaires preambule.aux, articles.aux, et amendements.aux. Ceux-ci contiennent de l’information telle que les numéros de page et les renvois (voir Cross references). Si maintenant vous mettez en commentaire les lignes de \includeonly contenant preambule et amendements et exécutez LaTeX de nouveau alors le document résultant ne contiendra que la matière issue de articles.tex, mais pas celui de preamblue.tex ni de amendements.tex. Néanmoins, la totalité de l’information auxiliaire issue des fichiers omis est toujours là, y compris le numéro de la page où commence le chapitre.

S’il n’y a pas de \includeonly dans le préambule du document, alors LaTeX inclut tous les fichiers demandés par des commandes \include.

La commande \include fabrique une nouvelle page. Pour éviter cela, voir \input (ce qui, cependant, ne retient pas l’information auxiliaire).

Voir Larger book template, pour un autre exemple utilisant \include et \includeonly. Cet exemple utilise également \input pour certaine matière qui ne débute pas nécessairement sur une nouvelle page.

Les noms de fichiers peuvent impliquer un chemin.

\documentclass{book}
\includeonly{
  chapitres/chap1,
  }
\begin{document}
\include{chapitres/chap1}
\end{document}

Pour rendre votre document portable vis à vis des diverses distributions et plateformes vous devriez éviter les espaces dans les noms de fichier. Traditionnellement on utilise des tirets de 6 ou de 8 à la place. Néanmoins, pour le nom ‘amo amas amat’, ce qui suit fonctionne sous TeX Live sur GNU/Linux:

\documentclass{book}
\includeonly{
  "amo\space amas\space amat"
  }
\begin{document}
\include{"amo\space amas\space amat"}
\end{document}

et ceci fonctionne sous MiKTeX sur Windows:

\documentclass{book}
\includeonly{
  {"amo amas amat"}
  }
\begin{document}
\include{{"amo amas amat"}}
\end{document}

Vous ne pouvez pas utiliser \include au sein d’un fichier qui lui-même est inclus via \include, sans quoi vous obtenez l’erreur ‘LaTeX Error: \include cannot be nested’. La commande \include ne peut pas apparaître dans le préambule ; sans quoi vous obtenez l’erreur ‘LaTeX Error: Missing \begin{document}’.

Si un fichier que vous incluez par \include n’existe pas, par exemple si vous tapez la commande \include{athiesme} par erreur à la place de \include{atheisme}, alors LaTeX ne produit pas une erreur mais un avertissement ‘No file athiesme.tex.’ (Il crée également le fichier athiesme.aux).

Si vous faites un \include du fichier racine dans lui-même alors vous obtenez tout d’abord ‘LaTeX Error: Can be used only in preamble’. Les exécutions suivantes donnent ‘TeX capacity exceeded, sorry [text input levels=15]’. Pour réparer cela, vous devez enlever l’inclusion \include{racine} mais aussi détruire le fichier racine.aux et exécuter de nouveau LaTeX.