\chapter{Documents scientifiques}
\label{chap-science}
\begin{epigraphe}{Les proverbes Pr \textbf{10} 14}
  Les sages thésaurisent la science\\
  mais la bouche du fou\\
  est un danger permanent.
\end{epigraphe}

\begin{introchap}{Voici} venu le moment de vous parler des quelques
caractéristiques des documents dits \emph{scientifiques}. Si le
problème des formules et autres équations a été abordé avec brio au
chapitre~\ref{chap-maths}, il reste tout de même un gros morceau à
avaler : la bibliographie. Sachez quand même que si
l'ingurgitation peut être difficile, la suite vous permettra de vous
simplifier grandement le travail. Nous profiterons également de ce
chapitre pour expliquer le principe de la génération d'index.

Nous vous parlerons donc des quelques particularités de la rédaction
d'ar\-ticle, ensuite viendra un exposé sur la génération d'une
bibliographie, la génération d'index, enfin la méthode utile à
connaître pour diviser un gros document en petites parties.
\end{introchap}

\section{Article}
\index{article!rédaction}
Pour rédiger un article, rien de bien nouveau, tout ce qui a été vu
jusqu'ici s'applique. On notera juste l'utilisation dans le préambule,
des commandes :
\begin{itemize}
\item \ltxcom{title} pour définir le titre,
\item \ltxcom{date} pour définir la date,
\item \ltxcom{author} pour définir les auteurs,
\item \ltxcom{thanks} pour spécifier l'affiliation des auteurs.
\end{itemize}
Pour insérer le titre à partir de ces définitions, il est nécessaire
d'ajouter la commande \ltxcom{maketitle} \textbf{après} le
\verb+\begin{document}+ : \small
\begin{ltxcode}
  \documentclass{article}
  \title{Le seuillage à 128 : une révolution !}
  \author{M. C. Orlanrien\\
          Institut du Pixel\\
          42007 Saint-Etienne---FRANCE}
  \date{2 Avril 1927}

  \begin{document}
  \maketitle%  c'est ici qu'est inséré le titre
  ø\normalfont...ø
  \end{document}
