diff options
author | Norbert Preining <norbert@preining.info> | 2023-01-30 03:04:17 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2023-01-30 03:04:17 +0000 |
commit | 326add29024271cbd541ac55448e616e833ae5fa (patch) | |
tree | 3a7301e802591c20575b65b94b21291641e7641f /macros/luatex/latex/piton/piton-french.tex | |
parent | dab4e7c261c34234f9d9f1ac92923d6f903046ef (diff) |
CTAN sync 202301300304
Diffstat (limited to 'macros/luatex/latex/piton/piton-french.tex')
-rw-r--r-- | macros/luatex/latex/piton/piton-french.tex | 2745 |
1 files changed, 1453 insertions, 1292 deletions
diff --git a/macros/luatex/latex/piton/piton-french.tex b/macros/luatex/latex/piton/piton-french.tex index fa8d300841..a55beb8191 100644 --- a/macros/luatex/latex/piton/piton-french.tex +++ b/macros/luatex/latex/piton/piton-french.tex @@ -1,1293 +1,1454 @@ -% -*- coding: utf-8 ; -*-
-\documentclass[dvipsnames]{article}
-
-\usepackage{fontspec}
-
-\usepackage[french]{babel}
-\frenchsetup{og = « , fg = »}
-
-\usepackage[footnotehyper,escape-inside=$$,math-comments]{piton}
-
-\usepackage[executable=python.exe]{pyluatex}
-
-\usepackage{xcolor}
-
-\usepackage{geometry}
-\geometry{left=2.8cm,right=2.8cm,top=2.5cm,bottom=2.5cm,papersize={21cm,29.7cm}}
-
-\usepackage{enumitem}
-\usepackage{verbatim}
-\usepackage{amsmath}
-\usepackage{tabularx}
-\usepackage{booktabs}
-\usepackage{tcolorbox}
-
-\usepackage{caption}
-
-% We use \MakeShortVerb of shortvrb and not \DefineShortVerb of fancyvrb
-% because we don't want the contents of short verbatim colored in gray
-\usepackage{shortvrb}
-\MakeShortVerb{\|}
-
-\usepackage{varwidth}
-
-\skip\footins = 2\bigskipamount
-
-\usepackage{fancyvrb}
-\fvset{commandchars=\~\#\@,formatcom=\color{gray}}
-\def\emphase{\bgroup\color{RoyalPurple}\let\next=}
-
-
-\usepackage{titlesec}
-\titlespacing*{\section}{0pt}{6.5ex plus 1ex minus .2ex}{4.3ex plus .2ex}
-\titlespacing*{\subsection}{0pt}{4.5ex plus 1ex minus .2ex}{2ex plus .2ex}
-
-\def\interitem{\vspace{7mm plus 2 mm minus 3mm}}
-
-
-\usepackage[hyperfootnotes = false]{hyperref}
-
-\hypersetup
- {
- pdfinfo =
- {
- Title = L’extension piton ,
- Subject = Une extension LaTeX ,
- Author = F. Pantigny
- }
- }
-
-
-
-
-\NewDocumentCommand {\pkg} {m} {\textsf{#1}}
-\NewDocumentCommand {\cls} {m} {\textsf{#1}}
-
-\setlength{\parindent}{0pt}
-
-
-\begin{document}
-
-\PitonOptions{splittable = 4}
-
-\VerbatimFootnotes
-
-
-\title{L'extension LaTeX \pkg{piton}\thanks{Ce document correspond à la
-version~\myfileversion\space de \pkg{piton}, à la date du~\myfiledate.}}
-\author{F. Pantigny \\ \texttt{fpantigny@wanadoo.fr}}
-
-\maketitle
-
-\begin{abstract}
-L'extension \pkg{piton} propose des outils pour composer du code Python avec une coloration syntaxique
-en utilisant la bibliothèque Lua LPEG. L'extension \pkg{piton} nécessite l'emploi de LuaLaTeX.
-\end{abstract}
-
-\section{Présentation}
-
-L'extension \pkg{piton} utilise la librairie Lua nommée LPEG\footnote{LPEG est une librairie de capture de motifs
- (\emph{pattern-matching} en anglais) pour Lua, écrite en C, fondée sur les PEG (\emph{parsing expression
- grammars}): \url{http://www.inf.puc-rio.br/~roberto/lpeg/}} pour «parser» le code Python et le composer avec un
-coloriage syntaxique. Comme elle utilise du code Lua, elle fonctionne uniquement avec |lualatex| (et ne va pas
-fonctionner avec les autres moteurs de compilation LaTeX, que ce soit |latex|, |pdflatex| ou |xelatex|). Elle
-n'utilise aucun programme extérieur et la compilation ne requiert donc pas |--shell-escape|. La compilation est
-très rapide puisque tout le travail du parseur est fait par la librairie LPEG, écrite en C.
-
-\bigskip
-Voici un exemple de code Python composé avec l'environnement |{Piton}| proposé par \pkg{piton}.
-
-\bigskip
-\begin{Piton}
-from math import pi
-
-def arctan(x,n=10):
- """Compute the mathematical value of arctan(x)
-
- n is the number of terms in the sum
- """
- if x < 0:
- return -arctan(-x) # appel récursif
- elif x > 1:
- return pi/2 - arctan(1/x)
- #> (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\#>.}
- else:
- s = 0
- for k in range(n):
- s += (-1)**k/(2*k+1)*x**(2*k+1)
- return s
-\end{Piton}
-
-\bigskip
-
-L'extension LaTeX \pkg{piton} est entièrement contenue dans le fichier |piton.sty|. Ce
-fichier peut être placé dans le répertoire courant ou dans une arborescence |texmf|. Le mieux reste néanmoins
-d'installer \pkg{piton} avec une distribution TeX comme MiKTeX, TeX~Live ou MacTeX.
-
-
-\section{Utilisation de l'extension}
-
-\subsection{Chargement de l'extension}
-
-L'extension \pkg{piton} se charge simplement avec la commande |\usepackage| : |\usepackage{piton}|.
-
-On a cependant deux remarques à formuler :
-\begin{itemize}
-\item l'extension \pkg{piton} utilise l'extension \pkg{xcolor} (mais \pkg{piton} ne charge pas \pkg{xcolor} : si
-\pkg{xcolor} n'est pas chargée avant le |\begin{document}|, une erreur fatale sera levée) ;
-
-\item l'extension \pkg{piton} n'est utilisable qu'avec LuaLaTeX : si un autre moteur de compilation (comme |latex|,
-|pdflatex| ou |xelatex|) est utilisé, une erreur fatale sera levée.
-\end{itemize}
-
-\subsection{Les commandes et environnements à la disposition de l'utilisateur}
-
-L'extension \pkg{piton} fournit plusieurs outils pour composer du code Python: les commandes |\piton|,
-l'environnement |{Piton}| et la commande |\PitonInputFile|.
-
-\begin{itemize} \setlength{\fboxsep}{1pt}
-\item La commande \colorbox{gray!20}{\ttfamily \textbackslash piton} doit être utilisée pour composer de petits éléments de code à l'intérieur d'un
-paragraphe. Par exemple :
-
-{\color{gray}\verb|\piton{def carré(x): return x*x}|}\qquad
-\piton{def carré(x): return x*x}
-
-La syntaxe et les particularités de la commande sont détaillées ci-après.
-
-
-\item L'environnement \colorbox{gray!20}{\ttfamily \{Piton\}} doit être utilisé pour composer des codes de
-plusieurs lignes. Comme cet environnement prend son argument selon un mode verbatim, il ne peut pas être utilisé
-dans l'argument d'une commande LaTeX. Pour les besoins de personnalisation, il est possible de définir de nouveaux
-environnements similaires à |{Piton}| en utilisant la commande |\NewPitonEnvironment| : cf. partie
-\ref{NewPitonEnvironment} p.~\pageref{NewPitonEnvironment}.
-
-\item La commande \colorbox{gray!20}{\ttfamily \textbackslash PitonInputFile} doit être utilisée pour insérer et
-composer un fichier extérieur.
-
-Cette commande prend en argument optionnel entre crochets deux clés |first-line| et |last-line| qui permettent de
-n'insérer que la partie du fichier comprise entre les lignes correspondantes.
-\end{itemize}
-
-
-\subsection{La syntaxe de la commande \textbackslash piton}
-
-
-La commande |\piton| possède en fait une syntaxe double. Elle est peut être utilisée comme une commande standard de
-LaTeX prenant son argument entre accolades (|\piton{...}|), ou bien selon la syntaxe de la commande |\verb| où l'argument est
-délimité entre deux caractères identiques (par ex. : \verb!\piton|...|!). On détaille maintenant ces deux syntaxes.
-
-\bigskip
-\begin{itemize}
-\item {\color{blue} \textsf{Syntaxe} \verb|\piton{...}|}\par\nobreak
-
-Quant son argument est donné entre accolades, la commande |\piton| ne prend pas son argument en mode verbatim. Les
-points suivants doivent être remarqués :
-
-\begin{itemize}
-\item plusieurs espaces successifs sont remplacés par un unique espace ;
-\item il n'est pas possible d'utiliser le caractère |%| à l'intérieur ;
-\item les accolades doivent apparaître par paires correctement imbriquées;
-\item les commandes LaTeX (celles commençant par une contre-oblique |\| mais également les caractères actifs) sont
-complètement développées (mais non exécutées).
-\end{itemize}
-
-Un mécanisme d'échappement est fourni : les commandes |\\|, |\%|, |\{| et |\}| insèrent les caractères
-correspondants |\|, |%|,
-|{| et |}|. Ces deux dernières commandes ne sont nécessaires que si on a besoin d'insérer des accolades
-non équilibrées.
-
-Les autres caractères (y compris |#|, |^|, |_|, |&|, |$| % $
-et |@|) doivent être insérés sans contre-oblique.
-
-Exemples :
-
-\begin{tabular}{>{\color{gray}}l@{\hspace*{1cm}}l}
-\verb|\piton{ma_chaîne = '\\n'}| &
-\piton{ma_chaîne = '\\n' } \\
-\verb|\piton{def pair(n): return n\%2==0}| &
-\piton{def pair(n): return n\%2==0 } \\
-\verb|\piton{c="#" # une affectation }| &
-\piton{c="#" # une affectation } \\
-\verb|\piton{my_dict = {'a': 3, 'b': 4}}| &
-\piton{my_dict = {'a': 3, 'b': 4}}
-\end{tabular}
-
-\smallskip
-La commande |\piton| avec son argument entre accolades peut être utilisée dans les arguments des autres commandes LaTeX.\footnote{La commande
- |\piton| peut par exemple être
- utilisée dans une note de bas de page. Exemple : \piton{s = 'Une chaîne'}.}
-
-\bigskip
-\item {\color{blue} \textsf{Syntaxe} \verb!\piton|...|!}\par\nobreak
-
-Quand la commande |\piton| prend son argument entre deux caractères identiques, cet argument est pris \emph{en mode
- verbatim}. De ce fait, avec cette syntaxe, la commande |\piton| ne peut \emph{pas} être utilisée dans l'argument d'une
-autre fonction.
-
-\medskip
-Exemples :
-
-\begin{tabular}{>{\color{gray}}l@{\hspace*{1cm}}l}
-\verb!\piton|ma_chaîne = '\n'|! &
-\piton|ma_chaîne = '\n'| \\
-\verb|\piton!def pair(n): return n%2==0!| &
-\piton!def pair(n): return n%2==0! \\
-\verb|\piton+c="#" # une affectation +| &
-\piton+c="#" # une affectation + \\
-\verb|\piton?my_dict = {'a': 3, 'b': 4}?| &
-\piton!my_dict = {'a': 3, 'b': 4}!
-\end{tabular}
-
-\end{itemize}
-
-\section{Personnalisation}
-
-\subsection{La commande \textbackslash PitonOptions}
-
-\NewDocumentCommand{\Definition}{m}
- {{\setlength{\fboxsep}{1pt}\colorbox{gray!20}{\ttfamily \vphantom{gl}#1}}}
-
-
-La commande |\PitonOptions| prend en argument une liste de couples \textsl{clé=valeur}. La portée des réglages
-effectués par cette commande est le groupe TeX courant.\footnote{On rappelle que tout environnement LaTeX est, en particulier, un groupe.}
-
-\begin{itemize}
-\item La clé \Definition{gobble} prend comme valeur un entier positif $n$ : les $n$ premiers caractères de chaque
-ligne sont alors retirés (avant formatage du code) dans les environnements |{Piton}|. Ces $n$ caractères ne sont
-pas nécessairement des espaces.
-
-\item Quand la clé \Definition{auto-gobble} est activée, l'extension \pkg{piton} détermine la valeur minimale $n$
-du nombre d'espaces successifs débutant chaque ligne (non vide) de l'environnement |{Piton}| et applique |gobble|
-avec cette valeur de~$n$.
-
-\item Quand la clé \Definition{env-gobble} est activée, \pkg{piton} analyse la dernière ligne de l'environnement,
-c'est-à-dire celle qui contient le |\end{Piton}| et détermine si cette ligne ne comporte que des espaces suivis par
-|\end{Piton}|. Si c'est le cas, \pkg{piton} calcule le nombre $n$ de ces espaces et applique |gobble| avec cette
-valeur de~$n$. Le nom de cette clé vient de \emph{environment gobble}: le nombre d'espaces à retirer ne dépend que
-de la position des délimiteurs |\begin{Piton}| et |\end{Piton}| de l'environnement.
-
-\item Avec la clé \Definition{line-numbers}, les lignes \emph{non vides} (et toutes les lignes des
-\emph{docstrings}, y compris celles qui sont vides) sont numérotées dans les environnements \verb|{Piton}| et dans
-les listings produits par la commande |\PitonInputFile|.
-
-\item Avec la clé \Definition{all-line-numbers}, \emph{toutes} les lignes sont numérotées, y compris les lignes vides.
-
-\item La clé \Definition{left-margin} fixe une marge sur la gauche. Cette clé peut être utile, en particulier, en
-conjonction avec l'une des clés |line-numbers| et |all-line-numbers| si on ne souhaite pas que les numéros de ligne
-soient dans une position en débordement sur la gauche.
-
-Il est possible de donner à la clé |left-margin| la valeur spéciale~|auto|. Avec cette valeur, une marge est
-insérée automatiquement pour les numéros de ligne quand l'une des clés |line-numbers| ou |all-line-numbers| est
-utilisée. Voir un exemple à la partie \ref{example-numbering} p.~\pageref{example-numbering}.
-
-\item Avec la clé \Definition{resume}, le compteur de lignes n'est pas remis à zéro comme il l'est normalement au
-début d'un environnement |{Piton}| ou bien au début d'un listing produit par |\PitonInputFile|. Cela permet de
-poursuivre la numérotation d'un environnement à l'autre.
-
-\item La clé \Definition{background-color} fixe la couleur de fond des environnements |{Piton}| et des listings
-produits par |\PitonInputFile| (ce fond a une largeur égale à la valeur courante de |\linewidth|).
-
-\item \colorbox{yellow!50}{\textbf{Modification 1.2}}\enskip En activant la clé \Definition{show-spaces-in-strings}, les
-espaces dans les chaînes courtes (c'est-à-dire celles délimitées par |'| ou |"|) sont matérialisés par le caractère
-␣ (U+2423 : \textsc{open box}). Bien sûr, le caractère U+2423 doit être présent dans la fonte mono-chasse
-utilisée.\footnote{L'extension \pkg{piton} utilise simplement la fonte mono-chasse courante. Pour la changer, le
- mieux est d'utiliser |\setmonofont| de \pkg{fontspec}.}\par\nobreak
-%
-\begingroup
-\PitonOptions{show-spaces-in-strings}
-Exemple : \piton{my_string = 'Très bonne réponse'}
-\endgroup
-
-\smallskip
-Avec la clé \Definition{show-spaces}, tous les espaces sont matérialisés (et aucune coupure de ligne ne peut plus
-intervenir sur ces espace matérialisés, même si la clé |break-lines| est active).
-\end{itemize}
-
-\bigskip
-
-\begingroup
-\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
-\begin{Verbatim}
-~emphase&\PitonOptions{line-numbers,auto-gobble,background-color = gray!15}@
-\begin{Piton}
- from math import pi
-
- def arctan(x,n=10):
- """Compute the mathematical value of arctan(x)
-
- n is the number of terms in the sum
- """
- if x < 0:
- return -arctan(-x) # appel récursif
- elif x > 1:
- return pi/2 - arctan(1/x)
- #> (on a utilisé le fait que $\arctan(x)+\arctan(1/x)=\pi/2$ pour $x>0$)
- else:
- s = 0
- for k in range(n):
- s += (-1)**k/(2*k+1)*x**(2*k+1)
- return s
-\end{Piton}
-\end{Verbatim}
-\endgroup
-
-\begingroup
-\PitonOptions{line-numbers,auto-gobble,background-color = gray!15}
-\begin{Piton}
- from math import pi
-
- def arctan(x,n=10):
- """Compute the value of arctan(x)
-
- n is the number of terms in the sum
- """
- if x < 0:
- return -arctan(-x) # appel récursif
- elif x > 1:
- return pi/2 - arctan(1/x)
- #> (on a utilisé le fait que $\arctan(x)+\arctan(1/x)=\pi/2$ pour $x>0$)
- else:
- s = 0
- for k in range(n):
- s += (-1)**k/(2*k+1)*x**(2*k+1)
- return s
-\end{Piton}
-\endgroup
-
-
-\bigskip
-La commande |\PitonOptions| propose d'autres clés qui seront décrites plus loin (voir en particulier la coupure des
-pages et des lignes p.~\pageref{breakable}).
-
-
-\subsection{Les styles}
-
-\label{styles}
-
-L'extension \pkg{piton} fournit la commande |\SetPitonStyle| pour personnaliser les différents styles utilisés pour
-formater les éléments syntaxiques des listings Python. Ces personnalisations ont une portée qui correspond au
-groupe TeX courant.\footnote{On rappelle que tout environnement LaTeX est, en particulier, un groupe.}
-
-\bigskip
-La commande |\SetPitonStyle| prend en argument une liste de couples \textsl{clé=valeur}. Les clés sont les noms des
-styles et les valeurs sont les instructions LaTeX de formatage correspondantes.
-
-\bigskip
-Ces instructions LaTeX doivent être des instructions de formatage du type de |\bfseries|, |\slshape|,
-|\color{...}|, etc. (les commandes de ce type sont parfois qualifiées de \emph{semi-globales}). Il est aussi
-possible de mettre, \emph{à la fin de la liste d'instructions}, une commande LaTeX prenant exactement un argument.
-
-\bigskip
-Voici un exemple qui change le style utilisé pour le nom d'une fonction Python, au moment de sa définition
-(c'est-à-dire après le mot-clé |def|).
-
-\begin{Verbatim}
-\SetPitonStyle
- { Name.Function = \bfseries \setlength{\fboxsep}{1pt}\colorbox{yellow!50} }
-\end{Verbatim}
-
-Dans cet exemple, |\colorbox{yellow!50}| doit être considéré comme le nom d'une fonction LaTeX qui prend exactement
-un argument, puisque, habituellement, elle est utilisée avec la syntaxe
-|\colorbox{yellow!50}{|\texttt{\slshape text}|}|.
-
-\medskip
-\begingroup
-\SetPitonStyle
- { Name.Function = \bfseries \setlength{\fboxsep}{1pt}\colorbox{yellow!50} }
-Avec ce réglage, on obtient : \piton{def cube(x) : return x * x * x }
-\endgroup
-
-
-\bigskip
-Les différents styles sont décrits dans la table \ref{Semantic}. Les réglages initiaux effectués par \pkg{piton}
-dans |piton.sty| sont inspirés par le style \pkg{manni} de Pygments.\footnote{Voir
- \url{https://pygments.org/styles/}. À remarquer que, par défaut, Pygments propose pour le style \pkg{manni} un
- fond coloré dont la couleur est la couleur HTML |#F0F3F3|.}
-
-\begin{table}[htb]
-\centering
-\caption{Les styles proposés par \pkg{piton}}
-\label{Semantic}
-\begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
-\toprule
-\normalfont Style & Usage \\
-\midrule
-Number & les nombres \\
-String.Short & les chaînes de caractères courtes (entre \texttt{'} ou \texttt{"}) \\
-String.Long & les chaînes de caractères longues (entre \texttt{'''} ou \texttt{"""}) sauf les chaînes de
- documentation \\
-String & cette clé fixe à la fois |String.Short| et |String.Long| \\
-String.Doc & les chaînes de documentation (seulement entre |"""| suivant PEP~257) \\
-String.Interpol & les éléments syntaxiques des champs des f-strings (c'est-à-dire les caractères \texttt{\{}et \texttt{\}}) \\
-Operator & les opérateurs suivants : \texttt{!= == << >> - \~{} + / * \% = < > \& .} \verb+|+ \verb|@| \\
-Operator.Word & les opérateurs suivants : |in|, |is|, |and|, |or| et |not| \\
-Name.Builtin & la plupart des fonctions prédéfinies par Python \\
-Name.Function & le nom des fonctions définies par l'utilisateur \emph{au moment de leur définition}, c'est-à-dire
- après le mot-clé \verb|def| \\
-Name.Decorator & les décorateurs (instructions débutant par \verb|@|) \\
-Name.Namespace & le nom des modules (= bibliothèques extérieures) \\
-Name.Class & le nom des classes au moment de leur définition, c'est-à-dire après le mot-clé \verb|class| \\
-Exception & le nom des exceptions prédéfinies (ex.: SyntaxError) \\
-Comment & les commentaires commençant par \texttt{\#} \\
-Comment.LaTeX & les commentaires commençant par \texttt{\#>} qui sont composés en LaTeX par \pkg{piton} (et
- appelés simplement «commentaires LaTeX» dans ce document) \\
-Keyword.Constant & |True|, |False| et |None| \\
-Keyword & les mots-clés suivants :
- \ttfamily assert, break, case, continue, del,
- elif, else, except, exec, finally, for, from,
- global, if, import, lambda, non local,
- pass, raise, return, try, while,
- with, yield, yield from.\\
- \bottomrule
-\end{tabularx}
-\end{table}
-
-
-
-
-
-
-\subsection{Définition de nouveaux environnements}
-
-\label{NewPitonEnvironment}
-
-Comme l'environnement |{Piton}| a besoin d'absorber son contenu d'une manière spéciale (à peu près comme du texte
-verbatim), il n'est pas possible de définir de nouveaux environnements directement au-dessus de l'environnement
-|{Piton}| avec les commandes classiques |\newenvironment| et |\NewDocumentEnvironment|.
-
-C'est pourquoi \pkg{piton} propose une commande |\NewPitonEnvironment|. Cette commande a la même syntaxe que la
-commande classique |\NewDocumentEnvironment|.
-
-\bigskip
-Par exemple, avec l'instruction suivante, un nouvel environnement |{Python}| sera défini avec le même comportement
-que l'environnement |{Piton}|:
-
-{\color{gray}\verb|\NewPitonEnvironment{Python}{}{}{}|}
-
-
-\bigskip
-Si on souhaite un environnement |{Python}| qui prenne en argument optionnel entre crochets les clés de
-|\PitonOptions|, on peut écrire :
-
-{\color{gray}\verb|\NewPitonEnvironment{Python}{O{}}{\PitonOptions{#1}}{}|}
-
-\bigskip
-Si on souhaite un environnement |{Python}| qui compose le code inclus dans une boîte de \pkg{tcolorbox}, on peut
-écrire:
-
-\begin{verbatim}
-\NewPitonEnvironment{Python}{}
- {\begin{tcolorbox}}
- {\end{tcolorbox}}
-\end{verbatim}
-
-\bigskip
-Avec ce nouvel environnement |{Python}|, on écrire :
-
-\begin{Verbatim}
-~emphase#\begin{Python}@
-def carré(x):
- """Calcule le carré d'un nombre"""
- return x*x
-~emphase#\end{Python}@
-\end{Verbatim}
-
-\NewPitonEnvironment{Python}{}
- {\begin{tcolorbox}}
- {\end{tcolorbox}}
-
-\begin{Python}
-def carré(x):
- """Calcule le carré d'un nombre"""
- return x*x
-\end{Python}
-
-
-\section{Fonctionnalités avancées}
-
-\subsection{Les échappements vers LaTeX}
-
-L'extension \pkg{piton} propose plusieurs mécanismes d'échappement vers LaTeX :
-\begin{itemize}
-\item Il est possible d'avoir des commentaires entièrement composés en LaTeX.
-\item Il est possible d'avoir, dans les commentaires Python, les éléments entre \texttt{\$} composés en mode
-mathématique de LaTeX.
-\item Il est possible d'insérer du code LaTeX à n'importe quel endroit d'un listing Python.
-\item Dans le cas où la classe Beamer est utilisée, l'extension \pkg{piton} détecte automatiquement certaines
-commandes de Beamer.
-\end{itemize}
-
-
-\subsubsection{Les «commentaires LaTeX»}
-
-Dans ce document, on appelle «commentaire LaTeX» des commentaires qui débutent par |#>|. Tout ce qui suit ces deux
-caractères, et jusqu'à la fin de la ligne, sera composé comme du code LaTeX standard.
-
-Il y a deux outils pour personnaliser ces commentaires.
-
-\begin{itemize}
-\item Il est possible de changer le marquage syntaxique utilisé (qui vaut initialement~|#>|). Pour ce faire, il
-existe une clé |comment-latex|, disponible seulement au chargement de \pkg{piton} (c'est-à-dire au moment du
-|\usepackage|), qui permet de choisir les caractères qui (précédés par~|#|) serviront de marqueur syntaxique.
-
-Par exemple, avec le chargement suivant :
-
-\quad \verb|\usepackage[comment-latex = LaTeX]{piton}|
-
-les commentaires LaTeX commenceront par~|#LaTeX|.
-
-Si on donne la valeur nulle à la clé |comment-latex|, tous les commentaires Python (débutant par~|#|) seront en
-fait des «commentaires LaTeX».
-
-\smallskip
-\item Il est possible de changer le formatage du commentaire LaTeX lui-même en changeant le style \pkg{piton}
-|Comment.LaTeX|.
-
-Par exemple, avec |\SetPitonStyle{Comment.LaTeX = \normalfont\color{blue}}|, les commentaires LaTeX seront composés
-en bleu.
-
-Si on souhaite qu'un croisillon (|#|) soit affiché en début de commentaire dans le \textsc{pdf}, on peut régler
-|Comment.LaTeX| de la manière suivante :
-
-\begin{Verbatim}
-\SetPitonStyle{Comment.LaTeX = \color{gray}\~#\normalfont\space }
-\end{Verbatim}
-
-Pour d'autres exemples de personnalisation des commentaires LaTeX, voir la partie \ref{example-comments}
-p.~\pageref{example-comments}.
-\end{itemize}
-
-
-\subsubsection{La clé «math-comments»}
-
-Il est possible de demander que, dans les commentaires Python normaux, c'est-à-dire débutant par~|#| (et non par
-|#>|), les éléments placés entre symboles \texttt{\$} soient composés en mode mathématique de LaTeX (le reste du
-commentaire restant composé en verbatim).
-
-La clé |math-comments|, qui n'est disponible qu'au chargement de \pkg{piton} (c'est-à-dire au moment du
-|\usepackage|), active ce comportement.
-
-\bigskip
-Dans l'exemple suivant, on suppose que la clé |math-comments| a été utilisée au chargement de \pkg{piton}.
-
-\begin{Verbatim}
-\begin{Piton}
-def carré(x):
- return x*x ~# renvoie $x^2$
-\end{Piton}
-\end{Verbatim}
-
-\begin{Piton}
-def carré(x):
- return x*x # renvoie $x^2$
-\end{Piton}
-
-
-\subsubsection{Le mécanisme «espace-inside»}
-
-Il est aussi possible de surcharger les listings Python pour y insérer du code LaTeX à peu près n'importe où (mais
-entre deux lexèmes, bien entendu). Cette fonctionnalité n'est pas activée par défaut par \pkg{piton}. Pour
-l'utiliser, il faut spécifier les deux caractères marquant l'échappement (le premier le commençant et le deuxième
-le terminant) en utilisant la clé |escape-inside| au chargement de \pkg{piton} (c'est-à-dire au moment du
-|\usepackage|). Les deux caractères peuvent être identiques.
-
-
-\bigskip
-Dans l'exemple suivant, on suppose que l'extension \pkg{piton} a été chargée de la manière suivante :
-
-\begin{Verbatim}
-\usepackage[~emphase#escape-inside=$$@]{piton}
-\end{Verbatim}
-
-\medskip
-Dans le code suivant, qui est une programmation récursive de la factorielle, on décide de surligner en jaune
-l'instruction qui contient l'appel récursif.
-\begin{Verbatim}
-\begin{Piton}
-def fact(n):
- if n==0:
- return 1
- else:
- ~emphase#$\colorbox{yellow!50}{$@return n*fact(n-1)~emphase#$}$@
-\end{Piton}
-\end{Verbatim}
-
-\begin{Piton}
-def fact(n):
- if n==0:
- return 1
- else:
- $\colorbox{yellow!50}{$return n*fact(n-1)$}$
-\end{Piton}
-
-\bigskip
-\emph{Attention} : L'échappement vers LaTeX permis par les caractères de |escape-inside| n'est pas actif dans les
-chaînes de caractères ni dans les commentaires (pour avoir un commentaire entièrement en échappement vers LaTeX,
-c'est-à-dire ce qui est
-appelé dans ce document «commentaire LateX», il suffit de le faire débuter par |#>|).
-
-
-
-\subsubsection{Comportement dans la classe Beamer}
-
-\colorbox{yellow!50}{\textbf{Nouveau 1.1}}
-
-\smallskip
-Quand \pkg{piton} est utilisé dans la classe \cls{beamer}\footnote{L'extension \pkg{piton} détecte la classe \cls{beamer} mais il est aussi possible, si le
- besoin s'en faisait sentir, d'activer ce comportement avec la clé |beamer| au chargement de \pkg{piton} :
- |\usepackage[beamer]{piton}|}, les commandes suivantes de \cls{beamer}, classées selon
-leur nombre d'arguments obligatoires, sont directement
-reconnues dans les environnements |{Piton}| :
-%
-\begin{itemize}
-\item aucun argument obligatoire : |\pause| ;
-\item un argument obligatoire : |\action|, |\alert|, |\invisible|, |\only|, |\uncover| et |\visible| ;
-\item deux arguments obligatoire : |\alt| ;
-\item trois arguments obligatoires : |\temporal|.
-\end{itemize}
-
-\medskip
-Néanmoins, il y a deux restrictions pour le contenu des arguments obligatoires de ces commandes.
-\begin{itemize}
-\item les accolades dans les arguments obligatoires de ces commandes doivent être équilibrées (cependant, les
-accolades présentes dans des chaînes courtes\footnote{Les chaînes courtes de Python sont les chaînes (string)
- délimitées par les caractères \texttt{'} ou \texttt{"} non triplés. En Python, les chaînes de caractères courtes
- ne peuvent pas s'étendre sur plusieurs lignes de code.} de Python ne sont pas prises en compte) ;
-\item l'argument obligatoire ne doit pas contenir \textbf{aucun retour à la ligne} (s'il y en a, une erreur
-fatale est levée).
-\end{itemize}
-
-\medskip
-Remarquons que, comme l'environnement |{Piton}| prend son argument selon un mode verbatim, il convient, ce qui
-n'est pas surprenant, de l'utiliser dans des environnements |{frame}| de Beamer protégés par la clé |fragile|.\footnote{On
- rappelle que pour un environnement |{frame}| de Beamer qui utilise la clé |fragile|, l'instruction |\end{frame}|
- doit être seule sur une ligne (à l'exception d'éventuels espaces en début de ligne).}
-
-\medskip
-Voici un exemple complet de fichier :
-
-\begin{Verbatim}[formatcom = \small\color{gray}]
-\documentclass{beamer}
-\usepackage{piton}
-\begin{document}
-\begin{frame}[fragile]
-\begin{Piton}
-def string_of_list(l):
- """Convertit une liste de nombres en chaîne"""
-~emphase# \only<2->{s = "{" + str(l[0])}@
-~emphase# \only<3->{for x in l[1:]: s = s + "," + str(x)}@
-~emphase# \only<4->{s = s + "}"}@
- return s
-\end{Piton}
-\end{frame}
-\end{document}
-\end{Verbatim}
-
-Dans l'exemple précédent, les accolades des deux chaînes de caractères Python |"{"| et |"}"| sont correctement interprétées (sans aucun
-caractère d'échappement).
-
-
-\bigskip
-\colorbox{yellow!50}{\textbf{Nouveau 1.2}}
-
-Quand \pkg{piton} est utilisé dans la classe \pkg{beamer}, les environnements suivants de Beamer sont directement
-reconnus dans les environnements |{Piton}| : |{uncoverenv}|, |{onlyenv}|, |{visibleenv}| et |{invisibleenv}|.
-
-\medskip
-Il y a néanmoins une restriction : ces environnements doivent englober des \emph{lignes entières de code Python}.
-
-\medskip
-On peut par exemple écrire :
-
-\begin{Verbatim}[formatcom = \small\color{gray}]
-\documentclass{beamer}
-\usepackage{piton}
-\begin{document}
-\begin{frame}[fragile]
-\begin{Piton}
-def carré(x):
- """Calcule le carré de l'argument"""
- ~emphase#\begin{uncoverenv}<2>@
- return x*x
- ~emphase#\end{uncoverenv}@
-\end{Piton}
-\end{frame}
-\end{document}
-\end{Verbatim}
-
-
-
-
-
-\bigskip
-\subsection{Coupure des pages et des lignes}
-
-\label{breakable}
-
-\subsubsection{Coupure des pages}
-
-Par défaut les listings produits par l'environnement |{Piton}| et par la commande |\PitonInputFile| sont
-insécables.
-
-Néanmoins, la commande |\PitonOptions| propose la clé |splittable| pour autoriser de telles coupures.
-
-\begin{itemize}
-\item Si la clé |splittable| est utilisée sans valeur, les listings sont sécables n'importe où.
-
-\item Si la clé |splittable| est utilisée avec une valeur numérique $n$ (qui doit être un entier naturel non nul),
-alors les listings seront sécables mais aucune coupure ne pourra avoir lieu entre les $n$~premières lignes, ni
-entre les $n$~dernières. De ce fait, |splittable=1| est équivalent à |splittable|.
-\end{itemize}
-
-\medskip
-\emph{Remarque}\par\nobreak
-
-Même avec une couleur de fond (fixée avec |background-color|), les sauts de page sont possibles, à partir du moment
-où la clé |splittable| est utilisée.\footnote{Avec la clé |splittable|, un environnement |{Piton}| est sécable même dans un environnement de
- \pkg{tcolorbox} (à partir du moment où la clé |breakable| de \pkg{tcolorbox} est utilisée). On précise cela parce
- que, en revanche, un environnement de \pkg{tcolorbox} inclus dans un autre environnement de \pkg{tcolorbox} n'est
- pas sécable, même quand les deux utilisent la clé |breakable|.}
-
-\subsubsection{Coupure des lignes}
-
-Par défaut, les éléments produits par \pkg{piton} ne peuvent pas être coupés par une fin de ligne. Il existe
-néanmoins des clés pour autoriser de telles coupures (les points de coupure possibles sont les espaces, y compris
-les espaces dans les chaînes Python).
-\begin{itemize}
-\item Avec la clé |break-lines-in-piton|, les coupures de ligne sont autorisées dans la commande |\piton{...}|
-(mais pas dans la commande \verb+|...|+, c'est-à-dire avec la syntaxe verbatim).
-
-\item Avec la clé |break-lines-in-Piton|, les coupures de ligne sont autorisées dans l'environnement |{Piton}|
-(d'où la lettre |P| capitale dans le nom) et dans les listings produits par |\PitonInputFile|.
-
-\item La clé |break-lines| est la conjonction des deux clés précédentes.
-\end{itemize}
-
-\medskip
-\colorbox{yellow!50}{\textbf{Nouveau 1.2}}\enskip Depuis la version 1.2, la clé |break-lines| autorise les coupures
-de lignes dans |\piton{...}| et pas seulement dans |{Piton}|.
-
-\medskip
-L'extension \pkg{piton} fournit aussi plusieurs clés pour contrôler l'apparence des coupures de ligne autorisées par |break-lines-in-Piton|.
-
-\begin{itemize}
-\item Avec la clé |indent-broken-lines|, l'indentation de la ligne coupée est respectée à chaque retour à la ligne.
-
-\item La clé |end-of-broken-line| correspond au symbole placé à la fin d'une ligne coupée. Sa valeur initiale est :
-|\hspace*{0.5em}\textbackslash|.
-
-\item La clé |continuation-symbol| correspond au symbole placé à chaque retour de ligne dans la marge gauche. Sa
-valeur initiale est : |+\;|.
-
-\item La clé |continuation-symbol-on-indentation| correspond au symbole placé à chaque retour de ligne au niveau de
-l'indentation (uniquement dans le cas où la clé |indent-broken-lines| est active). Sa valeur initiale est :
-|$\hookrightarrow\;$|.
-\end{itemize}
-
-\bigskip
-Le code suivant a été composé dans une |{minipage}| de largeur 12~cm avec le réglage suivant :
-
-\begin{Verbatim}
-\PitonOptions{break-lines,indent-broken-lines,background-color=gray!15}
-\end{Verbatim}
-
-\begin{center}
-\PitonOptions{break-lines,indent-broken-lines,background-color=gray!15}
-\begin{minipage}{12cm}
-\begin{Piton}
-def dict_of_liste(liste):
- """Convertit une liste de subrs et de descriptions de glyphes en dictionnaire"""
- dict = {}
- for liste_lettre in liste:
- if (liste_lettre[0][0:3] == 'dup'): # si c'est un subr
- nom = liste_lettre[0][4:-3]
- print("On traite le subr de numéro " + nom)
- else:
- nom = liste_lettre[0][1:-3] # si c'est un glyphe
- print("On traite le glyphe du caractère " + nom)
- dict[nom] = [traite_ligne_Postscript(k) for k in liste_lettre[1:-1]]
- return dict
-\end{Piton}
-\end{minipage}
-\end{center}
-
-
-
-\bigskip
-\subsection{Notes de pied de page dans les environnements de piton}
-
-\label{footnote}
-
-Si vous voulez mettre des notes de pied de page dans un environnement de \pkg{piton} (ou bien dans un listing
-produit par |\PitonInputFile|, bien que cela paraisse moins pertinent dans ce cas-là) vous pouvez utiliser une
-paire |\footnotemark|--|\footnotetext|.
-
-\smallskip
-Néanmoins, il est également possible d'extraire les notes de pieds de page avec l'extension \pkg{footnote} ou bien
-l'extension \pkg{footnotehyper}.
-
-\smallskip
-Si \pkg{piton} est chargée avec l'option |footnote| (avec |\usepackage[footnote]{piton}|) l'extension
-\pkg{footnote} est chargée (si elle ne l'est pas déjà) et elle est utilisée pour extraire les notes de pied de
-page.
-
-\smallskip
-Si \pkg{piton} est chargée avec l'option |footnotehyper|, l'extension \pkg{footnotehyper} est chargée (si
-elle ne l'est pas déjà) et elle est utilisée pour extraire les notes de pied de page.
-
-\smallskip
-Attention : Les extensions \pkg{footnote} et \pkg{footnotehyper} sont incompatibles.
-L'extension \pkg{footnotehyper} est le successeur de l'extension \pkg{footnote}
-et devrait être utilisée préférentiellement. L'extension \pkg{footnote} a quelques défauts ;
-en particulier, elle doit être chargée après l'extension \pkg{xcolor} et elle n'est pas parfaitement
-compatible avec \pkg{hyperref}.
-
-\medskip
-Dans ce document, l'extension \pkg{piton} a été chargée avec l'option |footnotehyper| et c'est pourquoi des notes
-peuvent être mises dans les environnements |{Piton}| : voir un exemple sur la première page de ce document.
-
-\subsection{Tabulations}
-
-\smallskip
-Même s'il est recommandé d'indenter les listings Python avec des espaces (cf. PEP~8), \pkg{piton} accepte les
-caractères de tabulations (U+0009) en début de ligne. Chaque caractère U+0009 est remplacé par $n$ espaces. La
-valeur initiale de~$n$ est~4 mais on peut la changer avec la clé |tab-size| de |\PitonOptions|.
-
-\smallskip
-Il existe aussi une clé |tabs-auto-gobble| qui détermine le nombre minimal de caractères U+0009 débutant chaque
-ligne (non vide) de l'environnement |{Piton}| et applique |gobble| avec cette valeur (avant le remplacement des
-caractères U+0009 par des espaces, bien entendu). Cette clé est donc similaire à la clé |auto-gobble| mais agit sur
-des caractères U+0009 au lieu de caractères U+0020 (espaces).
-
-\section{Exemples}
-
-
-\subsection{Numérotation des lignes}
-
-\label{example-numbering}
-
-On rappelle que l'on peut demander la numérotation des lignes des listings avec la clé |line-numbers| ou la clé |all-line-numbers|.
-
-Par défaut, les numéros de ligne sont composés par \pkg{piton} en débordement à gauche (en utilisant en interne la commande |\llap| de LaTeX).
-
-Si on ne veut pas de débordement, on peut utiliser l'option |left-margin=auto| qui va insérer une marge adaptée aux
-numéros qui seront insérés (elle est plus large quand les numéros dépassent 10).
-
-
-\begingroup
-\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
-\begin{Verbatim}
-~emphase&\PitonOptions{background-color=gray!10, left-margin = auto, line-numbers}@
-\begin{Piton}
-def arctan(x,n=10):
- if x < 0:
- return -arctan(-x) #> (appel récursif)
- elif x > 1:
- return pi/2 - arctan(1/x) #> (autre appel récursif)
- else:
- return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
-\end{Piton}
-\end{Verbatim}
-\endgroup
-
-
-
-\begingroup
-\PitonOptions{background-color=gray!10,left-margin = auto, line-numbers}
-\begin{Piton}
-def arctan(x,n=10):
- if x < 0:
- return -arctan(-x) #> (appel récursif)
- elif x > 1:
- return pi/2 - arctan(1/x) #> (autre appel récursif)
- else:
- return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
-\end{Piton}
-\endgroup
-
-
-\bigskip
-
-\subsection{Formatage des commentaires LaTeX}
-
-\label{example-comments}
-
-On peut modifier le style |Comment.LaTeX| (avec |\SetPitonStyle|) pour faire afficher les commentaires
-LaTeX (qui débutent par |#>|) en butée à droite.
-
-\begingroup
-\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
-\begin{Verbatim}
-\PitonOptions{background-color=gray!10}
-~emphase&\SetPitonStyle{Comment.LaTeX = \hfill \normalfont\color{gray}}@
-\begin{Piton}
-def arctan(x,n=10):
- if x < 0:
- return -arctan(-x) #> appel récursif
- elif x > 1:
- return pi/2 - arctan(1/x) #> autre appel récursif
- else:
- return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
-\end{Piton}
-\end{Verbatim}
-\endgroup
-
-\begingroup
-\PitonOptions{background-color=gray!10}
-\SetPitonStyle{Comment.LaTeX = \hfill \normalfont\color{gray}}
-\begin{Piton}
-def arctan(x,n=10):
- if x < 0:
- return -arctan(-x) #> appel récursif
- elif x > 1:
- return pi/2 - arctan(1/x) #> autre appel récursif
- else:
- return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
-\end{Piton}
-\endgroup
-
-
-\vspace{1cm}
-On peut aussi faire afficher les commentaires dans une deuxième colonne à droite si on limite la largeur du code
-proprement dit avec un environnement |{minipage}| de LaTeX.
-
-
-\begingroup
-\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
-\begin{Verbatim}
-\PitonOptions{background-color=gray!10}
-~emphase&\NewDocumentCommand{\MyLaTeXCommand}{m}{\hfill \normalfont\itshape\rlap{\quad #1}}@
-~emphase&\SetPitonStyle{Comment.LaTeX = \MyLaTeXCommand}@
-~emphase&\begin{minipage}{12cm}@
-\begin{Piton}
-def arctan(x,n=10):
- if x < 0:
- return -arctan(-x) #> appel récursif
- elif x > 1:
- return pi/2 - arctan(1/x) #> autre appel récursif
- else:
- s = 0
- for k in range(n):
- s += (-1)**k/(2*k+1)*x**(2*k+1)
- return s
-\end{Piton}
-~emphase&\end{minipage}@
-\end{Verbatim}
-\endgroup
-
-
-
-\begingroup
-\PitonOptions{background-color=gray!10}
-\NewDocumentCommand{\MyLaTeXCommand}{m}{\hfill \normalfont\itshape\rlap{\quad #1}}
-\SetPitonStyle{Comment.LaTeX = \MyLaTeXCommand}
-\begin{minipage}{12cm}
-\begin{Piton}
-def arctan(x,n=10):
- if x < 0:
- return -arctan(-x) #> appel récursif
- elif x > 1:
- return pi/2 - arctan(1/x) #> autre appel récursif
- else:
- s = 0
- for k in range(n):
- s += (-1)**k/(2*k+1)*x**(2*k+1)
- return s
-\end{Piton}
-\end{minipage}
-\endgroup
-
-\bigskip
-
-\subsection{Notes dans les listings}
-
-Pour pouvoir extraire les notes (introduites par |\footnote|), l'extension |piton| doit être chargée, soit avec la
-clé |footnote|, soit avec la clé |footnotehyper|, comme expliqué à la section \ref{footnote} p.~\pageref{footnote}.
-Dans le présent document, l'extension \pkg{piton} a été chargée par la clé |footnotehyper|.
-
-Bien entendu, une commande |\footnote| ne peut apparaître que dans un commentaire LaTeX (qui débute par |#>|). Un
-tel commentaire peut se limiter à cette unique commande |\footnote|, comme dans l'exemple suivant.
-
-\begingroup
-\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
-\begin{Verbatim}
-\PitonOptions{background-color=gray!10}
-\begin{Piton}
-def arctan(x,n=10):
- if x < 0:
- return -arctan(-x)~emphase&#>\footnote{Un premier appel récursif.}]@
- elif x > 1:
- return pi/2 - arctan(1/x)~emphase&#>\footnote{Un deuxième appel récursif.}@
- else:
- return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
-\end{Piton}
-\end{Verbatim}
-\endgroup
-
-\begingroup
-\PitonOptions{background-color=gray!10}
-\begin{Piton}
-def arctan(x,n=10):
- if x < 0:
- return -arctan(-x)#>\footnote{Un premier appel récursif.}
- elif x > 1:
- return pi/2 - arctan(1/x)#>\footnote{Un deuxième appel récursif.}
- else:
- return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
-\end{Piton}
-\endgroup
-
-
-\vspace{1cm}
-
-Si on utilise l'environnement |{Piton}| dans un environnement |{minipage}| de LaTeX, les notes sont, bien entendu,
-composées au bas de l'environnement |{minipage}|. Rappelons qu'une telle |{minipage}| ne peut être coupée par un
-saut de page.
-
-
-\begingroup
-\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
-\begin{Verbatim}
-\PitonOptions{background-color=gray!10}
-\emphase\begin{minipage}{\linewidth}
-\begin{Piton}
-def arctan(x,n=10):
- if x < 0:
- return -arctan(-x)~emphase&#>\footnote{Un premier appel récursif.}@
- elif x > 1:
- return pi/2 - arctan(1/x)~emphase&#>\footnote{Un deuxième appel récursif.}@
- else:
- return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
-\end{Piton}
-\end{minipage}
-\end{Verbatim}
-\endgroup
-
-\begingroup
-\PitonOptions{background-color=gray!10}
-\begin{minipage}{\linewidth}
-\begin{Piton}
-def arctan(x,n=10):
- if x < 0:
- return -arctan(-x)#>\footnote{Un premier appel récursif.}
- elif x > 1:
- return pi/2 - arctan(1/x)#>\footnote{Un deuxième appel récursif.}
- else:
- return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
-\end{Piton}
-\end{minipage}
-\endgroup
-
-
-\vspace{1cm}
-Si on encapsule l'environnement |{Piton}| dans un environnement |{minipage}| pour, typiquement, limiter la largeur
-d'un fond coloré, il faut encadrer l'ensemble dans un environnement |{savenotes}| (de \pkg{footnote} ou
-\pkg{footnotehyper}) si on veut avoir les notes reportées en pied de page.
-
-\begingroup
-\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
-\begin{Verbatim}
-\PitonOptions{background-color=gray!10}
-~emphase&\begin{savenotes}@
-\begin{minipage}{13cm}
-\begin{Piton}
-def arctan(x,n=10):
- if x < 0:
- return -arctan(-x)~emphase&#>\footnote{Un premier appel récursif.}@
- elif x > 1:
- return pi/2 - arctan(1/x)~emphase&#>\footnote{Un deuxième appel récursif.}@
- else:
- return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
-\end{Piton}
-\end{minipage}
-~emphase&\end{savenotes}@
-\end{Verbatim}
-\endgroup
-
-
-
-\begin{savenotes}
-\PitonOptions{background-color=gray!10}
-\begin{minipage}{13cm}
-\begin{Piton}
-def arctan(x,n=10):
- if x < 0:
- return -arctan(-x)#>\footnote{Un premier appel récursif.}
- elif x > 1:
- return pi/2 - arctan(1/x)#>\footnote{Un deuxième appel récursif.}
- else:
- return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
-\end{Piton}
-\end{minipage}
-\end{savenotes}
-
-\bigskip
-
-\subsection{Un exemple de réglage des styles}
-
-Les styles graphiques ont été présentés à la partie \ref{styles}, p.~\pageref{styles}.
-
-\smallskip
-On présente ici un réglage de ces styles adapté pour les documents en noir et blanc. On l'utilise avec la fonte
-\emph{DejaVu Sans Mono}\footnote{Voir: \url{https://dejavu-fonts.github.io}} spécifiée avec la commande
- |\setmonofont| de \pkg{fontspec}.
-
-
-\begin{Verbatim}
-\setmonofont[Scale=0.85]{DejaVu Sans Mono}
-
-\SetPitonStyle
- {
- Number = ,
- String = \itshape ,
- String.Doc = \color{gray} \itshape ,
- Operator = ,
- Operator.Word = \bfseries ,
- Name.Builtin = ,
- Name.Function = \bfseries \colorbox{gray!20} ,
- Comment = \color{gray} ,
- Comment.LaTeX = \normalfont \color{gray},
- Keyword = \bfseries ,
- Name.Namespace = ,
- Name.Class = ,
- Name.Type = ,
- InitialValues = \color{gray}
- }
-\end{Verbatim}
-
-
-\begingroup
-
-
-\setmonofont[Scale=0.85]{DejaVu Sans Mono}
-
-\SetPitonStyle
- {
- Number = ,
- String = \itshape ,
- String.Doc = \color{gray} \itshape ,
- Operator = ,
- Operator.Word = \bfseries ,
- Name.Builtin = ,
- Name.Function = \bfseries \colorbox{gray!20} ,
- Comment = \color{gray} ,
- Comment.LaTeX = \normalfont \color{gray},
- Keyword = \bfseries ,
- Name.Namespace = ,
- Name.Class = ,
- Name.Type = ,
- InitialValues = \color{gray}
- }
-
-
-\bigskip
-
-\begin{Piton}
-from math import pi
-
-def arctan(x,n=10):
- """Compute the mathematical value of arctan(x)
-
- n is the number of terms in the sum
- """
- if x < 0:
- return -arctan(-x) # appel récursif
- elif x > 1:
- return pi/2 - arctan(1/x)
- #> (on a utilisé le fait que $\arctan(x)+\arctan(1/x)=\pi/2$ pour $x>0$)
- else:
- s = 0
- for k in range(n):
- s += (-1)**k/(2*k+1)*x**(2*k+1)
- return s
-\end{Piton}
-
-
-\endgroup
-
-\section{Utilisation avec pyluatex}
-
-L'extension \pkg{pyluatex} est une extension qui permet l'exécution de code Python à partir de |lualatex| (pourvu
-que Python soit installé sur la machine et que la compilation soit effectuée avec |lualatex| et |--shell-escape|).
-
-Voici, à titre d'exemple, un environnement |{PitonExecute}| qui formate un listing Python (avec \pkg{piton}) et qui
-affiche également dessous le résultat de l'exécution de ce code avec Python.
-
-
-\begin{Verbatim}
-\ExplSyntaxOn
-\NewDocumentEnvironment { ~emphase#PitonExecute@ } { ! O { } }
- {
- \PyLTVerbatimEnv
- \begin{pythonq}
- }
- {
- \end{pythonq}
- \directlua
- {
- tex.print("\\PitonOptions{~#1}")
- tex.print("\\begin{Piton}")
- tex.print(pyluatex.get_last_code())
- tex.print("\\end{Piton}")
- tex.print("")
- }
- \begin{center}
- \directlua{tex.print(pyluatex.get_last_output())}
- \end{center}
- }
-\ExplSyntaxOff
-\end{Verbatim}
-
-\ExplSyntaxOn
-\NewDocumentEnvironment { PitonExecute } { ! O { } }
- {
- \PyLTVerbatimEnv
- \begin{pythonq}
- }
- {
- \end{pythonq}
- \directlua
- {
- tex.print("\\PitonOptions{~#1}")
- tex.print("\\begin{Piton}")
- tex.print(pyluatex.get_last_code())
- tex.print("\\end{Piton}")
- tex.print("")
- }
- \begin{center}
- \directlua{tex.print(pyluatex.get_last_output())}
- \end{center}
- }
-\ExplSyntaxOff
-
-Cet environnement |{PitonExcecute}| prend en argument optionnel (entre crochets) les options proposées par la
-commande |\PitonOptions|.
-
-\bigskip
-Voici un exemple d'utilisation de cet environnement |{PitonExecute}| :
-
-\begin{Verbatim}
-\begin{~emphase#PitonExecute@}[background-color=gray!15]
-def square(x):
- return x*x
-print(f'The square of 12 is {square(12)}.')
-\end{~emphase#PitonExecute@}
-\end{Verbatim}
-
-
-\medskip
-\begin{PitonExecute}[background-color=gray!15]
-def square(x):
- return x*x
-print(f'The square of 12 is {square(12)}.')
-\end{PitonExecute}
-
-
-
-\section*{Autre documentation}
-
-Le document |piton.pdf| (fourni avec l'extension \pkg{piton}) contient une traduction anglaise de la
-documentation ici présente, ainsi que le code source commenté et un historique des versions.
-
-
+% -*- coding: utf-8 ; -*- +\documentclass[dvipsnames]{article} + +\usepackage{fontspec} + +\usepackage[french]{babel} +\frenchsetup{og = « , fg = »} + +\usepackage[footnotehyper,escape-inside=$$,math-comments]{piton} + +\usepackage[executable=python.exe]{pyluatex} + +\usepackage{xcolor} + +\usepackage{geometry} +\geometry{left=2.8cm,right=2.8cm,top=2.5cm,bottom=2.5cm,papersize={21cm,29.7cm}} + +\usepackage{enumitem} +\usepackage{verbatim} +\usepackage{amsmath} +\usepackage{tabularx} +\usepackage{booktabs} +\usepackage{tcolorbox} + +\usepackage{caption} + +% We use \MakeShortVerb of shortvrb and not \DefineShortVerb of fancyvrb +% because we don't want the contents of short verbatim colored in gray +\usepackage{shortvrb} +\MakeShortVerb{\|} + +\usepackage{varwidth} + +\skip\footins = 2\bigskipamount + +\usepackage{fancyvrb} +\fvset{commandchars=\~\#\@,formatcom=\color{gray}} +\def\emphase{\bgroup\color{RoyalPurple}\let\next=} + + +\usepackage{titlesec} +\titlespacing*{\section}{0pt}{6.5ex plus 1ex minus .2ex}{4.3ex plus .2ex} +\titlespacing*{\subsection}{0pt}{4.5ex plus 1ex minus .2ex}{2ex plus .2ex} + +\def\interitem{\vspace{7mm plus 2 mm minus 3mm}} + + +\usepackage[hyperfootnotes = false]{hyperref} + +\hypersetup + { + pdfinfo = + { + Title = L’extension piton , + Subject = Une extension LaTeX , + Author = F. Pantigny + } + } + + + + +\NewDocumentCommand {\pkg} {m} {\textsf{#1}} +\NewDocumentCommand {\cls} {m} {\textsf{#1}} + +\setlength{\parindent}{0pt} + + +\begin{document} + +\PitonOptions{splittable = 4} + +\VerbatimFootnotes + + +\title{L'extension LaTeX \pkg{piton}\thanks{Ce document correspond à la +version~\myfileversion\space de \pkg{piton}, à la date du~\myfiledate.}} +\author{F. Pantigny \\ \texttt{fpantigny@wanadoo.fr}} + +\maketitle + +\begin{abstract} +L'extension \pkg{piton} propose des outils pour composer du code Python avec une coloration syntaxique +en utilisant la bibliothèque Lua LPEG. L'extension \pkg{piton} nécessite l'emploi de LuaLaTeX. +\end{abstract} + + + +\section{Présentation} + +L'extension \pkg{piton} utilise la librairie Lua nommée LPEG\footnote{LPEG est une librairie de capture de motifs + (\emph{pattern-matching} en anglais) pour Lua, écrite en C, fondée sur les PEG (\emph{parsing expression + grammars}): \url{http://www.inf.puc-rio.br/~roberto/lpeg/}} pour «parser» le code Python et le composer avec un +coloriage syntaxique. Comme elle utilise du code Lua, elle fonctionne uniquement avec |lualatex| (et ne va pas +fonctionner avec les autres moteurs de compilation LaTeX, que ce soit |latex|, |pdflatex| ou |xelatex|). Elle +n'utilise aucun programme extérieur et la compilation ne requiert donc pas |--shell-escape|. La compilation est +très rapide puisque tout le travail du parseur est fait par la librairie LPEG, écrite en C. + +\bigskip +Voici un exemple de code Python composé avec l'environnement |{Piton}| proposé par \pkg{piton}. + + +\bigskip +\begin{Piton} +from math import pi + +def arctan(x,n=10): + """Calcule la valeur mathématique de arctan(x) + + n est le nombre de termes de la somme + """ + if x < 0: + return -arctan(-x) # appel récursif + elif x > 1: + return pi/2 - arctan(1/x) + #> (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\#>.} + else: + s = 0 + for k in range(n): + s += (-1)**k/(2*k+1)*x**(2*k+1) + return s +\end{Piton} + + +\bigskip + +L'extension LaTeX \pkg{piton} est entièrement contenue dans le fichier |piton.sty|. Ce +fichier peut être placé dans le répertoire courant ou dans une arborescence |texmf|. Le mieux reste néanmoins +d'installer \pkg{piton} avec une distribution TeX comme MiKTeX, TeX~Live ou MacTeX. + + +\section{Utilisation de l'extension} + +\subsection{Chargement de l'extension} + +L'extension \pkg{piton} se charge simplement avec la commande |\usepackage| : |\usepackage{piton}|. + +On a cependant deux remarques à formuler : +\begin{itemize} +\item l'extension \pkg{piton} utilise l'extension \pkg{xcolor} (mais \pkg{piton} ne charge pas \pkg{xcolor} : si +\pkg{xcolor} n'est pas chargée avant le |\begin{document}|, une erreur fatale sera levée) ; + +\item l'extension \pkg{piton} n'est utilisable qu'avec LuaLaTeX : si un autre moteur de compilation (comme |latex|, +|pdflatex| ou |xelatex|) est utilisé, une erreur fatale sera levée. +\end{itemize} + +\subsection{Les commandes et environnements à la disposition de l'utilisateur} + +L'extension \pkg{piton} fournit plusieurs outils pour composer du code Python: les commandes |\piton|, +l'environnement |{Piton}| et la commande |\PitonInputFile|. + +\begin{itemize} \setlength{\fboxsep}{1pt} +\item La commande \colorbox{gray!20}{\ttfamily \textbackslash piton} doit être utilisée pour composer de petits éléments de code à l'intérieur d'un +paragraphe. Par exemple : + +{\color{gray}\verb|\piton{def carré(x): return x*x}|}\qquad +\piton{def carré(x): return x*x} + +La syntaxe et les particularités de la commande sont détaillées ci-après. + + +\item L'environnement \colorbox{gray!20}{\ttfamily \{Piton\}} doit être utilisé pour composer des codes de +plusieurs lignes. Comme cet environnement prend son argument selon un mode verbatim, il ne peut pas être utilisé +dans l'argument d'une commande LaTeX. Pour les besoins de personnalisation, il est possible de définir de nouveaux +environnements similaires à |{Piton}| en utilisant la commande |\NewPitonEnvironment| : cf. partie +\ref{NewPitonEnvironment} p.~\pageref{NewPitonEnvironment}. + +\item La commande \colorbox{gray!20}{\ttfamily \textbackslash PitonInputFile} doit être utilisée pour insérer et +composer un fichier extérieur. + +Cette commande prend en argument optionnel entre crochets deux clés |first-line| et |last-line| qui permettent de +n'insérer que la partie du fichier comprise entre les lignes correspondantes. +\end{itemize} + + +\subsection{La syntaxe de la commande \textbackslash piton} + + +La commande |\piton| possède en fait une syntaxe double. Elle est peut être utilisée comme une commande standard de +LaTeX prenant son argument entre accolades (|\piton{...}|), ou bien selon la syntaxe de la commande |\verb| où l'argument est +délimité entre deux caractères identiques (par ex. : \verb!\piton|...|!). On détaille maintenant ces deux syntaxes. + +\bigskip +\begin{itemize} +\item {\color{blue} \textsf{Syntaxe} \verb|\piton{...}|}\par\nobreak + +Quant son argument est donné entre accolades, la commande |\piton| ne prend pas son argument en mode verbatim. Les +points suivants doivent être remarqués : + +\begin{itemize} +\item plusieurs espaces successifs sont remplacés par un unique espace ; +\item il n'est pas possible d'utiliser le caractère |%| à l'intérieur ; +\item les accolades doivent apparaître par paires correctement imbriquées; +\item les commandes LaTeX (celles commençant par une contre-oblique |\| mais également les caractères actifs) sont +complètement développées (mais non exécutées). +\end{itemize} + +Un mécanisme d'échappement est fourni : les commandes |\\|, |\%|, |\{| et |\}| insèrent les caractères +correspondants |\|, |%|, +|{| et |}|. Ces deux dernières commandes ne sont nécessaires que si on a besoin d'insérer des accolades +non équilibrées. + +\smallskip +\colorbox{yellow!50}{\textbf{Nouveau 1.3}}\enskip La commande |\|␣ insère un espace. Elle peut être utilisée si on +veut insérer plusieurs espaces successifs. + +\smallskip +Les autres caractères (y compris |#|, |^|, |_|, |&|, |$| % $ +et |@|) doivent être insérés sans contre-oblique. + +Exemples : + +\begin{tabular}{>{\color{gray}}l@{\hspace*{1cm}}l} +\verb|\piton{ma_chaîne = '\\n'}| & +\piton{ma_chaîne = '\\n' } \\ +\verb|\piton{def pair(n): return n\%2==0}| & +\piton{def pair(n): return n\%2==0 } \\ +\verb|\piton{c="#" # une affectation }| & +\piton{c="#" # une affectation } \\ +\verb|\piton{c="#" \ \ \ # une affectation }| & +\piton{c="#" \ \ \ # une affectation } \\ +\verb|\piton{my_dict = {'a': 3, 'b': 4}}| & +\piton{my_dict = {'a': 3, 'b': 4}} +\end{tabular} + +\smallskip +La commande |\piton| avec son argument entre accolades peut être utilisée dans les arguments des autres commandes LaTeX.\footnote{La commande + |\piton| peut par exemple être + utilisée dans une note de bas de page. Exemple : \piton{s = 'Une chaîne'}.} + +\bigskip +\item {\color{blue} \textsf{Syntaxe} \verb!\piton|...|!}\par\nobreak + +Quand la commande |\piton| prend son argument entre deux caractères identiques, cet argument est pris \emph{en mode + verbatim}. De ce fait, avec cette syntaxe, la commande |\piton| ne peut \emph{pas} être utilisée dans l'argument d'une +autre fonction. + +\medskip +Exemples : + +\begin{tabular}{>{\color{gray}}l@{\hspace*{1cm}}l} +\verb!\piton|ma_chaîne = '\n'|! & +\piton|ma_chaîne = '\n'| \\ +\verb|\piton!def pair(n): return n%2==0!| & +\piton!def pair(n): return n%2==0! \\ +\verb|\piton+c="#" # une affectation +| & +\piton+c="#" # une affectation + \\ +\verb|\piton?my_dict = {'a': 3, 'b': 4}?| & +\piton!my_dict = {'a': 3, 'b': 4}! +\end{tabular} + +\end{itemize} + + + +\section{Personnalisation} + +\subsection{La commande \textbackslash PitonOptions} + +\NewDocumentCommand{\Definition}{m} + {{\setlength{\fboxsep}{1pt}\colorbox{gray!20}{\ttfamily \vphantom{gl}#1}}} + + +La commande |\PitonOptions| prend en argument une liste de couples \textsl{clé=valeur}. La portée des réglages +effectués par cette commande est le groupe TeX courant.\footnote{On rappelle que tout environnement LaTeX est, en particulier, un groupe.} + +\begin{itemize} +\item La clé \Definition{gobble} prend comme valeur un entier positif $n$ : les $n$ premiers caractères de chaque +ligne sont alors retirés (avant formatage du code) dans les environnements |{Piton}|. Ces $n$ caractères ne sont +pas nécessairement des espaces. + +\item Quand la clé \Definition{auto-gobble} est activée, l'extension \pkg{piton} détermine la valeur minimale $n$ +du nombre d'espaces successifs débutant chaque ligne (non vide) de l'environnement |{Piton}| et applique |gobble| +avec cette valeur de~$n$. + +\item Quand la clé \Definition{env-gobble} est activée, \pkg{piton} analyse la dernière ligne de l'environnement, +c'est-à-dire celle qui contient le |\end{Piton}| et détermine si cette ligne ne comporte que des espaces suivis par +|\end{Piton}|. Si c'est le cas, \pkg{piton} calcule le nombre $n$ de ces espaces et applique |gobble| avec cette +valeur de~$n$. Le nom de cette clé vient de \emph{environment gobble}: le nombre d'espaces à retirer ne dépend que +de la position des délimiteurs |\begin{Piton}| et |\end{Piton}| de l'environnement. + +\item Avec la clé \Definition{line-numbers}, les lignes \emph{non vides} (et toutes les lignes des +\emph{docstrings}, y compris celles qui sont vides) sont numérotées dans les environnements \verb|{Piton}| et dans +les listings produits par la commande |\PitonInputFile|. + +\item Avec la clé \Definition{all-line-numbers}, \emph{toutes} les lignes sont numérotées, y compris les lignes vides. + +\item La clé \Definition{left-margin} fixe une marge sur la gauche. Cette clé peut être utile, en particulier, en +conjonction avec l'une des clés |line-numbers| et |all-line-numbers| si on ne souhaite pas que les numéros de ligne +soient dans une position en débordement sur la gauche. + +Il est possible de donner à la clé |left-margin| la valeur spéciale~|auto|. Avec cette valeur, une marge est +insérée automatiquement pour les numéros de ligne quand l'une des clés |line-numbers| ou |all-line-numbers| est +utilisée. Voir un exemple à la partie \ref{example-numbering} p.~\pageref{example-numbering}. + +\item Avec la clé \Definition{resume}, le compteur de lignes n'est pas remis à zéro comme il l'est normalement au +début d'un environnement |{Piton}| ou bien au début d'un listing produit par |\PitonInputFile|. Cela permet de +poursuivre la numérotation d'un environnement à l'autre. + +\item La clé \Definition{background-color} fixe la couleur de fond des environnements |{Piton}| et des listings +produits par |\PitonInputFile| (ce fond a une largeur égale à la valeur courante de |\linewidth|). + +\colorbox{yellow!50}{\textbf{Nouveau 1.3}}\enskip La clé |background-color| accepte une couleur définie «à la +volée», c'est-à-dire que l'on peut écrire par exemple |background-color = [cmyk]{0.1,0.05,0,0}| + +\item \colorbox{yellow!50}{\textbf{Nouveau 1.3}}\enskip Avec la clé \Definition{prompt-background-color}, +\pkg{piton} ajoute un fond coloré aux lignes débutant par le prompt «|>>>|» (et sa continuation «|...|») +caractéristique des consoles Python avec boucle \textsc{repl} (\emph{read-only-eval loop}). Pour un exemple +d'utilisation de cette clé, voir la partie \ref{pythonrepl} p.~\pageref{pythonrepl} + +\item \colorbox{yellow!50}{\textbf{Modification 1.2}}\enskip En activant la clé \Definition{show-spaces-in-strings}, les +espaces dans les chaînes courtes (c'est-à-dire celles délimitées par |'| ou |"|) sont matérialisés par le caractère +␣ (U+2423 : \textsc{open box}). Bien sûr, le caractère U+2423 doit être présent dans la fonte mono-chasse +utilisée.\footnote{L'extension \pkg{piton} utilise simplement la fonte mono-chasse courante. Pour la changer, le + mieux est d'utiliser |\setmonofont| de \pkg{fontspec}.}\par\nobreak +% +\begingroup +\PitonOptions{show-spaces-in-strings} +Exemple : \piton{my_string = 'Très bonne réponse'} +\endgroup + +\smallskip +Avec la clé \Definition{show-spaces}, tous les espaces sont matérialisés (et aucune coupure de ligne ne peut plus +intervenir sur ces espaces matérialisés, même si la clé |break-lines| est active). +\end{itemize} + +\bigskip + +\begingroup +\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}} +\begin{Verbatim} +~emphase&\PitonOptions{line-numbers,auto-gobble,background-color = gray!15}@ +\begin{Piton} + from math import pi + + def arctan(x,n=10): + """Calcule la valeur mathématique de arctan(x) + + n est le nombre de termes de la somme + """ + if x < 0: + return -arctan(-x) # appel récursif + elif x > 1: + return pi/2 - arctan(1/x) + #> (on a utilisé le fait que $\arctan(x)+\arctan(1/x)=\pi/2$ pour $x>0$) + else: + s = 0 + for k in range(n): + s += (-1)**k/(2*k+1)*x**(2*k+1) + return s +\end{Piton} +\end{Verbatim} +\endgroup + + +\begingroup +\PitonOptions{line-numbers,auto-gobble,background-color = gray!15} +\begin{Piton} + from math import pi + + def arctan(x,n=10): + """Compute the value of arctan(x) + + n is the number of terms in the sum + """ + if x < 0: + return -arctan(-x) # appel récursif + elif x > 1: + return pi/2 - arctan(1/x) + #> (on a utilisé le fait que $\arctan(x)+\arctan(1/x)=\pi/2$ pour $x>0$) + else: + s = 0 + for k in range(n): + s += (-1)**k/(2*k+1)*x**(2*k+1) + return s +\end{Piton} +\endgroup + + + +\bigskip +La commande |\PitonOptions| propose d'autres clés qui seront décrites plus loin (voir en particulier la coupure des +pages et des lignes p.~\pageref{breakable}). + + +\subsection{Les styles} + +\label{styles} + +L'extension \pkg{piton} fournit la commande |\SetPitonStyle| pour personnaliser les différents styles utilisés pour +formater les éléments syntaxiques des listings Python. Ces personnalisations ont une portée qui correspond au +groupe TeX courant.\footnote{On rappelle que tout environnement LaTeX est, en particulier, un groupe.} + +\bigskip +La commande |\SetPitonStyle| prend en argument une liste de couples \textsl{clé=valeur}. Les clés sont les noms des +styles et les valeurs sont les instructions LaTeX de formatage correspondantes. + +\bigskip +Ces instructions LaTeX doivent être des instructions de formatage du type de |\bfseries|, |\slshape|, +|\color{...}|, etc. (les commandes de ce type sont parfois qualifiées de \emph{semi-globales}). Il est aussi +possible de mettre, \emph{à la fin de la liste d'instructions}, une commande LaTeX prenant exactement un argument. + +\bigskip +Voici un exemple qui change le style utilisé pour le nom d'une fonction Python, au moment de sa définition +(c'est-à-dire après le mot-clé |def|). + +\begin{Verbatim} +\SetPitonStyle + { Name.Function = \bfseries \setlength{\fboxsep}{1pt}\colorbox{yellow!50} } +\end{Verbatim} + +Dans cet exemple, |\colorbox{yellow!50}| doit être considéré comme le nom d'une fonction LaTeX qui prend exactement +un argument, puisque, habituellement, elle est utilisée avec la syntaxe +|\colorbox{yellow!50}{|\texttt{\slshape text}|}|. + +\medskip +\begingroup +\SetPitonStyle + { Name.Function = \bfseries \setlength{\fboxsep}{1pt}\colorbox{yellow!50} } +Avec ce réglage, on obtient : \piton{def cube(x) : return x * x * x } +\endgroup + + +\bigskip +Les différents styles sont décrits dans la table \ref{Semantic}. Les réglages initiaux effectués par \pkg{piton} +dans |piton.sty| sont inspirés par le style \pkg{manni} de Pygments.\footnote{Voir + \url{https://pygments.org/styles/}. À remarquer que, par défaut, Pygments propose pour le style \pkg{manni} un + fond coloré dont la couleur est la couleur HTML |#F0F3F3|. Il est possible d'avoir la même couleur dans |{Piton}| + avec l'instruction : |\PitonOptions{background-color = [HTML]{F0F3F3}}|} + +\begin{table}[htb] +\centering +\caption{Les styles proposés par \pkg{piton}} +\label{Semantic} +\begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}} +\toprule +\normalfont Style & Usage \\ +\midrule +Number & les nombres \\ +String.Short & les chaînes de caractères courtes (entre \texttt{'} ou \texttt{"}) \\ +String.Long & les chaînes de caractères longues (entre \texttt{'''} ou \texttt{"""}) sauf les chaînes de + documentation \\ +String & cette clé fixe à la fois |String.Short| et |String.Long| \\ +String.Doc & les chaînes de documentation (seulement entre |"""| suivant PEP~257) \\ +String.Interpol & les éléments syntaxiques des champs des f-strings (c'est-à-dire les caractères \texttt{\{}et \texttt{\}}) \\ +Operator & les opérateurs suivants : \texttt{!= == << >> - \~{} + / * \% = < > \& .} \verb+|+ \verb|@| \\ +Operator.Word & les opérateurs suivants : |in|, |is|, |and|, |or| et |not| \\ +Name.Builtin & la plupart des fonctions prédéfinies par Python \\ +Name.Function & le nom des fonctions définies par l'utilisateur \emph{au moment de leur définition}, c'est-à-dire + après le mot-clé \verb|def| \\ +Name.Decorator & les décorateurs (instructions débutant par \verb|@|) \\ +Name.Namespace & le nom des modules (= bibliothèques extérieures) \\ +Name.Class & le nom des classes au moment de leur définition, c'est-à-dire après le mot-clé \verb|class| \\ +Exception & le nom des exceptions prédéfinies (ex.: SyntaxError) \\ +Comment & les commentaires commençant par \texttt{\#} \\ +Comment.LaTeX & les commentaires commençant par \texttt{\#>} qui sont composés en LaTeX par \pkg{piton} (et + appelés simplement «commentaires LaTeX» dans ce document) \\ +Keyword.Constant & |True|, |False| et |None| \\ +Keyword & les mots-clés suivants : + \ttfamily assert, break, case, continue, del, + elif, else, except, exec, finally, for, from, + global, if, import, lambda, non local, + pass, raise, return, try, while, + with, yield, yield from.\\ + \bottomrule +\end{tabularx} +\end{table} + + + + + + +\subsection{Définition de nouveaux environnements} + +\label{NewPitonEnvironment} + +Comme l'environnement |{Piton}| a besoin d'absorber son contenu d'une manière spéciale (à peu près comme du texte +verbatim), il n'est pas possible de définir de nouveaux environnements directement au-dessus de l'environnement +|{Piton}| avec les commandes classiques |\newenvironment| et |\NewDocumentEnvironment|. + +C'est pourquoi \pkg{piton} propose une commande |\NewPitonEnvironment|. Cette commande a la même syntaxe que la +commande classique |\NewDocumentEnvironment|. + +\bigskip +Par exemple, avec l'instruction suivante, un nouvel environnement |{Python}| sera défini avec le même comportement +que l'environnement |{Piton}|: + +{\color{gray}\verb|\NewPitonEnvironment{Python}{}{}{}|} + + +\bigskip +Si on souhaite un environnement |{Python}| qui prenne en argument optionnel entre crochets les clés de +|\PitonOptions|, on peut écrire : + +{\color{gray}\verb|\NewPitonEnvironment{Python}{O{}}{\PitonOptions{#1}}{}|} + +\bigskip +Si on souhaite un environnement |{Python}| qui compose le code inclus dans une boîte de \pkg{tcolorbox}, on peut +écrire: + +\begin{verbatim} +\NewPitonEnvironment{Python}{} + {\begin{tcolorbox}} + {\end{tcolorbox}} +\end{verbatim} + +\bigskip +Avec ce nouvel environnement |{Python}|, on peut écrire : + +\begin{Verbatim} +~emphase#\begin{Python}@ +def carré(x): + """Calcule le carré d'un nombre""" + return x*x +~emphase#\end{Python}@ +\end{Verbatim} + +\NewPitonEnvironment{Python}{} + {\begin{tcolorbox}} + {\end{tcolorbox}} + +\begin{Python} +def carré(x): + """Calcule le carré d'un nombre""" + return x*x +\end{Python} + + +\section{Fonctionnalités avancées} + +\subsection{Les échappements vers LaTeX} + +L'extension \pkg{piton} propose plusieurs mécanismes d'échappement vers LaTeX : +\begin{itemize} +\item Il est possible d'avoir des commentaires entièrement composés en LaTeX. +\item Il est possible d'avoir, dans les commentaires Python, les éléments entre \texttt{\$} composés en mode +mathématique de LaTeX. +\item Il est possible d'insérer du code LaTeX à n'importe quel endroit d'un listing Python. +\end{itemize} +Ces mécanismes vont être détaillés dans les sous-parties de cette partie. + +\smallskip +À remarquer également que, dans le cas où \pkg{piton} est utilisée dans la classe \cls{beamer}, \pkg{piton} détecte +la plupart des commandes et environnements de Beamer : voir la sous-section \ref{beamer}, p.~\pageref{beamer}. + + +\subsubsection{Les «commentaires LaTeX»} + +Dans ce document, on appelle «commentaire LaTeX» des commentaires qui débutent par |#>|. Tout ce qui suit ces deux +caractères, et jusqu'à la fin de la ligne, sera composé comme du code LaTeX standard. + +Il y a deux outils pour personnaliser ces commentaires. + +\begin{itemize} +\item Il est possible de changer le marquage syntaxique utilisé (qui vaut initialement~|#>|). Pour ce faire, il +existe une clé |comment-latex|, disponible seulement au chargement de \pkg{piton} (c'est-à-dire au moment du +|\usepackage|), qui permet de choisir les caractères qui (précédés par~|#|) serviront de marqueur syntaxique. + +Par exemple, avec le chargement suivant : + +\quad \verb|\usepackage[comment-latex = LaTeX]{piton}| + +les commentaires LaTeX commenceront par~|#LaTeX|. + +Si on donne la valeur nulle à la clé |comment-latex|, tous les commentaires Python (débutant par~|#|) seront en +fait des «commentaires LaTeX». + +\smallskip +\item Il est possible de changer le formatage du commentaire LaTeX lui-même en changeant le style \pkg{piton} +|Comment.LaTeX|. + +Par exemple, avec |\SetPitonStyle{Comment.LaTeX = \normalfont\color{blue}}|, les commentaires LaTeX seront composés +en bleu. + +Si on souhaite qu'un croisillon (|#|) soit affiché en début de commentaire dans le \textsc{pdf}, on peut régler +|Comment.LaTeX| de la manière suivante : + +\begin{Verbatim} +\SetPitonStyle{Comment.LaTeX = \color{gray}\~#\normalfont\space } +\end{Verbatim} + +Pour d'autres exemples de personnalisation des commentaires LaTeX, voir la partie \ref{example-comments} +p.~\pageref{example-comments}. +\end{itemize} + + +\bigskip +\colorbox{yellow!50}{\textbf{Nouveau 1.3}}\enskip Si l'utilisateur a demandé l'affichage des numéros de ligne (avec +|line-numbers| ou |all-line-numbers|), il est possible de faire référence à ce numéro de ligne avec la commande +|\label| placée dans un commentaire LaTeX.\footnote{Cette fonctionnalité est implémentée en redéfinissant, dans les +environnements |{Piton}|, la commande |\label|. Il peut donc y avoir des incompatibilités avec les extensions qui +redéfinissent (globalement) cette commande |\label| (comme \pkg{varioref}, \pkg{refcheck}, \pkg{showlabels}, etc.)} + + + + +\subsubsection{La clé «math-comments»} + +Il est possible de demander que, dans les commentaires Python normaux, c'est-à-dire débutant par~|#| (et non par +|#>|), les éléments placés entre symboles \texttt{\$} soient composés en mode mathématique de LaTeX (le reste du +commentaire restant composé en verbatim). + +La clé |math-comments|, qui n'est disponible qu'au chargement de \pkg{piton} (c'est-à-dire au moment du +|\usepackage|), active ce comportement. + +\bigskip +Dans l'exemple suivant, on suppose que la clé |math-comments| a été utilisée au chargement de \pkg{piton}. + +\begin{Verbatim} +\begin{Piton} +def carré(x): + return x*x ~# renvoie $x^2$ +\end{Piton} +\end{Verbatim} + +\begin{Piton} +def carré(x): + return x*x # renvoie $x^2$ +\end{Piton} + + +\subsubsection{Le mécanisme «espace-inside»} + +Il est aussi possible de surcharger les listings Python pour y insérer du code LaTeX à peu près n'importe où (mais +entre deux lexèmes, bien entendu). Cette fonctionnalité n'est pas activée par défaut par \pkg{piton}. Pour +l'utiliser, il faut spécifier les deux caractères marquant l'échappement (le premier le commençant et le deuxième +le terminant) en utilisant la clé |escape-inside| au chargement de \pkg{piton} (c'est-à-dire au moment du +|\usepackage|). Les deux caractères peuvent être identiques. + + +\bigskip +Dans l'exemple suivant, on suppose que l'extension \pkg{piton} a été chargée de la manière suivante : + +\begin{Verbatim} +\usepackage[~emphase#escape-inside=$$@]{piton} +\end{Verbatim} + +\medskip +Dans le code suivant, qui est une programmation récursive de la factorielle, on décide de surligner en jaune +l'instruction qui contient l'appel récursif. +\begin{Verbatim} +\begin{Piton} +def fact(n): + if n==0: + return 1 + else: + ~emphase#$\colorbox{yellow!50}{$@return n*fact(n-1)~emphase#$}$@ +\end{Piton} +\end{Verbatim} + +\begin{Piton} +def fact(n): + if n==0: + return 1 + else: + $\colorbox{yellow!50}{$return n*fact(n-1)$}$ +\end{Piton} + +\bigskip +\emph{Attention} : L'échappement vers LaTeX permis par les caractères de |escape-inside| n'est pas actif dans les +chaînes de caractères ni dans les commentaires (pour avoir un commentaire entièrement en échappement vers LaTeX, +c'est-à-dire ce qui est +appelé dans ce document «commentaire LateX», il suffit de le faire débuter par |#>|). + + + + +\subsection{Comportement dans la classe Beamer} + +\label{beamer} + +Quand l'extension \pkg{piton} est utilisée dans la classe \cls{beamer}\footnote{L'extension \pkg{piton} détecte la + classe \cls{beamer} mais il est aussi possible, si le besoin s'en faisait sentir, d'activer ce comportement avec + la clé |beamer| au chargement de \pkg{piton} : |\usepackage[beamer]{piton}|}, le comportement de \pkg{piton} est +légèrement modifié, comme décrit maintenant. + +\subsubsection{\{Piton\} et \textbackslash PitonInputFile sont ``overlay-aware''} + +Quand \pkg{piton} est utilisé avec Beamer, l'environnement |{Piton}| et la commande |\PitonInputFile| acceptent +l'argument optionnel |<...>| de Beamer pour indiquer les «\emph{overlays}» concernés. + +On peut par exemple écrire : + +\begin{Verbatim} +\begin{Piton}~emphase#<2-5>@ +... +\end{Piton} +\end{Verbatim} + +ou aussi + +\begin{Verbatim} +\PitonInputFile~emphase#<2-5>@{mon_fichier.py} +\end{Verbatim} + + +\subsubsection{Commandes de Beamer reconnues dans \{Piton\} et \textbackslash PitonInputFile} + +Quand \pkg{piton} est utilisé dans la classe \cls{beamer}, les commandes suivantes de \cls{beamer} (classées selon +leur nombre d'arguments obligatoires) sont directement reconnues dans les environnements |{Piton}| (ainsi que dans +les listings composés par la commande |\PitonInputFile|, même si c'est sans doute moins utile). +% +\begin{itemize} +\item aucun argument obligatoire : |\pause|\footnote{On remarquera que, bien sûr, on peut aussi utiliser |\pause| + dans un «commentaire LaTeX», c'est-à-dire en écrivant |#> \pause|. Ainsi, si le code Python est copié, il est + interprétable par Python.} ; +\item un argument obligatoire : |\action|, |\alert|, |\invisible|, |\only|, |\uncover| et |\visible| ; +\item deux arguments obligatoire : |\alt| ; +\item trois arguments obligatoires : |\temporal|. +\end{itemize} + +\medskip +Néanmoins, il y a deux restrictions pour le contenu des arguments obligatoires de ces commandes. +\begin{itemize} +\item les accolades dans les arguments obligatoires de ces commandes doivent être équilibrées (cependant, les +accolades présentes dans des chaînes courtes\footnote{Les chaînes courtes de Python sont les chaînes (string) + délimitées par les caractères \texttt{'} ou \texttt{"} non triplés. En Python, les chaînes de caractères courtes + ne peuvent pas s'étendre sur plusieurs lignes de code.} de Python ne sont pas prises en compte) ; +\item l'argument obligatoire ne doit pas contenir \textbf{aucun retour à la ligne} (s'il y en a, une erreur +fatale est levée). +\end{itemize} + +\medskip +Remarquons que, comme l'environnement |{Piton}| prend son argument selon un mode verbatim, il convient, ce qui +n'est pas surprenant, de l'utiliser dans des environnements |{frame}| de Beamer protégés par la clé |fragile|.\footnote{On + rappelle que pour un environnement |{frame}| de Beamer qui utilise la clé |fragile|, l'instruction |\end{frame}| + doit être seule sur une ligne (à l'exception d'éventuels espaces en début de ligne).} + +\medskip +Voici un exemple complet de fichier : + +\begin{Verbatim}[formatcom = \small\color{gray}] +\documentclass{beamer} +\usepackage{piton} +\begin{document} +\begin{frame}[fragile] +\begin{Piton} +def string_of_list(l): + """Convertit une liste de nombres en chaîne""" +~emphase# \only<2->{s = "{" + str(l[0])}@ +~emphase# \only<3->{for x in l[1:]: s = s + "," + str(x)}@ +~emphase# \only<4->{s = s + "}"}@ + return s +\end{Piton} +\end{frame} +\end{document} +\end{Verbatim} + +Dans l'exemple précédent, les accolades des deux chaînes de caractères Python |"{"| et |"}"| sont correctement interprétées (sans aucun +caractère d'échappement). + + +\bigskip +\subsubsection{Environnements de Beamer reconnus dans \{Piton\} et \textbackslash PitonInputFile} + +Quand \pkg{piton} est utilisé dans la classe \pkg{beamer}, les environnements suivants de Beamer sont directement +reconnus dans les environnements |{Piton}| (ainsi que dans les listings composés par la commande |\PitonInputFile| +même si c'est sans doute moins utile).: |{uncoverenv}|, |{onlyenv}|, |{visibleenv}| et |{invisibleenv}|. + +\medskip +Il y a néanmoins une restriction : ces environnements doivent englober des \emph{lignes entières de code Python}. + +\pagebreak + +\medskip +On peut par exemple écrire : + +\begin{Verbatim}[formatcom = \small\color{gray}] +\documentclass{beamer} +\usepackage{piton} +\begin{document} +\begin{frame}[fragile] +\begin{Piton} +def carré(x): + """Calcule le carré de l'argument""" + ~emphase#\begin{uncoverenv}<2>@ + return x*x + ~emphase#\end{uncoverenv}@ +\end{Piton} +\end{frame} +\end{document} +\end{Verbatim} + + + + + +\bigskip +\subsection{Coupure des pages et des lignes} + +\label{breakable} + +\subsubsection{Coupure des pages} + +Par défaut les listings produits par l'environnement |{Piton}| et par la commande |\PitonInputFile| sont +insécables. + +Néanmoins, la commande |\PitonOptions| propose la clé |splittable| pour autoriser de telles coupures. + +\begin{itemize} +\item Si la clé |splittable| est utilisée sans valeur, les listings sont sécables n'importe où. + +\item Si la clé |splittable| est utilisée avec une valeur numérique $n$ (qui doit être un entier naturel non nul), +alors les listings seront sécables mais aucune coupure ne pourra avoir lieu entre les $n$~premières lignes, ni +entre les $n$~dernières. De ce fait, |splittable=1| est équivalent à |splittable|. +\end{itemize} + +\medskip +\emph{Remarque}\par\nobreak + +Même avec une couleur de fond (fixée avec |background-color|), les sauts de page sont possibles, à partir du moment +où la clé |splittable| est utilisée.\footnote{Avec la clé |splittable|, un environnement |{Piton}| est sécable même dans un environnement de + \pkg{tcolorbox} (à partir du moment où la clé |breakable| de \pkg{tcolorbox} est utilisée). On précise cela parce + que, en revanche, un environnement de \pkg{tcolorbox} inclus dans un autre environnement de \pkg{tcolorbox} n'est + pas sécable, même quand les deux utilisent la clé |breakable|.} + +\subsubsection{Coupure des lignes} + +Par défaut, les éléments produits par \pkg{piton} ne peuvent pas être coupés par une fin de ligne. Il existe +néanmoins des clés pour autoriser de telles coupures (les points de coupure possibles sont les espaces, y compris +les espaces dans les chaînes Python). +\begin{itemize} +\item Avec la clé |break-lines-in-piton|, les coupures de ligne sont autorisées dans la commande |\piton{...}| +(mais pas dans la commande \verb+|...|+, c'est-à-dire avec la syntaxe verbatim). + +\item Avec la clé |break-lines-in-Piton|, les coupures de ligne sont autorisées dans l'environnement |{Piton}| +(d'où la lettre |P| capitale dans le nom) et dans les listings produits par |\PitonInputFile|. + +\item La clé |break-lines| est la conjonction des deux clés précédentes. +\end{itemize} + +\medskip +L'extension \pkg{piton} fournit aussi plusieurs clés pour contrôler l'apparence des coupures de ligne autorisées par |break-lines-in-Piton|. + +\begin{itemize} +\item Avec la clé |indent-broken-lines|, l'indentation de la ligne coupée est respectée à chaque retour à la ligne. + +\item La clé |end-of-broken-line| correspond au symbole placé à la fin d'une ligne coupée. Sa valeur initiale est : +|\hspace*{0.5em}\textbackslash|. + +\item La clé |continuation-symbol| correspond au symbole placé à chaque retour de ligne dans la marge gauche. Sa +valeur initiale est : |+\;|. + +\item La clé |continuation-symbol-on-indentation| correspond au symbole placé à chaque retour de ligne au niveau de +l'indentation (uniquement dans le cas où la clé |indent-broken-lines| est active). Sa valeur initiale est : +|$\hookrightarrow\;$|. +\end{itemize} + +\bigskip +Le code suivant a été composé dans une |{minipage}| de largeur 12~cm avec le réglage suivant : + +\begin{Verbatim} +\PitonOptions{break-lines,indent-broken-lines,background-color=gray!15} +\end{Verbatim} + +\begin{center} +\PitonOptions{break-lines,indent-broken-lines,background-color=gray!15} +\begin{minipage}{12cm} +\begin{Piton} +def dict_of_liste(liste): + """Convertit une liste de subrs et de descriptions de glyphes en dictionnaire""" + dict = {} + for liste_lettre in liste: + if (liste_lettre[0][0:3] == 'dup'): # si c'est un subr + nom = liste_lettre[0][4:-3] + print("On traite le subr de numéro " + nom) + else: + nom = liste_lettre[0][1:-3] # si c'est un glyphe + print("On traite le glyphe du caractère " + nom) + dict[nom] = [traite_ligne_Postscript(k) for k in liste_lettre[1:-1]] + return dict +\end{Piton} +\end{minipage} +\end{center} + + + +\bigskip +\subsection{Notes de pied de page dans les environnements de piton} + +\label{footnote} + +Si vous voulez mettre des notes de pied de page dans un environnement de \pkg{piton} (ou bien dans un listing +produit par |\PitonInputFile|, bien que cela paraisse moins pertinent dans ce cas-là) vous pouvez utiliser une +paire |\footnotemark|--|\footnotetext|. + +\smallskip +Néanmoins, il est également possible d'extraire les notes de pieds de page avec l'extension \pkg{footnote} ou bien +l'extension \pkg{footnotehyper}. + +\smallskip +Si \pkg{piton} est chargée avec l'option |footnote| (avec |\usepackage[footnote]{piton}|) l'extension +\pkg{footnote} est chargée (si elle ne l'est pas déjà) et elle est utilisée pour extraire les notes de pied de +page. + +\smallskip +Si \pkg{piton} est chargée avec l'option |footnotehyper|, l'extension \pkg{footnotehyper} est chargée (si +elle ne l'est pas déjà) et elle est utilisée pour extraire les notes de pied de page. + +\smallskip +Attention : Les extensions \pkg{footnote} et \pkg{footnotehyper} sont incompatibles. +L'extension \pkg{footnotehyper} est le successeur de l'extension \pkg{footnote} +et devrait être utilisée préférentiellement. L'extension \pkg{footnote} a quelques défauts ; +en particulier, elle doit être chargée après l'extension \pkg{xcolor} et elle n'est pas parfaitement +compatible avec \pkg{hyperref}. + +\medskip +Dans ce document, l'extension \pkg{piton} a été chargée avec l'option |footnotehyper| et c'est pourquoi des notes +peuvent être mises dans les environnements |{Piton}| : voir un exemple sur la première page de ce document. + +\subsection{Tabulations} + +\smallskip +Même s'il est recommandé d'indenter les listings Python avec des espaces (cf. PEP~8), \pkg{piton} accepte les +caractères de tabulations (U+0009) en début de ligne. Chaque caractère U+0009 est remplacé par $n$ espaces. La +valeur initiale de~$n$ est~4 mais on peut la changer avec la clé |tab-size| de |\PitonOptions|. + +\smallskip +Il existe aussi une clé |tabs-auto-gobble| qui détermine le nombre minimal de caractères U+0009 débutant chaque +ligne (non vide) de l'environnement |{Piton}| et applique |gobble| avec cette valeur (avant le remplacement des +caractères U+0009 par des espaces, bien entendu). Cette clé est donc similaire à la clé |auto-gobble| mais agit sur +des caractères U+0009 au lieu de caractères U+0020 (espaces). + +\section{Exemples} + + +\subsection{Numérotation des lignes} + +\label{example-numbering} + +On rappelle que l'on peut demander la numérotation des lignes des listings avec la clé |line-numbers| ou la clé |all-line-numbers|. + +Par défaut, les numéros de ligne sont composés par \pkg{piton} en débordement à gauche (en utilisant en interne la commande |\llap| de LaTeX). + +Si on ne veut pas de débordement, on peut utiliser l'option |left-margin=auto| qui va insérer une marge adaptée aux +numéros qui seront insérés (elle est plus large quand les numéros dépassent 10). + + +\begingroup +\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}} +\begin{Verbatim} +~emphase&\PitonOptions{background-color=gray!10, left-margin = auto, line-numbers}@ +\begin{Piton} +def arctan(x,n=10): + if x < 0: + return -arctan(-x) #> (appel récursif) + elif x > 1: + return pi/2 - arctan(1/x) #> (autre appel récursif) + else: + return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) ) +\end{Piton} +\end{Verbatim} +\endgroup + + + +\begingroup +\PitonOptions{background-color=gray!10,left-margin = auto, line-numbers} +\begin{Piton} +def arctan(x,n=10): + if x < 0: + return -arctan(-x) #> (appel récursif) + elif x > 1: + return pi/2 - arctan(1/x) #> (autre appel récursif) + else: + return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) ) +\end{Piton} +\endgroup + + +\bigskip + +\subsection{Formatage des commentaires LaTeX} + +\label{example-comments} + +On peut modifier le style |Comment.LaTeX| (avec |\SetPitonStyle|) pour faire afficher les commentaires +LaTeX (qui débutent par |#>|) en butée à droite. + +\begingroup +\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}} +\begin{Verbatim} +\PitonOptions{background-color=gray!10} +~emphase&\SetPitonStyle{Comment.LaTeX = \hfill \normalfont\color{gray}}@ +\begin{Piton} +def arctan(x,n=10): + if x < 0: + return -arctan(-x) #> appel récursif + elif x > 1: + return pi/2 - arctan(1/x) #> autre appel récursif + else: + return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) ) +\end{Piton} +\end{Verbatim} +\endgroup + +\begingroup +\PitonOptions{background-color=gray!10} +\SetPitonStyle{Comment.LaTeX = \hfill \normalfont\color{gray}} +\begin{Piton} +def arctan(x,n=10): + if x < 0: + return -arctan(-x) #> appel récursif + elif x > 1: + return pi/2 - arctan(1/x) #> autre appel récursif + else: + return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) ) +\end{Piton} +\endgroup + + +\vspace{1cm} +On peut aussi faire afficher les commentaires dans une deuxième colonne à droite si on limite la largeur du code +proprement dit avec un environnement |{minipage}| de LaTeX. + + +\begingroup +\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}} +\begin{Verbatim} +\PitonOptions{background-color=gray!10} +~emphase&\NewDocumentCommand{\MyLaTeXCommand}{m}{\hfill \normalfont\itshape\rlap{\quad #1}}@ +~emphase&\SetPitonStyle{Comment.LaTeX = \MyLaTeXCommand}@ +~emphase&\begin{minipage}{12cm}@ +\begin{Piton} +def arctan(x,n=10): + if x < 0: + return -arctan(-x) #> appel récursif + elif x > 1: + return pi/2 - arctan(1/x) #> autre appel récursif + else: + s = 0 + for k in range(n): + s += (-1)**k/(2*k+1)*x**(2*k+1) + return s +\end{Piton} +~emphase&\end{minipage}@ +\end{Verbatim} +\endgroup + + + +\begingroup +\PitonOptions{background-color=gray!10} +\NewDocumentCommand{\MyLaTeXCommand}{m}{\hfill \normalfont\itshape\rlap{\quad #1}} +\SetPitonStyle{Comment.LaTeX = \MyLaTeXCommand} +\begin{minipage}{12cm} +\begin{Piton} +def arctan(x,n=10): + if x < 0: + return -arctan(-x) #> appel récursif + elif x > 1: + return pi/2 - arctan(1/x) #> autre appel récursif + else: + s = 0 + for k in range(n): + s += (-1)**k/(2*k+1)*x**(2*k+1) + return s +\end{Piton} +\end{minipage} +\endgroup + +\bigskip + +\subsection{Notes dans les listings} + +Pour pouvoir extraire les notes (introduites par |\footnote|), l'extension |piton| doit être chargée, soit avec la +clé |footnote|, soit avec la clé |footnotehyper|, comme expliqué à la section \ref{footnote} p.~\pageref{footnote}. +Dans le présent document, l'extension \pkg{piton} a été chargée par la clé |footnotehyper|. + +Bien entendu, une commande |\footnote| ne peut apparaître que dans un commentaire LaTeX (qui débute par |#>|). Un +tel commentaire peut se limiter à cette unique commande |\footnote|, comme dans l'exemple suivant. + +\begingroup +\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}} +\begin{Verbatim} +\PitonOptions{background-color=gray!10} +\begin{Piton} +def arctan(x,n=10): + if x < 0: + return -arctan(-x)~emphase&#>\footnote{Un premier appel récursif.}]@ + elif x > 1: + return pi/2 - arctan(1/x)~emphase&#>\footnote{Un deuxième appel récursif.}@ + else: + return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) ) +\end{Piton} +\end{Verbatim} +\endgroup + +\begingroup +\PitonOptions{background-color=gray!10} +\begin{Piton} +def arctan(x,n=10): + if x < 0: + return -arctan(-x)#>\footnote{Un premier appel récursif.} + elif x > 1: + return pi/2 - arctan(1/x)#>\footnote{Un deuxième appel récursif.} + else: + return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) ) +\end{Piton} +\endgroup + + +\vspace{1cm} + +Si on utilise l'environnement |{Piton}| dans un environnement |{minipage}| de LaTeX, les notes sont, bien entendu, +composées au bas de l'environnement |{minipage}|. Rappelons qu'une telle |{minipage}| ne peut être coupée par un +saut de page. + + +\begingroup +\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}} +\begin{Verbatim} +\PitonOptions{background-color=gray!10} +\emphase\begin{minipage}{\linewidth} +\begin{Piton} +def arctan(x,n=10): + if x < 0: + return -arctan(-x)~emphase&#>\footnote{Un premier appel récursif.}@ + elif x > 1: + return pi/2 - arctan(1/x)~emphase&#>\footnote{Un deuxième appel récursif.}@ + else: + return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) ) +\end{Piton} +\end{minipage} +\end{Verbatim} +\endgroup + +\begingroup +\PitonOptions{background-color=gray!10} +\begin{minipage}{\linewidth} +\begin{Piton} +def arctan(x,n=10): + if x < 0: + return -arctan(-x)#>\footnote{Un premier appel récursif.} + elif x > 1: + return pi/2 - arctan(1/x)#>\footnote{Un deuxième appel récursif.} + else: + return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) ) +\end{Piton} +\end{minipage} +\endgroup + + +\vspace{1cm} +Si on encapsule l'environnement |{Piton}| dans un environnement |{minipage}| pour, typiquement, limiter la largeur +d'un fond coloré, il faut encadrer l'ensemble dans un environnement |{savenotes}| (de \pkg{footnote} ou +\pkg{footnotehyper}) si on veut avoir les notes reportées en pied de page. + +\begingroup +\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}} +\begin{Verbatim} +\PitonOptions{background-color=gray!10} +~emphase&\begin{savenotes}@ +\begin{minipage}{13cm} +\begin{Piton} +def arctan(x,n=10): + if x < 0: + return -arctan(-x)~emphase&#>\footnote{Un premier appel récursif.}@ + elif x > 1: + return pi/2 - arctan(1/x)~emphase&#>\footnote{Un deuxième appel récursif.}@ + else: + return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) ) +\end{Piton} +\end{minipage} +~emphase&\end{savenotes}@ +\end{Verbatim} +\endgroup + + + +\begin{savenotes} +\PitonOptions{background-color=gray!10} +\begin{minipage}{13cm} +\begin{Piton} +def arctan(x,n=10): + if x < 0: + return -arctan(-x)#>\footnote{Un premier appel récursif.} + elif x > 1: + return pi/2 - arctan(1/x)#>\footnote{Un deuxième appel récursif.} + else: + return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) ) +\end{Piton} +\end{minipage} +\end{savenotes} + +\bigskip + +\subsection{Un exemple de réglage des styles} + +Les styles graphiques ont été présentés à la partie \ref{styles}, p.~\pageref{styles}. + +\smallskip +On présente ici un réglage de ces styles adapté pour les documents en noir et blanc. On l'utilise avec la fonte +\emph{DejaVu Sans Mono}\footnote{Voir: \url{https://dejavu-fonts.github.io}} spécifiée avec la commande + |\setmonofont| de \pkg{fontspec}. + + +\begin{Verbatim} +\setmonofont[Scale=0.85]{DejaVu Sans Mono} + +\SetPitonStyle + { + Number = , + String = \itshape , + String.Doc = \color{gray} \itshape , + Operator = , + Operator.Word = \bfseries , + Name.Builtin = , + Name.Function = \bfseries \colorbox{gray!20} , + Comment = \color{gray} , + Comment.LaTeX = \normalfont \color{gray}, + Keyword = \bfseries , + Name.Namespace = , + Name.Class = , + Name.Type = , + InitialValues = \color{gray} + } +\end{Verbatim} + + +\begingroup + + +\setmonofont[Scale=0.85]{DejaVu Sans Mono} + +\SetPitonStyle + { + Number = , + String = \itshape , + String.Doc = \color{gray} \itshape , + Operator = , + Operator.Word = \bfseries , + Name.Builtin = , + Name.Function = \bfseries \colorbox{gray!20} , + Comment = \color{gray} , + Comment.LaTeX = \normalfont \color{gray}, + Keyword = \bfseries , + Name.Namespace = , + Name.Class = , + Name.Type = , + InitialValues = \color{gray} + } + + +\bigskip + +\begin{Piton} +from math import pi + +def arctan(x,n=10): + """Compute the mathematical value of arctan(x) + + n is the number of terms in the sum + """ + if x < 0: + return -arctan(-x) # appel récursif + elif x > 1: + return pi/2 - arctan(1/x) + #> (on a utilisé le fait que $\arctan(x)+\arctan(1/x)=\pi/2$ pour $x>0$) + else: + s = 0 + for k in range(n): + s += (-1)**k/(2*k+1)*x**(2*k+1) + return s +\end{Piton} + + +\endgroup + +\section{Utilisation avec pyluatex} + +\subsection{Utilisation standard de pyluatex} + +L'extension \pkg{pyluatex} est une extension qui permet l'exécution de code Python à partir de |lualatex| (pourvu +que Python soit installé sur la machine et que la compilation soit effectuée avec |lualatex| et |--shell-escape|). + +Voici, à titre d'exemple, un environnement |{PitonExecute}| qui formate un listing Python (avec \pkg{piton}) et qui +affiche également dessous le résultat de l'exécution de ce code avec Python. + + +\begin{Verbatim} +\ExplSyntaxOn +\NewDocumentEnvironment { ~emphase#PitonExecute@ } { ! O { } } + { + \PyLTVerbatimEnv + \begin{pythonq} + } + { + \end{pythonq} + \directlua + { + tex.print("\\PitonOptions{~#1}") + tex.print("\\begin{Piton}") + tex.print(pyluatex.get_last_code()) + tex.print("\\end{Piton}") + tex.print("") + } + \begin{center} + \directlua{tex.print(pyluatex.get_last_output())} + \end{center} + } +\ExplSyntaxOff +\end{Verbatim} + +\ExplSyntaxOn +\NewDocumentEnvironment { PitonExecute } { ! O { } } + { + \PyLTVerbatimEnv + \begin{pythonq} + } + { + \end{pythonq} + \directlua + { + tex.print("\\PitonOptions{~#1}") + tex.print("\\begin{Piton}") + tex.print(pyluatex.get_last_code()) + tex.print("\\end{Piton}") + tex.print("") + } + \begin{center} + \directlua{tex.print(pyluatex.get_last_output())} + \end{center} + } +\ExplSyntaxOff + +Cet environnement |{PitonExecute}| prend en argument optionnel (entre crochets) les options proposées par la +commande |\PitonOptions|. + +\bigskip +Voici un exemple d'utilisation de cet environnement |{PitonExecute}| : + +\begin{Verbatim} +\begin{~emphase#PitonExecute@}[background-color=gray!15] +def square(x): + return x*x +print(f'The square of 12 is {square(12)}.') +\end{~emphase#PitonExecute@} +\end{Verbatim} + + +\medskip +\begin{PitonExecute}[background-color=gray!15] +def square(x): + return x*x +print(f'The square of 12 is {square(12)}.') +\end{PitonExecute} + +\bigskip + +\subsection{Utilisation de l'environnement \{pythonrepl\} de pyluatex} + +\label{pythonrepl} + +L'environnement |{pythonrepl}| de \pkg{pyluatex} passe son contenu à Python et renvoie ce que l'on obtient quand on +fournit ce code à une boucle \textsc{repl} (\emph{read-eval-print loop}) de Python. On obtient un entrelacement +d'instructions précédées par le prompt |>>>| de Python et des valeurs renovées par Python (et de ce qui a été +demandé d'être affiché avec des \piton{print} de Python). + +\medskip +Il est ensuite possible de passer cela à un environnement |{Piton}| qui va faire un coloriage syntaxique +et mettre sur fond grisé les lignes correspondant aux instructions fournies à l'interpréteur Python (gràce à la clé +|prompt-background-color| de |\PitonOptions|). + + +\medskip +Voici la programmation d'un environnement |{PitonREPL}| qui effectue ce travail. + +\begin{Verbatim} +\NewDocumentEnvironment { PitonREPL } { ! O { } } + { + \PitonOptions + { background-color=white, + ~emphase#prompt-background-color = gray!10@, + ~#1 + } + \PyLTVerbatimEnv + \begin{pythonrepl} + } + { + \directlua + { + tex.print("\\begin{Piton}") + tex.print(pyluatex.get_last_output()) + tex.print("\\end{Piton}") + tex.print("") + } + \end{pythonrepl} + } +\end{Verbatim} + +\medskip +Voici un exemple d'utilisation de ce nouvel environnement |{PitonREPL}|. + +\medskip +\begin{Verbatim} +~emphase#\begin{PitonREPL}@ +def valeur_absolue(x): + "Renvoie la valeur absolue de x" + if x > 0: + return x + else: + return -x + +valeur_absolue(-3) +valeur_absolue(0) +valeur_absolue(5) +~emphase#\end{PitonREPL}@ +\end{Verbatim} + +\bigskip + + +\NewDocumentEnvironment { PitonREPL } { } + { + \PitonOptions{background-color=white,prompt-background-color = gray!10} + \PyLTVerbatimEnv + \begin{pythonrepl} + } + { + \directlua + { + tex.print("\\begin{Piton}") + tex.print(pyluatex.get_last_output()) + tex.print("\\end{Piton}") + tex.print("") + } + \end{pythonrepl} + } + + +\begin{PitonREPL} +def valeur_absolue(x): + "Renvoie la valeur absolue de x" + if x > 0: + return x + else: + return -x + +valeur_absolue(-3) +valeur_absolue(0) +valeur_absolue(5) +\end{PitonREPL} + + + +\section*{Autre documentation} + +Le document |piton.pdf| (fourni avec l'extension \pkg{piton}) contient une traduction anglaise de la +documentation ici présente, ainsi que le code source commenté et un historique des versions. + + \end{document}
\ No newline at end of file |