Debian Codegraph @

texmf-dist/doc/lualatex/piton/piton-french.tex

raw
1 % -*- coding: utf-8 ; -*-
2 \documentclass[dvipsnames,svgnames]{article}
3
4 \usepackage{fontspec}
5
6 \usepackage{polyglossia}
7 \setmainlanguage{french}
8
9 \usepackage[footnotehyper]{piton}
10 \PitonOptions
11 {
12 splittable = 4 ,
13 math-comments,
14 begin-escape = ? ,
15 end-escape = ? ,
16 begin-escape-math = \( ,
17 end-escape-math = \) ,
18 detected-commands = { \highLight , \footnote , \emph , \textsl , \textbackslash } ,
19 vertical-detected-commands = \newpage ,
20 raw-detected-commands = { \NomTable , \rowcolor } ,
21 }
22
23
24 \ExplSyntaxOn
25
26 \dim_new:N \l__pantigny_width_dim
27
28 \keys_define:nn { pantigny }
29 { width .dim_set:N = \l__pantigny_width_dim }
30
31 \NewPitonEnvironment { Code } { O { } }
32 {
33 \SetPitonStyle{ Number = , Comment = , String = }
34 \PitonOptions{language = minimal}
35 \char_set_catcode_other:N |
36 \cs_set_eq:NN \emph \emphase
37 \dim_zero:N \l__pantigny_width_dim
38 \keys_set:nn { pantigny } { #1 }
39 \color{gray}
40 \dim_compare:nNnT \l__pantigny_width_dim > \c_zero_dim
41 {
42 \PitonOptions { width = \l__pantigny_width_dim }
43 \begin{minipage}[c]{\l__pantigny_width_dim}
44 }
45 }
46 { \dim_compare:nNnT \l__pantigny_width_dim > \c_zero_dim
47 { \end{minipage} }
48 }
49
50 \ExplSyntaxOff
51
52
53 \usepackage[executable=python3.exe]{pyluatex}
54
55 \usepackage{xcolor}
56
57 \usepackage{geometry}
58 \geometry{left=2.8cm,right=2.8cm,top=2.5cm,bottom=2.5cm,papersize={21cm,29.7cm}}
59
60 \usepackage{enumitem}
61 \usepackage{verbatim}
62 \usepackage{amsmath}
63 \usepackage{tabularx}
64 \usepackage{booktabs}
65 \usepackage[framemethod=tikz]{mdframed}
66 \usepackage{tcolorbox}
67 \tcbuselibrary{skins,breakable}
68 \tcbset{enhanced}
69
70 \usepackage{luacolor,lua-ul}
71 \usepackage{caption}
72
73 % We use \MakeShortVerb of shortvrb and not \DefineShortVerb of fancyvrb
74 % because we don't want the contents of short verbatim colored in gray
75 \usepackage{shortvrb}
76 \MakeShortVerb{\|}
77
78 \usepackage{varwidth}
79
80 \skip\footins = 2\bigskipamount
81
82 \usepackage{fancyvrb}
83 \fvset{commandchars=\~\#\@,formatcom=\color{gray}}
84 \def\emphase{\bgroup\color{RoyalPurple}\let\next=}
85
86
87 \usepackage{titlesec}
88 \titlespacing*{\section}{0pt}{6.5ex plus 1ex minus .2ex}{4.3ex plus .2ex}
89 \titlespacing*{\subsection}{0pt}{4.5ex plus 1ex minus .2ex}{2ex plus .2ex}
90
91 \def\interitem{\vspace{7mm plus 2 mm minus 3mm}}
92
93
94 \usepackage[hyperfootnotes = false]{hyperref}
95 \usepackage{bookmark}
96
97 \hypersetup
98 {
99 pdfinfo =
100 {
101 Title = L’extension piton ,
102 Subject = Une extension LaTeX ,
103 Author = F. Pantigny
104 }
105 }
106
107 \usepackage{makeidx}
108 \makeindex
109
110 \usepackage{underscore}
111
112 \NewDocumentCommand{\Definition}{m}
113 {{\setlength{\fboxsep}{1pt}\colorbox{gray!20}{\ttfamily \vphantom{gl}#1}}}
114
115 \NewDocumentCommand{\DefinitionCommand}{m}
116 {{\setlength{\fboxsep}{1pt}\colorbox{gray!20}{\ttfamily
117 \vphantom{gl}\textbackslash #1}}}
118
119
120 \NewDocumentCommand{\indexcommand}{m}{\index{#1@\texttt{\textbackslash #1}}}
121
122 \NewDocumentCommand{\indexenv}{m}{\index{#1@\texttt{\{#1\}}}}
123
124
125 \NewDocumentCommand {\pkg} {m} {\textsf{#1}}
126 \NewDocumentCommand {\cls} {m} {\textsf{#1}}
127
128 \setlength{\parindent}{0pt}
129
130 \newcommand{\CC}{{C\nolinebreak[4]\hspace{-.05em}\raisebox{.4ex}{\tiny\bfseries ++}}}
131
132 \begin{document}
133
134
135
136 \UseName{VerbatimFootnotes}
137
138
139 \title{L'extension LaTeX \pkg{piton}\thanks{Ce document correspond à la
140 version~\PitonFileVersion\space de \pkg{piton}, à la date du~\PitonFileDate.}}
141 \author{F. Pantigny \\ \texttt{[email protected]}}
142
143 \maketitle
144
145 \begin{abstract}
146 L'extension \pkg{piton} propose des outils pour composer des codes informatiques avec
147 coloration syntaxique. Elle nécessite l'emploi de la LuaLaTeX car le travail principal est
148 fait en utilisant la bibliothèque Lua LPEG.
149 \end{abstract}
150
151
152 \section{Présentation}
153
154
155
156 L'extension \pkg{piton} utilise la librairie Lua nommée LPEG\footnote{LPEG est
157 une librairie de capture de motifs (\emph{pattern-matching} en anglais) pour
158 Lua, écrite en C, fondée sur les PEG (\emph{parsing expression grammars}):
159 \url{http://www.inf.puc-rio.br/~roberto/lpeg/}} pour «parser» des listings
160 informatiques avec coloriage syntaxique. Comme elle utilise le Lua de LuaLaTeX,
161 elle fonctionne uniquement avec |lualatex| (et ne va pas fonctionner avec les
162 autres moteurs de compilation LaTeX, que ce soit |latex|, |pdflatex| ou
163 |xelatex|). Elle n'utilise aucun programme extérieur et donc, a fortiori, elle
164 ne requiert pas l'utilisation de |--shell-escape| lors de la compilation. La
165 compilation est très rapide puisque tout le travail du parseur est fait par la
166 librairie LPEG, écrite en C.
167
168 \medskip
169 Voici un exemple de code Python composé avec l'environnement |{Piton}|
170 proposé par \pkg{piton}.
171
172
173 \medskip
174 \begin{Piton}
175 from math import pi
176
177 def arctan(x,n:int=10):
178 """Calcule la valeur mathématique de arctan(x)
179
180 n est le nombre de termes de la somme
181 """
182 if x < 0:
183 return -arctan(-x) # appel récursif
184 elif x > 1:
185 return pi/2 - arctan(1/x)
186 #> (on a utilisé le fait que $\arctan(x)+\arctan(1/x)=\pi/2$ pour $x>0$)\footnote{Cet échappement vers LaTeX a été obtenu en débutant par \ttfamily\#>.}
187 else:
188 s = 0
189 for k in range(n):
190 s += (-1)**k/(2*k+1)*x**(2*k+1)
191 return s
192 \end{Piton}
193
194 \medskip
195 Les principaux concurrents de l'extension \pkg{piton} sont certainement les extensions
196 bien connues \pkg{listings} et \pkg{minted}.
197
198
199 \medskip
200 Le nom de cette extension (\pkg{piton}) a été choisi un peu arbitrairement en référence
201 aux pitons d'alpinisme qui servent à gravir les montagnes.
202
203
204 L'extension \pkg{piton} se compose de deux fichiers : |piton.sty| et |piton.lua| (le
205 fichier LaTeX |piton.sty| chargé par |\usepackage| va à son tour charger le fichier
206 |piton.lua|). Les deux fichiers doivent être présents dans un répertoire où LaTeX pourra
207 les trouver, de préférence dans une arborescence |texmf|. Le mieux reste néanmoins
208 d'installer \pkg{piton} avec une distribution TeX comme MiKTeX, TeX~Live ou MacTeX.
209
210 \medskip
211 On remarquera que le caractère \emph{quote} (U+0027 : \verb|'|) n'est jamais converti
212 par \pkg{piton} en l'apostrophe U+2019. Il n'y a pas besoin de charger l'extension
213 \pkg{upquote}.
214
215
216
217 \section{Utilisation de l'extension}
218
219 L'extension \pkg{piton} doit être utilisée avec \textbf{LuaLaTeX exclusivement}
220 : si un autre moteur de compilation (comme |latex|, |pdflatex| ou |xelatex|) est
221 utilisé, une erreur fatale sera levée.
222
223
224 \subsection{Choix du langage}
225
226 Les langages informatiques pris en charge par \pkg{piton} se classent en deux catégories :
227 \begin{itemize}
228 \item les langages reconnus nativement par \pkg{piton} qui sont au
229 nombre de quatre : Python, OCaml, SQL, C (ou plutôt \CC) plus deux
230 langages minimalistes nommés |minimal|\footnote{Le langage |minimal|
231 peut servir pour formater du pseudo-code :
232 cf.~p.~\pageref{minimal}.} et |verbatim|;
233 \item les langages définis par l'utilisateur avec la commande |\NewPitonLanguage| décrite
234 p.~\pageref{NewPitonLanguage} (les parseurs de ces langages ne pourront jamais être aussi
235 précis que ceux proposés nativement par \pkg{piton)}.
236 \end{itemize}
237
238
239 \smallskip
240 Par défaut, le langage est Python.
241
242 \smallskip
243 \index{language (clé)}
244 On peut changer de langage avec la clé \Definition{language} de |\PitonOptions| :
245
246 \smallskip
247 |\PitonOptions{language = OCaml}|
248
249 \smallskip
250 En fait, le nom des langages, pour \pkg{piton}, est toujours \textbf{insensible à la
251 casse}. Dans cet exemple, on aurait tout aussi bien pu écrire |Ocaml| ou |ocaml|.
252
253 \smallskip
254 Pour les développeurs, précisons que le nom du langage courant est stocké (en minuscules)
255 dans la variable publique L3 nommée |\l_piton_language_str|.
256
257 \smallskip
258 Dans la suite de ce document, on parlera préférentiellement de Python mais les
259 fonctionnalités s'appliquent aussi aux autres langages.
260
261
262
263 \subsection{Chargement de l'extension}
264
265
266 L'extension \pkg{piton} se charge simplement avec |\usepackage{piton}|.
267
268 \smallskip
269 Elle utilise et charge l'extension \pkg{xcolor}. Elle n'utilise pas de programme
270 extérieur.
271
272 \subsection{Les commandes et environnements à la disposition de l'utilisateur}
273
274 \indexenv{Piton}
275
276 L'extension \pkg{piton} fournit plusieurs outils pour composer du code informatique : la
277 commande |\piton|, l'environnement |{Piton}| et la commande |\PitonInputFile|.
278
279 \begin{itemize}
280 \item La commande \DefinitionCommand{piton} doit être utilisée
281 pour composer de petits éléments de code à l'intérieur d'un paragraphe. Par exemple :
282
283 {\color{gray}\verb|\piton{def carré(x): return x*x}|}\qquad
284 \piton{def carré(x): return x*x}
285
286 La syntaxe et les particularités de la commande sont détaillées ci-après.
287
288
289 \item L'environnement \Definition{\{Piton\}} doit être utilisé pour composer des
290 codes de plusieurs lignes. Comme cet environnement prend son argument selon un
291 mode verbatim, il ne peut pas être utilisé dans l'argument d'une commande LaTeX.
292 Pour les besoins de personnalisation, il est possible de définir de nouveaux
293 environnements similaires à |{Piton}| en utilisant la commande
294 \DefinitionCommand{NewPitonEnvironment} ou ses variantes :
295 cf.~partie~\ref{NewPitonEnvironment} p.~\pageref{NewPitonEnvironment}.
296
297 \item La commande \DefinitionCommand{PitonInputFile} doit être utilisée pour insérer et
298 composer un fichier externe : cf.~partie~\ref{PitonInputFile},
299 p.~\pageref{PitonInputFile}.
300 \end{itemize}
301
302
303 \subsection{La double syntaxe de la commande \texttt{\textbackslash piton}}
304
305 \indexcommand{piton}
306
307 La commande |\piton| possède en fait une double syntaxe. Elle est peut être utilisée comme
308 une commande standard de LaTeX prenant son argument entre accolades (|\piton{...}|), ou
309 bien selon la syntaxe de la commande
310 \texttt{\textbackslash verb} de LaTeX où l'argument est délimité entre deux caractères
311 identiques (par ex. : \verb!\piton|...|! ou \verb!\piton+...+!).
312 On détaille maintenant ces deux syntaxes.
313
314 \bigskip
315 \begin{itemize}
316 \item {\color{blue} \textsf{Syntaxe} \verb|\piton{...}|}
317
318 \nobreak
319 Quand son argument est donné entre accolades, la commande |\piton| ne prend \emph{pas} son
320 argument en mode verbatim. Les points suivants doivent être remarqués :
321
322 \begin{itemize}
323 \item plusieurs espaces successives sont remplacées par une unique espace, ainsi que les
324 retours à la ligne
325
326 {\color{cyan} mais la commande |\|␣ est fournie pour forcer l'insertion d'une espace} ;
327
328 \item il n'est pas possible d'utiliser le caractère |%| à l'intérieur,
329
330 {\color{cyan} mais la commande |\%| est fournie pour insérer un |%|} ;
331
332 \item les accolades doivent apparaître par paires correctement imbriquées,
333
334 {\color{cyan} mais les commandes |\{| et |\}| sont aussi fournies pour insérer des
335 accolades individuelles} ;
336
337 \item les commandes LaTeX\footnote{Cela s'applique aux commandes commençant par
338 une contre-oblique |\| mais également aux caractères actifs, c'est-à-dire ceux
339 de catcode~13.} de l'argument de |\piton| sont complètement développées (au sens de TeX)
340 sans être exécutées
341
342 {\color{cyan} et on peut donc utiliser |\\| pour insérer une contre-oblique}.
343 \end{itemize}
344
345 Les autres caractères (y compris |#|, |^|, |_|, |&|, |$| % $
346 et |@|) doivent être insérés sans contre-oblique.
347
348 \bigskip
349 \begin{tabular}{>{\color{gray}}w{l}{75mm}@{\hspace*{1cm}}l}
350 \omit Exemples : \hfil \\
351 \noalign{\vskip1mm}
352 \verb|\piton{ma_chaîne = '\\n'}| &
353 \piton{ma_chaîne = '\\n' } \\
354 \verb|\piton{def pair(n): return n\%2==0}| &
355 \piton{def pair(n): return n\%2==0 } \\
356 \verb|\piton{c="#" # une affectation }| &
357 \piton{c="#" # une affectation } \\
358 \verb|\piton{c="#" \ \ \ # une affectation }| &
359 \piton{c="#" \ \ \ # une affectation } \\
360 \verb|\piton{my_dict = {'a': 3, 'b': 4}}| &
361 \piton{my_dict = {'a': 3, 'b': 4}}
362 \end{tabular}
363
364 \bigskip
365 La commande |\piton| avec son argument entre accolades peut être utilisée dans les
366 arguments des autres commandes LaTeX.\footnote{La commande |\piton| peut par exemple être
367 utilisée dans une note de bas de page. Exemple : \piton{x = 123}.}
368
369 En revanche, comme son argument subit un développement (au sens de TeX), il faut prendre
370 soin à ne pas utiliser dans son argument de commandes fragiles (c'est-à-dire des commandes
371 qui ne sont ni \emph{protected} ni \emph{fully expandable}).
372
373 \bigskip
374 \item {\color{blue} \textsf{Syntaxe} \verb!\piton|...|!}
375
376 \nobreak
377 Quand la commande |\piton| prend son argument entre deux caractères identiques (tous les
378 caractères sont autorisés sauf |%|,
379 |\|, |#|, |{|, |}| et l'espace), cet argument est pris \emph{en mode verbatim}. De ce
380 fait, avec cette syntaxe, la commande |\piton| ne peut \emph{pas} être utilisée dans
381 l'argument d'une autre fonction.
382
383 \medskip
384 \begin{tabular}{>{\color{gray}}w{l}{75mm}@{\hspace*{1cm}}l}
385 \omit Exemples : \hfil \\
386 \noalign{\vskip1mm}
387 \verb!\piton|ma_chaîne = '\n'|! &
388 \piton|ma_chaîne = '\n'| \\
389 \verb|\piton!def pair(n): return n%2==0!| &
390 \piton!def pair(n): return n%2==0! \\
391 \verb|\piton+c="#" # une affectation +| &
392 \piton+c="#" # une affectation + \\
393 \verb|\piton?my_dict = {'a': 3, 'b': 4}?| &
394 \piton!my_dict = {'a': 3, 'b': 4}!
395 \end{tabular}
396
397 \end{itemize}
398
399
400
401 \section{Personnalisation}
402
403
404 \subsection{Les clés de la commande \texttt{\textbackslash PitonOptions}}
405
406
407 \indexcommand{PitonOptions}
408
409 La commande |\PitonOptions| prend en argument une liste de couples \textsl{clé=valeur}. La
410 portée des réglages effectués par cette commande est le groupe TeX courant.\footnote{On
411 rappelle que tout environnement LaTeX est, en particulier, un groupe.}
412
413 Ces clés peuvent aussi être appliquées à un environnement |{Piton}| individuel (entre
414 crochets).
415
416 \begin{itemize}
417 \item La clé \Definition{language} spécifie le langage informatique considéré (la casse
418 n'est pas prise en compte). On peut choisir l'un des six langages prédéfinis (|Python|,
419 |OCaml|, |C|, |SQL|, |minimal| et |verbatim|) ou bien le nom d'un langage défini par
420 l'utilisateur avec |\NewPitonLanguage| (voir partie~\ref{NewPitonLanguage},
421 p.~\pageref{NewPitonLanguage}).
422
423 La valeur initiale est |Python|.
424
425 \item \index{font-command} La clé \Definition{font-command} contient des
426 instructions de fonte qui seront insérées au début de chaque élément formaté par
427 \pkg{piton}, que ce soit avec la commande |\piton|, l'environnement |{Piton}| ou
428 bien la commande |\PitonInputFile| (il n'y a que les «commentaires LaTeX» pour
429 lesquels ces instructions de fonte ne sont pas utilisées).
430
431 La valeur initiale de ce paramètre |font-command| est |\ttfamily|, ce qui fait,
432 que, par défaut, \pkg{piton} utilise la fonte mono-chasse courante.
433
434 Cette clé possède aussi une syntaxe additive avec, c'est-à-dire que l'on peut
435 écrire : |font-command +=| $\langle$\textsl{instructions}$\rangle$. Les
436 tokens $\langle$\textsl{instructions}$\rangle$ sont alors ajoutées à droite
437 de la valeur courante du paramètre.
438
439
440 \item \index{gobble}\label{gobble} La clé \Definition{gobble} prend comme valeur
441 un entier positif $n$ : les $n$ premiers caractères de chaque ligne sont alors
442 retirés (avant formatage du code) dans les environnements |{Piton}|. Ces $n$
443 caractères ne sont pas nécessairement des espaces.
444
445 Quand la clé |gobble| est utilisée sans valeur, elle se comporte comme la clé
446 |auto-gobble|, que l'on décrit maintenant.
447
448 \item \index{auto-gobble}\index{gobble!auto-gobble} Quand la clé
449 \Definition{auto-gobble} est activée, l'extension \pkg{piton} détermine la
450 valeur minimale $n$ du nombre d'espaces successifs débutant chaque ligne (non
451 vide) de l'environnement |{Piton}| et applique |gobble| avec cette valeur
452 de~$n$.
453
454 \item \index{env-gobble}\index{gobble!env-gobble} Quand la clé
455 \Definition{env-gobble} est activée, \pkg{piton} analyse la dernière ligne de
456 l'environnement, c'est-à-dire celle qui contient le \texttt{\textbackslash
457 end\{Piton\}} et détermine si cette ligne ne comporte que des espaces suivis
458 par \texttt{\textbackslash end\{Piton\}}. Si c'est le cas, \pkg{piton} calcule
459 le nombre $n$ de ces espaces et applique |gobble| avec cette valeur de~$n$. Le
460 nom de cette clé vient de \emph{environment gobble}: le nombre d'espaces à
461 retirer ne dépend que de la position des délimiteurs |\begin{Piton}| et
462 \texttt{\textbackslash end\{Piton\}} de l'environnement.
463
464
465 \item \index{line-numbers} La clé \Definition{line-numbers} active la
466 numérotation des lignes (en débordement à gauche) dans les environnements
467 |{Piton}| et dans les listings produits par la commande |\PitonInputFile|.
468
469 Cette clé propose en fait plusieurs sous-clés.
470 \begin{itemize}
471 \item La clé \Definition{line-numbers/skip-empty-lines} demande que les lignes
472 vides (qui ne contiennent que des espaces) soient considérées comme non
473 existantes en ce qui concerne la numérotation des lignes (si la clé |/absolute|,
474 décrite plus bas, est active, la clé |/skip-empty-lines| n'a pas d'effet dans
475 |\PitonInputFile|). La valeur initiale de cette clé est |true| (et non
476 |false|).\footnote{Avec le langage Python, les lignes vides des
477 \emph{docstrings} sont prises en compte.}
478
479
480 \item La clé \Definition{line-numbers/label-empty-lines} demande que les labels
481 (les numéros) des lignes vides soient affichés. Si la clé |/skip-empty-lines|
482 est active, la clé |/label-empty-lines| est sans effet. La valeur initiale de
483 cette clé est |true|.\footnote{Quand la clé |split-on-empty-lines| est activée,
484 les labels des lignes vides ne sont jamais imprimés.}
485
486 \item La clé \Definition{line-numbers/step} doit être utilisée quand on ne veut
487 pas faire afficher tous les numéros de ligne. Si $n$ est la valeur de cette clé,
488 les numéros ne seront affichés que de~$n$ en~$n$. Bien sûr, la valeur initiale
489 vaut~$1$.
490
491 \item La clé \Definition{line-numbers/absolute} demande, pour les listings
492 générés par |\PitonInputFile|, que les numéros de lignes affichés soient absolus
493 (c'est-à-dire ceux du fichier d'origine). Elle n'a d'intérêt que si on n'insère
494 qu'une partie du fichier (cf. partie~\ref{part-of-a-file},
495 p.~\pageref{part-of-a-file}). La clé |/absolute| est sans effet dans les
496 environnements |{Piton}|.
497
498 \item La clé \Definition{line-numbers/resume} reprend la numérotation là où elle
499 avait été laissée au dernier listing. En fait, la clé |line-numbers/resume| a un
500 alias, qui est |resume| tout court (car on peut être amené à l'utiliser
501 souvent).
502
503 \item La clé \Definition{line-numbers/start} impose que la numérotation commence
504 à ce numéro.
505
506 \item La clé \Definition{line-numbers/sep} est la distance horizontale entre les
507 numéros de lignes (insérés par |line-numbers|) et les lignes du code
508 informatique. La valeur initiale est 0.7~em.
509
510 \item La clé \Definition{line-numbers/format} est une liste de tokens qui est
511 insérée avant le numéro de ligne pour le formater. Il est possible de mettre
512 \emph{en dernière position} de cette liste une commande LaTeX à un argument
513 comme |\fbox|.
514
515 La valeur initiale est |\footnotesize \color{gray}|.
516
517
518 \item \colorbox{yellow!50}{\textbf{Nouveau 4.11}}
519
520 \nobreak
521 La clé \Definition{line-numbers/position} indique la position des numéros : à
522 gauche, avec la valeur |left| ou bien à droite avec la valeur |right|. La valeur
523 initiale est |left|.
524
525
526 \item \colorbox{yellow!50}{\textbf{Nouveau 4.13}}
527
528 \nobreak
529 Avec la clé \Definition{line-numbers/lmmono10-drawn}, les numéros de lines
530 utilisent la fonte \emph{Latin Modern Mono 10} mais les chiffres sont dessinés
531 et non affichés comme du texte. Ainsi, lors d'un copier-coller, les lecteurs de
532 \textsc{pdf} ne captureront pas ces numéros de lignes.
533
534 \end{itemize}
535
536 Pour la commodité, un dispositif de factorisation du préfixe |line-numbers| est
537 disponible, c'est-à-dire que l'on peut écrire, par exemple :
538
539 \begin{Code}
540 \PitonOptions
541 {
542 line-numbers =
543 {
544 skip-empty-lines = false ,
545 label-empty-lines = false ,
546 sep = 1 em ,
547 format = \footnotesize \color{blue}
548 }
549 }
550 \end{Code}
551
552 Attention : le code précédent ne suffit pas à activer l'affichage des numéros de
553 ligne. Pour cela, il faut encore utiliser la clé |line-numbers| de manière absolue
554 (c'est-à-dire sans valeur).
555
556 \item \index{left-margin} La clé \Definition{left-margin} fixe une marge sur la
557 gauche. Cette clé peut être utile, en particulier, en conjonction avec la clé
558 |line-numbers| si on ne souhaite pas que les numéros de ligne soient dans une
559 position en débordement sur la gauche.
560
561
562 Il est possible de donner à la clé |left-margin| la valeur spéciale~|auto|. Avec
563 cette valeur, une marge est insérée automatiquement pour les numéros de ligne
564 quand la clé |line-numbers| est utilisée. Voir un exemple à la partie
565 \ref{example-numbering} p.~\pageref{example-numbering}.
566
567 \item \index{right-margin}
568 \colorbox{yellow!50}{\textbf{New 4.11}}
569
570 \nobreak
571 La clé \Definition{right-margin} est similaire à la
572 clé précédente, mais pour la marge de droite.
573
574 \item \index{background-color} \label{background-color} La clé
575 \Definition{background-color} fixe la couleur de fond des environnements
576 |{Piton}| et des listings produits par |\PitonInputFile| (ce fond a une largeur
577 que l'on peut fixer avec la clé |width| ou la clé |max-width| décrites
578 ci-dessous).
579
580 La clé |background-color| accepte une couleur définie
581 «à la volée», c'est-à-dire que l'on peut écrire par exemple
582 |background-color = [cmyk]{0.1,0.05,0,0}|
583
584 \smallskip
585 La clé |background-color| accepte aussi en argument une \emph{liste} de
586 couleurs. Les lignes sont alors coloriées de manière cyclique avec ces couleurs.
587
588 \smallskip
589 Dans cette liste, la couleur spéciale \Definition{none} désigne une absence de couleur.
590
591 \emph{Exemple} : |\PitonOptions{background-color = {gray!5,none}}|
592
593 \item \index{rounded-corners}
594 On peut utiliser \Definition{rounded-corners} pour demander des coins arrondis
595 pour les fonds colorés spécifiés par |background-color|. La valeur initiale de
596 ce paramètre est $0$~pt, ce qui fait que les coins ne sont pas arrondis. Si on
597 utilise la clé |rounded-corners|, l'extension \pkg{tikz} doit être chargée car
598 ces coins arrondis sont tracés avec \pkg{tikz}. Si \pkg{tikz} n'est pas chargé,
599 une erreur sera levée à la première utilisation de la clé |rounded-corners|.
600
601 La valeur par défaut de |rounded-corners| vaut $4$~pt.\footnote{Cette valeur par
602 défaut est la valeur initiale des \emph{rounded corners} de \pkg{tikz}.}
603
604
605 \item \index{prompt-background-color} Avec la clé
606 \Definition{prompt-background-color}, \pkg{piton} ajoute un fond coloré aux
607 lignes débutant par le prompt «|>>>|» (et sa continuation «|...|»)
608 caractéristique des consoles Python avec boucle \textsc{repl}
609 (\emph{read-eval-print loop}). Pour un exemple d'utilisation de cette clé, voir
610 la partie \ref{python} p.~\pageref{python}.
611
612 La valeurs initiale est : |gray!15|
613
614
615 \item \index{width (clé)} \label{width} La clé \Definition{width} fixe la largeur du
616 listing produit. La valeur initiale de ce paramètre est la valeur courante de
617 |\linewidth| (paramètre LaTeX qui indique la largeur courante des lignes de texte).
618
619 Ce paramètre est utilisé pour :
620 \begin{itemize}
621 \item couper les lignes trop longues (sauf, bien sûr, quand la clé |break-lines| est
622 mise à |false|: cf. p.~\pageref{line-breaks}) ;
623 \item les fonds colorés spécifiés par les clés |background-color| et
624 |prompt-background-color| ;
625 \item les fonds colorés tracés par la clé |\rowcolor|
626 (cf.~p.~\pageref{rowcolor});
627 \item la largeur de la boîte LaTeX créée par la clé |box| (cf. p.~\pageref{box}) ;
628 \item la largeur de la boîte graphique créée par la clé |tcolorbox|
629 (cf. p.~\pageref{tcolorbox}).
630 \end{itemize}
631
632 \item \index{max-width (clé)}
633 La clé \Definition{max-width} est similaire à la clé |width| mais elle fixe la
634 largeur maximale des lignes. Si les lignes du listings sont toutes plus courtes
635 que la valeur fournie à |max-width|, la largeur (qui sera transmise au paramètre
636 |width|) sera la largeur maximale des lignes du listing, c'est-à-dire la largeur naturelle
637 du listing.
638
639 Pour la lisibilité du code, |width=min| est un raccourci pour |max-width=\linewidth|.
640
641 \item \index{show-spaces-in-strings} En activant la clé
642 \Definition{show-spaces-in-strings}, les espaces dans les chaînes de
643 caractères\footnote{Pour le langage Python, cela ne s'applique que pour les chaînes
644 courtes, c'est-à-dire celles délimitées par~\verb|'| ou~\verb|"| et, en particulier,
645 cela ne s'applique pas pour les \emph{doc strings}. En OCaml, cela ne s'applique pas
646 pour les \emph{quoted strings}.} sont matérialisés par le caractère ␣ (U+2423 :
647 \textsc{open box}). Bien sûr, le caractère U+2423 doit être présent
648 dans la fonte mono-chasse utilisée.\footnote{La valeur initiale de |font-command| est
649 |\ttfamily| ce qui fait que, par défaut, l'extension \pkg{piton} utilise simplement la
650 fonte mono-chasse courante.}
651
652 \nobreak
653 \begingroup
654 \PitonOptions{show-spaces-in-strings}
655 Exemple : \piton{my_string = 'Très bonne réponse'}
656 \endgroup
657
658 \item \index{show-spaces} Avec la clé \Definition{show-spaces}, tous les espaces
659 sont matérialisés par le caractère ␣ (et aucune coupure de ligne ne peut plus
660 intervenir sur ces espaces matérialisés, même quand la clé
661 |break-lines|\footnote{cf. \ref{line-breaks} p.~\pageref{line-breaks}.} est
662 active). Il faut néanmoins remarquer que les espaces en fin de ligne sont tous
663 supprimés par \pkg{piton} --- et ne seront donc pas représentés par~␣. Pour leur
664 part, quand la clé |show-spaces| est active, les tabulations de début de ligne
665 sont représentées par des flèches.
666 \end{itemize}
667
668 \bigskip
669 \begin{small}
670 \begin{Verbatim}
671 ~emphase#\begin{Piton}[language=C,line-numbers,gobble,background-color=gray!15@
672 ~emphase# rounded-corners,width=min,splittable=4]@
673 void bubbleSort(int arr[], int n) {
674 int temp;
675 int swapped;
676 for (int i = 0; i < n-1; i++) {
677 swapped = 0;
678 for (int j = 0; j < n - i - 1; j++) {
679 if (arr[j] > arr[j + 1]) {
680 temp = arr[j];
681 arr[j] = arr[j + 1];
682 arr[j + 1] = temp;
683 swapped = 1;
684 }
685 }
686 if (!swapped) break;
687 }
688 }
689 ~emphase#~textbackslash#@end{Piton}@
690 \end{Verbatim}
691 \end{small}
692
693
694 \begin{Piton}[language=C,line-numbers,gobble,
695 background-color = gray!15,rounded-corners,width=min]
696 void bubbleSort(int arr[], int n) {
697 int temp;
698 int swapped;
699 for (int i = 0; i < n-1; i++) {
700 swapped = 0;
701 for (int j = 0; j < n - i - 1; j++) {
702 if (arr[j] > arr[j + 1]) {
703 temp = arr[j];
704 arr[j] = arr[j + 1];
705 arr[j + 1] = temp;
706 swapped = 1;
707 }
708 }
709 if (!swapped) break;
710 }
711 }
712 \end{Piton}
713
714
715 \bigskip
716 La commande |\PitonOptions| propose d'autres clés qui seront décrites plus loin (voir en
717 particulier la coupure des pages et des lignes p.~\pageref{breakable}).
718
719
720
721 \subsection{Les styles}
722
723 \label{styles}
724 \index{styles (concept de \pkg{piton})}
725
726 \subsubsection{Notion de style}
727
728 L'extension \pkg{piton} fournit la commande |\SetPitonStyle| pour personnaliser les
729 différents styles utilisés pour formater les éléments syntaxiques des listings
730 informatiques. Ces personnalisations ont une portée qui correspond au groupe TeX
731 courant.\footnote{On rappelle que tout environnement LaTeX est, en particulier, un
732 groupe.}
733
734 \bigskip
735 \indexcommand{SetPitonStyle} La commande |\SetPitonStyle| prend en argument une liste de
736 couples \textsl{clé=valeur}. Les clés sont les noms des styles et les valeurs sont les
737 instructions LaTeX de formatage correspondantes.
738
739 \bigskip
740 Ces instructions LaTeX doivent être des instructions de formatage du type de |\bfseries|,
741 |\slshape|, |\color{...}|, etc. (les commandes de ce type sont parfois
742 qualifiées de \emph{semi-globales}). Il est aussi possible de mettre, \emph{à la fin de la liste
743 d'instructions}, une commande LaTeX prenant exactement un argument.
744
745 \bigskip
746 Voici un exemple qui change le style utilisé pour le nom d'une fonction Python, au moment
747 de sa définition (c'est-à-dire après le mot-clé |def|). Elle utilise la commande
748 |\highLight| de \pkg{lua-ul} (qui nécessite lui-même le chargement de \pkg{luacolor}).
749
750 \medskip
751 \begin{Code}
752 \SetPitonStyle
753 { Name.Function = \bfseries \highLight[red!30] }
754 \end{Code}
755
756 Ici, |\highLight[red!30]| doit être considéré comme le nom d'une fonction LaTeX qui prend
757 exactement un argument, puisque, habituellement, elle est utilisée avec
758 |\highLight[red!30]{|\texttt{\slshape text}|}|.
759
760 \medskip
761 \begingroup
762 \SetPitonStyle
763 { Name.Function = \bfseries \highLight[red!30] }
764 Avec ce réglage, on obtient : \piton{def cube(x) : return x * x * x }
765 \endgroup
766
767 \bigskip
768 L'usage des différents styles suivant le langage informatique considéré est décrit dans la
769 partie \ref{Semantic}, à partir de la page \pageref{Semantic}.
770
771
772 \bigskip
773 \indexcommand{PitonStyle} La commande \DefinitionCommand{PitonStyle} prend en argument le
774 nom d'un style et permet de récupérer la valeur (en tant que liste d'instructions LaTeX)
775 de ce style. Cette commande est «complètement développable» au sens de TeX.
776
777 \smallskip
778 Par exemple, on peut écrire, dans le texte courant, |{\PitonStyle{Keyword}{function}}| et
779 on aura le mot {\PitonStyle{Keyword}{function}} formaté comme un mot-clé.
780
781 \smallskip
782 La syntaxe |{\PitonStyle{|\textsl{\texttt{style}}|}{...}}| est nécessaire pour pouvoir
783 tenir compte à la fois des commandes semi-globales et des commandes à argument
784 potentiellement présentes dans la valeur courante du style \texttt{\textsl{style}}.
785
786
787 \subsubsection{Styles locaux et globaux}
788
789 Un style peut être défini de manière globale avec la commande |\SetPitonStyle|. Cela veut
790 dire qu'il s'appliquera par défaut à tous les langages informatiques qui utilisent ce
791 style.
792
793 \medskip
794 Par exemple, avec la commande
795 \begin{Verbatim}
796 \SetPitonStyle{Comment = \color{gray}}
797 \end{Verbatim}
798 tous les commentaires (que ce soit en Python, en C, en OCaml, etc. ou dans un langage
799 défini avec |\NewPitonLanguage|) seront composés en gris.
800
801 \bigskip
802 Mais il est aussi possible de définir un style localement pour un certain langage
803 informatique en passant le nom du langage en argument optionnel (entre crochets) de la
804 commande |\SetPitonStyle|.\footnote{On rappelle que, dans \pkg{piton}, les noms des
805 langages informatiques ne sont pas sensibles à la casse.}
806
807 \medskip
808 Par exemple, avec la commande
809 \begin{Verbatim}
810 \SetPitonStyle~emphase#[SQL]@{Keyword = \color[HTML]{006699} \bfseries \MakeUppercase}
811 \end{Verbatim}
812 les mots-clés dans les listings SQL seront composés en lettres capitales, même s'ils
813 s'apparaissent en minuscules dans le fichier source LaTeX (on rappelle que, en SQL, les
814 mot-clés ne sont pas sensibles à la casse et donc forcer leur mise en capitales peut être
815 envisagé).
816
817 \medskip
818 Comme on s'en doute, si un langage informatique utilise un certain style et que ce style
819 n'est pas défini localement pour ce langage, c'est la version globale qui est utilisée.
820 Cette notion de globalité n'a pas de rapport avec la notion de liaison locale de TeX
821 (notion de groupe TeX).\footnote{Du point de vue des groupes de TeX, les liaisons faites
822 par |\SetPitonStyle| sont toujours locales.}
823
824 \medskip
825 Les styles fournis par défaut par \pkg{piton} sont tous définis globalement.
826
827
828 \bigskip
829 \subsubsection{La commande \textbackslash rowcolor}
830
831 \label{rowcolor}
832 \indexcommand{rowcolor}
833
834 \nobreak
835 \medskip
836 L'extension \pkg{piton} fournit la commande \DefinitionCommand{rowcolor} qui impose un
837 fond coloré à la ligne courante (\emph{toute la ligne} et pas seulement la partie
838 contenant du texte) et que l'on peut utiliser dans les styles.
839
840 \smallskip
841 La commande |\rowcolor| a une syntaxe similaire à la commande classique |\color|. Par
842 exemple, il est possible d'écrire |\rowcolor[rgb]{0.8,1,0.8}|.
843
844 \smallskip
845 La commande |\rowcolor| est protégée contre le développement TeX.
846
847 \smallskip
848 Voici un exemple pour le langage Python où on modifie le style |String.Doc|
849 des \emph{documentation strings} pour avoir un fond coloré gris.
850
851
852 \medskip
853 % Ici, ne pas utiliser {Code}
854 \begin{Verbatim}
855 ~emphase#\SetPitonStyle{String.Doc = \rowcolor{gray!15}\color{black!80}}@
856 \begin{Piton}[width=min]
857 def square(x):
858 """Calcule le carré de x
859 Deuxième ligne de la documentation"""
860 return x*x
861 \end{Piton}
862 \end{Verbatim}
863
864
865 \bigskip
866 \begingroup
867 \SetPitonStyle{String.Doc = \rowcolor{gray!15}\color{black!80}}
868 \begin{Piton}[width=min]
869 def square(x):
870 """Calcule le carré de x
871 Deuxième ligne de la documentation"""
872 return x*x
873 \end{Piton}
874 \endgroup
875
876 \bigskip
877 Si la commande |\rowcolor| apparaît (via un style de \pkg{piton}) dans une commande
878 |\piton|, elle est sans effet (comme on s'en doute).
879
880
881 \bigskip
882 \subsubsection{Le style UserFunction}
883
884 \index{UserFunction (style)}
885
886 \bigskip
887 Il existe un style spécial nommé |UserFunction|. Ce style s'applique aux noms des
888 fonctions précédemment définies par l'utilisateur (par exemple, avec le langage Python,
889 ces noms de fonctions sont ceux qui apparaissent après le mot-clé \piton{def} dans un
890 listing Python précédent). La valeur initiale de ce style est |\PitonStyle{Identifier}|,
891 ce qui fait que ces noms de fonctions sont formatés comme les autres identificateurs
892 (c'est-à-dire, par défaut, sans formatage particulier, si ce n'est celui donné par
893 |font-command|).
894
895 Néanmoins, il est possible de changer la valeur de ce style, comme tous les autres styles,
896 avec la commande |\SetPitonStyle|.
897
898 \medskip
899 Dans l'exemple suivant, on règle les styles |Name.Function| et |UserFunction| de manière à
900 ce que, quand on clique sur le nom d'une fonction Python précédemment définie par
901 l'utilisateur, on soit renvoyé vers la définition (informatique) de cette fonction. Cette
902 programmation utilise les fonctions |\hypertarget| et |\hyperlink| de \pkg{hyperref}.
903
904 \begingroup
905
906 \NewDocumentCommand{\MyDefFunction}{m}{\hypertarget{piton:#1}{\color[HTML]{CC00FF}{#1}}}
907 \NewDocumentCommand{\MyUserFunction}{m}{\hyperlink{piton:#1}{#1}}
908
909 \SetPitonStyle
910 {
911 Name.Function = \MyDefFunction ,
912 UserFunction = \MyUserFunction
913 }
914
915 \medskip
916 \begin{Code}
917 \NewDocumentCommand{\MyDefFunction}{m}
918 {\hypertarget{piton:#1}{\color[HTML]{CC00FF}{#1}}}
919 \NewDocumentCommand{\MyUserFunction}{m}{\hyperlink{piton:#1}{#1}}
920
921 \SetPitonStyle{Name.Function = \MyDefFunction, \emph{UserFunction} = \MyUserFunction}
922 \end{Code}
923
924 \smallskip
925
926 \begin{Piton}
927 def transpose(v,i,j):
928 x = v[i]
929 v[i] = v[j]
930 v[j] = x
931
932 def passe(v):
933 for in in range(0,len(v)-1):
934 if v[i] > v[i+1]:
935 transpose(v,i,i+1)
936 \end{Piton}
937
938 \medskip
939 (Certains lecteurs de \textsc{pdf} affichent un cadre autour du mot |transpose| cliquable
940 et d'autres non.)
941
942
943 \endgroup
944
945 \PitonClearUserFunctions[Python]
946
947 \bigskip
948 \begin{small}
949 Bien sûr, la liste des noms de fonctions Python précédemment définies est gardée en
950 mémoire de LuaLaTeX (de manière globale, c'est-à-dire indépendamment des groupes TeX).
951 L'extension \pkg{piton} fournit une commande qui permet de vider cette liste : c'est la
952 commande \DefinitionCommand{PitonClearUserFunctions}. Quand elle est utilisée sans
953 argument, cette commande s'applique à tous les langages informatiques utilisées par
954 l'utilisateur mais on peut spécifier en argument optionnel (entre crochets) une liste de
955 langages informatiques auxquels elle s'appliquera.\footnote{On rappelle que, dans
956 \pkg{piton}, les noms des langages informatiques ne sont pas sensibles à la casse. }
957 \end{small}
958
959
960
961
962
963 \subsection{Définition de nouveaux environnements}
964
965 \label{NewPitonEnvironment}
966 \indexcommand{NewPitonEnvironment}
967 \indexcommand{RenewPitonEnvironment}
968 \indexcommand{DeclarePitonEnvironment}
969 \indexcommand{ProvidePitonEnvironment}
970
971 Comme l'environnement |{Piton}| a besoin d'absorber son contenu d'une manière spéciale (à
972 peu près comme du texte verbatim), il n'est pas possible de définir de nouveaux
973 environnements directement au-dessus de l'environnement |{Piton}| avec les commandes
974 classiques |\newenvironment| (de LaTeX standard) et |\NewDocumentEnvironment| (de LaTeX3).
975
976 Il est possible d'utiliser |\NewEnvironmentCopy| sur l'environment |{Piton}| mais
977 l'utilité est limitée.
978
979 C'est pourquoi \pkg{piton} propose une commande \DefinitionCommand{NewPitonEnvironment}.
980 Cette commande a la même syntaxe que la commande classique
981 |\NewDocumentEnvironment|.\footnote{Néanmoins, le spécificateur d'argument~|b|, qui sert à
982 capter le corps de l'environnement comme un argument LaTeX, n'est pas autorisé
983 (bien entendu).}
984
985 \medskip
986 Il existe aussi les commandes suivantes similaires à celles de LaTeX3 :
987 \DefinitionCommand{RenewPitonEnvironment},
988 \DefinitionCommand{DeclarePitonEnvironment} et \DefinitionCommand{ProvidePitonEnvironment}.
989
990
991
992 \bigskip
993 Par exemple, avec l'instruction suivante, un nouvel environnement |{Python}| sera défini
994 avec le même comportement que l'environnement |{Piton}|:
995
996 \medskip
997 \begin{Code}
998 \emph{\NewPitonEnvironment}{Python}{O{}}{\PitonOptions{#1}}{}
999 \end{Code}
1000
1001 \bigskip
1002 Si on souhaite un environnement |{Python}| qui compose le code inclus dans une boîte de
1003 \pkg{mdframed}, on peut écrire :
1004
1005 \begin{footnotesize}
1006 \begin{Verbatim}
1007 \usepackage[framemethod=tikz]{mdframed} % dans le préambule
1008 \end{Verbatim}
1009 \end{footnotesize}
1010
1011 \medskip
1012 \begin{Code}
1013 \emph{\NewPitonEnvironment}{Python}{}
1014 {\begin{mdframed}[roundcorner=3mm]}
1015 {\end{mdframed}}
1016 \end{Code}
1017
1018 \bigskip
1019 Avec ce nouvel environnement |{Python}|, on peut écrire :
1020
1021 \medskip
1022 \begin{Code}
1023 \emph{\begin{Python}}
1024 def carré(x):
1025 """Calcule le carré de x"""
1026 return x*x
1027 \emph{\end{Python}}
1028 \end{Code}
1029
1030 \NewPitonEnvironment{Python}{}
1031 {\begin{mdframed}[roundcorner=3mm]}
1032 {\end{mdframed}}
1033
1034 \begin{Python}
1035 def carré(x):
1036 """Calcule le carré de x"""
1037 return x*x
1038 \end{Python}
1039
1040 \bigskip
1041 On peut faire une construction similaire avec une boîte graphique de \pkg{tcolorbox}.
1042 Néanmoins, pour permettre une meilleure cohérence entre \pkg{tcolorbox} et \pkg{piton},
1043 l'extension \pkg{piton} propose la clé |tcolorbox| : cf.~p.~\pageref{tcolorbox}.
1044
1045 \section{Définition de nouveaux langages avec la syntaxe de listings}
1046
1047 \indexcommand{NewPitonLanguage}
1048 \label{NewPitonLanguage}
1049 \index{listings@\pkg{listings} (extension)}
1050
1051 \medskip
1052 L'extension \pkg{listings} est une célèbre extension LaTeX pour formater des codes informatiques.
1053
1054 \medskip
1055 Elle propose une commande |\lstdefinelanguage| pour définir de nouveaux langages. Cette
1056 commande est aussi utilisée en interne par \pkg{listings} pour sa définition des languages
1057 (en fait, pour cela, \pkg{listings} utilise une commande nommée |\lst@definelanguage| mais
1058 celle-ci a la même syntaxe que |\lstdefinelanguage|).
1059
1060 \medskip
1061 L'extension \pkg{piton} propose une commande \DefinitionCommand{NewPitonLanguage} pour
1062 définir de nouveaux langages (utilisables avec les outils de \pkg{piton}) avec quasiment
1063 la même syntaxe que |\lstdefinelanguage|.
1064
1065 \medskip
1066 Précisons tout de suite que l'extension \pkg{piton} n'utilise \emph{pas} cette commande
1067 pour définir les langages qu'elle propose nativement (Python, C, OCaml, SQL, |minimal| et
1068 |verbatim|), ce qui permet de proposer des parseurs plus puissants.
1069
1070 \medskip
1071 Par exemple, dans le fichier |lstlang1.sty|, qui est un des fichiers de definition des
1072 langages proposés par défaut par \pkg{listings}, on trouve les instructions suivantes
1073 (dans la version 1.10a).
1074
1075 \begin{Verbatim}[formatcom=\small\color{gray}]
1076 \lst~@definelanguage{Java}%
1077 {morekeywords={abstract,boolean,break,byte,case,catch,char,class,%
1078 const,continue,default,do,double,else,extends,false,final,%
1079 finally,float,for,goto,if,implements,import,instanceof,int,%
1080 interface,label,long,native,new,null,package,private,protected,%
1081 public,return,short,static,super,switch,synchronized,this,throw,%
1082 throws,transient,true,try,void,volatile,while},%
1083 sensitive,%
1084 morecomment=[l]//,%
1085 morecomment=[s]{/*}{*/},%
1086 morestring=[b]",%
1087 morestring=[b]',%
1088 }[keywords,comments,strings]
1089 \end{Verbatim}
1090
1091 \medskip
1092 Pour définir un language nommé |Java| pour \pkg{piton}, il suffit d'écrire le code
1093 suivant, {\bfseries où le dernier argument de |\lst@definelanguage|, qui est entre
1094 crochets, a été supprimé} (en fait, les symboles \verb+%+ pourraient être supprimés sans
1095 problème).
1096
1097 \medskip
1098 \begin{small}
1099 \begin{Verbatim}
1100 ~emphase#\NewPitonLanguage@{Java}%
1101 {morekeywords={abstract,boolean,break,byte,case,catch,char,class,%
1102 const,continue,default,do,double,else,extends,false,final,%
1103 finally,float,for,goto,if,implements,import,instanceof,int,%
1104 interface,label,long,native,new,null,package,private,protected,%
1105 public,return,short,static,super,switch,synchronized,this,throw,%
1106 throws,transient,true,try,void,volatile,while},%
1107 sensitive,%
1108 morecomment=[l]//,%
1109 morecomment=[s]{/*}{*/},%
1110 morestring=[b]",%
1111 morestring=[b]',%
1112 }
1113 \end{Verbatim}
1114 \end{small}
1115
1116 \NewPitonLanguage{Java}
1117 {morekeywords={abstract,boolean,break,byte,case,catch,char,class,
1118 const,continue,default,do,double,else,extends,false,final,
1119 finally,float,for,goto,if,implements,import,instanceof,int,
1120 interface,label,long,native,new,null,package,private,protected,
1121 public,return,short,static,super,switch,synchronized,this,throw,
1122 throws,transient,true,try,void,volatile,while},
1123 sensitive,
1124 morecomment=[l]//,
1125 morecomment=[s]{/*}{*/},
1126 morestring=[b]",
1127 morestring=[b]',
1128 }
1129
1130
1131 \medskip
1132 On peut alors utiliser le language Java comme n'importe quel autre langage prédéfini de
1133 \pkg{piton}.
1134
1135 Voici un exemple de code Java formaté dans un environnement~|{Piton}| avec la
1136 clé~|language=Java|.\footnote{On rappelle que, pour \pkg{piton}, les noms de langages
1137 informatiques ne sont pas sensibles à la casse, ce qui fait que l'on aurait pu aussi
1138 bien utiliser : |language=java|.}
1139
1140 \bigskip
1141 \begingroup
1142 \small
1143 \PitonOptions{splittable-on-empty-lines}
1144 \begin{Piton}[language = Java]
1145 public class Cipher { // cryptage par le chiffre de César
1146 public static void main(String[] args) {
1147 String str = "The quick brown fox Jumped over the lazy Dog";
1148 System.out.println( Cipher.encode( str, 12 ));
1149 System.out.println( Cipher.decode( Cipher.encode( str, 12), 12 ));
1150 }
1151
1152 public static String decode(String enc, int offset) {
1153 return encode(enc, 26-offset);
1154 }
1155
1156 public static String encode(String enc, int offset) {
1157 offset = offset % 26 + 26;
1158 StringBuilder encoded = new StringBuilder();
1159 for (char i : enc.toCharArray()) {
1160 if (Character.isLetter(i)) {
1161 if (Character.isUpperCase(i)) {
1162 encoded.append((char) ('A' + (i - 'A' + offset) % 26 ));
1163 } else {
1164 encoded.append((char) ('a' + (i - 'a' + offset) % 26 ));
1165 }
1166 } else {
1167 encoded.append(i);
1168 }
1169 }
1170 return encoded.toString();
1171 }
1172 }
1173 \end{Piton}
1174 \endgroup
1175
1176 \bigskip
1177 Les clés de la commande |\lstdefinelanguage| de \pkg{listings} prises en charge par
1178 |\NewPitonLanguage| sont : |morekeywords|, |otherkeywords|, |sensitive|, |keywordsprefix|,
1179 |moretexcs|, |morestring| (avec les lettres |b|, |d|, |s| et |m|), |morecomment| (avec les
1180 lettres |i|, |l|, |s|, |n| et |f|\footnote{Pour la lettre |f|, seule une spécification de commentaire commençant en première colonne est autorisée.})), |moredelim| (avec les lettres |i|, |l|, |s|, |*| et |**|),
1181 |moredirectives|, |tag|, |alsodigit|, |alsoletter| et |alsoother|.
1182
1183 Pour la description de ces clés, on renvoie à la documentation de \pkg{listings} (taper
1184 |texdoc| |listings| dans un terminal).
1185
1186 \bigskip
1187 Par exemple, pour formater du code LaTeX, on pourra créer le language suivant :
1188 %
1189 {\color{gray}
1190 \begin{verbatim}
1191 \NewPitonLanguage{LaTeX}{keywordsprefix = \ , alsoother = @_ }
1192 \end{verbatim}
1193 }
1194
1195 Initialement, les caractères |@| et |_| sont considérés comme des lettres (au sens de \pkg{listings})
1196 car de nombreux langages de programmation les autorisent dans les mots-clés et les identificateurs. Avec
1197 \verb|alsoother = @_|, on les retire de la catégorie des lettres.
1198
1199 \section{Importation et exportation de listings}
1200
1201 \subsection{Importation d'un listing fourni par un fichier externe}
1202
1203 \label{PitonInputFile}
1204
1205 \subsubsection{La commande \textbackslash PitonInputFile}
1206
1207 \indexcommand{PitonInputFile}
1208
1209 La commande \DefinitionCommand{PitonInputFile} permet d'insérer tout ou partie d'un
1210 fichier extérieur dont le nom est passé en argument. Il existe aussi des commandes
1211 \DefinitionCommand{PitonInputFileT}, \DefinitionCommand{PitonInputFileF} et
1212 \DefinitionCommand{PitonInputFileTF} avec des arguments correspondant aux lettres |T| et
1213 |F|, arguments qui seront exécutés dans le cas où le fichier a été trouvé (lettre |T|) ou
1214 pas (lettre |F|).
1215
1216 \smallskip
1217 La syntaxe des chemins (absolus et relatifs) est la suivante :
1218 \begin{itemize}
1219 \item Les chemins commençant par |/| sont des chemins absolus.
1220
1221 \emph{Exemple} : |\PitonInputFile{/Users/joe/Documents/programme.py}|
1222
1223 \item Les chemins ne commençant pas par |/| sont relatifs au répertoire courant.
1224
1225 \emph{Exemple} : |\PitonInputFile{les_listings/programme.py}|
1226 \end{itemize}
1227
1228
1229 \index{path}
1230 La clé \Definition{path} de la commande |\PitonOptions| permet de spécifier une
1231 \emph{liste} de chemins où sera recherché le fichier à inclure (dans cette liste, les
1232 chemins sont séparés par des virgules). Comme précédemment, les chemins absolus doivent
1233 débuter par une oblique~|/|.
1234
1235
1236 \subsubsection{Insertion d'une partie d'un fichier}
1237
1238 \label{part-of-a-file}
1239 \indexcommand{PitonInputFile}
1240
1241 En fait, il existe des mécanismes permettant de n'insérer qu'une partie du fichier en
1242 question.
1243 \begin{itemize}
1244 \item On peut spécifier la partie à insérer par les numéros de lignes (dans le fichier
1245 d'origine).
1246 \item On peut aussi spécifier la partie à insérer par des marqueurs textuels.
1247 \end{itemize}
1248 Dans les deux cas, si on souhaite numéroter les lignes avec les numéros des lignes du
1249 fichier d'origine, il convient d'utiliser la clé |line-numbers/absolute|.
1250
1251 \bigskip
1252 \textbf{Avec les numéros de lignes absolus}
1253
1254 \nobreak
1255 La commande |\PitonInputFile| propose les clés \Definition{first-line} et
1256 \Definition{last-line} qui permettent de n'insérer que la partie du fichier comprise entre
1257 les lignes correspondantes. Ne pas confondre avec la clé |line-numbers/start| qui demande
1258 un numérotage des lignes commençant à la valeur donnée à cette clé (en un sens
1259 |line-numbers/start| concerne la sortie alors que |first-line| et |last-line| concernent
1260 l'entrée).
1261
1262 \bigskip
1263 \textbf{Avec des marqueurs textuels}
1264
1265 \index{marker/beginning}
1266 \index{marker/end}
1267
1268 \nobreak
1269 Pour utiliser cette technique, il convient d'abord de spécifier le format des marqueurs
1270 marquant le début et la fin de la partie du fichier à inclure. Cela se fait avec les deux
1271 clés \Definition{marker/beginning} et \Definition{marker/end} (usuellement dans la
1272 commande |\PitonOptions|).
1273
1274 \medskip
1275 Prenons d'abord un exemple.
1276
1277 \medskip
1278 Supposons que le fichier à inclure contienne des solutions à des exercices de
1279 programmation sur le modèle suivant :
1280
1281 \begin{small}
1282 \begin{Code}
1283 #[Exercice 1] Version itérative
1284 def fibo(n):
1285 if n==0: return 0
1286 else:
1287 u=0
1288 v=1
1289 for i in range(n-1):
1290 w = u+v
1291 u = v
1292 v = w
1293 return v
1294 #<Exercice 1>
1295 \end{Code}
1296 \end{small}
1297
1298 Les marqueurs de début de début et de fin sont les chaînes |#[Exercice 1]| et
1299 |#<Exercice 1>|. La chaîne «|Exercice 1|» sera appelée le \emph{label} de l'exercice (ou
1300 de la partie du fichier à inclure).
1301
1302 Pour spécifier des marqueurs de cette sorte dans \pkg{piton}, on utilisera les clés
1303 |marker/beginning| et |marker/end| de la manière suivante (le caractère |#| des
1304 commentaires de Python doit être inséré sous la forme échappée |\#|).
1305
1306 \smallskip
1307 \begin{Code}
1308 \PitonOptions{ \emph{marker/beginning} = \#[#1] , \emph{marker/end} = \#<#1> }
1309 \end{Code}
1310
1311 \smallskip
1312 Comme on le voit, |marker/beginning| est une expression correspondant à la fonction
1313 mathématique qui, au nom du label (par exemple |Exercice 1|), associe le marqueur de début
1314 (dans l'exemple |#[Exercice 1]|). La chaîne |#1| correspond aux occurrences de l'argument
1315 de cette fonction (c'est la syntaxe habituelle de TeX). De même pour |marker/end|.\footnote{Du point de vue de LaTeX, les deux fonctions passées en argument doivent être \emph{fully expandable}.}
1316
1317
1318 \bigskip
1319 Pour insérer une partie marquée d'un fichier, il suffit alors d'utiliser la clé
1320 \Definition{range} de |\PitonInputFile|.
1321
1322 \smallskip
1323 \begin{Verbatim}
1324 \PitonInputFile[~emphase#range = Exercice 1@]{~textsl#nom_du_fichier@}
1325 \end{Verbatim}
1326
1327 \medskip
1328 \begin{Piton}
1329 def fibo(n):
1330 if n==0: return 0
1331 else:
1332 u=0
1333 v=1
1334 for i in range(n-1):
1335 w = u+v
1336 u = v
1337 v = w
1338 return v
1339 \end{Piton}
1340
1341 \vspace{1cm} \index{marker/include-lines} La clé \Definition{marker/include-lines} demande
1342 que les lignes contenant les marqueurs soient également insérées.
1343
1344 \begin{Verbatim}
1345 \PitonInputFile[~emphase#marker/include-lines@,range = Exercice 1]{~textsl#nom_du_fichier@}
1346 \end{Verbatim}
1347
1348 \begin{Piton}
1349 #[Exercice 1] Version itérative
1350 def fibo(n):
1351 if n==0: return 0
1352 else:
1353 u=0
1354 v=1
1355 for i in range(n-1):
1356 w = u+v
1357 u = v
1358 v = w
1359 return v
1360 #<Exercice 1>
1361 \end{Piton}
1362
1363
1364 \bigskip
1365 \index{begin-range} \index{end-range} Il existe en fait aussi les clés
1366 \Definition{begin-range} et \Definition{end-range} pour insérer plusieurs contenus marqués
1367 simultanément.
1368
1369 Par exemple, pour insérer les solutions des exercices 3 à 5, on pourra écrire (à condition
1370 que le fichier soit structuré correctement!):
1371
1372 \begin{Verbatim}
1373 \PitonInputFile[~emphase#begin-range = Exercice 3, end-range = Exercice 5@]{~textsl#nom_du_fichier@}
1374 \end{Verbatim}
1375
1376
1377 \subsection{Exportation de listings}
1378
1379 À côté de la commande |\PitonInputFile| qui permet d'insérer dans le \textsc{pdf}
1380 tout ou partie d'un fichier extérieur, \pkg{piton} propose des outils pour exporter
1381 des listings inclus dans le fichier source LaTeX vers le disque ou bien en pièces jointes
1382 du \textsc{pdf} généré.
1383
1384 \begin{itemize}
1385 \item \index{write (clé)} La clé \Definition{write} prend en argument un nom de
1386 fichier (avec l'extension) et écrit le contenu\footnote{En fait, il ne s'agit
1387 pas exactement du contenu de l'environnement mais de la valeur renvoyée par
1388 l'instruction Lua |piton.get_last_code()| qui en est une version sans les
1389 surcharges de formatage LaTeX (voir la partie \ref{API}, p.~\pageref{API}).}
1390 de l'environnement courant dans ce fichier. À la première utilisation du fichier
1391 par \pkg{piton} (au cours d'une compilation avec LuaLaTeX), celui-ci est effacé.
1392 L'écriture du fichier ne se fait en fait qu'à la fin de la compilation avec LuaLaTeX.
1393
1394 Pour la lisibilité, \pkg{piton} fournit la clé \Definition{no-write} (sans valeur) comme
1395 alias de |write=|.
1396
1397 \item \index{path-write} La clé \Definition{path-write} indique un chemin où
1398 seront écrits les fichiers écrits par l'emploi de la clé |write| précédente.
1399
1400 \item \index{join (clé)}
1401 La clé \Definition{join} est similaire à la clé |write| mais les fichiers créés sont
1402 \emph{joints} (comme «pièces jointes») dans le \textsc{pdf}. Attention :
1403 certains lecteurs de \textsc{pdf} ne proposent pas d'outil permettant d'accéder à
1404 ces fichiers joints.
1405
1406
1407 Pour la lisibilité, \pkg{piton} fournit la clé \Definition{no-join} (sans valeur) comme
1408 alias de |join=|.
1409
1410
1411 \item \index{print (clé)}
1412 La clé \Definition{print} contrôle l'affichage effectif du contenu des
1413 environnements |{Piton}| dans le \textsc{pdf}. Bien entendu, la valeur initiale de cette
1414 clé est |true|. Néanmoins, dans certains circonstances, il peut être utile
1415 d'utiliser |print=false| (dans le cas, par exemple, où la clé |write|, ou bien
1416 la clé |join|, est utilisée).
1417
1418 \item \index{paperclip (clé)}
1419 La clé \Definition{paperclip} va, pour chaque environnement |{Piton}|, ajouter dans la marge
1420 droite une annotation \textsc{pdf} liée à un fichier joint dans le \textsc{pdf} correspondant
1421 au listing de l'environnement.
1422
1423 La valeur fournie à la clé |paperclip| est le nom qui sera donné au fichier joint. Si aucune
1424 valeur n'est fournie, le fichier sera nommé \texttt{listing_\textsl{i}.txt} où \textsl{i}
1425 est un compteur géré par \pkg{piton} incrémenté à chaque utilisation de la clé |paperclip|
1426 sans valeur.
1427
1428 \medskip
1429 \begin{Code}
1430 \begin{Piton}[\emph{paperclip},background-color=gray!15]
1431 def carré(x):
1432 """Calcule le carré de x"""
1433 return x*x
1434 \end{Piton}
1435 \end{Code}
1436
1437 \medskip
1438 \begin{Piton}[paperclip,background-color=gray!15]
1439 def carré(x):
1440 """Calcule le carré de x"""
1441 return x*x
1442 \end{Piton}
1443
1444
1445 \item \index{annotation (clé)}
1446 La clé \Definition{annotation} va, pour chaque environnement |{Piton}|, ajouter
1447 dans la marge droite une annotation \textsc{pdf} de type note contenant
1448 directement le listing de l'environnement |{Piton}|.
1449
1450 \medskip
1451 \begin{Code}
1452 \begin{Piton}[\emph{annotation},background-color=gray!15]
1453 def carré(x):
1454 """Calcule le carré de x"""
1455 return x*x
1456 \end{Piton}
1457 \end{Code}
1458
1459 \medskip
1460 \begin{Piton}[annotation,background-color=gray!15]
1461 def carré(x):
1462 """Calcule le carré de x"""
1463 return x*x
1464 \end{Piton}
1465
1466
1467 \end{itemize}
1468
1469 \section{Fonctionnalités avancées}
1470
1471 \subsection{La clé «box»}
1472
1473 \index{box (clé)}
1474 \label{box}
1475
1476
1477 \nobreak
1478 \smallskip
1479 Si on souhaite composer un listing dans une boîte de LaTeX, on doit utiliser la clé
1480 \Definition{box}. Cette clé prend comme valeur |c|, |t| ou |b| correspondant
1481 au paramètre de position verticale (comme dans un environnement |{minipage}| de LaTeX, qui
1482 crée aussi une boîte LaTeX). La valeur par défaut est |c| (comme pour |{minipage}|).
1483
1484 \smallskip
1485 L'emploi de la clé |box| active |width=min| (sauf, bien sûr, si on utilise
1486 explicitement |width| ou |max-width|). Pour les clés |width| et |max-width|,
1487 cf.~p.~\pageref{width}.
1488
1489
1490 \smallskip
1491 \begin{Code}
1492 \begin{center}
1493 \PitonOptions{\emph{box},background-color=gray!15}
1494 \begin{Piton}
1495 def square(x):
1496 return x*x
1497 \end{Piton}
1498 \hspace{1cm}
1499 \begin{Piton}
1500 def cube(x):
1501 return x*x*x
1502 \end{Piton}
1503 \end{center}
1504 \end{Code}
1505
1506 \begin{center}
1507 \PitonOptions{box,background-color=gray!15}
1508 \begin{Piton}
1509 def square(x):
1510 return x*x
1511 \end{Piton}
1512 \hspace{1cm}
1513 \begin{Piton}
1514 def cube(x):
1515 return x*x*x
1516 \end{Piton}
1517 \end{center}
1518
1519 \vspace{1cm} Il est possible d'utiliser la clé |box| avec une valeur numérique pour |width|
1520 (5~cm dans l'exemple qui suit).
1521
1522 \begin{Code}
1523 \begin{center}
1524 \PitonOptions{\emph{box,width=5cm},background-color=gray!15}
1525 \begin{Piton}
1526 def square(x):
1527 return x*x
1528 \end{Piton}
1529 \hspace{1cm}
1530 \begin{Piton}
1531 def cube(x):
1532 return x*x*x
1533 \end{Piton}
1534 \end{center}
1535 \end{Code}
1536
1537 \begin{center}
1538 \PitonOptions{box,width=5cm,background-color=gray!15}
1539 \begin{Piton}
1540 def square(x):
1541 return x*x
1542 \end{Piton}
1543 \hspace{1cm}
1544 \begin{Piton}
1545 def cube(x):
1546 return x*x*x
1547 \end{Piton}
1548 \end{center}
1549
1550
1551 \vspace{1cm}
1552 Voici un exemple avec la clé |max-width|, égale à 7~cm pour les deux listings.
1553
1554 \begin{Code}
1555 \begin{center}
1556 \PitonOptions{\emph{box=t,max-width=7cm},background-color=gray!15}
1557 \begin{Piton}
1558 def square(x):
1559 return x*x
1560 \end{Piton}
1561 \hspace{1cm}
1562 \begin{Piton}
1563 def P(x):
1564 return 24*x**8 - 7*x**7 + 12*x**6 -4*x**5 + 4*x**3 + x**2 - 5*x + 2
1565 \end{Piton}
1566 \end{center}
1567 \end{Code}
1568
1569 \begin{center}
1570 \PitonOptions{box=t,max-width=7cm,background-color=gray!15}
1571 \begin{Piton}
1572 def square(x):
1573 return x*x
1574 \end{Piton}
1575 \hspace{1cm}
1576 \begin{Piton}
1577 def P(x):
1578 return 24*x**8 - 7*x**7 + 12*x**6 -4*x**5 + 4*x**3 + x**2 - 5*x + 2
1579 \end{Piton}
1580 \end{center}
1581
1582
1583 \subsection{La clé «tcolorbox»}
1584
1585 \label{tcolorbox}
1586 \index{tcolorbox (clé)}
1587
1588 L'extension \pkg{piton} propose une clé \Definition{tcolorbox} qui facilite
1589 l'utilisation de l'extension \pkg{tcolorbox} en coordination avec l'extension
1590 \pkg{piton}. Néanmoins, l'extension \pkg{piton} ne charge \emph{pas} \pkg{tcolorbox}
1591 et l'utilisateur final doit l'avoir chargée. Il doit aussi avoir chargé la
1592 librairie |breakable| de \pkg{tcolorbox} avec |\tcbuselibrary{breakable}| dans le
1593 préambule du document LaTeX. Si ce n'est pas le cas, une erreur sera levée à la première
1594 utilisation de la clé |tcolorbox|.
1595
1596
1597 \bigskip
1598 Quand la clé |tcolorbox| est utilisée, le listing formaté par \pkg{piton} est
1599 inclus dans un environnement |{tcolorbox}|. Cela s'applique aussi bien à la
1600 commande |\PitonInputFile| qu'à un environnement |{Piton}| (ou, plus
1601 généralement, à un environnement défini par |\NewPitonEnvironment|:
1602 cf.~p.~\pageref{NewPitonEnvironment}). Dans le cas où la clé |splittable| de
1603 \pkg{piton} est utilisée (cf. p.~\pageref{coupure-de-pages}), la boîte graphique
1604 créée par \pkg{tcolorbox} sera sécable par un saut de page.
1605
1606 \bigskip
1607 Dans le présent document, on a, de plus, chargé, dans le préambule du document LaTeX,
1608 la librairie |skins| de \pkg{tcolorbox} et activé la \emph{skin} |enhanced| pour avoir
1609 une meilleure apparence au niveau du saut de page.
1610
1611 \begin{footnotesize}
1612 \begin{Verbatim}
1613 \tcbuselibrary{skins,breakable} % dans le préambule
1614 \tcbset{enhanced} % dans le préambule
1615 \end{Verbatim}
1616 \end{footnotesize}
1617
1618 \smallskip
1619 \begin{Code}
1620 \begin{Piton}\emph{[tcolorbox,splittable=3]}
1621 def carré(x):
1622 """Calcule le carré de x"""
1623 return x*x
1624 ...
1625 def carré(x):
1626 """Calcule le carré de x"""
1627 return x*x
1628 \end{Piton}
1629 \end{Code}
1630
1631 \begin{Piton}[tcolorbox,splittable=3]
1632 def carré(x):
1633 """Calcule le carré de x"""
1634 return x*x
1635 def carré(x):
1636 """Calcule le carré de x"""
1637 return x*x
1638 def carré(x):
1639 """Calcule le carré de x"""
1640 return x*x
1641 def carré(x):
1642 """Calcule le carré de x"""
1643 return x*x
1644 def carré(x):
1645 """Calcule le carré de x"""
1646 return x*x
1647 def carré(x):
1648 """Calcule le carré de x"""
1649 return x*x
1650 def carré(x):
1651 """Calcule le carré de x"""
1652 return x*x
1653 def carré(x):
1654 """Calcule le carré de x"""
1655 return x*x
1656 def carré(x):
1657 """Calcule le carré de x"""
1658 return x*x
1659 def carré(x):
1660 """Calcule le carré de x"""
1661 return x*x
1662 def carré(x):
1663 """Calcule le carré de x"""
1664 return x*x
1665 def carré(x):
1666 """Calcule le carré de x"""
1667 return x*x
1668 def carré(x):
1669 """Calcule le carré de x"""
1670 return x*x
1671 def carré(x):
1672 """Calcule le carré de x"""
1673 return x*x
1674 def carré(x):
1675 """Calcule le carré de x"""
1676 return x*x
1677 def carré(x):
1678 """Calcule le carré de x"""
1679 return x*x
1680 def carré(x):
1681 """Calcule le carré de x"""
1682 return x*x
1683 def carré(x):
1684 """Calcule le carré de x"""
1685 return x*x
1686 def carré(x):
1687 """Calcule le carré de x"""
1688 return x*x
1689 def carré(x):
1690 """Calcule le carré de x"""
1691 return x*x
1692 \end{Piton}
1693
1694
1695 Bien sûr, si on veut changer la couleur du fond, on n'utilise pas
1696 |background-color| de \pkg{piton} mais les outils fournis par \pkg{tcolorbox}
1697 (la clé |colback| pour la couleur du fond).
1698
1699
1700 \bigskip
1701 Si on souhaite ajuster la largeur de la boîte graphique au contenu, il suffit
1702 d'utiliser la clé |width=min| fournie par \pkg{piton} (cf. p.~\pageref{width}).
1703 On peut aussi utiliser |width| ou |max-width| avec une valeur numérique.
1704 L'environnement est sécable si la clé |splittable| est utilisée
1705 (cf. p.~\pageref{coupure-de-pages}).
1706
1707 \smallskip
1708 \begin{Code}
1709 \begin{Piton}\emph{[tcolorbox,width=min,splittable=3]}
1710 def carré(x):
1711 """Calcule le carré de x"""
1712 return x*x
1713 ...
1714 def carré(x):
1715 """Calcule le carré de x"""
1716 return x*x
1717 \end{Piton}
1718 \end{Code}
1719
1720 \smallskip
1721 \begin{Piton}[tcolorbox,width=min,splittable=3]
1722 def carré(x):
1723 """Calcule le carré de x"""
1724 return x*x
1725 def carré(x):
1726 """Calcule le carré de x"""
1727 return x*x
1728 def carré(x):
1729 """Calcule le carré de x"""
1730 return x*x
1731 def carré(x):
1732 """Calcule le carré de x"""
1733 return x*x
1734 def carré(x):
1735 """Calcule le carré de x"""
1736 return x*x
1737 def carré(x):
1738 """Calcule le carré de x"""
1739 return x*x
1740 def carré(x):
1741 """Calcule le carré de x"""
1742 return x*x
1743 def carré(x):
1744 """Calcule le carré de x"""
1745 return x*x
1746 def carré(x):
1747 """Calcule le carré de x"""
1748 return x*x
1749 def carré(x):
1750 """Calcule le carré de x"""
1751 return x*x
1752 def carré(x):
1753 """Calcule le carré de x"""
1754 return x*x
1755 def carré(x):
1756 """Calcule le carré de x"""
1757 return x*x
1758 def carré(x):
1759 """Calcule le carré de x"""
1760 return x*x
1761 def carré(x):
1762 """Calcule le carré de x"""
1763 return x*x
1764 \end{Piton}
1765
1766
1767
1768 \bigskip
1769 Si on souhaite que le résultat soit produit dans une boîte LaTeX (en dépit de son nom,
1770 un environnement de \pkg{tcolorbox} n'est pas nécessairement une boîte LaTeX),
1771 il suffit d'utiliser, conjointement avec la clé |tcolorbox|, la clé |box| fournie
1772 par \pkg{piton} (cf. p.~\pageref{box}). Bien sûr, la boîte LaTeX ainsi créée ne sera \emph{pas}
1773 sécable par un saut de page (comme toutes les boîtes de LaTeX), même si la clé |splittable|
1774 (cf.~p.~\pageref{splittable}) est active.
1775
1776 On rappelle que l'emploi de la clé |box| active |width=min| (sauf si on utilise
1777 explicitement |width| ou |max-width|).
1778
1779 \smallskip
1780 \begin{Code}
1781 \begin{center}
1782 \PitonOptions{\emph{tcolorbox,box=t}}
1783 \begin{Piton}
1784 def square(x):
1785 return x*x
1786 \end{Piton}
1787 \hspace{1cm}
1788 \begin{Piton}
1789 def cube(x):
1790 """Le cube de x"""
1791 return x*x*x
1792 \end{Piton}
1793 \end{center}
1794 \end{Code}
1795
1796 \begin{center}
1797 \PitonOptions{tcolorbox,box=t}%
1798 \begin{Piton}
1799 def square(x):
1800 return x*x
1801 \end{Piton}
1802 \hspace{1cm}
1803 \begin{Piton}
1804 def cube(x):
1805 """Le cube de x"""
1806 return x*x*x
1807 \end{Piton}
1808 \end{center}
1809
1810 \bigskip
1811 Pour un exemple plus sophistiqué d'utilisation de la clé |tcolorbox|, voir l'exemple fourni
1812 à la page~\pageref{examples-tcolorbox}.
1813
1814
1815
1816
1817 \subsection{Coupure des lignes et des pages}
1818
1819 \label{breakable}
1820
1821 \subsubsection{Coupure des lignes}
1822
1823 \label{line-breaks}
1824
1825 Il existe des clés pour contrôler les coupures de ligne (les points de coupure
1826 possibles sont les espaces, y compris les espaces qui sont dans les chaînes de
1827 caractères des langages informatiques).
1828 \begin{itemize}
1829 \item \index{break-lines!break-lines-in-piton} Avec la clé
1830 \Definition{break-lines-in-piton}, les coupures de ligne sont autorisées dans la commande
1831 |\piton{...}| (mais pas dans la commande \verb+\piton|...|+, c'est-à-dire avec la syntaxe
1832 verbatim).
1833
1834 \item \index{break-lines!break-lines-in-Piton} Avec la clé
1835 \Definition{break-lines-in-Piton}, les coupures de ligne sont autorisées dans
1836 l'environnement |{Piton}| (d'où la lettre |P| capitale dans le nom) et les
1837 listings produits par |\PitonInputFile|. {\bfseries La valeur initiale de ce paramètre est
1838 |true| (et non |false|).}
1839
1840 \item \index{break-lines} La clé \Definition{break-lines} est la conjonction des deux clés
1841 précédentes.
1842 \end{itemize}
1843
1844 \medskip
1845 L'extension \pkg{piton} fournit aussi plusieurs clés pour contrôler l'apparence des
1846 coupures de ligne autorisées par |break-lines-in-Piton|.
1847
1848 \begin{itemize}
1849 \item \index{indent-broken-lines} Avec la clé \Definition{indent-broken-lines},
1850 l'indentation de la ligne coupée est respectée à chaque retour à la ligne (à condition que
1851 la fonte utilisée soit une fonte mono-chasse, ce qui est le cas par défaut puisque la
1852 valeur initiale de |font-command| est |\ttfamily|).
1853
1854 \item \index{end-of-broken-line} La clé \Definition{end-of-broken-line} correspond au
1855 symbole placé à la fin d'une ligne coupée. Sa valeur initiale est :
1856 |\hspace*{0.5em}\textbackslash|.
1857
1858 \item \index{continuation-symbol} La clé \Definition{continuation-symbol} correspond au
1859 symbole placé à chaque retour de ligne dans la marge gauche. Sa valeur initiale est :
1860 |+\;| (la commande |\;| insère un petit espace horizontal).
1861
1862 \item \index{continuation-symbol-on-indentation} La clé
1863 \Definition{continuation-symbol-on-indentation} correspond au symbole placé à chaque
1864 retour de ligne au niveau de l'indentation (uniquement dans le cas où la clé
1865 |indent-broken-lines| est active). Sa valeur initiale est : |$\hookrightarrow\;$|.
1866 \end{itemize}
1867
1868 \bigskip
1869 Le code suivant a été composé avec le réglage suivant :
1870
1871 \begin{Verbatim}
1872 \PitonOptions{width=12cm,indent-broken-lines,background-color=gray!15}
1873 \end{Verbatim}
1874
1875
1876 \begin{center}
1877 \PitonOptions{width=12cm,indent-broken-lines,background-color=gray!15}
1878 \begin{Piton}
1879 def dict_of_liste(liste):
1880 """Convertit une liste de subrs et de descriptions de glyphes en dictionnaire"""
1881 dict = {}
1882 for liste_lettre in liste:
1883 if (liste_lettre[0][0:3] == 'dup'): # si c'est un subr
1884 nom = liste_lettre[0][4:-3]
1885 print("On traite le subr de numéro " + nom)
1886 else:
1887 nom = liste_lettre[0][1:-3] # si c'est un glyphe
1888 print("On traite le glyphe du caractère " + nom)
1889 dict[nom] = [traite_ligne_Postscript(k) for k in liste_lettre[1:-1]]
1890 return dict
1891 \end{Piton}
1892 \end{center}
1893
1894
1895 \bigskip
1896 Avec la clé \Definition{break-strings-anywhere}, les chaînes de caractères pourront être
1897 coupées n'importe où (et pas seulement sur les espaces).
1898
1899
1900 \bigskip
1901 Avec la clé \Definition{break-numbers-anywhere}, les nombres peuvent être coupés n'importe où.
1902
1903
1904 \subsubsection{Coupure des pages}
1905
1906 \label{splittable}
1907 \label{coupure-de-pages}
1908 \index{splittable}
1909 \index{splittable-on-empty-lines}
1910
1911
1912 Par défaut, les listings produits par l'environnement |{Piton}| et par la commande
1913 |\PitonInputFile| sont insécables.
1914
1915
1916 Néanmoins, \pkg{piton} propose les clés |splittable-on-empty-lines| et |splittable| pour
1917 autoriser de telles coupures.
1918
1919 \begin{itemize}
1920 \item La clé \Definition{splittable-on-empty-lines} autorise les coupures sur les lignes
1921 vides du listing. Les lignes considérées comme vides sont celles qui ne comportent que des
1922 espaces (et il aurait peut-être été plus habile de parler de lignes blanches).
1923
1924 \medskip
1925 \item La clé |splittable-on-empty-lines| peut bien sûr être insuffisante et c'est pourquoi
1926 \pkg{piton} propose la clé \Definition{splittable}.
1927
1928 Quand la clé |splittable| est utilisée avec la valeur numérique $n$ (qui doit être un
1929 entier naturel non nul) le listing pourra être coupé n'importe où avec cette exception
1930 qu'aucune coupure ne pourra avoir lieu entre les $n$~premières lignes, ni entre les
1931 $n$~dernières.\footnote{Remarquer que l'on parle des lignes du listing d'origine, une
1932 telle ligne pouvant être composée sur plusieurs lignes dans le \textsc{pdf} final (quand la
1933 clé |break-lines-in-Piton| est active).}
1934
1935 Par exemple, |splittable = 4| pourrait être un réglage raisonnable.
1936
1937 Employée sans argument, la clé |splittable| est équivalente à |splittable = 1|, et les
1938 listings sont alors sécables n'importe où (ce n'est pas recommandable).
1939
1940 La valeur initiale de la clé |splittable| vaut 100, ce qui fait que les listings ne sont
1941 pas sécables.
1942 \end{itemize}
1943
1944 \medskip
1945 \begin{tcolorbox}[breakable]
1946 Même avec une couleur de fond (fixée avec |background-color|), les sauts de page sont
1947 possibles, à partir du moment où |splittable-on-empty-lines| ou |splittable| est
1948 utilisée.
1949
1950 \medskip
1951 Avec la clé |splittable|, un environnement |{Piton}| est sécable même dans un
1952 environnement de \pkg{tcolorbox} (à partir du moment où la clé |breakable| de
1953 \pkg{tcolorbox} est utilisée). On précise cela parce que, en revanche, un
1954 environnement de \pkg{tcolorbox} inclus dans un autre environnement de
1955 \pkg{tcolorbox} n'est pas sécable, même quand les deux utilisent la clé
1956 |breakable| de \pkg{tcolorbox}.
1957
1958 \medskip
1959 On illustre ce point avec le code suivant (l'environnement |{tcolorbox}| dans lequel nous
1960 nous trouvons utilise la clé |breakable|).
1961
1962 \medskip
1963 \begin{Code}
1964 \begin{Piton}\emph{[background-color=gray!30,rounded-corners,
1965 width=min,splittable=4]}
1966 def carré(x):
1967 """Calcule le carré de x"""
1968 return x*x
1969 def carré(x):
1970 """Calcule le carré de x"""
1971 return x*x
1972 ...
1973 def carré(x):
1974 """Calcule le carré de x"""
1975 return x*x
1976 \end{Piton}
1977 \end{Code}
1978
1979 \bigskip
1980 \begin{Piton}[background-color=gray!30,rounded-corners,width=min,splittable=4]
1981 def carré(x):
1982 """Calcule le carré de x"""
1983 return x*x
1984 def carré(x):
1985 """Calcule le carré de x"""
1986 return x*x
1987 def carré(x):
1988 """Calcule le carré de x"""
1989 return x*x
1990 def carré(x):
1991 """Calcule le carré de x"""
1992 return x*x
1993 def carré(x):
1994 """Calcule le carré de x"""
1995 return x*x
1996 def carré(x):
1997 """Calcule le carré de x"""
1998 return x*x
1999 def carré(x):
2000 """Calcule le carré de x"""
2001 return x*x
2002 def carré(x):
2003 """Calcule le carré de x"""
2004 return x*x
2005 def carré(x):
2006 """Calcule le carré de x"""
2007 return x*x
2008 def carré(x):
2009 """Calcule le carré de x"""
2010 return x*x
2011 def carré(x):
2012 """Calcule le carré de x"""
2013 return x*x
2014 def carré(x):
2015 """Calcule le carré de x"""
2016 return x*x
2017 def carré(x):
2018 """Calcule le carré de x"""
2019 return x*x
2020 def carré(x):
2021 """Calcule le carré de x"""
2022 return x*x
2023 def carré(x):
2024 """Calcule le carré de x"""
2025 return x*x
2026 \end{Piton}
2027
2028 \end{tcolorbox}
2029
2030 \bigskip
2031 \subsection{Découpe d'un listing en sous-listings}
2032
2033 \index{split-on-empty-lines}
2034 \label{split-on-empty-lines}
2035 \index{split-separation}
2036 \index{env-used-by-split}
2037
2038 L'exension \pkg{piton} fournit la clé \Definition{split-on-empty-lines}, qui ne doit pas
2039 être confondue avec la clé |splittable-on-empty-lines| définie précédemment.
2040
2041 \smallskip
2042 Pour comprendre le fonctionnement de la clé |split-on-empty-lines|, il faut imaginer que
2043 l'on a à composer un fichier informatique qui contient une succession de définitions de
2044 fonctions informatiques. Dans la plupart des langages informatiques, ces définitions
2045 successives sont séparées par des lignes vides (ou plutôt des lignes blanches,
2046 c'est-à-dire des lignes qui ne contiennent que des espaces).
2047
2048 \smallskip
2049 La clé |split-on-empty-lines| coupe le listing au niveau des lignes vides. Les lignes
2050 vides successives sont supprimées et remplacées par le contenu du paramètre correspondant
2051 à la clé \Definition{split-separation}.
2052 \begin{itemize}
2053 \item Ce paramètre doit contenir du matériel à insérer en \emph{mode vertical} de TeX. On
2054 peut, par exemple, mettre la primitive TeX |\hrule|.
2055
2056 \item La valeur initiale de ce paramètre est
2057 |\vspace{\baselineskip}\vspace{-1.25pt}|, ce qui, au final, correspond à une
2058 ligne vide dans le \textsc{pdf} produit (cet espace vertical est supprimé s'il tombe au
2059 niveau d'un saut de page).
2060
2061 \item L'extension \pkg{piton} propose en fait aussi la clé \Definition{split-separation~+} qui ajoute
2062 du contenu à droite de |split-separation|. Le nom de cette clé contient un espace
2063 de manière à pouvoir écrire, par exemple : |split-separation += \hrule|.
2064 \end{itemize}
2065
2066 Chaque morceau du code informatique est formaté (de manière autonome) dans un
2067 environnement dont le nom est donné par la clé \Definition{env-used-by-split}.
2068 La valeur initiale de ce paramètre est, sans surprise, |Piton| et les différents
2069 morceaux sont donc composés dans des environnements |{Piton}|. Si on décide de
2070 donner une autre valeur à la clé |env-used-by-split|, on doit bien sûr donner le
2071 nom d'un environnement créé par |\NewPitonEnvironment|
2072 (cf.~partie~\ref{NewPitonEnvironment}, p.~\pageref{NewPitonEnvironment}).
2073
2074 \smallskip
2075 Chaque morceau du listing de départ étant composé dans son environnement, il dispose de sa
2076 propre numérotation des lignes (si la clé |line-numbers| est active) et de son propre fond
2077 coloré (si la clé |background-color| est utilisée), séparé des fonds des autres morceaux.
2078 Si elle est active, la clé |splittable| s'applique de manière autonome dans chaque
2079 morceau. Bien sûr, des sauts de page peuvent intervenir entre les différents morceaux du
2080 code, quelle que soit la valeur de la clé |splittable|.
2081
2082 \bigskip
2083 \begin{Code}
2084 \begin{Piton}[\emph{split-on-empty-lines},background-color=gray!15,line-numbers]
2085 def carré(x):
2086 """Calcule le carré de x"""
2087 return x*x
2088
2089 def cube(x):
2090 """Calcule le cube de x"""
2091 return x*x*x
2092 \end{Piton}
2093 \end{Code}
2094
2095 \medskip
2096 \begin{Piton}[split-on-empty-lines,background-color=gray!15,line-numbers]
2097 def carré(x):
2098 """Calcule le carré de x"""
2099 return x*x
2100
2101 def cube(x):
2102 """Calcule le cube de x"""
2103 return x*x*x
2104 \end{Piton}
2105
2106
2107 \vspace{5mm}
2108 Si on souhaite au contraire une continuité de numérotation, on peut ajouter
2109 |\PitonOptions{resume}| au paramètre |split-separation| :
2110
2111 \bigskip
2112 \begin{Code}
2113 \begin{Piton}[
2114 split-on-empty-lines,
2115 \emph{split-separation += \PitonOptions{resume}} ,
2116 background-color=gray!15,
2117 line-numbers
2118 ]
2119 def carré(x):
2120 """Calcule le carré de x"""
2121 return x*x
2122
2123 def cube(x):
2124 """Calcule le cube de x"""
2125 return x*x*x
2126 \end{Piton}
2127 \end{Code}
2128
2129 \medskip
2130 \begin{Piton}[
2131 split-on-empty-lines,
2132 split-separation += \PitonOptions{resume} ,
2133 background-color=gray!15,
2134 line-numbers
2135 ]
2136 def carré(x):
2137 """Calcule le carré de x"""
2138 return x*x
2139
2140 def cube(x):
2141 """Calcule le cube de x"""
2142 return x*x*x
2143 \end{Piton}
2144
2145
2146 \bigskip
2147 \textbf{Attention} : Comme chaque morceau est traité de manière indépendante, les
2148 commandes spécifiées par |detected-commands| ou |raw-detected-commands|
2149 (cf.~p.~\pageref{detected-commands}) et les commandes et environnements de Beamer
2150 automatiquement détectés par \pkg{piton} ne doivent pas enjamber les lignes vides du
2151 listing de départ.
2152
2153
2154
2155 \bigskip
2156 \subsection{Mise en évidence d'identificateurs}
2157
2158 \indexcommand{SetPitonIdentifier}
2159 \label{SetPitonIdentifier}
2160
2161 La commande \DefinitionCommand{SetPitonIdentifier} permet de changer automatiquement le
2162 formatage de certains identificateurs en se fondant sur leur nom.
2163
2164 \smallskip
2165 Cette commande prend trois arguments : un optionnel et deux obligatoires.
2166
2167 \begin{itemize}
2168 \item L'argument optionnel (entre crochets) indique le langage (informatique) concerné ;
2169 si cet argument est absent, les réglages faits par |\SetPitonIdentifier| s'appliqueront à
2170 tous les langages.\footnote{On rappelle que, dans \pkg{piton}, les noms des langages
2171 informatiques ne sont pas sensibles à la casse.}
2172
2173 \item Le premier argument obligatoire est une liste de noms d'identificateurs séparés par
2174 des virgules.
2175
2176 \item Le deuxième argument obligatoire est une liste d'instructions LaTeX de formatage du
2177 même type que pour les styles précédemment définis (cf. \ref{styles},
2178 p.~\pageref{styles}).
2179
2180
2181 \end{itemize}
2182
2183 \emph{Attention} : Seuls les identificateurs peuvent voir leur formatage affecté. Les
2184 mots-clés et les noms de fonctions prédéfinies ne seront pas affectés, même s'ils figurent
2185 dans le premier argument de |\SetPitonIdentifier|.
2186
2187 \medskip
2188 \begin{Code}
2189 \emph{\SetPitonIdentifier{l1,l2}{\color{red}}}
2190 \begin{Piton}
2191 def tri(l):
2192 """Tri par segmentation"""
2193 if len(l) <= 1:
2194 return l
2195 else:
2196 a = l[0]
2197 l1 = [ x for x in l[1:] if x < a ]
2198 l2 = [ x for x in l[1:] if x >= a ]
2199 return tri(l1) + [a] + tri(l2)
2200 \end{Piton}
2201 \end{Code}
2202
2203
2204 \bigskip
2205
2206 \begingroup
2207
2208 \SetPitonIdentifier{l1,l2}{\color{red}}
2209
2210 \begin{Piton}
2211 def tri(l):
2212 """Tri par segmentation"""
2213 if len(l) <= 1:
2214 return l
2215 else:
2216 a = l[0]
2217 l1 = [ x for x in l[1:] if x < a ]
2218 l2 = [ x for x in l[1:] if x >= a ]
2219 return tri(l1) + [a] + tri(l2)
2220 \end{Piton}
2221
2222 \endgroup
2223
2224 \bigskip
2225 Avec la commande |\SetPitonIdentifiers|, on peut ajouter à un langage informatique de
2226 nouvelles fonctions prédéfinies (ou de nouveaux mots-clés, etc.) qui seront détectées par
2227 \pkg{piton}.
2228
2229 \medskip
2230 \begin{Code}
2231 \emph{\SetPitonIdentifier[Python]}
2232 {cos, sin, tan, floor, ceil, trunc, pow, exp, ln, factorial}
2233 {\PitonStyle{Name.Builtin}}
2234
2235 \begin{Piton}
2236 from math import *
2237 cos(pi/2)
2238 factorial(5)
2239 ceil(-2.3)
2240 floor(5.4)
2241 \end{Piton}
2242 \end{Code}
2243
2244
2245
2246 \medskip
2247 \begingroup
2248
2249 \SetPitonIdentifier[Python]
2250 {cos, sin, tan, floor, ceil, trunc, pow, exp, ln, factorial}
2251 {\PitonStyle{Name.Builtin}}
2252
2253 \begin{Piton}
2254 from math import *
2255 cos(pi/2)
2256 factorial(5)
2257 ceil(-2.3)
2258 floor(5.4)
2259 \end{Piton}
2260
2261
2262 \endgroup
2263
2264
2265
2266 \subsection{Les échappements vers LaTeX}
2267
2268 \index{echappements@échappements vers LaTeX}
2269 \label{LaTeX-escapes}
2270
2271 L'extension \pkg{piton} propose plusieurs mécanismes d'échappement vers LaTeX :
2272 \begin{itemize}
2273 \item Il est possible d'avoir des commentaires entièrement composés en LaTeX.
2274 \item Il est possible d'avoir, dans les commentaires, les éléments entre
2275 \texttt{\$} composés en mode mathématique de LaTeX.
2276 \item Il est possible de demander à \pkg{piton} de détecter directement certaines
2277 commandes LaTeX avec leur argument.
2278 \item Il est possible d'insérer du code LaTeX à n'importe quel endroit d'un listing.
2279 \end{itemize}
2280 Ces mécanismes vont être détaillés dans les sous-parties suivantes.
2281
2282 \smallskip
2283 À remarquer également que, dans le cas où \pkg{piton} est utilisée dans la classe
2284 \cls{beamer}, \pkg{piton} détecte la plupart des commandes et environnements de Beamer :
2285 voir la sous-section \ref{beamer}, p.~\pageref{beamer}.
2286
2287
2288
2289 \subsubsection{Les «commentaires LaTeX»}
2290
2291 \index{comment-latex}
2292 \index{commentaires LaTeX}
2293
2294 Dans ce document, on appelle «commentaire LaTeX» des commentaires qui débutent par |#>|.
2295 Tout ce qui suit ces deux caractères, et jusqu'à la fin de la ligne, sera composé comme du
2296 code LaTeX standard.
2297
2298 Il y a deux outils pour personnaliser ces commentaires.
2299
2300 \begin{itemize}
2301 \item Il est possible de changer le marquage syntaxique utilisé (qui vaut
2302 initialement~|#>|). Pour ce faire, il existe une clé \Definition{comment-latex},
2303 \emph{disponible uniquement dans le préambule du document}, qui permet de choisir les
2304 caractères qui (précédés par~|#|) serviront de marqueur syntaxique.
2305
2306 Par exemple, avec le réglage suivant (fait dans le préambule du document) :
2307
2308 |\PitonOptions{comment-latex = LaTeX}|
2309
2310 les commentaires LaTeX commenceront par~|#LaTeX|.
2311
2312 Si on donne la valeur nulle à la clé |comment-latex|, tous les commentaires Python
2313 (débutant par~|#|) seront en fait des «commentaires LaTeX».
2314
2315 \smallskip
2316 \item Il est possible de changer le formatage du commentaire LaTeX lui-même en changeant
2317 le style \pkg{piton} |Comment.LaTeX|.
2318
2319 Par exemple, avec |\SetPitonStyle{Comment.LaTeX = \normalfont\color{blue}}|, les
2320 commentaires LaTeX seront composés en bleu.
2321
2322 Si on souhaite qu'un croisillon (|#|) soit affiché en début de commentaire dans le
2323 \textsc{pdf}, on peut régler |Comment.LaTeX| de la manière suivante :
2324
2325 \begin{Verbatim}
2326 \SetPitonStyle{Comment.LaTeX = \color{gray}\~#\normalfont\space }
2327 \end{Verbatim}
2328
2329 Pour d'autres exemples de personnalisation des commentaires LaTeX, voir la partie \ref{example-comments}
2330 p.~\pageref{example-comments}.
2331 \end{itemize}
2332
2333
2334 \bigskip
2335 \indexcommand{zlabel}
2336 \indexcommand{zcref}
2337 \index{label-as-zlabel}
2338 Si l'utilisateur a demandé l'affichage des numéros de ligne avec |line-numbers|, il est
2339 possible de faire référence à ce numéro de ligne avec la commande |\label| placée dans un
2340 commentaire LaTeX.\footnote{Cette fonctionnalité est implémentée en redéfinissant, dans
2341 les environnements |{Piton}|, la commande |\label|. Il peut donc y avoir des
2342 incompatibilités avec les extensions qui redéfinissent (globalement) cette commande
2343 |\label| (comme \pkg{varioref}, \pkg{refcheck}, \pkg{showlabels}, etc.)}
2344 De même, la commande |\zlabel| du paquetage \pkg{zref} peut être utilisée.\footnote{
2345 Y compris la commande |\zcref| de \pkg{zref-clever}.}
2346 La clé |label-as-zlabel| qui est disponible dans |\PitonOptions| dans le préambule du document
2347 permet d'utiliser |\label| à la place de |\zlabel| dans les commentaires LaTeX (ce qui est
2348 le comportement par défaut de \pkg{zref} en général).
2349
2350 \subsubsection{La clé «math-comments»}
2351
2352 \index{math-comments}
2353
2354 Il est possible de demander que, dans les commentaires, les éléments placés
2355 entre symboles \texttt{\$} soient composés en mode mathématique de LaTeX (le
2356 reste du commentaire restant composé en verbatim).
2357
2358 La clé \Definition{math-comments} (\emph{qui ne peut être activée que dans le préambule du
2359 document}) active ce comportement.
2360
2361 \bigskip
2362 Dans l'exemple suivant, on suppose que |\PitonOptions{math-comments}| a été utilisé dans
2363 le préambule du document.
2364
2365 \begin{Verbatim}
2366 \begin{Piton}
2367 def carré(x):
2368 return x*x ~# renvoie $x^2$
2369 \end{Piton}
2370 \end{Verbatim}
2371
2372 \begin{Piton}
2373 def carré(x):
2374 return x*x # renvoie $x^2$
2375 \end{Piton}
2376
2377
2378
2379 \subsubsection{La clé «detected-commands» et ses variantes}
2380
2381 \index{detected-commands (clé)}
2382 \index{raw-detected-commands (clé)}
2383 \index{vertical-detected-commands (clé)}
2384 \label{detected-commands}
2385 \label{raw-detected-commands}
2386 \label{vertical-detected-commands}
2387
2388 La clé \Definition{detected-commands} de |\PitonOptions| permet de spécifier une liste de
2389 noms de commandes LaTeX qui seront directement détectées par \pkg{piton}.
2390
2391 \begin{itemize}
2392 \item Cette clé |detected-commands| ne peut être utilisée que dans le préambule du
2393 document.
2394
2395 \item Les noms de commandes LaTeX peuvent apparaître \emph{avec} ou \emph{sans}
2396 la contre-oblique (ex. : |detected-commands = { \emph , textbf }|).
2397
2398 \item Ces commandes doivent être des commandes LaTeX à un seul argument obligatoire entre
2399 accolades (et ces accolades doivent apparaître explicitement dans le listing).
2400
2401 \item Ces commandes doivent être des commandes qui s'exécutent en mode horizontal de LaTeX
2402 (à l'intérieur d'une ligne de code).
2403
2404 \item Ces commandes doivent être \textbf{protégées}\footnote{On rappelle que, par défaut,
2405 |\NewDocumentCommand| crée des commandes protégées au contraire de la commande
2406 historique |\newcommand| de LaTeX (et de |\def| de TeX).} contre le développement au
2407 sens de TeX (car la commande |\piton| développe son argument avant de le passer à Lua pour
2408 analyse syntaxique).
2409 \end{itemize}
2410
2411 \medskip
2412 Dans l'exemple suivant, qui est une programmation récursive en C de la
2413 factorielle, on décide de surligner en jaune l'appel récursif. La commande
2414 |\highLight| de \pkg{lua-ul}\footnote{L'extension \pkg{lua-ul} requiert
2415 elle-même l'extension \pkg{luacolor}.} permet de le faire facilement.
2416
2417 \begin{footnotesize}
2418 \begin{Verbatim}
2419 \PitonOptions{~emphase#detected-commands@ = \highLight} % dans le préambule
2420 \end{Verbatim}
2421 \end{footnotesize}
2422
2423 \begin{Verbatim}
2424 \begin{Piton}[language=C]
2425 int factorielle(int n)
2426 {
2427 if (n > 0) ~emphase#\highLight{return n * factorielle(n - 1)}@ ;
2428 else return 1;
2429 }
2430 \end{Piton}
2431 \end{Verbatim}
2432
2433 \begin{Piton}[language=C]
2434 int factorielle(int n)
2435 {
2436 if (n > 0) \highLight{return n * factorielle(n - 1)} ;
2437 else return 1;
2438 }
2439 \end{Piton}
2440
2441 \bigskip
2442 La clé \Definition{raw-detected-commands} est similaire à la clé |detected-commands| mais
2443 \pkg{piton} ne fera pas d'analyse syntaxique des arguments des commandes LaTeX ainsi
2444 détectées.
2445
2446 S'il y a un retour à la ligne dans un argument d'une commande faisant l'objet d'un
2447 |raw-detected-commands|, celui-ci sera remplacé par une espace comme le fait LaTeX par
2448 défaut.
2449
2450 \medskip
2451 Supposons, par exemple, que l'on souhaite, dans le texte courant d'un document
2452 traitant des bases de données, introduire des spécifications de tables
2453 \textsc{sql} par le nom de la table, suivi, entre parenthèses, par les noms de
2454 ses champs (ex. : |client (non, prénom)|).
2455
2456 Si on insère cet élément dans une commande |\piton|, le mot \emph{client} ne va pas
2457 être reconnu comme un nom de table mais comme un nom de champ. On peut définir
2458 une commande personnelle |\NomTable|
2459 à appliquer à la main aux noms des tables. Pour cela, on la déclare avec
2460 |raw-detected-commands| pour que son argument ne soit pas réanalysé par \pkg{piton}
2461 (cette réanalyse entraînerait son formatage comme un nom de champ).
2462
2463
2464 \medskip
2465 Dans le préambule du document LaTeX, on insère les lignes suivantes :
2466 \begin{Verbatim}
2467 \NewDocumentCommand{\NomTable}{m}{{\PitonStyle{Name.Table}{~#1}}}
2468 \PitonOptions{language=SQL, ~emphase#raw-detected-commands = \NomTable@}
2469 \end{Verbatim}
2470
2471 Dans le corps du document, l'instruction :
2472
2473 \begin{Verbatim}
2474 Exemple : \piton{\NomTable{client} (nom, prénom)}
2475 \end{Verbatim}
2476
2477 \NewDocumentCommand{\NomTable}{m}{{\PitonStyle{Name.Table}{#1}}}
2478
2479 donne alors le résultat suivant :
2480
2481 \smallskip
2482 \begingroup
2483 \PitonOptions{language=SQL}%
2484 Exemple : \piton{\NomTable{client} (nom, prénom)}
2485 \endgroup
2486
2487
2488 \bigskip
2489 La clé \Definition{vertical-detected-commands} est similaire à la clé
2490 |raw-detected-commands| mais les commandes ainsi détectées doivent être des
2491 commandes LaTeX (à un argument) qui s'exécutent en mode vertical entre les lignes
2492 du listing.
2493
2494 \smallskip
2495 On peut par exemple demander la détection de |\newpage| par
2496
2497 \begin{Verbatim}
2498 \PitonOptions{~emphase#vertical-detected-commands@ = \newpage}
2499 \end{Verbatim}
2500
2501 et demander dans un listing un saut de page obligatoire par |\newpage{}| (la paire
2502 d'accolades |{}| est obligatoire car les commandes détectées par \pkg{piton} sont censées
2503 être des commandes LaTeX à un seul argument obligatoire).
2504
2505 \medskip
2506 \begin{Code}
2507 \begin{Piton}
2508 def carré(x):
2509 return x*x \emph{\textbackslash{}newpage{}}
2510 def cube(x):
2511 return x*x*x
2512 \end{Piton}
2513 \end{Code}
2514
2515 \medskip
2516 On peut aussi envisager de demander la détection de la commande |\vspace|.
2517
2518 \subsubsection{Le mécanisme «escape»}
2519
2520 \index{begin-escape}
2521 \index{end-escape}
2522 \label{escape}
2523
2524 Il est aussi possible de surcharger les listings informatiques pour y insérer du code
2525 LaTeX à peu près n'importe où (mais entre deux lexèmes, bien entendu). Cette
2526 fonctionnalité n'est pas activée par défaut par \pkg{piton}. Pour l'utiliser, il faut
2527 spécifier les deux délimiteurs marquant l'échappement (le premier le commençant et le
2528 deuxième le terminant) en utilisant les clés \Definition{begin-escape} et
2529 \Definition{end-escape} (\emph{qui ne sont accessibles que dans le préambule du
2530 document}). Les deux délimiteurs peuvent être identiques.
2531
2532 \medskip
2533 On reprend l'exemple précédent de la factorielle et on souhaite surligner en rose
2534 l'instruction qui contient l'appel récursif. La commande |\highLight| de \pkg{lua-ul}
2535 permet de le faire avec la syntaxe |\highLight[LightPink]{...}|. Du fait de la présence de
2536 l'argument optionnel entre crochets, on ne peut pas utiliser la clé |detected-commands|
2537 comme précédemment mais on peut utiliser le mécanisme «escape» qui est plus général.
2538
2539 \smallskip
2540 \begin{small}
2541 \begin{Verbatim}
2542 \PitonOptions{~emphase#begin-escape=!,end-escape=!@} % dans le préambule du document LaTeX
2543 \end{Verbatim}
2544 \end{small}
2545
2546 \medskip
2547 \begin{Verbatim}
2548 \begin{Piton}
2549 def fact(n):
2550 if n==0:
2551 return 1
2552 else:
2553 ~emphase#!\highLight[LightPink]{!@return n*fact(n-1)~emphase#!}!@
2554 \end{Piton}
2555 \end{Verbatim}
2556
2557 \medskip
2558 \begin{Piton}
2559 def fact(n):
2560 if n==0:
2561 return 1
2562 else:
2563 ?\highLight[LightPink]{?return n*fact(n-1)?}?
2564 \end{Piton}
2565
2566
2567
2568 \bigskip
2569 \emph{Attention} : Le mécanisme «escape» n'est pas actif dans les chaînes de caractères ni
2570 dans les commentaires (pour avoir un commentaire entièrement en échappement vers LaTeX,
2571 c'est-à-dire ce qui est appelé dans ce document «commentaire LaTeX», il suffit de le faire
2572 débuter par |#>|).
2573
2574
2575 \subsubsection{Le mécanisme «escape-math»}
2576
2577 \index{escape-math}
2578 \index{begin-escape-math}
2579 \index{end-escape-math}
2580
2581 Le mécanisme «escape-math» est très similaire au mécanisme «escape» puisque la seule
2582 différence est que les éléments en échappement LaTeX y sont composés en mode mathématique.
2583
2584 On active ce mécanisme avec les clés \Definition{begin-escape-math} et
2585 \Definition{end-escape-math} (\emph{qui ne sont accessibles que dans le préambule du
2586 document}).
2587
2588 \medskip
2589 Malgré la proximité technique, les usages du mécanisme «escape-math» sont en fait assez
2590 différents de ceux du mécanisme «escape». En effet, comme le contenu en échappement est
2591 composé en mode mathématique, il est, en particulier, composé dans un groupe TeX et ne
2592 pourra donc pas servir à changer le formatage d'autres unités lexicales.
2593
2594 \medskip
2595 Dans les langages où le caractère |$| ne joue pas un rôle syntaxique important, on peut
2596 assez naturellement vouloir activer le mécanisme «escape-math» avec le caractère |$|:
2597 \begin{Verbatim}
2598 \PitonOptions{~emphase#begin-escape-math=$,end-escape-math=$@}
2599 \end{Verbatim}
2600 Remarquer que le caractère |$| ne doit \emph{pas} être protégé par une contre-oblique. % $
2601
2602 \bigskip
2603 Néanmoins, il est sans doute plus prudent d'utiliser |\(| et |\)|, qui sont des
2604 délimiteurs du mode mathématique proposés par LaTeX.
2605 \begin{Verbatim}
2606 \PitonOptions{~emphase#begin-escape-math=\(,end-escape-math=\)@}
2607 \end{Verbatim}
2608
2609 \bigskip
2610 Voici un exemple d'utilisation typique :
2611
2612 \begin{Verbatim}
2613 \begin{Piton}[line-numbers]
2614 def arctan(x,n=10):
2615 if ~emphase#\(x < 0\)@
2616 return ~emphase#\(-\arctan(-x)\)@
2617 elif ~emphase#\(x > 1\)@ :
2618 return ~emphase#\(\pi/2 - \arctan(1/x)\)@
2619 else:
2620 s = ~emphase#\(0\)@
2621 for ~emphase#\(k\)@ in range(~emphase#\(n\)@): s += ~emphase#\(\smash{\frac{(-1)^k}{2k+1} x^{2k+1}}\)@
2622 return s
2623 \end{Piton}
2624 \end{Verbatim}
2625
2626
2627 \bigskip
2628
2629 \begin{Piton}[line-numbers]
2630 def arctan(x,n=10):
2631 if \(x < 0\) :
2632 return \(-\arctan(-x)\)
2633 elif \(x > 1\) :
2634 return \(\pi/2 - \arctan(1/x)\)
2635 else:
2636 s = \(0\)
2637 for \(k\) in range(\(n\)): s += \(\smash{\frac{(-1)^k}{2k+1} x^{2k+1}}\)
2638 return s
2639 \end{Piton}
2640
2641
2642 \subsection{Comportement dans la classe Beamer}
2643
2644 \label{beamer}
2645
2646 \index{Beamer@\cls{Beamer} (classe)}
2647
2648 \emph{Première remarque}
2649
2650 \nobreak
2651 Remarquons que, comme l'environnement |{Piton}| prend son argument selon un mode verbatim,
2652 il convient, ce qui n'est pas surprenant, de l'utiliser dans des environnements |{frame}|
2653 de Beamer protégés par la clé |fragile|, c'est-à-dire débutant par
2654 |\begin{frame}[fragile]|.\footnote{On rappelle que pour un environnement |{frame}| de
2655 Beamer qui utilise la clé |fragile|, l'instruction |\end{frame}| doit être seule sur une
2656 ligne (à l'exception d'éventuels espaces en début de ligne).}
2657
2658 Rappelons également que si le \emph{frame} ne contient qu'une seule diapo (\emph{slide}),
2659 il vaut mieux écrire : |\begin{frame}[fragile=singleslide]|
2660
2661 \medskip
2662 Quand l'extension \pkg{piton} est utilisée dans la classe
2663 \cls{beamer}\footnote{L'extension \pkg{piton} détecte la classe \cls{beamer} et
2664 l'extension \pkg{beamerarticle} si elle est chargée précédemment, mais il est aussi
2665 possible, si le besoin s'en faisait sentir, d'activer ce comportement avec la clé
2666 |beamer| au chargement de \pkg{piton} : |\usepackage[beamer]{piton}|}, le comportement
2667 de \pkg{piton} est légèrement modifié, comme décrit maintenant.
2668
2669 \subsubsection{\{Piton\} et \textbackslash PitonInputFile sont ``overlay-aware''}
2670
2671 Quand \pkg{piton} est utilisé avec Beamer, la command |\PitonInputFile| et
2672 l'environnement |{Piton}| (mais pas les environnements créés par
2673 |\NewPitonEnvironment|) acceptent l'argument optionnel |<...>| de Beamer pour
2674 indiquer les «\emph{overlays}» concernés. Cela est fait via un environnement |{actionenv}|
2675 de Beamer.
2676
2677 On peut par exemple écrire :
2678
2679 \begin{Verbatim}
2680 \begin{Piton}~emphase#<2-5>@
2681 ...
2682 \end{Piton}
2683 \end{Verbatim}
2684
2685 ou aussi
2686
2687 \begin{Verbatim}
2688 \PitonInputFile~emphase#<2-5>@{mon_fichier.py}
2689 \end{Verbatim}
2690
2691
2692
2693 \subsubsection{Commandes de Beamer reconnues dans \{Piton\} et \textbackslash PitonInputFile}
2694
2695 \index{detected-beamer-commands}
2696
2697 Quand \pkg{piton} est utilisé dans la classe \cls{beamer}, les commandes suivantes de
2698 \cls{beamer} (classées selon leur nombre d'arguments obligatoires) sont directement
2699 reconnues dans les environnements |{Piton}| (ainsi que dans les listings composés par la
2700 commande |\PitonInputFile|, même si c'est sans doute moins utile).
2701 %
2702 \begin{itemize}
2703 \item aucun argument obligatoire : |\pause|\footnote{On remarquera que, bien sûr, on peut
2704 aussi utiliser |\pause| dans un «commentaire LaTeX», c'est-à-dire en écrivant
2705 |#> \pause|. Ainsi, si le code Python est copié, il est interprétable par Python.} ;
2706 \item un argument obligatoire : |\action|, |\alert|, |\invisible|, |\only|, |\uncover| et
2707 |\visible| ; \newline
2708 La clé \Definition{detected-beamer-commands} permet de rajouter à cette liste de nouveaux
2709 noms de commandes (les noms de commandes ne doivent \emph{pas} être précédés de la
2710 contre-oblique) ;
2711 \item deux arguments obligatoires : |\alt| ;
2712 \item trois arguments obligatoires : |\temporal|.
2713 \end{itemize}
2714
2715 \medskip
2716 Ces commandes doivent être utilisées précédées et suivies d'un espace. Les accolades dans
2717 les arguments obligatoires de ces commandes doivent être équilibrées (cependant, les
2718 accolades présentes dans des chaînes courtes\footnote{Les chaînes courtes de Python sont
2719 les chaînes (string) délimitées par les caractères \texttt{'} ou \texttt{"} non triplés.
2720 En Python, les chaînes de caractères courtes ne peuvent pas s'étendre sur plusieurs
2721 lignes de code.} de Python ne sont pas prises en compte).
2722
2723 \medskip
2724 Concernant les fonctions |\alt| et |\temporal|, aucun retour à la ligne ne doit se trouver
2725 dans les arguments de ces fonctions.
2726
2727
2728
2729 \medskip
2730 Voici un exemple complet de fichier :
2731
2732 \medskip
2733 \begin{small}
2734 \begin{Code}
2735 \documentclass{beamer}
2736 \usepackage{piton}
2737 \begin{document}
2738 \begin{frame}[fragile]
2739 \begin{Piton}
2740 def string_of_list(l):
2741 """Convertit une liste de nombres en chaîne"""
2742 \emph{\only<2->{s = "{" + str(l[0])}}
2743 \emph{\only<3->{for x in l[1:]: s = s + "," + str(x)}}
2744 \emph{\only<4->{s = s + "}"}}
2745 return s
2746 \end{Piton}
2747 \end{frame}
2748 \end{document}
2749 \end{Code}
2750 \end{small}
2751
2752 \medskip
2753 Dans cet exemple, les accolades des deux chaînes de caractères Python |"{"| et
2754 |"}"| sont correctement interprétées (sans aucun caractère d'échappement).
2755
2756
2757 \bigskip
2758 \subsubsection{Environnements de Beamer reconnus dans \{Piton\} et \textbackslash PitonInputFile}
2759
2760 Quand \pkg{piton} est utilisé dans la classe \pkg{beamer}, les environnements suivants de
2761 Beamer sont directement reconnus dans les environnements |{Piton}| (ainsi que dans les
2762 listings composés par la commande |\PitonInputFile| même si c'est sans doute moins utile)
2763 : |{actionenv}|, |{alertenv}|, |{invisibleenv}|, |{onlyenv}|, |{uncoverenv}| et
2764 |{visibleenv}|.
2765
2766 \smallskip
2767 \index{detected-beamer-environments}
2768 On peut ajouter de nouveaux environnements à cette liste d'environnements reconnus avec la
2769 clé \Definition{detected-beamer-environments}.
2770
2771 \medskip
2772 Il y a néanmoins une restriction : ces environnements doivent englober des \emph{lignes
2773 entières de code}. Les instructions |\begin{...}| et |\end{...}| doivent être
2774 seules sur leurs lignes.
2775
2776
2777 \medskip
2778 On peut par exemple écrire :
2779
2780 \medskip
2781 \begin{small}
2782 \begin{Code}
2783 \documentclass{beamer}
2784 \usepackage{piton}
2785 \begin{document}
2786 \begin{frame}[fragile]
2787 \begin{Piton}
2788 def carré(x):
2789 """Calcule le carré de l'argument"""
2790 \emph{\begin{uncoverenv}<2>}
2791 return x*x
2792 \emph{\end{uncoverenv}}
2793 \end{Piton}
2794 \end{frame}
2795 \end{document}
2796 \end{Code}
2797 \end{small}
2798
2799
2800 \vspace{1cm}
2801 \textbf{Remarque à propos de la commande \textbackslash alert et de
2802 l'environnement \{alertenv\} de Beamer}
2803
2804 \nobreak
2805 \smallskip
2806 Beamer propose un moyen aisé de changer la couleur utilisée par l'environnement
2807 |{alertenv}| (et par suite la commande |\alert| qui s'appuie dessus). Par exemple, on peut
2808 écrire:
2809
2810 \begin{Verbatim}
2811 \setbeamercolor{~emphase#alerted text@}{fg=blue}
2812 \end{Verbatim}
2813
2814 Néanmoins, dans le cas d'une utilisation à l'intérieur d'un environnement |{Piton}| un tel
2815 réglage n'est sans doute pas pertinent, puisque, justement, \pkg{piton} va (le plus
2816 souvent) changer la couleur des élements selon leur valeur lexicale. On préfèrera sans
2817 doute un environnement |{alertenv}| qui change la couleur de fond des éléments à mettre en
2818 évidence.
2819
2820 \smallskip
2821 Voici un code qui effectuera ce travail en mettant un fond jaune. Ce code utilise la
2822 commande |\@highLight| de l'extension \pkg{lua-ul} (cette extension nécessite elle-même
2823 l'extension \pkg{luacolor}).
2824
2825 \begingroup
2826 \fvset{commandchars=\~\#\+,formatcom=\color{gray}}
2827 \begin{Verbatim}
2828 \setbeamercolor{alerted text}{bg=yellow!50}
2829 \makeatletter
2830 \AddToHook{env/Piton/begin}
2831 {\renewenvironment<>{alertenv}{\only~#1{~emphase#\@highLight+[alerted text.bg]}}{}}
2832 \makeatother
2833 \end{Verbatim}
2834 \endgroup
2835
2836 Ce code redéfinit localement l'environnement |{alertenv}| à l'intérieur de l'environnement
2837 |{Piton}| (on rappelle que la commande |\alert| s'appuie sur cet environnement
2838 |{alertenv}|).
2839
2840
2841 \bigskip
2842 \subsection{Notes de pied de page dans les environnements de piton}
2843
2844 \index{footnote@\pkg{footnote} (extension)}
2845 \index{footnote (clé)}
2846 \index{footnotehyper@\pkg{footnotehyper} (extension)}
2847 \index{footnotehyper (clé)}
2848
2849 \label{footnote}
2850
2851
2852 \smallskip
2853 Si vous voulez mettre des notes de pied de page dans un environnement de \pkg{piton} (ou
2854 bien dans un listing produit par |\PitonInputFile|, bien que cela paraisse moins pertinent
2855 dans ce cas-là) vous pouvez utiliser une paire |\footnotemark|--|\footnotetext|.
2856
2857 \smallskip
2858 Néanmoins, il est également possible d'extraire les notes de pieds de page avec
2859 l'extension \pkg{footnote} ou bien l'extension \pkg{footnotehyper}.
2860
2861 \smallskip
2862 Si \pkg{piton} est chargée avec l'option \Definition{footnote} (avec
2863 |\usepackage[footnote]{piton}|) l'extension \pkg{footnote} est chargée (si elle ne l'est
2864 pas déjà) et elle est utilisée pour extraire les notes de pied de page.
2865
2866 \smallskip
2867 Si \pkg{piton} est chargée avec l'option \Definition{footnotehyper}, l'extension
2868 \pkg{footnotehyper} est chargée (si elle ne l'est pas déjà) et elle est utilisée pour
2869 extraire les notes de pied de page.
2870
2871 \smallskip
2872 Attention : Les extensions \pkg{footnote} et \pkg{footnotehyper} sont incompatibles.
2873 L'extension \pkg{footnotehyper} est le successeur de l'extension \pkg{footnote} et devrait
2874 être utilisée préférentiellement. L'extension \pkg{footnote} a quelques défauts ; en
2875 particulier, elle doit être chargée après l'extension \pkg{xcolor} et elle n'est pas
2876 parfaitement compatible avec \pkg{hyperref}.
2877
2878
2879 \medskip
2880 \textbf{Remarque importante} : Si vous utilisez Beamer, il faut savoir que Beamer a son
2881 propre système d'extraction des notes de pied de page et vous n'avez donc pas à charger
2882 \pkg{piton} avec la clé |footnote| ou bien la clé |footnotehyper|.
2883
2884 \bigskip
2885 Par défaut, une commande |\footnote| ne peut apparaître que dans un «commentaire LaTeX».
2886 Mais on peut aussi ajouter la commande |\footnote| à la liste des
2887 \emph{detected-commands} (cf.~partie~\ref{detected-commands},
2888 p.~\pageref{detected-commands}).
2889
2890 \medskip
2891 Dans ce document, l'extension \pkg{piton} a été chargée avec l'option |footnotehyper| et
2892 on rajouté la commande |\footnote| aux \emph{detected-commands} avec le code suivant
2893 dans le préambule du document LaTeX :
2894
2895 \qquad \verb|\PitonOptions{detected-commands = footnote}|
2896
2897 \begingroup
2898 \fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
2899 \begin{Verbatim}
2900 \PitonOptions{background-color=gray!15}
2901 \begin{Piton}
2902 def arctan(x,n=10):
2903 if x < 0:
2904 return -arctan(-x)~emphase&\footnote{Un premier appel récursif.}@
2905 elif x > 1:
2906 return pi/2 - arctan(1/x)~emphase&\footnote{Un deuxième appel récursif.}@
2907 else:
2908 return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
2909 \end{Piton}
2910 \end{Verbatim}
2911 \endgroup
2912
2913 \begingroup
2914 \PitonOptions{background-color=gray!15}
2915 \begin{Piton}
2916 def arctan(x,n=10):
2917 if x < 0:
2918 return -arctan(-x)\footnote{Un premier appel récursif.}
2919 elif x > 1:
2920 return pi/2 - arctan(1/x)\footnote{Un deuxième appel récursif.}
2921 else:
2922 return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
2923 \end{Piton}
2924 \endgroup
2925
2926
2927 \vspace{1cm}
2928
2929 Si on utilise l'environnement |{Piton}| dans un environnement |{minipage}| de LaTeX, les
2930 notes sont, bien entendu, composées au bas de l'environnement |{minipage}|. Rappelons
2931 qu'une telle |{minipage}| ne peut \emph{pas} être coupée par un saut de page.
2932
2933
2934 \begingroup
2935 \fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
2936 \begin{Verbatim}
2937 \PitonOptions{background-color=gray!15}
2938 ~emphase&\begin{minipage}{\linewidth}@
2939 \begin{Piton}
2940 def arctan(x,n=10):
2941 if x < 0:
2942 return -arctan(-x)~emphase&\footnote{Un premier appel récursif.}@
2943 elif x > 1:
2944 return pi/2 - arctan(1/x)~emphase&\footnote{Un deuxième appel récursif.}@
2945 else:
2946 return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
2947 \end{Piton}
2948 ~emphase&\end{minipage}@
2949 \end{Verbatim}
2950 \endgroup
2951
2952 \begingroup
2953 \PitonOptions{background-color=gray!15}
2954 \begin{minipage}{\linewidth}
2955 \begin{Piton}
2956 def arctan(x,n=10):
2957 if x < 0:
2958 return -arctan(-x)\footnote{Un premier appel récursif.}
2959 elif x > 1:
2960 return pi/2 - arctan(1/x)\footnote{Un deuxième appel récursif.}
2961 else:
2962 return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
2963 \end{Piton}
2964 \end{minipage}
2965 \endgroup
2966
2967
2968
2969 \subsection{Tabulations}
2970
2971 \index{tabulations}
2972 \index{tab-size}
2973
2974 \smallskip
2975 Même s'il est sans doute recommandable d'indenter les listings informatiques avec des
2976 espaces et non des tabulations\footnote{Voir, par exemple, pour le langage Python, la note PEP~8.},
2977 \pkg{piton} accepte les caractères de tabulations (U+0009) en début de ligne. Chaque
2978 caractère U+0009 est remplacé par $n$ espaces. La valeur initiale de~$n$ est~4 mais on
2979 peut la changer avec la clé \Definition{tab-size} de |\PitonOptions|.
2980
2981 \smallskip
2982 Il existe aussi une clé \Definition{tabs-auto-gobble} qui détermine le nombre minimal de
2983 caractères U+0009 débutant chaque ligne (non vide) de l'environnement |{Piton}| et
2984 applique |gobble| avec cette valeur (avant le remplacement des caractères U+0009 par des
2985 espaces, bien entendu). Cette clé est donc similaire à la clé |auto-gobble| mais agit sur
2986 des caractères U+0009 au lieu de caractères U+0020 (espaces).
2987
2988 \smallskip
2989 La clé |env-gobble| n'est pas compatible avec les tabulations.
2990
2991
2992 \section{API pour les développeurs}
2993
2994
2995 \index{piton.last@\texttt{piton.get\_last\_code} (fonction Lua)}
2996 \label{API}
2997
2998 La variable L3 \DefinitionCommand{l_piton_language_str} contient le nom du
2999 langage courant (en minuscules).
3000
3001 \bigskip
3002
3003 L'extension \pkg{piton} fournit une fonction Lua
3004 \Definition{piton.get_last_code} sans argument permettant de récupérer le code
3005 contenu dans le dernier environnement de \pkg{piton}.
3006 \begin{itemize}
3007 \item Les retours à la ligne (présents dans l'environnement de départ)
3008 apparaissent comme des caractères |\r| (c'est-à-dire des caractères U+000D).
3009
3010 \item Le code fourni par |piton.get_last_code()| tient compte de l'éventuelle
3011 application d'une clé |gobble| (cf. p.~\pageref{gobble}).
3012
3013 \item Les surcharges du code (qui entraînent des échappements vers LaTeX) ont
3014 été retirées du code fourni par |piton.get_last_code()|. Cela s'applique aux
3015 commandes LaTeX déclarées par la clé |detected-commands| et ses variantess (cf.
3016 partie~\ref{detected-commands}) et aux éléments insérés avec le mécanisme
3017 «|escape|» (cf. partie~\ref{escape}).
3018
3019 \item |piton.get_last_code| est une fonction Lua et non une chaîne de caractères
3020 : les traitements présentés précédemment sont exécutés lorsque la fonction est
3021 appelée. De ce fait, il peut être judicieux de stocker la valeur renvoyée par
3022 |piton.get_last_code()| dans une variable Lua si on doit l'utiliser plusieurs
3023 fois.
3024 \end{itemize}
3025
3026 \medskip
3027 Pour un exemple d'utilisation, voir la partie concernant l'utilisation
3028 (standard) de \pkg{pyluatex}, partie~\ref{pyluatex}, p.~\pageref{pyluatex}.
3029
3030 \section{Exemples}
3031
3032
3033
3034 \subsection{Un exemple de réglage des styles}
3035
3036 Les styles graphiques ont été présentés à la partie \ref{styles}, p.~\pageref{styles}.
3037
3038 \smallskip
3039 On présente ici un réglage de ces styles adapté pour les documents en noir et blanc.
3040
3041 Ce réglage utilise la commande |\highLight| de \pkg{lua-ul} (cette extension nécessite
3042 elle-même l'extension \pkg{luacolor}).
3043
3044
3045 \begin{Verbatim}
3046 \SetPitonStyle
3047 {
3048 Number = ,
3049 String = \itshape ,
3050 String.Doc = \color{gray} \itshape ,
3051 Operator = ,
3052 Operator.Word = \bfseries ,
3053 Name.Builtin = ,
3054 Name.Function = \bfseries \highLight[gray!20] ,
3055 Comment = \color{gray} ,
3056 Comment.LaTeX = \normalfont \color{gray},
3057 Keyword = \bfseries ,
3058 Name.Namespace = ,
3059 Name.Class = ,
3060 Name.Type = ,
3061 InitialValues = \color{gray}
3062 }
3063 \end{Verbatim}
3064
3065
3066 Dans ce réglage, de nombreuses valeurs fournies aux clés sont vides, ce qui
3067 signifie que le style correspondant n'insèrera aucune instruction de formatage,
3068 si ce n'est celles données par le paramètre |font-command|, dont la valeur
3069 initiale est |\ttfamily| (l'élément sera composé dans la couleur standard, le
3070 plus souvent, en noir, etc.). Ces entrées avec valeurs nulles sont néanmoins
3071 nécessaires car la valeur initiale de ces styles dans \pkg{piton} n'est
3072 \emph{pas} vide.
3073
3074 \begingroup
3075
3076 \SetPitonStyle
3077 {
3078 Number = ,
3079 String = \itshape ,
3080 String.Doc = \color{gray} \itshape ,
3081 Operator = ,
3082 Operator.Word = \bfseries ,
3083 Name.Builtin = ,
3084 Name.Function = \bfseries \highLight[gray!20] ,
3085 Comment = \color{gray} ,
3086 Comment.LaTeX = \normalfont \color{gray},
3087 Keyword = \bfseries ,
3088 Name.Namespace = ,
3089 Name.Class = ,
3090 Name.Type = ,
3091 InitialValues = \color{gray}
3092 }
3093
3094
3095 \bigskip
3096
3097 \begin{Piton}
3098 from math import pi
3099
3100 def arctan(x,n=10):
3101 """Compute the mathematical value of arctan(x)
3102
3103 n is the number of terms in the sum
3104 """
3105 if x < 0:
3106 return -arctan(-x) # appel récursif
3107 elif x > 1:
3108 return pi/2 - arctan(1/x)
3109 #> (on a utilisé le fait que $\arctan(x)+\arctan(1/x)=\pi/2$ pour $x>0$)
3110 else:
3111 s = 0
3112 for k in range(n):
3113 s += (-1)**k/(2*k+1)*x**(2*k+1)
3114 return s
3115 \end{Piton}
3116
3117
3118 \endgroup
3119
3120
3121 \subsection{Numérotation des lignes}
3122
3123 \label{example-numbering}
3124 \index{numérotation des lignes de code|emph}
3125
3126 On rappelle que l'on peut demander la numérotation des lignes des listings avec
3127 la clé |line-numbers| (utilisée sans valeur).
3128
3129 Par défaut, les numéros de ligne sont composés par \pkg{piton} en débordement à
3130 gauche (en utilisant en interne la commande |\llap| de LaTeX).
3131
3132
3133 \begingroup
3134 \fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
3135 \begin{Verbatim}
3136 ~emphase&\PitonOptions{background-color=gray!15, line-numbers}@
3137 \begin{Piton}
3138 def arctan(x,n=10):
3139 if x < 0:
3140 return -arctan(-x) #> (appel récursif)
3141 elif x > 1:
3142 return pi/2 - arctan(1/x) #> (autre appel récursif)
3143 else:
3144 s = 0.0
3145 for k in range(n):
3146 s = s + (-1)**k/(2*k+1)*x**(2*k+1)
3147 return s
3148 \end{Piton}
3149 \end{Verbatim}
3150 \endgroup
3151
3152
3153
3154 \begingroup
3155 \PitonOptions{background-color=gray!15,line-numbers}
3156 \begin{Piton}
3157 def arctan(x,n=10):
3158 if x < 0:
3159 return -arctan(-x) #> (appel récursif)
3160 elif x > 1:
3161 return pi/2 - arctan(1/x) #> (autre appel récursif)
3162 else:
3163 s = 0.0
3164 for k in range(n):
3165 s = s + (-1)**k/(2*k+1)*x**(2*k+1)
3166 return s
3167 \end{Piton}
3168 \endgroup
3169
3170 \bigskip
3171
3172 Si on ne veut pas de débordement, on peut utiliser l'option |left-margin=auto| qui va
3173 insérer une marge adaptée aux numéros qui seront insérés (elle est plus large quand les
3174 numéros dépassent 10).
3175
3176
3177 \begingroup
3178 \fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
3179 \begin{Verbatim}
3180 ~emphase&\PitonOptions{background-color=gray!15, left-margin = auto, line-numbers}@
3181 \begin{Piton}
3182 def arctan(x,n=10):
3183 if x < 0:
3184 return -arctan(-x) #> (appel récursif)
3185 elif x > 1:
3186 return pi/2 - arctan(1/x) #> (autre appel récursif)
3187 else:
3188 s = 0.0
3189 for k in range(n):
3190 s = s + (-1)**k/(2*k+1)*x**(2*k+1)
3191 return s
3192 \end{Piton}
3193 \end{Verbatim}
3194 \endgroup
3195
3196
3197
3198 \begingroup
3199 \PitonOptions{background-color=gray!15,left-margin = auto, line-numbers}
3200 \begin{Piton}
3201 def arctan(x,n=10):
3202 if x < 0:
3203 return -arctan(-x) #> (appel récursif)
3204 elif x > 1:
3205 return pi/2 - arctan(1/x) #> (autre appel récursif)
3206 else:
3207 s = 0.0
3208 for k in range(n):
3209 s = s + (-1)**k/(2*k+1)*x**(2*k+1)
3210 return s
3211 \end{Piton}
3212 \endgroup
3213
3214
3215 \bigskip
3216 On peut aussi demander la composition des numéros à droite avec
3217 |line-numbers/position=right| (la valeur initiale du paramètre
3218 |line-numbers/position| est, sans surprise, |left|). Il est bon dans ce cas de
3219 donner une valeur non nulle à |right-margin| (on peut aussi utiliser
3220 |right-margin=auto| mais la valeur effective résultante pour |right-margin| paraîtra
3221 dans doute trop faible en cas de longues lignes coupées).
3222
3223
3224 \begingroup
3225 \fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
3226 \begin{Verbatim}
3227 \PitonOptions
3228 {
3229 background-color=gray!15,
3230 ~emphase&line-numbers/position = right@,
3231 ~emphase&right-margin = 1cm@,
3232 ~emphase&line-numbers@
3233 }
3234 \begin{Piton}
3235 def arctan(x,n=10):
3236 if x < 0:
3237 return -arctan(-x) #> (appel récursif)
3238 elif x > 1:
3239 return pi/2 - arctan(1/x) #> (autre appel récursif)
3240 else:
3241 s = 0.0
3242 for k in range(n):
3243 s = s + (-1)**k/(2*k+1)*x**(2*k+1)
3244 return s
3245 \end{Piton}
3246 \end{Verbatim}
3247 \endgroup
3248
3249
3250
3251 \begingroup
3252 \PitonOptions
3253 {
3254 background-color=gray!15,
3255 line-numbers/position = right,
3256 right-margin = 1cm,
3257 line-numbers
3258 }
3259 \begin{Piton}
3260 def arctan(x,n=10):
3261 if x < 0:
3262 return -arctan(-x) #> (appel récursif)
3263 elif x > 1:
3264 return pi/2 - arctan(1/x) #> (autre appel récursif)
3265 else:
3266 s = 0.0
3267 for k in range(n):
3268 s = s + (-1)**k/(2*k+1)*x**(2*k+1)
3269 return s
3270 \end{Piton}
3271 \endgroup
3272
3273
3274
3275 \bigskip
3276 Le même exemple avec la clé |width=min|.
3277
3278 \begingroup
3279 \fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
3280 \begin{Verbatim}
3281 \PitonOptions
3282 {
3283 background-color=gray!15,
3284 ~emphase&line-numbers/position = right@,
3285 ~emphase&right-margin = 1cm@,
3286 ~emphase&line-numbers@,
3287 ~emphase&width=min@
3288 }
3289 \begin{Piton}
3290 def arctan(x,n=10):
3291 if x < 0:
3292 return -arctan(-x) #> (appel récursif)
3293 elif x > 1:
3294 return pi/2 - arctan(1/x) #> (autre appel récursif)
3295 else:
3296 s = 0.0
3297 for k in range(n):
3298 s = s + (-1)**k/(2*k+1)*x**(2*k+1)
3299 return s
3300 \end{Piton}
3301 \end{Verbatim}
3302 \endgroup
3303
3304
3305
3306 \begingroup
3307 \PitonOptions
3308 {
3309 background-color=gray!15,
3310 line-numbers/position = right,
3311 right-margin = 1cm,
3312 line-numbers,
3313 width=min
3314 }
3315 \begin{Piton}
3316 def arctan(x,n=10):
3317 if x < 0:
3318 return -arctan(-x) #> (appel récursif)
3319 elif x > 1:
3320 return pi/2 - arctan(1/x) #> (autre appel récursif)
3321 else:
3322 s = 0.0
3323 for k in range(n):
3324 s = s + (-1)**k/(2*k+1)*x**(2*k+1)
3325 return s
3326 \end{Piton}
3327 \endgroup
3328
3329
3330
3331 \bigskip
3332
3333 \subsection{Formatage des commentaires LaTeX}
3334
3335 \label{example-comments}
3336 \index{commentaires LaTeX|emph}
3337
3338 On peut modifier le style |Comment.LaTeX| (avec |\SetPitonStyle|) pour faire afficher les
3339 commentaires LaTeX (qui débutent par |#>|) en butée à droite.
3340
3341 \begingroup
3342 \fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
3343 \begin{Verbatim}
3344 \PitonOptions{background-color=gray!15}
3345 ~emphase&\SetPitonStyle{Comment.LaTeX = \hfill \normalfont\color{gray}}@
3346 \begin{Piton}
3347 def arctan(x,n=10):
3348 if x < 0:
3349 return -arctan(-x) #> appel récursif
3350 elif x > 1:
3351 return pi/2 - arctan(1/x) #> autre appel récursif
3352 else:
3353 return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
3354 \end{Piton}
3355 \end{Verbatim}
3356 \endgroup
3357
3358 \begingroup
3359 \PitonOptions{background-color=gray!15}
3360 \SetPitonStyle{Comment.LaTeX = \hfill \normalfont\color{gray}}
3361 \begin{Piton}
3362 def arctan(x,n=10):
3363 if x < 0:
3364 return -arctan(-x) #> appel récursif
3365 elif x > 1:
3366 return pi/2 - arctan(1/x) #> autre appel récursif
3367 else:
3368 return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
3369 \end{Piton}
3370 \endgroup
3371
3372
3373 \vspace{1cm} On peut aussi faire afficher les commentaires dans une deuxième colonne à
3374 droite si on limite la largeur du code proprement dit avec la clé |width|.
3375
3376 \begingroup
3377 \fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
3378 \begin{Verbatim}
3379 \PitonOptions{width=9cm, background-color=gray!15}
3380 ~emphase&\NewDocumentCommand{\MyLaTeXCommand}{m}{\hfill \normalfont\itshape\rlap{\quad #1}}@
3381 ~emphase&\SetPitonStyle{Comment.LaTeX = \MyLaTeXCommand}@
3382 \begin{Piton}
3383 def arctan(x,n=10):
3384 if x < 0:
3385 return -arctan(-x) #> appel récursif
3386 elif x > 1:
3387 return pi/2 - arctan(1/x) #> autre appel récursif
3388 else:
3389 s = 0
3390 for k in range(n):
3391 s += (-1)**k/(2*k+1)*x**(2*k+1)
3392 return s
3393 \end{Piton}
3394 \end{Verbatim}
3395 \endgroup
3396
3397
3398
3399 \begingroup
3400 \PitonOptions{width = 9cm , background-color=gray!15}
3401 \NewDocumentCommand{\MyLaTeXCommand}{m}{\hfill \normalfont\itshape\rlap{\quad #1}}
3402 \SetPitonStyle{Comment.LaTeX = \MyLaTeXCommand}
3403 \begin{Piton}
3404 def arctan(x,n=10):
3405 if x < 0:
3406 return -arctan(-x) #> appel récursif
3407 elif x > 1:
3408 return pi/2 - arctan(1/x) #> autre appel récursif
3409 else:
3410 s = 0
3411 for k in range(n):
3412 s += (-1)**k/(2*k+1)*x**(2*k+1)
3413 return s
3414 \end{Piton}
3415 \endgroup
3416
3417 \subsection{La commande \texttt{\textbackslash rowcolor}}
3418
3419 \indexcommand{rowcolor}
3420
3421 La commande |\rowcolor| a été décrite à la partie \ref{rowcolor},
3422 p.~\pageref{rowcolor}, dans la partie sur les styles. Rappelons qu'elle impose
3423 un fond coloré à la ligne courante (\emph{toute la ligne} et pas seulement la partie
3424 contenant du texte).
3425
3426 \medskip
3427 Cette commande |\rowcolor| peut être utilisée dans un style, comme illustré à la
3428 page~\pageref{rowcolor} mais on peut aussi envisager de l'utiliser directement
3429 dans un listing. Il faudra néanmoins utiliser un des mécanismes d'échappement
3430 vers LaTeX fournis par \pkg{piton}. Dans l'exemple suivant, on utilise la clé
3431 |raw-detected-commands| (cf.~p.~\pageref{raw-detected-commands}). On ne pourra
3432 pas utiliser une syntaxe comme |\rowcolor[rgb]{0.8,1,0.8}| car les «commandes
3433 détectées» sont des commandes à un seul argument mais on pourra utiliser
3434 |\rowcolor{[rgb]{0.8,1,0.8}}| (syntaxe acceptée par |\rowcolor|).
3435
3436 \nobreak
3437 \begin{footnotesize}
3438 \begin{Verbatim}
3439 \PitonOptions{raw-detected-commands = rowcolor} % dans le préambule
3440 \end{Verbatim}
3441 \end{footnotesize}
3442
3443 \medskip
3444
3445 \begin{BVerbatim}[boxwidth=87mm,baseline=c]
3446 \begin{Piton}[width=min]
3447 def fact(n):
3448 if n==0:
3449 return 1 ~emphase#\rowcolor{yellow!50}@
3450 else:
3451 return n*fact(n-1)
3452 \end{Piton}
3453 \end{BVerbatim}
3454 \hspace{1cm}
3455 \begin{Piton}[width=min,box]
3456 def fact(n):
3457 if n==0:
3458 return 1 \rowcolor{yellow!50}
3459 else:
3460 return n*fact(n-1)
3461 \end{Piton}
3462
3463
3464 \bigbreak
3465 Voici maintenant le même exemple avec utilisation conjointe de la clé
3466 |background-color| (cf. p.~\pageref{background-color}).
3467
3468 \medskip
3469 \begin{BVerbatim}[boxwidth=91mm,baseline=c]
3470 \begin{Piton}[width=min,~emphase#background-color=gray!15@]
3471 def fact(n):
3472 if n==0:
3473 return 1 ~emphase#\rowcolor{yellow!50}@
3474 else:
3475 return n*fact(n-1)
3476 \end{Piton}
3477 \end{BVerbatim}
3478 \hspace{6mm}
3479 \begin{Piton}[width=min,box,background-color=gray!15]
3480 def fact(n):
3481 if n==0:
3482 return 1 \rowcolor{yellow!50}
3483 else:
3484 return n*fact(n-1)
3485 \end{Piton}
3486
3487
3488 \bigbreak
3489 Comme on le constate, une marge a été ajoutée à gauche et à droite par la clé
3490 |background-color|. Pour avoir une telle marge sans couleur de fond générale, il
3491 convient d'utiliser |background-color| avec
3492 la couleur spéciale |none|.
3493
3494 \medskip
3495 \begin{BVerbatim}[boxwidth=87mm,baseline=c]
3496 \begin{Piton}[width=min,~emphase#background-color=none@]
3497 def fact(n):
3498 if n==0:
3499 return 1 ~emphase#\rowcolor{yellow!50}@
3500 else:
3501 return n*fact(n-1)
3502 \end{Piton}
3503 \end{BVerbatim}
3504 \hspace{1cm}
3505 \begin{Piton}[width=min,box,background-color=none]
3506 def fact(n):
3507 if n==0:
3508 return 1 \rowcolor{yellow!50}
3509 else:
3510 return n*fact(n-1)
3511 \end{Piton}
3512
3513
3514
3515 \subsection{Utilisation avec tcolorbox}
3516
3517 \label{examples-tcolorbox}
3518 \index{tcolorbox (clé)|emph}
3519
3520 La clé |tcolorbox| de \pkg{piton} a été présentée à la page \pageref{tcolorbox}.
3521
3522 Si on souhaite l'utiliser en paramétrant la boîte graphique créée par
3523 \pkg{tcolorbox} (avec les clés fournies par \pkg{tcolorbox}), il convient
3524 d'utiliser la commande |\tcbset| de \pkg{tcolorbox}. Pour limiter la portée de
3525 ces réglages, le mieux est sans doute de créer un nouvel environnement avec
3526 |\NewPitonEnvironment| (cf.~p.~\pageref{NewPitonEnvironment}). Cet environnement
3527 contiendra les personnalisations de \pkg{piton} (avec |\PitonOptions|) et celles
3528 de \pkg{tcolorbox} (avec |\tcbset|).
3529
3530 \bigskip
3531 Voici un exemple d'un tel environnement |{Python}| avec une colonne colorée à gauche
3532 pour les numéros de ligne.
3533
3534 \begin{footnotesize}
3535 \begin{Verbatim}
3536 \usepackage{tcolorbox} % dans le préambule
3537 \tcbuselibrary{breakable,skins} % dans le préambule
3538 \end{Verbatim}
3539 \end{footnotesize}
3540
3541 \medskip
3542
3543 \begin{Verbatim}
3544 \NewPitonEnvironment{Python}{m}
3545 {%
3546 \PitonOptions
3547 {
3548 ~emphase#tcolorbox@,
3549 splittable=3,
3550 width=min,
3551 line-numbers, % active les numéros de ligne
3552 line-numbers = % personnalisation des numéros de ligne
3553 {
3554 format = \footnotesize\color{white}\sffamily ,
3555 sep = 2.5mm
3556 }
3557 }%
3558 \tcbset
3559 {
3560 enhanced,
3561 title=~#1,
3562 fonttitle=\sffamily,
3563 left = 6mm,
3564 top = 0mm,
3565 bottom = 0mm,
3566 overlay=
3567 {%
3568 \begin{tcbclipinterior}%
3569 \fill[gray!80]
3570 (frame.south west) rectangle
3571 ([xshift=6mm]frame.north west);
3572 \end{tcbclipinterior}%
3573 }
3574 }
3575 }
3576 { }
3577 \end{Verbatim}
3578
3579 \bigskip
3580 Dans l'exemple d'utilisation qui suit, on a illustré le fait que l'on peut
3581 forcer un saut de page dans un tel environnement avec |\newpage{}| si on a
3582 demandé à \pkg{piton} de détecter la commande |\newpage| avec la clé
3583 |vertical-detected-commands| (cf.~p.~\pageref{vertical-detected-commands}) dans
3584 le préambule du document LaTeX.
3585
3586 Remarquer que l'on doit bien utiliser |\newpage{}| et non |\newpage| car les
3587 commandes LaTeX détectées par \pkg{piton} sont censées être des commandes à un argument
3588 entre accolades (les accolades doivent être explicites).
3589
3590 \begin{footnotesize}
3591 \begin{Verbatim}
3592 \PitonOptions{vertical-detected-commands = newpage} % dans le préambule
3593 \end{Verbatim}
3594 \end{footnotesize}
3595
3596 \begin{Verbatim}
3597 ~emphase#\begin{Python}@{Mon exemple}
3598 def carré(x):
3599 """Calcule le carré de x"""
3600 return x*x
3601 def carré(x):
3602 """Calcule le carré de x"""
3603 return x*x
3604 def carré(x):
3605 """Calcule le carré de x"""
3606 return x*x
3607 def carré(x):
3608 """Calcule le carré de x"""
3609 return x*x ~emphase#\newpage{}@
3610 def carré(x):
3611 """Calcule le carré de x"""
3612 return x*x
3613 ...
3614 def carré(x):
3615 """Calcule le carré de x"""
3616 return x*x
3617 ~emphase#\end{Python}@
3618 \end{Verbatim}
3619
3620 \bigskip
3621
3622 \RenewPitonEnvironment{Python}{m}
3623 {%
3624 \PitonOptions
3625 {
3626 tcolorbox,
3627 splittable=3,
3628 width=min,
3629 line-numbers,
3630 line-numbers =
3631 {
3632 format = \footnotesize\color{white}\sffamily ,
3633 sep = 2.5mm
3634 }
3635 }%
3636 \tcbset
3637 {
3638 enhanced,
3639 title=#1,
3640 fonttitle=\sffamily,
3641 left = 6mm,
3642 top = 0mm,
3643 bottom = 0mm,
3644 overlay=
3645 {%
3646 \begin{tcbclipinterior}%
3647 \fill[gray!80]
3648 (frame.south west) rectangle
3649 ([xshift=6mm]frame.north west);
3650 \end{tcbclipinterior}%
3651 }
3652 }
3653 }
3654 { }
3655
3656
3657 \begin{Python}{Mon exemple}
3658 def carré(x):
3659 """Calcule le carré de x"""
3660 return x*x
3661 def carré(x):
3662 """Calcule le carré de x"""
3663 return x*x
3664 def carré(x):
3665 """Calcule le carré de x"""
3666 return x*x
3667 def carré(x):
3668 """Calcule le carré de x"""
3669 return x*x \newpage{}
3670 def carré(x):
3671 """Calcule le carré de x"""
3672 return x*x
3673 def carré(x):
3674 """Calcule le carré de x"""
3675 return x*x
3676 def carré(x):
3677 """Calcule le carré de x"""
3678 return x*x
3679 def carré(x):
3680 """Calcule le carré de x"""
3681 return x*x
3682 def carré(x):
3683 """Calcule le carré de x"""
3684 return x*x
3685 def carré(x):
3686 """Calcule le carré de x"""
3687 return x*x
3688 def carré(x):
3689 """Calcule le carré de x"""
3690 return x*x
3691 def carré(x):
3692 """Calcule le carré de x"""
3693 return x*x
3694 def carré(x):
3695 """Calcule le carré de x"""
3696 return x*x
3697 def carré(x):
3698 """Calcule le carré de x"""
3699 return x*x
3700 def carré(x):
3701 """Calcule le carré de x"""
3702 return x*x
3703 def carré(x):
3704 """Calcule le carré de x"""
3705 return x*x
3706 def carré(x):
3707 """Calcule le carré de x"""
3708 return x*x
3709 def carré(x):
3710 """Calcule le carré de x"""
3711 return x*x
3712 def carré(x):
3713 """Calcule le carré de x"""
3714 return x*x
3715 def carré(x):
3716 """Calcule le carré de x"""
3717 return x*x
3718 def carré(x):
3719 """Calcule le carré de x"""
3720 return x*x
3721 def carré(x):
3722 """Calcule le carré de x"""
3723 return x*x
3724 def carré(x):
3725 """Calcule le carré de x"""
3726 return x*x
3727 def carré(x):
3728 """Calcule le carré de x"""
3729 return x*x
3730 def carré(x):
3731 """Calcule le carré de x"""
3732 return x*x
3733 def carré(x):
3734 """Calcule le carré de x"""
3735 return x*x
3736 def carré(x):
3737 """Calcule le carré de x"""
3738 return x*x
3739 \end{Python}
3740
3741 \subsection{Utilisation avec pyluatex}
3742
3743 \subsubsection{Utilisation standard de pyluatex}
3744
3745 \label{pyluatex}
3746 \index{pyluatex@{\pkg{pyluatex}} (extension)}
3747
3748
3749 \textcolor{red}{Attention: Les codes qui suivent nécessitent la version 0.7.0 de \pkg{pyluatex}.}
3750
3751 \bigskip
3752
3753 L'extension \pkg{pyluatex} est une extension qui permet l'exécution de code Python à
3754 partir de |lualatex| (pourvu que Python soit installé sur la machine et que la compilation
3755 soit effectuée avec |lualatex| et |--shell-escape|).
3756
3757 Voici, à titre d'exemple, un environnement |{PitonExecute}| qui formate un listing Python
3758 (avec \pkg{piton}) et qui affiche également dessous le résultat de l'exécution de ce code
3759 avec Python.
3760
3761 \medskip
3762 \begin{Code}
3763 \NewPitonEnvironment{\emph{PitonExecute}}{O{}}
3764 {\PitonOptions{#1}}
3765 {\begin{center}
3766 \directlua
3767 {
3768 pyluatex.execute(piton.get_last_code(),false,cctab_latex,
3769 false,false,true,"default",false,false)
3770 tex.print(pyluatex.get_last_output())
3771 }
3772 \end{center}}
3773 \end{Code}
3774
3775 \medskip
3776 \NewPitonEnvironment{PitonExecute}{O{}}
3777 {\PitonOptions{#1}}
3778 {\begin{center}
3779 \directlua
3780 {
3781 pyluatex.execute(piton.get_last_code(),false,cctab_latex,
3782 false,false,true,"default",false,false)
3783 tex.print(pyluatex.get_last_output())
3784 }
3785 \end{center}}
3786
3787
3788 On a utilisé la fonction Lua |piton.get_last_code| fournie dans l'API de \pkg{piton} :
3789 cf.~partie~\ref{API}, p.~\pageref{API}.
3790
3791 \bigskip
3792 Cet environnement |{PitonExecute}| prend en argument optionnel (entre crochets) les
3793 options proposées par la commande |\PitonOptions|.
3794
3795 \medskip
3796 \begin{Verbatim}
3797 \begin{~emphase#PitonExecute@}[background-color=gray!15]
3798 def carré(x):
3799 """Calcule le carré de x"""
3800 return x*x
3801 print(f'Le carré de 12 est {carré(12)}.')
3802 \end{~emphase#PitonExecute@}
3803 \end{Verbatim}
3804
3805
3806 \medskip
3807 \begin{PitonExecute}[background-color=gray!15]
3808 def carré(x):
3809 """Calcule le carré de x"""
3810 return x*x
3811 print(f'Le carré de 12 est {carré(12)}.')
3812 \end{PitonExecute}
3813
3814 \bigskip
3815 On peut, dans cet environnement, utiliser les mécanismes d'échappement vers
3816 LaTeX de la même manière que précédemment (cf. p.~\pageref{LaTeX-escapes}).
3817
3818 \begin{footnotesize}
3819 \begin{Verbatim}
3820 \usepackage{luacolor,lua-ul} % dans le préambule
3821 \PitonOptions{detected-commands = highLight} % dans le préambule
3822 \end{Verbatim}
3823 \end{footnotesize}
3824
3825 \medskip
3826 \begin{Verbatim}
3827 \begin{PitonExecute}[background-color=gray!15]
3828 def carré(x):
3829 """Calcule le carré de x"""
3830 ~emphase#\highLight{return x*x}@
3831 print(f'Le carré de 12 est {carré(12)}.')
3832 \end{PitonExecute}
3833 \end{Verbatim}
3834
3835 \medskip
3836 \begin{PitonExecute}[background-color=gray!15]
3837 def carré(x):
3838 """Calcule le carré de x"""
3839 \highLight{return x*x}
3840 print(f'Le carré de 12 est {carré(12)}.')
3841 \end{PitonExecute}
3842
3843
3844
3845 \bigskip
3846
3847 \subsubsection{Utilisation de l'environnement \{python\} de pyluatex avec la clé repl}
3848
3849 \label{python}
3850
3851 \index{python@\texttt{\{python\}} (environnement de \pkg{pyluatex})}
3852
3853 Avec la clé |repl|, l'environnement |{python}| de \pkg{pyluatex} passe son
3854 contenu à Python et renvoie ce que l'on obtient quand on fournit ce code à une
3855 boucle \textsc{repl} (\emph{read-eval-print loop}) de Python. On obtient un
3856 entrelacement d'instructions précédées par le prompt |>>>| de Python et des
3857 valeurs renvoyées par Python (et de ce qui a été demandé d'être affiché avec des
3858 \piton{print} de Python).
3859
3860 \medskip
3861 Il est ensuite possible de passer cela à un environnement |{Piton}| qui va faire un
3862 coloriage syntaxique et mettre sur fond grisé les lignes correspondant aux instructions
3863 fournies à l'interpréteur Python (la couleur de ce fond est réglable avec la clé
3864 |prompt-background-color| dont la valuer initiale est |gray!15|).
3865
3866
3867 \medskip
3868 Voici la programmation d'un environnement |{PitonREPL}| qui effectue ce travail (pour des
3869 raisons techniques, le |!| est ici obligatoire dans la signature de l'environnement). On
3870 ne peut pas procéder comme précédemment (dans l'utilisation «standard» de \pkg{pyluatex})
3871 car, bien sûr, c'est le retour fait par |{python}| qui doit être traité par
3872 \pkg{piton}. De ce fait, il ne sera pas possible de mettre des surcharges (avec
3873 |detected-commands|, |begin-escape|, etc.) dans le code.
3874
3875 \begin{Verbatim}
3876 \NewDocumentEnvironment{PitonREPL}{!O{}} % le ! est obligatoire
3877 {
3878 \PitonOptions
3879 {
3880 ~emphase#prompt-background-color=blue!15@ ,
3881 ~emphase#background-color=none@, % pour avoir des petites marges
3882 ~#1
3883 }
3884 \PyLTVerbatimEnv
3885 \begin{python}[repl,quiet]
3886 }
3887 {
3888 \end{python}
3889 \directlua
3890 {
3891 tex.print("\\begin{Piton}")
3892 tex.print(pyluatex.get_last_output())
3893 tex.print("\\end{Piton}")
3894 tex.print("")
3895 }
3896 \ignorespacesafterend
3897 }
3898 \end{Verbatim}
3899
3900 \medskip
3901 Voici un exemple d'utilisation de ce nouvel environnement |{PitonREPL}|.
3902
3903 \medskip
3904 \begin{Code}
3905 \emph{\begin{PitonREPL}}
3906 def valeur_absolue(x):
3907 """Renvoie la valeur absolue de x"""
3908 if x > 0:
3909 return x
3910 else:
3911 return -x
3912
3913 valeur_absolue(-3)
3914 valeur_absolue(0)
3915 valeur_absolue(5)
3916 \emph{\end{PitonREPL}}
3917 \end{Code}
3918
3919 \bigskip
3920
3921
3922 \NewDocumentEnvironment { PitonREPL } { }
3923 {
3924 \PitonOptions
3925 {
3926 prompt-background-color=blue!15 ,
3927 background-color=none ,
3928 }
3929 \PyLTVerbatimEnv
3930 \begin{python}[repl,quiet]
3931 }
3932 {
3933 \end{python}
3934 \directlua
3935 {
3936 tex.print("\\begin{Piton}")
3937 tex.print(pyluatex.get_last_output())
3938 tex.print("\\end{Piton}")
3939 tex.print("")
3940 }
3941 \ignorespacesafterend
3942 }
3943
3944
3945 \begin{PitonREPL}
3946 def valeur_absolue(x):
3947 """Renvoie la valeur absolue de x"""
3948 if x > 0:
3949 return x
3950 else:
3951 return -x
3952
3953 valeur_absolue(-3)
3954 valeur_absolue(0)
3955 valeur_absolue(5)
3956 \end{PitonREPL}
3957
3958
3959 \bigskip
3960 En fait, il est possible de ne pas faire afficher les prompts eux-mêmes (c'est-à-dire les
3961 chaînes de caractères |>>>| et |...|). En effet, \pkg{piton} propose un style pour ces
3962 éléments, qui est appelé |Prompt|. La valeur initial de ce style est vide, ce qui fait
3963 qu'aucune action n'est exécutée sur ces éléments qui sont donc affichés tels quels. En
3964 fournissant comme valeur une fonction qui se contente de gober son argument, on peut
3965 demander à ce qu'ils ne soient pas affichés.
3966
3967 \bigskip
3968 \begin{savenotes}
3969 \begin{Verbatim}
3970 \NewDocumentCommand{\Gobe}{m}{}#~color#black@~footnote#On a défini ici une fonction ~texttt#~string~Gobe@ mais, en fait, elle existe déjà en L3 sous le nom ~texttt#~string~use~_none:n@.@@
3971 \SetPitonStyle{ ~emphase#Prompt = \Gobe@ }
3972 \end{Verbatim}
3973 \end{savenotes}
3974
3975
3976
3977
3978 \NewDocumentCommand{\Gobe}{m}{}
3979 \ExplSyntaxOn
3980 \SetPitonStyle{ Prompt = \use_none:n }
3981 \ExplSyntaxOff
3982
3983 \bigskip
3984 L'exemple précédent donne alors :
3985
3986 \medskip
3987 \begin{Code}
3988 \emph{\begin{PitonREPL}}
3989 def valeur_absolue(x):
3990 """Renvoie la valeur absolue de x"""
3991 if x > 0:
3992 return x
3993 else:
3994 return -x
3995
3996 valeur_absolue(-3)
3997 valeur_absolue(0)
3998 valeur_absolue(5)
3999 \emph{\end{PitonREPL}}
4000 \end{Code}
4001
4002
4003 \bigskip
4004
4005 \begin{PitonREPL}
4006 def valeur_absolue(x):
4007 """Renvoie la valeur absolue de x"""
4008 if x > 0:
4009 return x
4010 else:
4011 return -x
4012
4013 valeur_absolue(-3)
4014 valeur_absolue(0)
4015 valeur_absolue(5)
4016 \end{PitonREPL}
4017
4018 \clearpage
4019
4020 \section{Les styles pour les différents langages informatiques}
4021
4022 \label{Semantic}
4023
4024
4025 \subsection{Le langage Python}
4026
4027 Le langage par défaut de l'extension \pkg{piton} est Python. Si besoin est, on peut
4028 revenir au langage Python avec |\PitonOptions{language=Python}|.
4029
4030 \bigskip
4031
4032 Les réglages initiaux effectués par \pkg{piton} dans |piton.sty| sont inspirés par le
4033 style \pkg{manni} de Pygments tel qu'il est appliqué au langage Python par
4034 Pygments.\footnote{Voir \url{https://pygments.org/styles/}. À remarquer que, par défaut,
4035 Pygments propose pour le style \pkg{manni} un fond coloré dont la couleur est la couleur
4036 HTML |#F0F3F3|. Il est possible d'avoir la même couleur dans |{Piton}| avec
4037 l'instruction : |\PitonOptions{background-color = [HTML]{F0F3F3}}|}
4038
4039 \vspace{1cm}
4040
4041
4042 \begin{center}
4043 \begin{tabularx}{\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
4044 \toprule
4045 \normalfont Style & Usage \\
4046 \midrule
4047 Number & les nombres \\
4048 String.Short & les chaînes de caractères courtes (entre \texttt{'} ou \texttt{"}) \\
4049 String.Long & les chaînes de caractères longues (entre \texttt{'''} ou \texttt{"""})
4050 sauf les chaînes de documentation (qui sont gérées par |String.Doc|)\\
4051 String & cette clé fixe à la fois |String.Short| et |String.Long| \\
4052 String.Doc & les chaînes de documentation (seulement entre |"""| suivant PEP~257) \\
4053 String.Interpol & les éléments syntaxiques des champs des f-strings (c'est-à-dire les
4054 caractères \texttt{\{} et \texttt{\}}) ; ce style hérite des styles
4055 |String.Short| et |String.Long| (suivant la chaîne où apparaît
4056 l'interpolation)\\
4057 Interpol.Inside & le contenu des interpolations dans les f-strings (c'est-à-dire les
4058 éléments qui se trouvent entre \texttt{\{} et~\texttt{\}}) ; si
4059 l'utilisateur n'a pas fixé ce style, ces éléments sont analysés et
4060 formatés par \pkg{piton} au même titre que le reste du code. \\
4061 Operator & les opérateurs suivants : \texttt{!= == << >> - \~{} + / * \% = < > \& .}
4062 \verb+|+ |@| \\ % |
4063 Operator.Word & les opérateurs suivants : |in|, |is|, |and|, |or| et |not| \\
4064 Name.Builtin & la plupart des fonctions prédéfinies par Python \\
4065 Name.Decorator & les décorateurs (instructions débutant par \verb|@|) \\
4066 Name.Namespace & le nom des modules (= bibliothèques extérieures) \\
4067 Name.Class & le nom des classes au moment de leur définition, c'est-à-dire après le
4068 mot-clé \verb|class| \\
4069 Name.Function & le nom des fonctions définies par l'utilisateur \emph{au moment de leur
4070 définition} (après le mot-clé |def|) \\
4071 UserFunction & le nom des fonctions précédemment définies par l'utilisateur (la valeur
4072 initiale de ce paramètre est {\ttfamily \textbackslash
4073 PitonStyle\{Identifier\}}, ce qui fait que ces noms de fonctions sont
4074 affichés comme les identifiants) \\
4075 Exception & les exceptions prédéfinies (ex.: \texttt{SyntaxError}) \\
4076 InitialValues & les valeurs initiales (et le symbole |=| qui précède) des arguments
4077 optionnels dans les définitions de fonctions ; si l'utilisateur n'a pas
4078 fixé ce style, ces éléments sont analysés et formatés par \pkg{piton}
4079 au même titre que le reste du code.\\
4080 Comment & les commentaires commençant par \texttt{\#} \\
4081 Comment.LaTeX & les commentaires commençant par \texttt{\#>} qui sont composés par
4082 \pkg{piton} comme du code LaTeX (et appelés simplement «commentaires
4083 LaTeX» dans ce document) \\
4084 Keyword.Constant & |True|, |False| et |None| \\
4085 Keyword & les mots-clés suivants :
4086 \ttfamily assert, break, case, continue, del,
4087 elif, else, except, exec, finally, for, from,
4088 global, if, import, in, lambda, non local,
4089 pass, raise, return, try, while,
4090 with, yield et yield from.\\
4091 Identifier & les identificateurs. \\
4092 \bottomrule
4093 \end{tabularx}
4094 \end{center}
4095
4096
4097 \newpage
4098
4099 \subsection{Le langage OCaml}
4100
4101 On peut basculer vers le langage |OCaml| avec la clé |language| : |language = OCaml|
4102
4103
4104 \bigskip
4105
4106
4107 \begin{center}
4108 \begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
4109 \toprule
4110 \normalfont Style & Usage \\
4111 \midrule
4112 Number & les nombres \\
4113 String.Short & les caractères (entre \texttt{'}) \\
4114 String.Long & les chaînes de caractères, entre |"| mais aussi les \emph{quoted-strings} \\
4115 String & cette clé fixe à la fois |String.Short| et |String.Long| \\
4116 Operator & les opérateurs, en particulier |+|, |-|, |/|, |*|, |@|, |!=|, |==|, |&&| \\
4117 Operator.Word & les opérateurs suivants : |asr|, |land|, |lor|, |lsl|, |lxor|,
4118 |mod| et |or| \\
4119 Name.Builtin & les fonctions |not|, |incr|, |decr|, |fst| et |snd| \\
4120 Name.Type & le nom des types OCaml \\
4121 Name.Field & le nom d'un champ de module \\
4122 Name.Constructor & le nom des constructeurs de types (qui débutent par une majuscule) \\
4123 Name.Module & le nom des modules \\
4124 Name.Function & le nom des fonctions définies par l'utilisateur \emph{au moment de leur
4125 définition} (après le mot-clé |let|) \\
4126 UserFunction & le nom des fonctions précédemment définies par l'utilisateur (la valeur
4127 initiale de ce paramètre est {\ttfamily \textbackslash
4128 PitonStyle\{Identifier\}}, ce qui fait que ces noms de fonctions sont
4129 affichés comme les identifiants) \\
4130 Exception & les exceptions prédéfinies (ex. : |End_of_File|) \\
4131 TypeParameter & les paramétreurs de type \\
4132 Comment & les commentaires, entre |(*| et |*)| ; ces commentaires peuvent être imbriqués \\
4133 Keyword.Constant & |true| et |false| \\
4134 Keyword & les mots-clés suivants :
4135 |assert|, |as|, |done|, |downto|, |do|, |else|, |exception|, |for|, |function| ,
4136 |fun|, |if|, |lazy|, |match|, |mutable|, |new|, |of|, |private|, |raise|,
4137 |then|, |to|, |try| , |virtual|, |when|, |while| et |with| \\
4138 Keyword.Governing & les mot-clés suivants : |and|, |begin|, |class|, |constraint|,
4139 |end|, |external|, |functor|, |include|, |inherit|, |initializer|,
4140 |in|, |let|, |method|, |module|, |object|, |open|, |rec|, |sig|,
4141 |struct|, |type| et |val|. \\
4142 Identifier & les identificateurs \\
4143 Delim & les délimiteurs |(|, |[|, \verb+[|+, |)|, |]| et \verb+|]+ \\
4144 Punct & les symboles de ponctuation |,| |:|, |;| et |!|. \\
4145 \bottomrule
4146 \end{tabularx}
4147 \end{center}
4148
4149 \vspace{1cm}
4150
4151 Voici un exemple :
4152
4153 \medskip
4154 \begin{Piton}[language = OCaml]
4155 let rec quick_sort lst = (* Tri par segmentation *)
4156 match lst with
4157 | [] -> []
4158 | pivot :: rest ->
4159 let left = List.filter (fun x -> x < pivot) rest in
4160 let right = List.filter (fun x -> x >= pivot) rest in
4161 quick_sort left @ [pivot] @ quick_sort right
4162 \end{Piton}
4163
4164 \newpage
4165
4166 \subsection[Le langage C (et C++)]{Le langage C (et \CC)}
4167
4168
4169 On peut basculer vers le langage |C| avec la clé |language| : |language = C|
4170
4171
4172 \bigskip
4173
4174 \begin{center}
4175 \begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
4176 \toprule
4177 \normalfont Style & Usage \\
4178 \midrule
4179 Number & les nombres \\
4180 String.Short & les caractères (entre \texttt{'}) \\
4181 String.Long & les chaînes de caractères (entre \texttt{"}) \\
4182 String.Interpol & les éléments \texttt{\%d}, \texttt{\%i}, \texttt{\%f}, \texttt{\%c},
4183 etc. dans les chaînes de caractères ; ce style hérite du style
4184 |String.Long| \\
4185 Operator & les opérateurs suivants : \texttt{!= == << >> - \~{} + / * \% = < > \& .} \verb+|+ |@| \\ % |
4186 Name.Type & les types prédéfinis suivants : |bool|, |char|, |char16_t|, |char32_t|,
4187 |double|, |float|, |int|, |int8_t|, |int16_t|, |int32_t|, |int64_t|, |long|,
4188 |short|, |signed|, |unsigned|, |void| et |wchar_t| \\
4189 Name.Builtin & les fonctions prédéfinies suivantes : |printf|, |scanf|, |malloc|, |sizeof|
4190 et |alignof| \\
4191 Name.Class & le nom des classes au moment de leur définition, c'est-à-dire après le
4192 mot-clé |class| \\
4193 Name.Function & le nom des fonctions définies par l'utilisateur \emph{au moment de leur
4194 définition} \\
4195 UserFunction & le nom des fonctions précédemment définies par l'utilisateur (la valeur
4196 initiale de ce paramètre est {\ttfamily \textbackslash
4197 PitonStyle\{Identifier\}}, ce qui fait que ces noms de fonctions sont
4198 affichés comme les identifiants) \\
4199 Preproc & les instructions du préprocesseur (commençant par |#|) \\
4200 Comment & les commentaires (commençant par \texttt{//} ou entre |/*| et |*/|) \\
4201 Comment.LaTeX & les commentaires commençant par \texttt{//>} qui sont composés par
4202 \pkg{piton} comme du code LaTeX (et appelés simplement «commentaires
4203 LaTeX» dans ce document) \\
4204 Keyword.Constant & |default|, |false|, |NULL|, |nullptr| et |true| \\
4205 Keyword & les mots-clés suivants : |alignas|, |asm|, |auto|, |break|, |case|, |catch|,
4206 |class|, |constexpr|, |const|, |continue|, |decltype|, |do|, |else|, |enum|,
4207 |extern|, |for|, |goto|, |if|, |nexcept|, |private|, |public|, |register|,
4208 |restricted|, |try|, |return|, |static|, |static_assert|, |struct|, |switch|,
4209 |thread_local|, |throw|, |typedef|, |union|, |using|, |virtual|, |volatile| et
4210 |while|
4211 \\
4212 Identifier & les identificateurs. \\
4213 \bottomrule
4214 \end{tabularx}
4215 \end{center}
4216
4217
4218 \newpage
4219
4220 \subsection{Le langage SQL}
4221
4222 On peut basculer vers le langage |SQL| avec la clé |language| : |language = SQL|
4223
4224
4225 \bigskip
4226
4227 \begin{center}
4228 \begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
4229 \toprule
4230 \normalfont Style & Usage \\
4231 \midrule
4232 Number & les nombres \\
4233 String.Long & les chaînes de caractères (entre \texttt{'} et non entre \texttt{"} car les éléments entre \texttt{"}
4234 sont des noms de champs et formatés avec |Name.Field|) \\
4235 Operator & les opérateurs suivants : \texttt{= != <> >= > < <= * + / } \\
4236 Name.Table & les noms des tables \\
4237 Name.Field & les noms des champs des tables \\
4238 Name.Builtin & les fonctions prédéfinies suivantes (leur nom n'est \emph{pas} sensible à
4239 la casse) : |avg|, |count|, |char_lenght|, |concat|, |curdate|,
4240 |current_date|, |date_format|, |day|, |lower|, |ltrim|, |max|, |min|,
4241 |month|, |now|, |rank|, |round|, |rtrim|, |substring|, |sum|, |upper| et
4242 |year|. \\
4243 Comment & les commentaires (débutant par |--| ou bien entre |/*| et |*/|) \\
4244 Comment.LaTeX & les commentaires commençant par \texttt{-->} qui sont composés par
4245 \pkg{piton} comme du code LaTeX (et appelés simplement «commentaires
4246 LaTeX» dans ce document) \\
4247 Keyword & les mots-clés suivants (leur nom n'est \emph{pas} sensible à la casse) :
4248 |abort|, |action|, |add|, |after|, |all|, |alter|, |always|, |analyze|,
4249 |and|, |as|, |asc|, |attach|, |autoincrement|, |before|, |begin|, |between|,
4250 |by|, |cascade|, |case|, |cast|, |check|, |collate|, |column|, |commit|,
4251 |conflict|, |constraint|, |create|, |cross|, |current|, |current_date|,
4252 |current_time|, |current_timestamp|, |database|, |default|, |deferrable|,
4253 |deferred|, |delete|, |desc|, |detach|, |distinct|, |do|, |drop|, |each|,
4254 |else|, |end|, |escape|, |except|, |exclude|, |exclusive|, |exists|,
4255 |explain|, |fail|, |filter|, |first|, |following|, |for|, |foreign|, |from|,
4256 |full|, |generated|, |glob|, |group|, |groups|, |having|, |if|, |ignore|,
4257 |immediate|, |in|, |index|, |indexed|, |initially|, |inner|, |insert|,
4258 |instead|, |intersect|, |into|, |is|, |isnull|, |join|, |key|, |last|,
4259 |left|, |like|, |limit|, |match|, |materialized|, |natural|, |no|, |not|,
4260 |nothing|, |notnull|, |null|, |nulls|, |of|, |offset|, |on|, |or|, |order|,
4261 |others|, |outer|, |over|, |partition|, |plan|, |pragma|, |preceding|,
4262 |primary|, |query|, |raise|, |range|, |recursive|, |references|, |regexp|,
4263 |reindex|, |release|, |rename|, |replace|, |restrict|, |returning|, |right|,
4264 |rollback|, |row|, |rows|, |savepoint|, |select|, |set|, |table|, |temp|,
4265 |temporary|, |then|, |ties|, |to|, |transaction|, |trigger|, |unbounded|,
4266 |union|, |unique|, |update|, |using|, |vacuum|, |values|, |view|, |virtual|,
4267 |when|, |where|, |window|, |with|, |without| \\
4268 \bottomrule
4269 \end{tabularx}
4270 \end{center}
4271
4272 \bigskip
4273 Si on souhaite que les mots-clés soient capitalisés automatiquement, on peut modifier le
4274 style |Keywords| localement pour le langage SQL avec l'instruction :
4275 \begin{Verbatim}
4276 \SetPitonStyle~emphase#[SQL]@{Keywords = \bfseries \MakeUppercase}
4277 \end{Verbatim}
4278
4279 \newpage
4280
4281 \subsection{Les langages définis par la commande \texttt{\textbackslash NewPitonLanguage}}
4282
4283 \indexcommand{NewPitonLanguage}
4284
4285 \vspace{1cm}
4286 La commande |\NewPitonLanguage|, qui permet de définir de nouveaux langages en utilisant
4287 la syntaxe de l'extension \pkg{listings}, a été présentée p.~\pageref{NewPitonLanguage}.
4288
4289 Tous les langages définis avec la commande |\NewPitonLanguage| partagent les mêmes styles.
4290
4291 \vspace{1cm}
4292
4293 \begin{center}
4294 \begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
4295 \toprule
4296 \normalfont Style & Usage \\
4297 \midrule
4298 Number & les nombres \\
4299 String.Long & les chaînes de caractères définies dans |\NewPitonLanguage| par la clé
4300 |morestring| \\
4301 Comment & les commentaires définis dans |\NewPitonLanguage| par la clé |morecomment| \\
4302 Comment.LaTeX & les commentaires qui sont composés par \pkg{piton} comme du code LaTeX (et
4303 appelés simplement «commentaires LaTeX» dans ce document) \\
4304 Keyword & les mots-clés, définis dans |\NewPitonLanguage| par les clés |morekeywords| et
4305 |moretexcs| (et également la clé |sensitive| qui indique si les mots-clés sont
4306 sensibles à la casse) \\
4307 Directive & les directives définies dans |\NewPitonLanguage| par la clé |moredirectives| \\
4308 Tag & les «tags» définis par la clé |tag| (les lexèmes détectés à l'intérieur d'un tag
4309 seront aussi composés avec leur propre style) \\
4310 Identifier & les identificateurs. \\
4311 \bottomrule
4312 \end{tabularx}
4313 \end{center}
4314
4315
4316 \vspace{1cm}
4317 Voici une possibilité de définition d'un language HTML, obtenu par une légère adaptation
4318 de la définition faite par \pkg{listings} (fichier |lstlang1.sty|).
4319
4320 \medskip
4321 \begin{small}
4322 \begin{Verbatim}
4323 \NewPitonLanguage{HTML}%
4324 {morekeywords={A,ABBR,ACRONYM,ADDRESS,APPLET,AREA,B,BASE,BASEFONT,%
4325 BDO,BIG,BLOCKQUOTE,BODY,BR,BUTTON,CAPTION,CENTER,CITE,CODE,COL,%
4326 COLGROUP,DD,DEL,DFN,DIR,DIV,DL,DOCTYPE,DT,EM,FIELDSET,FONT,FORM,%
4327 FRAME,FRAMESET,HEAD,HR,H1,H2,H3,H4,H5,H6,HTML,I,IFRAME,IMG,INPUT,%
4328 INS,ISINDEX,KBD,LABEL,LEGEND,LH,LI,LINK,LISTING,MAP,META,MENU,%
4329 NOFRAMES,NOSCRIPT,OBJECT,OPTGROUP,OPTION,P,PARAM,PLAINTEXT,PRE,%
4330 OL,Q,S,SAMP,SCRIPT,SELECT,SMALL,SPAN,STRIKE,STRING,STRONG,STYLE,%
4331 SUB,SUP,TABLE,TBODY,TD,TEXTAREA,TFOOT,TH,THEAD,TITLE,TR,TT,U,UL,%
4332 VAR,XMP,%
4333 accesskey,action,align,alink,alt,archive,axis,background,bgcolor,%
4334 border,cellpadding,cellspacing,charset,checked,cite,class,classid,%
4335 code,codebase,codetype,color,cols,colspan,content,coords,data,%
4336 datetime,defer,disabled,dir,event,error,for,frameborder,headers,%
4337 height,href,hreflang,hspace,http-equiv,id,ismap,label,lang,link,%
4338 longdesc,marginwidth,marginheight,maxlength,media,method,multiple,%
4339 name,nohref,noresize,noshade,nowrap,onblur,onchange,onclick,%
4340 ondblclick,onfocus,onkeydown,onkeypress,onkeyup,onload,onmousedown,%
4341 profile,readonly,onmousemove,onmouseout,onmouseover,onmouseup,%
4342 onselect,onunload,rel,rev,rows,rowspan,scheme,scope,scrolling,%
4343 selected,shape,size,src,standby,style,tabindex,text,title,type,%
4344 units,usemap,valign,value,valuetype,vlink,vspace,width,xmlns},%
4345 tag=<>,%
4346 alsoletter = - ,%
4347 sensitive=f,%
4348 morestring=[d]",
4349 }
4350 \end{Verbatim}
4351 \end{small}
4352
4353 \newpage
4354
4355 \subsection{Le langage «minimal»}
4356
4357
4358 \label{minimal}
4359 \index{minimal (langage «minimal»)}
4360
4361 On peut basculer vers le langage «|minimal|» avec la clé |language| : |language = minimal|
4362
4363
4364 \bigskip
4365
4366 \begin{center}
4367 \begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
4368 \toprule
4369 \normalfont Style & Usage \\
4370 \midrule
4371 Number & les nombres \\
4372 String & les chaînes de caractères (qui sont entre \texttt{"}) \\
4373 Comment & les commentaires (qui débutent par |#|) \\
4374 Comment.LaTeX & les commentaires commençant par \texttt{\#>} qui sont composés par
4375 \pkg{piton} comme du code LaTeX (et appelés simplement «commentaires
4376 LaTeX» dans ce document) \\
4377 Identifier & les identificateurs. \\
4378 \bottomrule
4379 \end{tabularx}
4380 \end{center}
4381
4382 \bigskip
4383 Ce langage «|minimal|» est proposé par \pkg{piton} à l'utilisateur final pour qu'il puisse
4384 y ajouter des formatages de mots-clés avec la commande |\SetPitonIdentifier| (cf.
4385 \ref{SetPitonIdentifier}, p.~\pageref{SetPitonIdentifier}) et créer par exemple un langage
4386 pour pseudo-code.
4387
4388 \vspace{2cm}
4389
4390 \subsection{Le langage «verbatim»}
4391
4392
4393 \label{verbatim}
4394 \index{verbatim (langage «verbatim»)}
4395
4396 On peut basculer vers le langage «|verbatim|» avec la clé |language| : |language = verbatim|
4397
4398 \bigskip
4399
4400 \begin{center}
4401 \begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
4402 \toprule
4403 \normalfont Style & Usage \\
4404 \midrule
4405 \emph{rien...} & \\
4406 \bottomrule
4407 \end{tabularx}
4408 \end{center}
4409
4410 \bigskip
4411 Le langage «|verbatim|» ne propose aucun style et ne fait donc aucun formatage
4412 syntaxique. On peut néanmoins y utiliser le mécanisme |detected-commands| (cf. partie
4413 \ref{detected-commands}, p.~\pageref{detected-commands}) ainsi que le
4414 mécanisme de détection des commandes et des environnements de Beamer.
4415
4416
4417
4418
4419
4420 \newpage
4421
4422 \phantomsection
4423 \addcontentsline{toc}{section}{Index}
4424
4425 \printindex
4426
4427
4428 \section*{Remerciements}
4429
4430 Remerciements à Yann Salmon et Pierre Le Scornet pour leurs nombreuses suggestions pertinentes.
4431
4432 \section*{Autre documentation}
4433
4434 Le document |piton.pdf| (fourni avec l'extension \pkg{piton}) contient
4435 une traduction anglaise de la documentation ici présente ainsi qu'un historique des versions.
4436 Le fichier |piton-code.pdf| contient le code commenté de l'extension \pkg{piton}.
4437
4438
4439 \medskip
4440 Les versions successives du fichier |piton.sty| fournies par
4441 TeX Live sont disponibles sur le serveur \textsc{svn} de TeX Live :
4442
4443 \smallskip
4444 {
4445 \small
4446 \nolinkurl{https://tug.org/svn/texlive/trunk/Master/texmf-dist/tex/lualatex/piton/piton.sty}
4447 }
4448
4449 \medskip
4450 Le développement de l'extension \pkg{piton} se fait sur le dépôt GitHub suivant :
4451
4452 \smallskip
4453 \verb|https://github.com/fpantigny/piton|
4454
4455
4456 \tableofcontents
4457
4458 \end{document}
4459
4460 % Local Variables:
4461 % fill-column: 80
4462 % End: