Conventions de codage

Liste des conventions de style

Ces conventions évolueront avec le temps, mais le fait d’en fixer dès maintenant quelques-unes devrait favoriser un style LaTeX uniforme. Nous appellerons « code¹ » le contenu des fichiers sources.

Dans tous les fichiers tex, limitez chaque ligne à 80 caractères.
N’indentez pas les fichiers tex. Servez-vous plutôt de la coloration syntaxique de votre éditeur pour repérer les environnements, entre autres.
Utilisez
```
\medskip\noindent
```
pour commencer un nouveau paragraphe, et
```
\noindent
```
pour commencer un nouveau paragraphe juste après un environnement.
Évitez, si possible, de répartir le code des formules mathématiques sur plusieurs lignes. Si le code complet, signes dollar englobants compris, ne tient pas sur une ligne, placez le premier signe dollar au tout début de la ligne suivante. S’il ne tient toujours pas, coupez le code à un endroit mathématiquement naturel.
Codez comme suit les formules mathématiques hors texte :
```
$$
...
...
$$
```
Autrement dit, ouvrez par deux signes dollar seuls sur une ligne, et fermez de la même manière.
N’utilisez aucune macro. En voici la raison : le fichier tex est ainsi plus facile à lire, et l’on peut commencer à en modifier n’importe quelle partie sans devoir apprendre d’innombrables macros. Cela ne rend pas non plus la saisie plus difficile ni plus longue. L’inconvénient est bien sûr qu’un même objet mathématique peut être composé différemment en TeX à différents endroits du texte, mais cela devrait se repérer facilement.
Les environnements d’énoncés que nous utilisons sont : « theorem », « proposition », « lemma » (style plain), « definition », « example », « exercise », « situation » (style definition), « remark », « remarks » (style remark). Il existe bien sûr aussi un environnement « proof ».
Codez comme suit un environnement « foo » :
```
\begin{foo}
...
...
\end{foo}
```
de même que pour les formules mathématiques hors texte.
Au lieu d’un environnement « corollary », employez simplement l’environnement « lemma », puisque le résultat servira vraisemblablement de toute façon à démontrer le théorème plus important qui suit.
Chaque lemme, proposition ou théorème doit être immédiatement suivi de sa démonstration. Évitez les démonstrations imbriquées.

Les fichiers preamble.tex, chapters.tex et fdl.tex sont des fichiers tex particuliers. Mis à part ceux-ci, chaque fichier tex a la structure suivante :

\input{preamble}
\begin{document}
\title{Title}
\maketitle
\tableofcontents
...
...
\input{chapters}
\bibliography{my}
\bibliographystyle{amsalpha}
\end{document}

Essayez d’ajouter des étiquettes aux lemmes, propositions et théorèmes, ainsi qu’aux remarques, exercices et autres environnements. Pour étiqueter un lemme, utilisez par exemple
```
\begin{lemma}
\label{lemma-bar}
...
\end{lemma}
```
et procédez de même pour tous les autres environnements. Autrement dit, l’étiquette d’un environnement nommé « foo » commence par « foo- ». En outre, toutes les étiquettes doivent être constituées uniquement de lettres minuscules, de chiffres et du symbole « - ».
Ne renvoyez jamais au « lemme ci-dessus » (ni à la proposition ci-dessus, etc.). Utilisez plutôt :
```
Lemma \ref{lemma-bar} above
```
Ainsi, déplacer ultérieurement des lemmes ne pose pour ainsi dire aucun problème.
Renvois entre fichiers. Pour renvoyer à un lemme d’étiquette « lemma-bar » dans le fichier foo.tex, dont le titre est « Foo », utilisez le code suivant :
```
Foo, Lemma \ref{foo-lemma-bar}
```
Si cela ne fonctionne pas, consultez le fichier preamble.tex afin d’y trouver la syntaxe correcte. Le fichier de sortie contiendra alors « Foo, lemme $<$link$>$ » : il sera donc clair que le lien pointe vers un autre fichier.
Dans les environnements de démonstration, évitez autant que possible les renvois à des résultats ultérieurs. (On devrait pouvoir écrire un test automatique à cette fin.)
Ne commencez aucune phrase par un symbole mathématique.
N’écrivez pas une phrase du type « Cela résulte de ce qui suit » juste avant un lemme, une proposition ou un théorème. Chaque phrase se termine par un point.
Énoncez toutes les hypothèses dans chaque lemme, proposition et théorème. Le lecteur peut ainsi déterminer plus facilement si un lemme, une proposition ou un théorème donné s’applique à son problème particulier.
Faites des démonstrations courtes : moins d’une page dans le PDF ou le DVI. On peut toujours y parvenir en scindant la démonstration en lemmes, entre autres.
Pour une propriété définie appelée foobar, utilisez
```
{\it foobar}
```
dans le code à l’intérieur de l’environnement de définition. Procédez de même si la définition figure dans le corps du document. Le lecteur repérera ainsi plus facilement ce qui est défini.
Placez dans son propre environnement de définition toute définition qui sera utilisée hors de la section où elle apparaît. Les définitions temporaires peuvent être données dans le texte. Les constructions mathématiques constituent un cas délicat : elles tiennent souvent lieu de définitions faisant intervenir plusieurs lemmes liés. Une bonne solution consiste peut-être à leur consacrer une courte section, afin que les utilisateurs puissent renvoyer à celle-ci plutôt qu’à une définition.
Ne numérotez les équations que si elles font effectivement l’objet d’un renvoi dans le texte. Nous pourrons toujours ajouter des étiquettes plus tard.
Dans les énoncés des lemmes, propositions et théorèmes, ainsi que dans les démonstrations, faites des phrases courtes. Par exemple, au lieu d’écrire « Soit $R$ un anneau et soit $M$ un $R$-module. », écrivez « Soit $R$ un anneau. Soit $M$ un $R$-module. ». En voici la raison : les parties plus délicates des démonstrations et des énoncés sont ainsi plus faciles à analyser.
Utilisez la commande
```
\section
```
pour créer des sections, mais essayez d’éviter les sous-sections et les sous-sous-sections.
Évitez les constructions LaTeX complexes.

Tout est la faute de Knuth. Voir [Knuth].↩︎