%%% Copyright (C) 2020 Vincent Goulet
%%%
%%% Ce fichier fait partie du projet
%%% «Rédaction avec LaTeX»
%%% https://gitlab.com/vigou3/formation-latex-ul
%%%
%%% Cette création est mise à disposition sous licence
%%% Attribution-Partage dans les mêmes conditions 4.0
%%% International de Creative Commons.
%%% https://creativecommons.org/licenses/by-sa/4.0/

\chapter{Organisation d'un document}
\label{chap:organisation}

La maitrise des notions du chapitre précédent permet déjà de composer
un document simple avec {\LaTeX}. Toutefois, la puissance du système
de mise en page se manifeste vraiment lors de la préparation de
documents élaborés comportant plusieurs divisions internes, une table
des matières, des renvois, etc. Le présent chapitre aborde ces aspects
d'organisation d'un document.

\section{Choix d'une classe}
\label{sec:organisation:classe}

La toute première chose à faire au moment de se lancer dans la
rédaction d'un document avec {\LaTeX} consiste normalement à choisir
une classe. Nous avons déjà expliqué à la \autoref{sec:bases:classes}
comment spécifier la classe à utiliser. Cette section présente les
différences entre les classes ainsi que les principales options
disponibles.

Les classes standards sont \class{article}, \class{report},
\class{book}, \class{letter} et \class{slides}.

\begin{description}
\item[\normalfont\class{article}] Articles scientifiques et autres
  documents de longueur modérée ne nécessitant pas une mise en page
  élaborée. Le folio (numéro de page) est placé au centre du pied de
  page. Le titre apparait dans le haut de la première page,
  immédiatement suivi du texte.
\item[\normalfont\class{report}] Rapports et autres documents plus
  longs pouvant être divisés en chapitres. Le titre apparait sur une
  page de titre. La mise en page est autrement identique à celle de la
  classe \class{article}.
\item[\normalfont\class{book}] Longs documents divisés en chapitres.
  La mise en page est conçue pour une impression recto verso. L'entête
  de la page (autre que la première du chapitre) contient le folio sur
  le bord extérieur et le titre de chapitre (page paire) ou le titre
  de section (page impaire). Le titre apparait sur une page de titre.
\item[\normalfont\class{letter}] Lettres et correspondance. Bien que
  puissante, cette classe est plus rarement utilisée. Nous n'en traitons
  pas davantage dans ce document.
\item[\normalfont\class{slides}] Diapositives simples pour des
  présentations. La \autoref{sec:trucs:diapositives} traite plus en
  détail de la production de diapositives.
\end{description}

On trouvera un sommaire des principales caractéristiques des classes
\class{article}, \class{report} et \class{book} dans le
\autoref{tab:organisation:classes}. De plus, les figures
\ref{fig:organisation:classes:article}--\ref{fig:organisation:classes:book}
fournissent des exemples de mise en page pour ces trois classes.

\begin{table}
  \caption{Caractéristiques des principales classes standards}
  \label{tab:organisation:classes}
  \begin{tabularx}{1.0\linewidth}{XXXXX}
    \toprule
    Classe & Divisions & Disposition & Entête & Pied de page \\
    \midrule
    \class{article} & parties,\newline sections, \dots
                       & recto & vide & folio centré \\
    \addlinespace[6pt]
    \class{report} & parties,\newline chapitres,\newline sections, \dots
                       & recto & vide & folio centré \\
    \addlinespace[6pt]
    \class{book} & parties,\newline chapitres,\newline sections, \dots
                       & recto verso & folio, titres & vide \\
    \bottomrule
  \end{tabularx}
\end{table}

\begin{figure}
  \begin{minipage}{0.49\linewidth}
    \fbox{\includegraphics[page=1,width=0.95\linewidth]{auxdoc/exemple-classe-article}}
  \end{minipage}
  \hfill
  \begin{minipage}{0.49\linewidth}
    \fbox{\includegraphics[page=2,width=0.95\linewidth]{auxdoc/exemple-classe-article}}
  \end{minipage}
  \caption{Exemple de mise en page avec la classe \class{article}}
  \label{fig:organisation:classes:article}
\end{figure}

\begin{figure}
  \begin{minipage}{0.49\linewidth}
    \fbox{\includegraphics[page=1,width=0.95\linewidth]{auxdoc/exemple-classe-report}}
  \end{minipage}
  \hfill
  \begin{minipage}{0.49\linewidth}
    \fbox{\includegraphics[page=2,width=0.95\linewidth]{auxdoc/exemple-classe-report}}
  \end{minipage}
  \caption{Exemple de mise en page avec la classe \class{report}}
  \label{fig:organisation:classes:report}
\end{figure}

\begin{figure}
  \begin{minipage}{0.49\linewidth}
    \fbox{\includegraphics[page=1,width=0.95\linewidth]{auxdoc/exemple-classe-book}}
  \end{minipage}
  \hfill
  \begin{minipage}{0.49\linewidth}
    \fbox{\includegraphics[page=2,width=0.95\linewidth]{auxdoc/exemple-classe-book}}
  \end{minipage}
  \caption{Exemple de mise en page avec la classe \class{book}}
  \label{fig:organisation:classes:book}
\end{figure}

Cet ouvrage fait une large place à la classe \class{memoir}
\citep{memoir}, une extension de la classe standard \class{book} qui
facilite à plusieurs égards la préparation de documents d'allure
professionnelle dans {\LaTeX}. Nous recommandons d'utiliser cette
classe en lieu et place de la classe \class{book}, ou même de la
classe \class{article} (voir ci-dessous).

La classe \class{memoir} incorpore d'office plus de 30 des paquetages
les plus populaires\footnote{%
  Consulter la section~18.24 de la documentation de \class{memoir}
  pour la liste ou encore le journal de la compilation (\emph{log})
  d'un document utilisant la classe.}. %
La classe fait partie des distributions {\LaTeX} modernes; elle
devrait être installée et disponible sur tout système. Elle est livrée
avec une %
\doc{memoir}{http://texdoc.net/pkg/memoir} %
exhaustive: le manuel d'instructions fait près de 600~pages! Il peut
être utile de s'y référer de temps à autre pour réaliser une mise en
page particulière.

Les auteurs de thèses et de mémoires déposés à l'Université Laval
doivent utiliser la classe \class{ulthese}; voir l'\autoref{chap:ulthese}.

On rappelle que l'on charge une classe de document au début du
préambule avec la commande
\begin{lstlisting}
\documentclass`\oarg{options}\marg{classe}'
\end{lstlisting}
Les \meta{options} disponibles varient d'une classe à l'autre. Les
plus courantes sont les suivantes.
\begin{description}
\item[\mdseries \code{10pt}, \code{11pt}, \code{12pt}] Taille de la
  police du document en points. La valeur par défaut est \code{10pt}.
  Nous recommandons d'utiliser plutôt \code{11pt}. C'est la taille par
  défaut avec la classe \class{ulthese}.
\item[\mdseries \code{oneside}, \code{twoside}] Disposition du
  document en recto seulement ou en recto verso. Ces options ne sont
  utiles que pour modifier la disposition par défaut de la classe. Les
  thèses et mémoires de l'Université Laval sont produits en recto
  seulement.
\item[\mdseries \code{openright}, \code{openany}] Position de la
  première page des chapitres toujours à droite (page impaire) ou
  immédiatement après la dernière page du chapitre précédent. Avec la
  valeur par défaut, \code{openany}, {\LaTeX} insérera une page
  blanche dans le document si un chapitre se termine sur une page
  impaire.
\item[\mdseries \code{article} (classe \class{memoir} seulement)] Mise
  en page comme celle d'un article. Avec cette option, \class{memoir}
  peut remplacer la classe \class{article}, ce qui permet d'utiliser
  une seule et même classe pour les deux principaux types de document
  (article et livre).
\end{description}

D'autres options permettent de contrôler la position du titre, la
disposition en une ou deux colonnes, ou encore la position des
équations hors paragraphe. \citet{Thurnherr:class-options} offre une
présentation succincte des options standards. Le chapitre~1 de la %
\doc{memoir}{http://texdoc.net/pkg/memoir} %
de \class{memoir} traite en plus des ajouts propres à cette classe.



\section{Parties d'un document}

Tout document de plus de quelques pages est normalement divisé en
chapitres, sections, sous-sections, etc. Il peut comporter une ou
plusieurs annexes et débuter par un résumé, notamment s'il s'agit d'un
article scientifique. Le document est habituellement coiffé d'un
titre, mais celui-ci est parfois affiché sur une page de titre
séparée.

Toutes ces considérations relevant essentiellement de la mise en page,
{\LaTeX} s'en charge pour nous. L'auteur n'a qu'à spécifier la
strucure logique du document à l'aide des commandes de la présente
section.

\subsection{Titre et page de titre}
\label{sec:organisation:parties:titre}

{\LaTeX} rend très simple la composition du titre d'un article
scientifique ou d'une page de titre simple (classes \class{report},
\class{book}, \class{memoir}). En premier lieu, on spécifie,
habituellement dans le préambule, le titre du document, le nom du ou
des auteurs et la date de publication avec les commandes suivantes:
\begin{lstlisting}
\title`\marg{Titre du document}'
\author`\marg{Prénom Nom {\bs\bs} Affiliation {\bs\bs} Adresse}'
\date`\marg{Date ou autre texte}'
\end{lstlisting}
Un long titre sera scindé automatiquement. L'auteur peut aussi scinder
le titre manuellement en insérant la commande {\bs\bs} aux points de
coupure. %
Si l'ouvrage comporte deux auteurs ou plus, on insère les informations
dans la commande \cmd{\author} les unes après les autres en séparant
chaque entrée par la commande \cmdprint{\and}. %
La commande \cmd{\date} insère le texte donné en argument (qu'il
s'agisse d'une date ou non) à l'endroit prévu à cet effet par
{\LaTeX}. Si l'on omet la commande, {\LaTeX} insère la date du jour au
moment de la compilation. Pour ne pas afficher la date, on laisse
l'argument vide:
\begin{lstlisting}
\date{}
\end{lstlisting}

Dans les articles scientifiques, le nom d'un auteur est fréquemment
suivi d'un appel de note renvoyant à des remerciements à un organisme
subventionnaire ou à quelque autre information additionnelle sur
l'auteur. On insère une telle note et son appel à l'endroit approprié
dans les commandes \cmd{\title} ou \cmd{\author} avec la commande
\begin{lstlisting}
\thanks`\marg{Texte}'
\end{lstlisting}

Les commandes ci-dessus ne permettent que de saisir les informations
relatives au titre. Pour produire le titre il faut, en second lieu,
insérér dans le corps du document la commande
\begin{lstlisting}
\maketitle
\end{lstlisting}

\begin{exemple}
  \label{ex:organisation:titre}
  Le code ci-dessous permet de créer un titre d'article standard. La
  page composée avec {\XeLaTeX} (puisque nous utilisons le paquetage
  \pkg{fontspec}) se trouve à la \autoref{fig:organisation:titre}.
  \begin{demo}
    \lstinputlisting[lastline=19]{auxdoc/exemple-titre.tex}
  \end{demo}

  La date de publication apparaissant dans l'illustration de la
  \autoref*{fig:organisation:titre} est celle de la compilation
  puisque la commande \cmdprint{\date} n'apparait pas dans le code
  source.

  On remarquera également que nous avons placé un symbole de
  commentaire \% immédiatement après le nom de l'auteur dans le code
  source. Tel qu'expliqué à la \autoref{sec:bases:caracteres:espaces},
  c'est pour éviter que {\LaTeX} ne transforme le retour à la ligne avant
  la commande \cmd{\thanks} en une espace entre le nom et l'appel de
  note.

  (Le paquetage \pkg{lorem} utilisé dans cet exemple permet
  d'insérer du faux texte \link{https://fr.lipsum.com}{Lorem Ipsum}
  dans un document \LaTeX.)
  \begin{figure}
    \centering
    \fbox{\includegraphics[width=0.7\linewidth]{auxdoc/exemple-titre}}
    \caption{Illustration d'un titre d'article standard.}
    \label{fig:organisation:titre}
  \end{figure}
  \qed
\end{exemple}

Nous avons mentionné plus haut que {\LaTeX} peut aussi produire
automatiquement la page de titre d'un rapport ou d'un livre. Il est
toutefois peu probable qu'elle convienne, surtout dans le cas d'un
livre. Une option plus flexible existe: les environnements
\Ie{titlepage} (classes standards) et \Ie{titlingpage} (classe
\class{memoir}) permettent de définir librement une page de
titre:
\begin{demo}
  \begin{minipage}{0.48\linewidth}
\begin{lstlisting}
\begin{titlepage}
  `\meta{Texte de la page de titre}'
\end{titlepage}
\end{lstlisting}
  \end{minipage}
  \hfill
  \begin{minipage}{0.48\linewidth}
\begin{lstlisting}
\begin{titlingpage}
  `\meta{Texte de la page de titre}'
\end{titlingpage}
\end{lstlisting}
  \end{minipage}
\end{demo}
L'auteur contrôle alors entièrement la disposition et la
composition des éléments de la page de titre. Nous renvoyons le
lecteur au chapitre~4 de la %
\doc{memoir}{http://texdoc.net/pkg/memoir} %
de \class{memoir} pour une liste de bonnes pratiques en matière de
composition de page de titre et pour des exemples détaillés.

Comme c'est souvent le cas dans les universités, le format de la page
de titre des thèses et mémoires de l'Université Laval est
prédéterminé. La classe \class{ulthese} fournit donc ses propres
commandes de composition; consulter sa %
\doc{ulthese}{http://texdoc.net/pkg/ulthese}.

\subsection{Résumé}
\label{sec:organisation:parties:resume}

Les articles scientifiques et les rapports comportent souvent un
résumé, habituellement composé en retrait des marges gauche et droite
et dans une police plus petite. On produit le résumé avec
l'environnement \Ie{abstract} des classes \class{article},
\class{report} ou \class{memoir}:
\begin{lstlisting}
\begin{abstract}
  `\meta{Texte du résumé}'
\end{abstract}
\end{lstlisting}

Il est plutôt rare que les livres comportent un résumé ou alors, comme
pour les thèses et mémoires de l'Université Laval, celui-ci
est simplement traité comme un chapitre normal non numéroté.

\subsection{Sections}
\label{sec:organisation:parties:sections}

Les commandes ci-dessous servent à découper un document en sections
qui seront automatiquement numérotées par {\LaTeX} de manière
séquentielle:
\begin{lstlisting}
\part`\oarg{titre court}\marg{titre}'
\chapter`\oarg{titre court}\marg{titre}'
\section`\oarg{titre court}\marg{titre}'
\subsection`\oarg{titre court}\marg{titre}'
\subsubsection`\oarg{titre court}\marg{titre}'
\paragraph`\oarg{titre court}\marg{titre}'
\subparagraph`\oarg{titre court}\marg{titre}'
\end{lstlisting}
Les commandes forment, dans l'ordre où elles sont données, une
hiérarchie des titres d'un document\footnote{%
  Nous n'avons jamais utilisé les niveaux de division
  \cmdprint{\paragraph} et \cmdprint{\subparagraph}.}. %
Tel que mentionné précédemment, la commande \cmd{\chapter} n'est pas
disponible avec la classe \class{article}.

Chaque commande prend en argument obligatoire le \meta{titre} de la
section. Si celui-ci est très long, il peut être utile de fournir en
argument optionnel un \meta{titre court}; c'est ce dernier qui
apparaitra dans la table des matières et dans les entêtes de page, le cas
échéant.

Toutes les commandes existent en version suivie d'une \verb=*= qui
supprime la numérotation ainsi que l'insertion éventuelle dans la
table des matières (plus de détails à la \autoref{sec:organisation:tdm}).

\tipbox{Éviter d'utiliser des sous-sous-sections numérotées (commande
  \cmdprint{\subsubsection}) dans un livre. Cela résulte en une
  numérotation à quatre niveaux qui s'avère difficile à suivre pour le
  lecteur.}

\subsection{Annexes}
\label{sec:organisation:parties:annexes}

Les annexes sont des sections ou des chapitres avec une numérotation
alphanumérique (A, A.1, ...) plutôt qu'entièrement numérique. On
informe {\LaTeX} que les sections suivantes doivent être traitées
comme des annexes en insérant dans le document la commande
%% [hack ci-dessous pour cacher la commande \appendix à reftex]
\begin{lstlisting}
`\verb=\appendix='
\end{lstlisting}
En plus de modifier le style de numérotation, la commande a pour effet
de changer le mot clé «Chapitre» pour «Annexe» dans les titres de
chapitre.

\subsection{Structure logique d'un livre}
\label{sec:oganisation:parties:livre}

Un livre se compose normalement de trois grandes parties logiques: les
pages liminaires (avant-propos, table des matières, tout ce qui
précède le chapitre premier); le corps du livre (chapitres et
annexes); les parties en fin d'ouvrage (bibliographie, index). Les
commandes
\begin{lstlisting}
\frontmatter
\mainmatter
\backmatter
\end{lstlisting}
qui sont disponibles avec les classes \class{book}, \class{memoir} et
\class{ulthese}, permettent d'identifier ces trois parties. Le
\autoref{tab:organisation:livre} résume l'effet de chaque commande.

\begin{table}
  \centering
  \caption{Commandes d'identification de la structure logique d'un
    livre et leurs effets}
  \label{tab:organisation:livre}
  \begin{tabular}{ll}
    \toprule
    Commande & Effets \\
    \midrule
    \cmd{\frontmatter} & numérotation des
                              pages en chiffres romains (i, ii, ...) \\
             & chapitres non numérotés \\
    \addlinespace[0.5\normalbaselineskip]
    \cmd{\mainmatter} & numérotation des pages
                             à partir de 1 en chiffres arabes \\
             & chapitres numérotés \\
    \addlinespace[0.5\normalbaselineskip]
    \cmd{\backmatter} & numérotation des pages
                             se poursuit \\
             & chapitres non numérotés \\
    \bottomrule
  \end{tabular}
\end{table}


\section{Table des matières}
\label{sec:organisation:tdm}

Dans la mesure où l'on a bien identifié les différentes divisions d'un
ouvrage avec les commandes mentionnées à la section précédente, la
production de la table des matières est on ne peut plus simple avec
{\LaTeX}: il suffit d'insérer la commande
\begin{lstlisting}
\tableofcontents
\end{lstlisting}
dans le corps du document à l'endroit où la table des matières doit
apparaitre. C'est tout!

Lorsque le paquetage \pkg{hyperref} \citep{hyperref} est chargé, la
commande \cmdprint{\tableofcontents} produit également la table des
matières du fichier PDF. Cela permet de naviguer dans le document
directement depuis la visionneuse PDF. La
\autoref{fig:organisation:tdm-dans-pdf} illustre cette fonctionnalité
avec la visionneuse Aperçu de macOS.

\begin{figure}
  \resizebox{\textwidth}{!}{\includegraphics{images/tdm-dans-pdf}}
  \caption[Consultation d'un document PDF avec la visionneuse Aperçu
  de macOS]{%
    Consultation d'un document PDF avec la visionneuse Aperçu
    de macOS. La barre latérale de gauche affiche la table des
    matières du fichier PDF, ce qui permet de naviguer dans le
    document sans devoir revenir à celle du document.}
  \label{fig:organisation:tdm-dans-pdf}
\end{figure}

\importantbox{La production initiale de la table des matières et la
  prise en compte de toute modification requiert jusqu'à trois
  compilations consécutives du document.}

Par défaut, une section non numérotée ne figure pas dans la table des
matières. Si l'on souhaite néanmoins l'y insérer, il faut utiliser la
commande suivante:
\begin{lstlisting}
\addtocontentsline{toc}`\marg{niveau}\marg{titre}'
\end{lstlisting}
où \meta{niveau} est le nom de la commande de division sans le
caractère {\bs} (\code{chapter}, \code{section}, etc.) et \meta{titre}
est le texte qui apparaitra dans la table des matières.

\begin{exemple}
  Selon les normes de présentation visuelle de la Faculté des études
  supérieures et postdoctorales pour les thèses et mémoires de
  l'Université Laval, les résumés, la liste des abbréviations et des
  sigles, les remerciements et l'avant-propos doivent être composés
  comme des chapitres normaux non numérotés. Cependant, ils doivent
  apparaitre dans la table des matières. Pour ce faire, les gabarits
  fournis avec la classe \class{ulthese} comportent des lignes de la
  forme:
\begin{lstlisting}
\chapter*{Résumé}
\phantomsection\addcontentsline{toc}{chapter}{Résumé}
\end{lstlisting}
  La commande \cmd{\phantomsection} est rendue nécessaire (ou
  recommandée) par le paquetage \pkg{hyperref} qui est chargé dans le
  préambule. %
  \qed
\end{exemple}

Outre une table des matières, les ouvrages scientifiques
comportent parfois une liste des figures et une liste des tableaux. On
obtient celles-ci avec les commandes
\begin{lstlisting}
\listoffigures
\listoftables
\end{lstlisting}

Dans les classes \class{memoir} et \class{ulthese}, les commandes
ci-dessus insèrent leur propre titre de section dans la table des
matière (autrement dit, la table des matières apparait dans la table
des matières). Les versions
\begin{lstlisting}
\tableofcontents*
\listoffigures*
\listoftables*
\end{lstlisting}
adoptent le comportement des classes standards, soit d'omettre ces
parties dans la table des matières.


\section{Renvois automatiques}
\label{sec:organisation:renvois}

Un document d'une certaine ampleur contiendra souvent des renvois à
une section, un tableau, une équation, voire une page
spécifique. Évidemment, le numéro de la section, du tableau, de
l'équation ou de la page est susceptible de changer au fil de la
rédaction du document. C'est pourquoi l'auteur ne devrait
\emph{jamais} insérer les revois manuellement dans le texte. C'est une
tâche qu'il vaut mieux confier à l'ordinateur.

\subsection{Étiquettes et renvois}
\label{sec:organisation:renvois:etiquettes}

Les renvois automatiques dans {\LaTeX} reposent sur un système
d'étiquettes attribuées à des éléments de contenu et de référencement
par ces étiquettes. Ainsi, pour renvoyer le lecteur à un élément de
contenu, il faut d'abord le nommer en insérant la commande
\begin{lstlisting}
\label`\marg{nom}'
\end{lstlisting}
à proximité de l'élément. Le choix du \meta{nom} est tout à fait libre. Il
peut être constitué de toute combinaison de lettres, de chiffres et de
symboles autres que les symboles réservés mentionnés à la
\autoref{sec:bases:caracteres:reserves}.

Ensuite, il devient possible d'insérer un renvoi à cet élément de contenu
n'importe où dans le document avec la commande
\begin{lstlisting}
\ref`\marg{nom}'
\end{lstlisting}
Pour renvoyer à la page où se trouve l'élément, on utilise la commande
\begin{lstlisting}
\pageref`\marg{nom}'
\end{lstlisting}

\begin{exemple}
  \label{ex:organisation:renvoi}
  Le code ci-dessous permet d'insérer un renvoi automatique à un
  numéro de section dans un document. Le résultat se trouve à la
  \autoref{fig:organisation:renvoi}.
\begin{lstlisting}[emph={\label,\ref}]
\section{Définitions}
\label{sec:definitions}

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Duis in auctor dui. Vestibulum ut, placerat ac, adipiscing
vitae, felis.

\section{Historique}

Tel que vu à la section \ref{sec:definitions}, on a...
\end{lstlisting}

  \begin{figure}
    \fbox{\includegraphics[viewport=124 550 484 664,clip=true,width=0.98\linewidth]{auxdoc/exemple-renvoi}}
    \caption{Texte produit par le code de
      l'\autoref{ex:organisation:renvoi} illustrant un renvoi
      automatique standard}
    \label{fig:organisation:renvoi}
  \end{figure}
  \qed
\end{exemple}

\tipbox{Un long document contiendra vraisemblablement un grand nombre
  d'étiquettes et de renvois. Afin de s'y retrouver et pour éviter les
  doublons, adopter une manière systématique et mnémotechnique de
  nommer les éléments.

  Pour le présent document, nous avons utilisé un système d'étiquettes
  de la forme suivante:
  \begin{itemize}
  \item \cmdprint{chap:\meta{chapitre}} pour les chapitres;
  \item \cmdprint{sec:\meta{chapitre}:\meta{section}} pour
    les sections;
  \item \cmdprint{tab:\meta{chapitre}:\meta{tableau}} pour
    les tableaux;
  \item \cmdprint{eq:\meta{chapitre}:\meta{equation}} pour
    les équations.
  \end{itemize}}

\subsection{Production des renvois}
\label{sec:organisation:renvois:production}

La production des renvois requiert deux à trois compilations.
Tant que {\LaTeX} n'a pas complété les renvois, le journal de
compilation contient, vers la toute fin, le message
\begin{verbatim}
LaTeX Warning: Label(s) may have changed. Rerun to get
cross-references right.
\end{verbatim}

On prendra également garde aux alertes suivantes dans le journal de
compilation. Elles identifient des correctifs à apporter dans le
système d'étiquettes et de renvois. D'abord, le message
\begin{verbatim}
LaTeX Warning: There were undefined references.
\end{verbatim}
indique qu'une ou plusieurs commandes \cmd{\ref} renvoient à un
\meta{nom} qui n'est pas défini avec \cmd{\label}. On trouvera alors
dans le document le caractère \textbf{?} en lieu et place du renvoi. À
l'inverse, le message
\begin{verbatim}
LaTeX Warning: There were multiply-defined labels.
\end{verbatim}
indique que plusieurs commandes \cmdprint{\label} utilisent le même
\meta{nom}. Cela est susceptible de causer des renvois vers le mauvais
élément de contenu.

\subsection{Renvois avec hyperliens}
\label{sec:organisation:renvois:hyperliens}

Lorsque chargé dans le document, le paquetage \pkg{hyperref} insère
des hyperliens vers les renvois dans les fichiers PDF. C'est très
pratique en consultation électronique d'un document.

\begin{exemple}
  \label{ex:organisation:renvoi-hyperref}
  Avec l'ajout de
\begin{lstlisting}
\usepackage{hyperref}
\end{lstlisting}
  dans le préambule, le code de l'\autoref{ex:organisation:renvoi}
  produit maintenant le type de renvoi illustré à la
  \autoref{fig:organisation:renvoi-hyperref}. Le texte en couleur
  contrastante est un hyperlien vers le titre de la section.

  \begin{figure}
    \centering
    \fbox{\includegraphics[viewport=124 550 484 664,clip=true,width=0.98\linewidth]{auxdoc/exemple-renvoi-hyperref}}
    \caption{Texte produit par le code de
      l'\autoref{ex:organisation:renvoi} après l'ajout du paquetage
      \pkg{hyperref}}
    \label{fig:organisation:renvoi-hyperref}
  \end{figure}
  \qed
\end{exemple}

L'inconvénient avec la procédure illustrée dans l'exemple précédent,
c'est que seul le numéro de la référence est transformé en hyperlien.
La zone disponible pour cliquer s'en trouve plutôt restreinte. Une
fonctionnalité du paquetage \pkg{hyperref} --- à laquelle nous avons eu
recours dans le présent document --- permet d'agrandir cette zone. La
commande
\begin{lstlisting}
\autoref`\marg{nom}'
\end{lstlisting}
permet de nommer automatiquement le type de renvoi (section, équation,
tableau, etc.) et de transformer en hyperlien à la fois ce texte et le
numéro du renvoi.

\begin{exemple}
  \label{ex:organisation:renvoi-autoref}
  On reprend le texte de l'\autoref{ex:organisation:renvoi}, mais en
  utilisant cette fois la commande \cmd{\autoref} pour insérer un
  renvoi dans le texte. On remarque que le mot «section» a été
  supprimé du code source pour laisser à la commande le soin d'insérer
  le vocable approprié dans le document.
\begin{lstlisting}[emph={\label,\autoref}]
\section{Définitions}
\label{sec:definitions}

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Duis in auctor dui. Vestibulum ut, placerat ac, adipiscing
vitae, felis.

\section{Historique}

Tel que vu à la \autoref{sec:definitions}, on a...
\end{lstlisting}
  Comme on peut le voir à la
  \autoref{fig:organisation:renvoi-autoref}, le mot «section» ainsi
  que son numéro forment maintenant l'hyperlien.

  \begin{figure}
    \centering
    \fbox{\includegraphics[viewport=124 550 484 664,clip=true,width=0.98\linewidth]{auxdoc/exemple-renvoi-autoref}}
    \caption{Texte produit par le code de
      l'\autoref{ex:organisation:renvoi-autoref}}
    \label{fig:organisation:renvoi-autoref}
  \end{figure}
  \qed
\end{exemple}

La \autoref{sec:trucs:hyperliens} fournit des détails
additionnels sur la gestion des hyperliens dans un document PDF.


\section{Document contenu dans plusieurs fichiers}
\label{sec:organisation:include}

Lorsque le préambule et le corps du texte demeurent relativement
courts (peu de commandes spéciales et moins d'une vingtaine de pages
de texte), il demeure assez simple et convivial d'en faire l'édition
dans un seul fichier à l'aide de son éditeur de texte favori.

Cependant, si le préambule devient long et complexe ou, surtout,
lorsque l'ampleur du document augmente jusqu'à compter un grand nombre
de pages sur plusieurs chapitres, il convient de répartir les diverses
parties du document dans des fichiers séparés.

La segmentation en plusieurs fichiers rend l'édition du texte plus
simple et plus efficace. De plus, durant la phase de rédaction, elle
peut significativement accélérer la compilation des documents très
longs ou comptant plusieurs images.

\subsection{Insertion du contenu d'un autre fichier}
\label{sec:organisation:include:input}

La commande \cmd{\input} permet d'insérer le contenu d'un autre
fichier dans un document {\LaTeX}. La syntaxe de la commande est
\begin{lstlisting}
\input`\marg{fichier}'
\end{lstlisting}
où le nom du fichier à insérer est \meta{fichier}\code{.tex}. On
laisse donc tomber l'extension \code{.tex}, qui est implicite. Le
contenu du fichier est inséré tel quel dans le document, comme s'il
avait été saisi dans le fichier qui contient l'appel à \cmd{\input}.

Le procédé est surtout utile pour sauvegarder séparément des bouts de
code qui gênent l'édition du texte (figures, longs
tableaux) ou qui sont communs entre plusieurs documents (licence
d'utilisation, auteur et affiliation).

La commande peut aussi être utilisée dans le préambule pour charger
une partie ou l'ensemble de celui-ci. Cela permet de composer un même
préambule pour plusieurs documents. Il suffit alors de faire
d'éventuelles modifications à un seul endroit pour les voir prendre
effet dans tous les documents.

\subsection{Insertion de parties d'un document}
\label{sec:organisation:include:include}

Il est recommandé de segmenter tout document d'une certaine ampleur
dans des fichiers \verb=.tex= distincts pour chaque partie ---
habituellement un fichier par chapitre. Le document complet est
composé à l'aide d'un fichier maitre qui contient le préambule
{\LaTeX} et un ensemble d'appels à la commande \cmdprint{\include}
pour réunir les parties dans un tout.

La syntaxe de \cmd{\include} est
\begin{lstlisting}
\include`\marg{fichier}'
\end{lstlisting}
où le nom du fichier à insérer est \meta{fichier}\code{.tex}. Ici
aussi on laisse tomber l'extension \code{.tex} qui est implicite.

Comme \cmd{\input}, la commande \cmd{\include} insère le contenu d'un
autre fichier dans un document. Toutefois, l'insertion d'un fichier
avec \cmd{\include} débute toujours une nouvelle page. On utilisera
donc cette commande principalement pour insérer des chapitres entiers
plutôt que seulement des portions de texte. De plus, un fichier inséré
avec \cmd{\include} peut contenir des appels à \cmd{\input}, mais pas
à \cmd{\include}.

\begin{exemple}
  La \autoref{fig:organisation:maitre} présente un exemple type de
  fichier maitre. On y utilise la commande \cmd{\include} pour
  composer un document chapitre par chapitre.

  \begin{figure}
    \centering
    \begin{minipage}{0.75\linewidth}
\begin{lstlisting}[numbers=left, numberstyle=\tiny]
\documentclass{ulthese}
  [...]

\begin{document}

\frontmatter

\include{introduction}
\tableofcontents*

\mainmatter
\include{historique}
\include{rappels}
\include{modele}
[...]

\end{document}
\end{lstlisting}
    \end{minipage}
    \caption[Structure type d'un fichier maitre]{%
      Structure type d'un fichier maitre. Les fichiers
      \code{historique.tex}, \code{rappels.tex} et \code{modele.tex}
      contiennent le texte des trois premiers chapitres.}
    \label{fig:organisation:maitre}
  \end{figure}
  \qed
\end{exemple}

Le principal avantage de \cmd{\include} par rapport à \cmd{\input}
réside dans le fait que {\LaTeX} peut préserver entre les compilations
les informations telles que les numéros de pages, de sections ou
d'équations, ainsi que les renvois et les références bibliographiques.
Cela permet, par exemple, de compiler le texte d'un seul chapitre ---
plutôt que le document entier --- et néanmoins obtenir une image
représentative du chapitre. Procéder ainsi accélère significativement
la compilation des documents longs ou complexes.

\subsection{Compilation partielle}
\label{sec:organisation:include:compilation}

La commande \cmd{\includeonly}, que l'on utilise exclusivement dans le
préambule, sert à spécifier le ou les fichiers à compiler tout en
préservant la numérotation et les références. Sa syntaxe est
\begin{lstlisting}
\includeonly`\marg{liste\_fichiers}'
\end{lstlisting}
où \meta{liste\_fichiers} contient les noms des fichiers à
inclure dans la compilation, séparés par des virgules et sans
l'extension \code{.tex}.

\tipbox{Utiliser des noms de fichiers qui permettent de facilement
  identifier leur contenu. Par exemple, un nom comme
  \fichier{rappels.tex} identifie clairement le contenu du fichier et
  il résiste mieux aux changements à l'ordre des chapitres que
  \fichier{chapitre1.tex}.}

Lors de l'utilisation de la commande \cmd{\includeonly}, toute la
numérotation dans les fichiers \meta{liste\_fichiers} suivra celle
établie lors de la compilation précédente. Si l'édition des fichiers
de \meta{liste\_fichiers} cause des changements dans la numérotation
et les références dans les autres parties du document, une nouvelle
compilation de l'ensemble ou d'une partie de celui-ci s'avérera
nécessaire.

\begin{exemple}
  Un document est composé en plusieurs parties avec les commandes
  suivantes:
\begin{lstlisting}
\include{historique}            % chapitre 1
\include{rappels}               % chapitre 2
\include{modele}                % chapitre 3
\end{lstlisting}
  Les chapitres débutent respectivement aux pages~1, 23 et 41.
  \begin{itemize}
  \item Si l'on ajoute au préambule du document la commande
\begin{lstlisting}
\includeonly{rappels}
\end{lstlisting}
    le numéro du chapitre sera toujours 2 et le folio de
    la première page sera toujours 23, même si les 22 pages
    précédentes ne se trouvent pas dans le document.
  \item Si l'on modifie le fichier \fichier{rappels.tex} de telle
    sorte que le chapitre se termine maintenant à la page 46, il
    faudra recompiler le document avec au moins les fichiers
    \fichier{rappels.tex} et \code{modele.tex} pour que les pages du
    chapitre~3 soient numérotées à partir de 47.
  \end{itemize}
  \qed
\end{exemple}

L'\autoref{ex:include} illustre mieux le cycle typique
d'utilisation des commandes \cmd{\include} et \cmd{\includeonly}.



%%%
%%% Exercices
%%%

\section{Exercices}
\label{sec:organisation:exercices}

\Opensolutionfile{solutions}[solutions-organisation]

\begin{Filesave}{solutions}
\section*{Chapitre \ref*{chap:organisation}}
\addcontentsline{toc}{section}{Chapitre \protect\ref*{chap:organisation}}

\end{Filesave}

\begin{exercice}[nosol]
  Utiliser le fichier \fichier{exercice\_parties.tex}.
  \begin{enumerate}
  \item Étudier la structure du document dans le code source.
  \item Ajouter un titre et un auteur au document à l'aide des
    commandes \cmdprint{\title} et \cmdprint{\author} se trouvant déjà
    dans le préambule.
  \item Créer la table des matières du document en le compilant deux à
    trois fois.
  \item Insérer deux ou trois titres de sections de différents niveaux
    dans le document et recompiler.
  \item La numérotation cesse à partir des sous-sections. C'est une
    particularité de la classe \class{memoir}. Recompiler le document
    après avoir ajouté au préambule la commande
\begin{lstlisting}
\maxsecnumdepth{subsection}
\end{lstlisting}
  \item Ajouter une annexe au document.
  \end{enumerate}
\end{exercice}

\begin{exercice}[nosol]
  Utiliser le fichier \fichier{exercice\_renvois.tex}.
  \begin{enumerate}
  \item Insérer dans le texte un renvoi au numéro d'une section.
  \item Activer le paquetage \pkg{hyperref} avec l'option
    \code{colorlinks} et comparer l'effet d'utiliser \cmd{\ref} ou
    \cmd{\autoref} pour le renvoi.
  \end{enumerate}
\end{exercice}

\begin{exercice}[nosol]
  \label{ex:include}
  Cet exercice fait appel au fichier maitre
  \fichier{exercice\_include.tex} et à plusieurs fichiers auxiliaires.
  Schématiquement, le document est composé ainsi:

  \medskip
  \begin{minipage}{\linewidth}
    \dirtree{%
      .1 exercice\_include.tex.
      .2 {\textbackslash}input pagetitre.tex.
      .2 {\textbackslash}include rpresentation.tex.
      .3 {\textbackslash}includegraphics console-screenshot.pdf.
      .2 {\textbackslash}include emacs.tex.
    }
  \end{minipage}
  \medskip

  La commande \cmd{\includegraphics} permet d'insérer une image dans
  un document {\LaTeX}. Elle provient du paquetage \pkg{graphicx}.

  \begin{enumerate}
  \item Étudier le code source du fichier maitre, puis le compiler
    deux à trois fois jusqu'à ce que tous les renvois soient à jour.
    Il est normal à ce stade que la figure~1 du document soit vide.
  \item Ajouter dans le préambule du fichier maitre la commande
\begin{lstlisting}
\includeonly{emacs}
\end{lstlisting}
    puis compiler le document.

    Observer que, malgré l'absence du chapitre~1, la numérotation et
    les références demeurent à jour, notamment la table des matières.
  \item Remplacer la commande ajoutée en b) dans le préambule du
    fichier maitre par la commande
\begin{lstlisting}
\includeonly{rpresentation}
\end{lstlisting}
    Vers la fin du fichier \fichier{rpresentation.tex}, activer la
    commande
\begin{lstlisting}
\includegraphics[width=\textwidth]{console-screenshot}
\end{lstlisting}
    en supprimant le symbole \% au début de la ligne. Compiler de
    nouveau le document deux fois.

    Les modifications ont eu pour effet d'ajouter une page au
    chapitre~1. Observer que, selon la table des matières, le
    chapitre~2 débute toujours à la page~3 alors que celle-ci est
    maintenant occupée par la figure~1.
  \item Afin de corriger la table des matières, désactiver dans le
    préambule du fichier maitre la commande \cmd{\includeonly}, puis
    compiler de nouveau le document quelques fois.
  \end{enumerate}
\end{exercice}

\begin{exercice}[nosol]
  Déplacer dans un fichier \fichier{preambule.tex} toutes les lignes
  du préambule du fichier \fichier{exercice\_include.tex} utilisé à
  l'exercice précédent, à l'exception de celles relatives à la page
  titre (titre, auteur, date). Insérer le préambule dans
  \fichier{exercice\_include.tex} avec la commande \cmd{\input}.
\end{exercice}

\Closesolutionfile{solutions}

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "formation-latex-ul"
%%% TeX-engine: xetex
%%% coding: utf-8
%%% End: