summaryrefslogtreecommitdiff
path: root/macros/luatex/latex/piton/piton-french.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/latex/piton/piton-french.tex')
-rw-r--r--macros/luatex/latex/piton/piton-french.tex361
1 files changed, 361 insertions, 0 deletions
diff --git a/macros/luatex/latex/piton/piton-french.tex b/macros/luatex/latex/piton/piton-french.tex
new file mode 100644
index 0000000000..5e9ee11c7a
--- /dev/null
+++ b/macros/luatex/latex/piton/piton-french.tex
@@ -0,0 +1,361 @@
+% -*- coding: utf-8 ; -*-
+\documentclass[dvipsnames]{article}
+\usepackage[french]{babel}
+\frenchsetup{og = « , fg = »}
+
+\usepackage[escape-inside=$$]{piton}
+
+\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{caption}
+\captionsetup{labelfont = bf}
+
+% 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{\|}
+
+
+\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{footnote}
+
+\usepackage[hyperfootnotes = false]{hyperref}
+
+\hypersetup
+ {
+ pdfinfo =
+ {
+ Title = L’extension piton ,
+ Subject = Une extension LaTeX ,
+ Author = F. Pantigny
+ }
+ }
+
+
+\NewDocumentEnvironment {scope} {} {} {}
+
+\NewDocumentCommand {\pkg} {m} {\textsf{#1}}
+\NewDocumentCommand {\cls} {m} {\textsf{#1}}
+
+\setlength{\parindent}{0pt}
+
+
+\begin{document}
+
+\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 librarie 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 value of arctan(x)
+ n is the number of terms if the sum"""
+ if x < 0:
+ return -arctan(-x) # recursive call
+ elif x > 1:
+ return pi/2 - arctan(1/x)
+ ## (on a utilisé le fait que $\arctan(x)+\arctan(1/x)=\frac{\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}
+
+
+
+\section{Installation}
+
+L'extension \pkg{piton} est composée de deux fichiers : |piton.sty| et |piton.lua| (le fichier LaTeX |piton.sty|
+chargé par |\usepackage| va à son tour charger le fichier |piton.lua|). Les deux fichiers doivent être présents
+dans un répertoire où LaTeX pourra les trouver. Le mieux est de les installer dans une arborescence |texmf|.
+
+
+\section{Utilisation de l'extension}
+
+Pour utiliser l'extension \pkg{piton}, l'utilisateur final a seulement à charger l'extension dans son document avec
+la commande classique |\usepackage| et se souvenir que la compilation doit être faite avec LuaLaTeX.
+
+\medskip
+L'extension \pkg{piton} fournit trois outils pour composer du code Python: la commande |\piton|, l'environnement
+|{Piton}| et la commande |\PitonInputFile|.
+
+\begin{itemize}
+\item La commande |\piton| doit être utilisée pour composer de petits éléments de code à l'intérieur d'un
+paragraphe. \emph{Attention} : Cette fonction prend son argument en mode \emph{verbatim} (comme la commande
+\verb|\verb|) et, de ce fait, cette fonction ne peut pas être utilisée à l'intérieur d'un argument d'une autre
+fonction (on peut néanmoins l'utiliser à l'intérieur d'un environnement).
+
+\item L'environnement |{Piton}| doit être utilisé pour composer des codes de plusieurs lignes.
+
+\item La commande |\PitonInputFile| doit être utilisée pour insérer et composer un fichier extérieur.
+\end{itemize}
+
+\bigskip
+Il est possible de composer des commentaires en LaTeX en commençant par |##| (c'est un échappement vers LaTeX). Les
+caractères |##| eux-mêmes ne seront pas imprimés.
+
+
+\section{Personnalisation}
+
+\subsection{La commande \textbackslash PitonOptions}
+
+La commande |\PitonOptions| propose quatre clés : |gobble|, |auto-gobble|, |line-numbers| et |all-line-numbers|.
+
+\begin{itemize}
+\item La clé |gobble| peut 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}|.
+
+\item Quand la clé |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'environnment |{Piton}| et applique |gobble| avec cette
+valeur de~$n$.
+
+\item Avec la clé |line-numbers|, les lignes \emph{non vides} sont numérotées dans les environnements \verb|{Piton}|
+et dans les listings produits par la commande |\PitonInputFile|.
+
+\item Avec la clé |all-line-numbers|, \emph{toutes} les lignes sont numérotées, y compris les lignes vides.
+\end{itemize}
+
+\bigskip
+
+\begingroup
+\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
+\begin{Verbatim}
+~emphase&\PitonOptions{line-numbers,auto-gobble}@
+\begin{Piton}
+ from math import pi
+
+ def arctan(x,n=10):
+ """Compute the value of arctan(x)
+ n is the number of terms if the sum"""
+ if x < 0:
+ return -arctan(-x) # recursive call
+ elif x > 1:
+ return pi/2 - arctan(1/x)
+ ## (on a utilisé le fait que $\arctan(x)+\arctan(1/x)=\frac{\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}
+\begin{Piton}
+ from math import pi
+
+ def arctan(x,n=10):
+ """Compute the value of arctan(x)
+ n is the number of terms if the sum"""
+ if x < 0:
+ return -arctan(-x) # recursive call
+ elif x > 1:
+ return pi/2 - arctan(1/x)
+ ## (on a utilisé le fait que $\arctan(x)+\arctan(1/x)=\frac{\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
+
+\subsection{L'option escape-inside}
+
+L'option |escape-inside| doit être utilisée au chargement de \pkg{piton} (c'est-à-dire dans l'instruction
+|\usepackage|). Pour des raisons techniques, elle ne peut pas être fixée dans |\PitonOptions|. Elle prend comme
+valeur deux caractères qui seront utilisés pour délimiter des parties qui seront composées en LaTeX.
+
+
+\bigskip
+Dans l'exemple suivant, on suppose que l'extension \pkg{piton} a été chargée de la manière suivante :
+
+\smallskip
+\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,
+il suffit de le faire débuter par |##|).
+
+\subsection{Les 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.
+
+\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 |\color{...}|, |\bseries|,
+|\slshape|, 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}{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
+
+
+
+\medskip
+Les différents styles sont décrits dans la table \ref{Semantic}.
+
+\begin{table}[htb]
+\centering
+\caption{Usage des différents styles}
+\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 \\
+String.Interpol & les éléments syntaxiques des champs des f-strings (c'est-à-dire les caractères \texttt{\{}, \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|@| dans les classes) \\
+Name.Namespace & le nom des modules (= bibliothèques extérieures) \\
+Name.Class & le nom des classes au moment de leur définition \\
+Exception & le nom des exceptions prédéfinies (eg: 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}
+ (\texttt{\#\#} est une séquence d'échappement vers LaTeX) \\
+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}
+
+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}|.
+
+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}|:
+
+\verb|\NewPitonEnvironment{Python}{}{}{}|
+
+\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}
+
+
+\end{document} \ No newline at end of file