\end{ltxcode}
\index{titre!d'un document} \normalsize Nous répétons\footnote{Parce
  qu'il paraît qu'enseigner c'est répéter} :  c'est la commande
\ltxcom{maketitle} qui génère et insère le titre et non les
définitions du préambule.

\index{article!style} En règle générale, les conférences ou revues qui
fournissent un fichier de style, proposent quelques variantes, par
exemple une commande \ltxcom{address} pour séparer les auteurs et leur
adresse respective, etc.  Mais l'idée de base reste la même.
% La commande \thanks est disponible dans la classe article...

\section{Bibliographie}

Il existe deux manières de rédiger une bibliographie avec \LaTeX{} :
l'une que l'on peut qualifier de « manuelle » consiste à insérer un
environnement \ltxenv{thebibliography} dans le document, l'autre que
nous allons décrire ici, utilise le programme \BibTeX{}. Voici le
principe :
\begin{enumerate}
\item on crée un ou plusieurs fichiers de données contenant une
  description de chaque entrée de bibliographie (article,
  conférence,...) au format \BibTeX{}. C'est l'inévitable tâche de
  \emph{saisie},
\item dans le document, on fait référence aux entrées par la commande
  \ltxcom{cite},
\item la bibliographie sera mise en page automatiquement selon un style
  particulier que vous choisirez.
\end{enumerate}

L'avantage de cette méthode est que vous saisissez une fois pour toute
les entrées de votre bibliographie. De plus, vous n'avez pas à vous
soucier de sa mise en page, dans la mesure où vous utilisez des
\emph{fichiers de style} ; il en existe plusieurs dizaines
correspondant à toutes sortes de standards, revues et autres
conférences. On trouve aussi sur internet beaucoup de bases de données
bibliographiques au format \BibTeX{} que l'on peut utiliser
directement dans ses documents.
\index{bibliographie!style}

Nous répétons qu'il existe des standards en matière de bibliographie,
mais que malheureusement certaines  revues prennent un malin plaisir
à pondre leur propre style de bibliographie. Le jour où vous publierez
dans ce genre de revue, vous aurez à créer ou adapter un fichier de
style. Pour ce faire, cherchez du coté de l'utilitaire \soft{makebst}.


\subsection{Fichier {\mdseries\ttfamily .bib}}

\index{bibliographie!saisie} \index{fichier!\texttt{.bib}} La première
opération est de constituer\footnote{Le module \AucTeX{}
  d'\soft{Emacs} possède un mode \BibTeX{} très pratique.} le fichier
de bibliographie qui doit de préférence porter l'extension
\texttt{.bib}.  Ce fichier doit suivre une syntaxe particulière.  Tout
d'abord, il faut savoir que \BibTeX{} distingue chaque entrée par son
\emph{type}.  Ainsi, chaque entrée correspond à un type de document :
livre, article, conférence, rapport technique,... En tout plus d'une
douzaine de types de document différents.
\begin{note}
  Accompagnant les distributions \LaTeX{}, on trouve normalement un
  fichier nommé \BibTeX ing (sous le nom
  \texttt{btxdoc.pdf}) écrit par Oran \bsc{Patashnik} il y a une
  vingtaine d'années et contenant une source importante d'information
  sur la manière de constuire un fichier au format \BibTeX.
\end{note}
Chaque \emph{type} d'entrée contient à son tour un certain nombre de
\emph{champs} dé\-cri\-vant l'entrée. La structure d'une entrée de bibliographie
est la suivante : 
\begin{monverbatim}
  @¢marg«entree»{¢marg«clef»,
    ¢marg[1]«champ» = {...},
    ¢marg[2]«champ» = {...},
    ...
    ¢marg[n]«champ» = {...}
    }
\end{monverbatim}
où \marg{entree} est le type de document (\texttt{article},
\texttt{inproceedings},...) et \marg[1]{champ},
\marg[2]{champ}, ..., \marg[n]{champ} sont les différents champs de
l'entrée de bibliographie. Ces différents mots réservés de \BibTeX{}
peuvent être saisis en majuscules ou en minuscules.

Le symbole \marg{clef} doit identifier le document de manière
univoque. Ce symbole est à rapprocher du symbole identifiant une
étiquette avec \ltxcom{label}. Pour vous permettre de commencer à
utiliser rapidement \BibTeX{} nous vous donnons, ici, un exemple pour
les trois principales entrées que vous serez amené à utiliser :

\subsubsection{Article dans une revue}
\index{bibliographie!article}
Un article dans une revue doit être saisi comme suit : 
\small
\begin{verbatim}
  @article{qtz:UchArb,
    author ={Uchiyama, Toshio and Arbib, Michael A.},
    title = {Color Image Segmentation 
             Using Competitive Learning},
    journal=pami,
    volume =16, number=2, pages={1197--1206},
    month=dec, year=1994}
\end{verbatim}
%D Euh, il est conseillé de ne pas mélanger les "..." et les {...}
\normalsize
Notez que :
\begin{enumerate}
\item les champs \texttt{author}, \texttt{title}, \texttt{journal},
  \texttt{year} sont obligatoires ;
\item pour les auteurs\footnote{Ces remarques concernant les auteurs
    sont valables pour les autres entrées (conférences, livres, etc.)}
  il est impératif de suivre l'ordre \marg{nom}, \marg{prénom} et de
  séparer \textbf{tous} les auteurs par \texttt{and} ;
%D     (cf. http://www.lsv.ens-cachan.fr/~markey/BibTeX/doc/ttb_en.pdf) ou
%D --> bien notre bouquin, à Jean-Côme et moi...
\item pour les auteurs ayant un nom composé ou à particule, on saisira :
\begin{verbatim}
     author="de la Motte Beuvron, Alain"
\end{verbatim}
  donc en respectant l'ordre \marg{particule}, \marg{nom},
  \marg{prenom} et en utilisant la virgule en guise de séparateur
  comme indiqué ci-dessus ;
\item tous les mois de l'année peuvent être produits grâce aux chaînes
  : \texttt{jan}, \texttt{feb}, \texttt{mar}, etc.
\end{enumerate}
Nous avons créé par commodité l'\emph{abréviation} \texttt{pami}
qui est définie au début de notre fichier \texttt{.bib} par : 
\small
\begin{verbatim}
  @string{pami="IEEE transactions on Pattern Analysis and 
                Machine Intelligence"}
\end{verbatim}
\normalsize 


\subsubsection{Article dans une conférence}
\index{bibliographie!conférence}
Eh oui, \BibTeX{} distingue un article dans une \emph{revue}, et un
article dans une \emph{conférence}. La structure est sensiblement la
même, si ce n'est qu'on utilise le champ \texttt{booktitle} pour le
titre de la conférence, à la place du titre de la revue : \small
\begin{verbatim}
  @Inproceedings{qtz:BouOrch,
    author={Bouman, Charles A. and Orchard, Michael T.}
    title={Color Image Display with a Limited Palette Size},
    booktitle={SPIE Conference on Visual Communications
               and Image Processing},
    volume=1199,pages={522--533},
    year=1989}
\end{verbatim}
\normalsize Ici les champs \texttt{author}, \texttt{title},
\texttt{booktitle}, \texttt{year} sont obligatoires, et l'on doit
choisir entre \texttt{volume} et \texttt{number}.
%@

\subsubsection{Un extrait de livre}
\index{bibliographie!livre}
On cite souvent un extrait---chapitre(s), ou page(s)---d'un livre
plutôt que le livre lui-même : 
\small
\begin{verbatim}
  @inBook{col:McA,
    author =    {MacAdam, David L.},
    title =     {Color Measurement},
    chapter =   4,
    pages   = {48--49},
    publisher = {Springer-Verlag},
    year =      1985}
\end{verbatim}
\normalsize Sont obligatoires : \texttt{author}, \texttt{title},
\texttt{chapter} ou \texttt{pages}, \texttt{publisher} (l'éditeur)
et \texttt{year}.
\begin{note} 
  Encore une fois nous ne saurons trop vous conseiller d'exploiter le
  mode \BibTeX{} du module \AucTeX{} d'\soft{Emacs}. Ce mode vous
  propose notamment un menu contenant tous les types d'entrée. La
  sélection d'un item de ce menu insère un « squelette » d'entrée dans
  votre fichier \texttt{.bib}\index{fichier!\texttt{.bib}}. Ce module
  est téléchargeable à
  \url{ftp://ftp.lip6.fr/pub/TeX/CTAN/support/auctex} et également
  disponible sous la forme d'un paquet Debian.
\end{note}

\subsection{Citation}
\index{citations}
\index{bibliographie!citations}
Une fois le (ou les) fichier(s) de bibliographie constitué(s), on peut
faire référence aux entrées par l'intermédiaire des clefs, avec la
commande \ltxcom{cite} :
\begin{ltxcode}
  \cite{ø\marg{clef}ø}
\end{ltxcode}
La commande \ltxcom{cite} a pour effet :
\begin{enumerate}
\item d'insérer un renvoi dont la forme dépend du style choisi ([2],
  [Loz95],...),
\item d'ajouter l'article cité dans la bibliographie de votre
  document.
\end{enumerate}
\begin{nota}
  Un article---au sens large du terme---n'apparaît dans la
  bibliographie que s'il fait l'objet d'une commande \ltxcom{cite}.
  Pour qu'un article apparaisse sans pour autant être cité, il faut
  utiliser la commande \ltxcom{nocite}\verb+{+\marg{clef}\verb+}+.
  L'article référencé par \marg{clef} sera alors inséré dans la
  bibliographie. Par ailleurs, la commande \ltxcom{nocite}\verb+{*}+
  insère \emph{toutes} les entrées de votre fichier de biblio.
\end{nota}

Avant de passer à l'étape de génération proprement dite, il est
nécessaire d'insérer à la fin du document \LaTeX{} un appel à la
commande :
\begin{flushleft}
  \ltxcom{bibliographystyle}
\end{flushleft}
pour stipuler un style de bibliographie, puis un appel à la commande :
\begin{flushleft}
  \ltxcom{bibliography}
\end{flushleft}
pour insérer effectivement la bibliographie. Pour le style :
\begin{ltxcode}
  \bibliographystyle{ø\marg{style}ø}
\end{ltxcode}
Les trois \marg{style}s prédéfinis\footnote{Cherchez sur les sites
  CTAN, dans le répertoire \texttt{biblio/bibtex/contrib} il y a
  plusieurs dizaines d'autres styles disponibles.} de \LaTeX{} sont :
\begin{itemize}
\item \texttt{plain} les citations sont sous la forme [2], et la
  bibliographie est  classée par auteur,
\item \texttt{unsrt} idem mais pas de tri, les documents apparaissent
  dans l'ordre où ils sont cités ; très utilisé pour les actes de
  conférences.
\item \texttt{alpha} les citations sont sous la forme « auteurs abrégés +
  année ».
\index{bibliographie!style!\texttt{plain}}
\index{bibliographie!style!\texttt{unsrt}}
\index{bibliographie!style!\texttt{alpha}}
\end{itemize}
Il faut ensuite spécifier quels sont les fichiers contenant les
informations bibliographiques sur lesquelles « pointent » les
commandes \ltxcom{cite} de votre document :
\begin{ltxcode}
  \bibliography{ø\marg{fichier1,fichier2,...}ø}
\end{ltxcode}
indiquera à \BibTeX{} d'inclure 
\texttt{fichier1.bib}, \texttt{fichier2.bib},... lors de son
traitement.
\index{fichier!\texttt{.bib}}

\subsection{Génération}

Pour générer la bibliographie :
\begin{enumerate}
\item effectuer une première compilation avec \LaTeX{} pour que le
  fichier auxiliaire \texttt{doc.aux} contienne les informations de
  \emph{citations} :
\begin{center}
  \includepsfraggraphics{bibtex1}
\end{center}
\item lancer \BibTeX{} pour générer la bibliographie dans le fichier
  \texttt{doc.bbl} :
  \begin{unixcom}
    bibtex doc
  \end{unixcom}
\begin{center}
  \includepsfraggraphics{bibtex2}
\end{center}

\item effectuer une deuxième compilation avec \LaTeX{} pour
  insérer la bibliographie :
\begin{center}
  \includepsfraggraphics{bibtex3}
\end{center}
\item résoudre les références croisées par une troisième compilation.
\end{enumerate}

\index{fichier!\texttt{.bbl}}
\index{fichier!\texttt{.blg}}
Si vous êtes curieux, vous verrez que le fichier \texttt{doc.bbl}
contient un environnement \ltxenv{thebibliography} prêt à
l'emploi\footnote{C'est-à-dire celui que vous auriez dû vous palucher
  si vous n'utilisiez pas \BibTeX{}.} et que le fichier \texttt{doc.blg}
est l'équivalent du \texttt{.log} : un fichier « log » contenant les
éventuelles erreurs ou warnings de la dernière utilisation de
\BibTeX{}.

\begin{nota}
  Le programme \soft{Bib\TeX} est sensible à la variable
  d'environnment \texttt{BIBINPUTS}. Il peut donc parfois être
  nécessaire d'ajouter la ligne :
  \index{bibinputs@\texttt{BIBINPUTS}!variable d'environnement}
  \index{variable d'environnement!\texttt{BIBINPUTS}}
\begin{unixcom}
  export BIBINPUTS=$HOME/LaTeX/biblio//:
\end{unixcom}
\continuenota%
  dans votre \texttt{.bash\_profile} pour que \BibTeX{} cherche vos
  fichiers de bibliographie dans le répertoire 
  \verb+$HOME/LaTeX/biblio+ (c'est un exemple). %$+
\end{nota}


\section{Index}
\label{science-index}
\index{index|textbf}


La génération d'index s'appuie sur deux concepts :
\begin{enumerate}
\item l'ajout de commandes \ltxcom{index} dans le document \LaTeX{}
  pour ajouter des entrées dans l'index ;
\item l'utilisation du programme \soft{makeindex} qui va trier et
  mettre en page l'index proprement dit.
\end{enumerate}
C'est la commande \ltxcom{printindex} qui insère l'index dans le
document. Cette commande est analogue à 
\ltxcom{tableofcontents}.


\subsection{Ce qu'il faut faire}
\label{sec-faire-index}

Voici un petit mémo pour faire un index.

\begin{enumerate}
  
\item rajouter deux commandes dans le document maître : 
\begin{ltxcode}
  \makeindex        ø\ccomment{pour dire à \LaTeX{} de générer les index}ø
  \begin{document}
  ø\normalfont ... le document ...ø
  \printindex    ø\ccomment{Pour réellement l'insérer dans le document}ø
  \end{document}
\end{ltxcode}

\item  ajouter une entrée dans l'index :
\begin{ltxcode}
  \index{bidule}           ø\ccomment{insère « bidule » dans l'index}ø
\end{ltxcode}

\item pour générer l'index pour le document \texttt{doc.tex}, on
  lancera successivement les trois commandes suivantes :
\begin{ltxcode}
  latex doc
  makeindex doc
  latex doc
\end{ltxcode}
\end{enumerate}


\subsection{Détail du fonctionnement}
\label{sec-detail-index}

La première compilation du document \texttt{doc.tex} (à la condition
que la séquence de contrôle \ltxcom{makeindex} soit présente dans son
préambule) génère un fichier \texttt{doc.idx} contenant les entrées de
l'index « en vrac » :
\begin{center}
  \includepsfraggraphics{makeindex1}
\end{center}
On utilise ensuite \soft{makeindex} pour classer et supprimer les
doublons dans ce fichier \texttt{doc.idx}, le résultat est mis dans
\texttt{doc.ind} ; une trace de l'exécution est stockée dans
\texttt{doc.ilg} :
\begin{center}
  \includegraphics[scale=0.6]{makeindex2}
\end{center}
\soft{makeindex} est bavard sur le terminal ; voici ce qu'il dit pour
générer l'index de ce document :
\begin{footnotesize}
\begin{verbatim}
This is makeindex, version 2.13 [07-Mar-1997] (using kpathsea).
Scanning input file guide.idx....done (982 entries accepted, 0 rejected).
Sorting entries...........done (11254 comparisons).
Generating output file guide.ind....done (745 lines written, 0 warnings).
Output written in guide.ind.
Transcript written in guide.ilg.
\end{verbatim}
\end{footnotesize}
Il faut donc veiller aux éventuels rejets ou avertissements
(\emph{warnings}) et se reporter au fichier log \texttt{doc.ilg} le
cas échéant.
La deuxième compilation avec \LaTeX{} permet d'insérer l'index formaté
(fichier \texttt{doc.ind}) à l'endroit spécifié par la commande
\ltxcom{printindex} dans \texttt{doc.tex} :
\begin{center}
  \includepsfraggraphics{makeindex3}
\end{center}

\begin{note}
  L'utilitaire \soft{makeindex} reconnaît l'option \texttt{-s} qui
  permet de spécifier un \emph{style} pour l'index. Ces
  styles---définis dans des fichiers portant
  l'extension~\texttt{.ist}---changent la mise en page de l'index. On
  utilise un fichier style de la manière suivante :
  \begin{unixcom}
   makeindex -s ¢marg«fichier-style» ¢marg«document-maitre»
  \end{unixcom}
  \continuenota%
  Cherchez sur votre distribution quels sont les fichiers de styles et
  testez-les.
\end{note}


\subsection{Différents types d'entrée d'index}
\label{sec-index-entries}

On peut utiliser des entrées un peu plus sophistiquées que la forme
vue jusqu'à maintenant (\emph{<mot> et <page>}). Il existe au moins
trois autres entrées :
\begin{enumerate}
\item les entrées hiérarchiques :
  \begin{ltxcode}
    \index{bidule!chouette}
  \end{ltxcode}
  insère une sous-entrée `chouette' à `bidule'
\item les entrées à cheval sur plusieurs pages :
\begin{ltxcode}
  \index{bidule|(}        ø\ccomment{à la page i}ø
  \index{bidule|)}        ø\ccomment{à la page j}ø
\end{ltxcode}
  génère une entrée de type : bidule i--j
\item les entrées symboliques :
  \begin{ltxcode}
    \index{alpha@\alpha}
  \end{ltxcode}
ajoute la lettre grecque $\alpha$ et la classe à l'entrée `alpha'. De
même :
  \begin{ltxcode}
    \index{eplucher@éplucher}
  \end{ltxcode}
  ajoute le mot \og éplucher\fg{} et le classe parmi les mots
  commençant par \og e\fg{}
\end{enumerate}
%D Il serait bon d'indiquer que ceci peut servir dans le cas suivant :
%D \index{eplucher@éplucher} ERREUR DANS LE SOURCE
Cette dernière forme peut également être utilisée pour mettre dans
l'index une entrée avec une mise en forme particulière, par exemple :
\begin{ltxcode}
  \index{bonjour@\textbf{bonjour}}
\end{ltxcode}
ajoute \textbf{bonjour} (bonjour en gras) dans l'index, et classe
cette entrée à `bonjour'. Enfin on peut vouloir afficher les numéros
de pages avec une mise en évidence particulière. On utilisera alors la
forme :
\begin{ltxcode}
  \index{ø\marg{entrée}ø|ø\marg{commande de mise en forme}ø}
\end{ltxcode}
Par exemple :
\begin{ltxcode}
  \index{bidule|textbf}
\end{ltxcode}
affichera le numéro de la page où apparaît ``bidule'' en gras (notez
qu'il n'y a pas de caractère \verb+\+ pour la commande de mise en
forme).

\subsection{Glossaire}
\label{sec-glossaire}
\index{glossaire}

On a parfois besoin de préciser la signification de certains termes
d'un document ; la partie d'un manuel qui regroupe l'explication de
ces termes s'appelle un \emph{glossaire}. Pour en générer, il faut
procéder de manière analogue à un \voir{sec-faire-index}{index} avec
quelques petites variations présentées au
paragraphe~\vref{sec-jouets-glossaire}.



\section{Diviser votre document}\label{sec-science-diviser}
\index{diviser document} \index{document!diviser} 

Lorsqu'on manipule un gros document, on peut le diviser naturellement
en chapitres ou parties. Il est alors conseillé de créer un document
\emph{maître} chargé d'inclure ces chapitres ou parties. Le document
maître a l'allure suivante :
\begin{ltxcode}
   \documentclass{book}
  
   \begin{document}
   \frontmatter % tout ce qui est introductif
   \include{preface}
   \tableofcontents
   \mainmatter  % le « corps » du document 
   \include{chapitre1}
   \include{chapitre2}
   \backmatter  % tout ce qui vient en fin de document
   \bibliographstyle{plain}
   \bibliography{machin,bidule,truc}
   \end{document}
\end{ltxcode}
\normalsize L'intérêt des commandes \ltxcom{include} réside dans le
fait qu'elles vous permettent de travailler sur un nombre réduit de
chapitres à la fois, tout en gardant l'intégrité du document. On
utilise pour cela la commande \ltxcom{includeonly} :
\begin{ltxcode}
  \includeonly{preface,savoir}
\end{ltxcode}
dans le préambule. Ceci permet de compiler uniquement la préface
(contenue dans le fichier \texttt{preface.tex}) et le chapitre
saisi dans le document \texttt{savoir.tex}.
\begin{nota}
  Chaque commande \ltxcom{include} commence une nouvelle page. Et il
  n'y a apparemment pas moyen de passer outre.  Vous aurez donc
  compris que \ltxcom{include} est à utiliser avec les commandes de
  section qui sautent une page (\ltxcom{chapter} et cie). Pour insérer
  un fichier sans saut de page, utilisez la commande
  \ltxcom{input}. Par contre, vous ne bénéficierez pas du mécanisme de
  document maître.
\end{nota}
Enfin, il est utile de noter que les trois commandes \ltxcom{frontmatter},
\ltxcom{mainmatter} et \ltxcom{backmatter},  ne sont pas
indispensables, mais permettent automatiquement d'adopter une numérotation
en roman pour les pages introductives et d'autres petites choses
(elles ne sont cependant accessibles que dans la classe
\ltxcls{book}).

\endinput






%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "../framabook"
%%% End: 
