Inclusion de listings avec l'extension listings

L'extension listings fournit sans nul doute une des plus riches manières d'insérer des listings dans vos documents. En effet, vous pourrez insérer des listings, gérer la numérotation, insérer une légende pour y faire référence, personnaliser l'aspect en ajoutant des cadres, des couleurs, colorer la syntaxe de vos programmes, ...

Nous allons, dans cette section parcourir toutes les fonctionnalités offertes dans cette extension. Pour en savoir plus, référez-vous à la documentation de l'extension.

Mode d'insertion

Il existe trois modes d'insertion de listing offerts par l'extension listings. On peut insérer un listing dans le texte (inline), séparé du texte ou depuis un fichier.

Dans le texte

Pour l'insertion dans le texte, on utilise la commande lstinline qui se comporte comme la commande verb, c'est-à-dire que pour délimiter son contenu, on utilise deux fois le même symbole. On peut également utiliser la syntaxe habituelle et préciser le code en paramètre de la commande.

On voit donc qu'il faut charger l'extension listings puis qu'on utilise lstinline pour insérer un listing dans le texte. Vous aurez aussi remarqué que l'on précise que le code est du Java en utilisant \lstset{language=java}, on en reparlera un peu plus loin.

Séparé du texte

Pour insérer un listing en dehors du texte, il faut utiliser l'environnement lstlisting. On peut utiliser l'option de l'environnement pour spécifier le langage, mais on y reviendra plus tard en détails.

Depuis un fichier externe

Rien de plus simple, une commande à qui on précise le nom du fichier et le tout est joué. Très pratique pour intégrer les sources de programme pour un rapport par exemple ...

Les options

Comme vous avez pu le voir, il existe deux manières de préciser des options pour la mise en forme des listings : soit on utilise la commande lstset qui change la valeur de l'option pour tout le document, soit on précise localement des options en utilisant l'option des commandes et environnements utilisé.

Toutes les options sont précisées par un couple clé=valeur comme déjà rencontré pour la commande includegraphics vue au chapitre 3.

Style du texte

On peut modifier l'apparence que va prendre le texte, en modifiant la police, la couleur, le style, ... Les options à utiliser sont reprises dans le tableau suivant.

En outre, vous avez peut-être remarqué sur la figure l12.9 que les espaces dans les chaines de caractères sont imprimés de manière visible. Si vous ne voulez pas voir les espaces, vous pouvez utiliser l'option showstringspaces et lui donner pour valeur false.

Dans cet exemple, on a donc le style de base qui définit une petite police, ensuite, on met les mots-clés en gras et en bleu, on souligne les identificateurs, les commentaires sont en gris moyen et italique, les chaines de caractères sont en rouge et on ne montre pas les espaces. Vous aurez remarqué que l'on a mis toutes les options séparées par des virgules dans un seule commande lstset. On aurait aussi pu écrire autant de commandes lstset qu'il y a d'options à définir.

La numérotation

On peut ajouter des numéros aux lignes d'un listing en utilisant des options particulières. On pourra jouer sur le numéro de la première ligne, sur le pas de la numérotation, sur le style des numéros. Le tableau suivant reprend les options relatives à la numérotation.

Dans notre exemple, on place les numéros de ligne à gauche du listing, les numéros sont minuscules, en gras et en bleu, on numérote les lignes multiples de 2, en commençant au numéro 11 et en forçant l'affichage du numéro de la première ligne. Enfin, les numéros sont à 10 points du listing.

Vous aurez remarqué que le mode de fonctionnement du numéro de la première ligne et du pas est exactement le même que pour l'environnement listing de l'extension moreverb vu à la section précédente, mais ici, on peut forcer l'affichage du numéro de la première ligne avec numberfirstline.

Continuation de listing

Rappelez-vous la section précédente, on avait un environnement listingcont qui permettait d'insérer un listing tout en gardant la numérotation d'un autre, en le continuant. On peut faire la même chose ici en utilisant l'option firstnumber.

Si vous donnez comme valeur à cette option last, la numérotation continuera celle du listing précédent. On peut également obtenir le même effet en donnant la valeur auto et en ajoutant un nom au listing avec l'option name. Dans ce cas, la numérotation continuera celle du listing précédent avec le même nom.

Reconnaissance syntaxique

On l'a déjà vu plus haut, pour activer la reconnaissance syntaxique, on utilise l'option language. On peut, en plus de spécifier le langage de programmation, spécifier un dialecte particulier que l'on précisera avant tout entre crochets. Par exemple, pour un code en C#, on écrit :

Lorsque l'on précise un dialecte, il convient d'entourer le nom du langage et du dialecte dans un bloc afin d'éviter des erreurs de compilation avec l'extension keyval.

Pour la liste des tout les langages supportés par défaut, nous vous renvoyons à la documentation de l'extension listings. Voici en vrac quelques langages supportés :

Ada, Algol, Assembler, bash, Basic, C, C++, Cobol, Delphi, Eiffel, Erlang, Fortran, Gnuplot, Haskell, HTML, Java, Lisp, make, Mathematica, Matlab, ML, Octave, Oz, Pascal, Perl, PHP, Prolog, Python, R, Ruby, Scilab, SQL, Tex, VBScript, Verilog, VHDL, XML, ...

Positionnement

Toute une série d'options ont traits au positionnement du listing par rapport au texte environnant. La première option est float. Si vous précisez cette option sans valeur, le listing va être mis dans un flottant. Vous pouvez également préciser la position préférée pour le flottant avec les lettres tbph (top, bottom, page, here) déjà rencontrée au chapitre 3.

L'exemple suivant montre comment paramétrer un listing qui doit préférentiellement être placé à l'endroit précisé par le code source, sinon en haut de la page suivante.

On peut ensuite modifier l'espace vertical entre le listing et le texte, au-dessus du listing avec aboveskip et en dessous avec belowskip. L'exemple suivant montre comment mettre 1cm entre le dessus du listing et le texte et 2cm entre le bas du listing et le texte.

Style du listing

Enfin, pour terminer cette première introduction à l'extension listings, découvrons comment personnaliser l'apparence du listing, en ajoutant un cadre autour, en changeant la couleur de fond, ...

Cadre

Pour ajouter un cadre rectangulaire autour du listing, on utilise l'option frame. La figure suivante illustre différents type de cadre obtenu avec différentes valeurs de l'option frame.

Vous pouvez voir que sur les deux dernies exemples, on utilise les lettres tblr pour spécifier si on veut une bordure en haut, en bas, à gauche ou à droite. Avec les lettres majuscules, on signale que l'on souhaite une double bordure.

Couleurs

On peut spécifier la couleur de fond du listing avec l'option backgroundcolor et la couleur du cadre si on en a un avec rulecolor. De plus, on a fillcolor qui est la couleur entre le texte et le premier cadre et rulesepcolor qui est la couleur entre les deux cadres si on a une double bordure. Le tout en exemple :

Légende, référence et liste des listings

Légende

On peut ajouter une légende à un listing, et ensuite imprimer la liste des listings, tout comme on avait déjà la liste des figures ou la liste des tables. On utilise l'option caption pour spécifier la légende du listing et la commande lstlistoflistings pour insérer la liste des listings.

Référence croisée

Rien de plus simple que de faire référence à un listing, on utilise le même principe que pour les figures et les tables : on ajoute une étiquette au listing en utilisant l'option label. Ensuite, on fait référence à un listing en utilisant la commande ref ou une variante comme vue au chapitre 6.