diff options
Diffstat (limited to 'macros/luatex/latex/piton/piton-french.tex')
| -rw-r--r-- | macros/luatex/latex/piton/piton-french.tex | 2094 |
1 files changed, 1201 insertions, 893 deletions
diff --git a/macros/luatex/latex/piton/piton-french.tex b/macros/luatex/latex/piton/piton-french.tex index 2794f5acda..ce776dbf8a 100644 --- a/macros/luatex/latex/piton/piton-french.tex +++ b/macros/luatex/latex/piton/piton-french.tex @@ -15,7 +15,7 @@ end-escape = ! , begin-escape-math = \( , end-escape-math = \) , - detected-commands = highLight + detected-commands = { highLight , footnote } } @@ -33,8 +33,6 @@ \usepackage{booktabs} \usepackage{tcolorbox} \usepackage{luacolor,lua-ul} - - \usepackage{caption} % We use \MakeShortVerb of shortvrb and not \DefineShortVerb of fancyvrb @@ -73,6 +71,8 @@ \usepackage{makeidx} \makeindex +\usepackage{underscore} + \NewDocumentCommand{\Definition}{m} {{\setlength{\fboxsep}{1pt}\colorbox{gray!20}{\ttfamily \vphantom{gl}#1}}} @@ -107,27 +107,34 @@ version~\PitonFileVersion\space de \pkg{piton}, à la date du~\PitonFileDate.}} \maketitle \begin{abstract} -L'extension \pkg{piton} propose des outils pour composer des codes informatiques avec coloration syntaxique. Elle -nécessite l'emploi de la LuaLaTeX car le travail principal est fait en utilisant la bibliothèque Lua LPEG. +L'extension \pkg{piton} propose des outils pour composer des codes informatiques avec +coloration syntaxique. Elle nécessite l'emploi de la LuaLaTeX car le travail principal est +fait en utilisant la bibliothèque Lua LPEG. \end{abstract} +\bigskip +{\color{red} Depuis la version 4.0, la syntaxe des chemins absolus et relatifs utilisés dans +|\PitonInputFile| a été changée : cf.~partie~\ref{PitonInputFile}, p.~\pageref{PitonInputFile}.} \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» des listings informatiques avec -coloriage syntaxique. Comme elle utilise le Lua de LuaLaTeX, 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. +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» des listings informatiques +avec coloriage syntaxique. Comme elle utilise le Lua de LuaLaTeX, 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| (sauf lorsque +la clé |write| est utilisée). La compilation est très rapide puisque tout le travail du +parseur est fait par la librairie LPEG, écrite en C. -\bigskip +\medskip Voici un exemple de code Python composé avec l'environnement |{Piton}| proposé par \pkg{piton}. -\bigskip +\medskip \begin{Piton} from math import pi @@ -148,41 +155,45 @@ def arctan(x,n=10:int): return s \end{Piton} -\bigskip -Les principaux concurrents de l'extension \pkg{piton} sont certainement les extensions bien connues \pkg{listings} -et \pkg{minted}. +\medskip +Les principaux concurrents de l'extension \pkg{piton} sont certainement les extensions +bien connues \pkg{listings} et \pkg{minted}. -\bigskip -Le nom de cette extension (\pkg{piton}) a été choisi un peu arbitrairement en référence aux pitons d'alpinisme qui -servent à gravir les montagnes. + +% \medskip +% Le nom de cette extension (\pkg{piton}) a été choisi un peu arbitrairement en référence +% aux pitons d'alpinisme qui servent à gravir les montagnes. \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, de préférence dans une arborescence |texmf|. Le mieux reste néanmoins +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, de préférence 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} -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. +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. \subsection{Choix du langage} Les langages informatiques pris en charge par \pkg{piton} se classent en deux catégories : \begin{itemize} -\item les langages reconnus nativement par \pkg{piton} qui sont au nombre de cinq : Python, OCaml, SQL, C (ou -plutôt \CC) et un langage nommé |minimal|\footnote{Le langage |minimal| peut servir pour formater du pseudo-code - : cf.~p.~\pageref{minimal}.} ; +\item les langages reconnus nativement par \pkg{piton} qui sont au nombre de cinq : +Python, OCaml, SQL, C (ou plutôt \CC) et deux langages minimalistes nommés |minimal|\footnote{Le langage + |minimal| peut servir pour formater du pseudo-code : cf.~p.~\pageref{minimal}.} et +|verbatim|; \item les langages définis par l'utilisateur avec la commande |\NewPitonLanguage| décrite -p.~\pageref{NewPitonLanguage} (les parseurs de ces langages ne pourront jamais être aussi précis que ceux proposés -nativement par \pkg{piton)}. +p.~\pageref{NewPitonLanguage} (les parseurs de ces langages ne pourront jamais être aussi +précis que ceux proposés nativement par \pkg{piton)}. \end{itemize} @@ -191,21 +202,22 @@ Par défaut, le langage est Python. \smallskip \index{language (clé)} -On peut changer de langage avec la clé |language| de |\PitonOptions| : +On peut changer de langage avec la clé \Definition{language} de |\PitonOptions| : \smallskip |\PitonOptions{language = OCaml}| \smallskip -En fait, le nom des langages, pour \pkg{piton}, est toujours \textbf{insensible à la casse}. Dans cet exemple, on -aurait tout aussi bien pu écrire |Ocaml| ou |ocaml|. +En fait, le nom des langages, pour \pkg{piton}, est toujours \textbf{insensible à la + casse}. Dans cet exemple, on aurait tout aussi bien pu écrire |Ocaml| ou |ocaml|. \smallskip -Pour les développeurs, précisons que le nom du langage courant est stocké (en minuscules) dans la variable publique -L3 nommée |\l_piton_language_str|. +Pour les développeurs, précisons que le nom du langage courant est stocké (en minuscules) +dans la variable publique L3 nommée |\l_piton_language_str|. \smallskip -Dans la suite de ce document, on parlera de Python mais les fonctionnalités s'appliquent aussi aux autres langages. +Dans la suite de ce document, on parlera préférentiellement de Python mais les +fonctionnalités s'appliquent aussi aux autres langages. @@ -215,21 +227,21 @@ Dans la suite de ce document, on parlera de Python mais les fonctionnalités s'a L'extension \pkg{piton} se charge simplement avec |\usepackage{piton}|. \smallskip -Si, à la fin du prambule, l'extension \pkg{xcolor} n'a pas été chargée (par l'utilisateur ou par une extension -chargée dans le préambule), \pkg{piton} charge l'extension \pkg{xcolor} avec |\usepackage{xcolor}|, c'est-à-dire -sans aucune option. L'extension \pkg{piton} ne charge pas d'autre extension. Elle n'utilise pas de programme -extérieur. +Si, à la fin du prambule, l'extension \pkg{xcolor} n'a pas été chargée (par l'utilisateur +ou par une extension chargée dans le préambule), \pkg{piton} charge l'extension +\pkg{xcolor} avec |\usepackage{xcolor}|, c'est-à-dire sans aucune option. L'extension +\pkg{piton} ne charge pas d'autre extension. Elle n'utilise pas de programme extérieur. \subsection{Les commandes et environnements à la disposition de l'utilisateur} \indexenv{Piton} -L'extension \pkg{piton} fournit plusieurs outils pour composer du code Python: les commandes |\piton|, -l'environnement |{Piton}| et la commande |\PitonInputFile|. +L'extension \pkg{piton} fournit plusieurs outils pour composer du code informatique : 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 : +\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} @@ -237,27 +249,16 @@ paragraphe. Par exemple : 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 \DefinitionCommand{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 externe. - -Il est possible de n'insérer qu'une partie de ce fichier : cf. partie~\ref{part-of-a-file}, -p.~\pageref{part-of-a-file}. - -La clé \Definition{path} de la commande |\PitonOptions| permet de spécifier une \emph{liste} de chemins où sera -recherché le fichier à inclure (dans cette liste, les chemins sont séparés par des virgules). - -L'extension \pkg{piton} propose aussi des commandes \colorbox{gray!20}{\ttfamily\textbackslash PitonInputFileT}, -\colorbox{gray!20}{\ttfamily \textbackslash PitonInputFileF} et -\colorbox{gray!20}{\ttfamily \textbackslash PitonInputFileTF} avec des arguments correspondant aux lettres |T| et -|F|, arguments qui seront executés dans le -cas où le fichier a été trouvé (lettre |T|) ou pas (lettre |F|). +\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 \DefinitionCommand{NewPitonEnvironment} : +cf.~partie~\ref{NewPitonEnvironment} p.~\pageref{NewPitonEnvironment}. +\item La commande \DefinitionCommand{PitonInputFile} doit être utilisée pour insérer et +composer un fichier externe : cf.~partie~\ref{PitonInputFile}, +p.~\pageref{PitonInputFile}. \end{itemize} @@ -265,19 +266,23 @@ cas où le fichier a été trouvé (lettre |T|) ou pas (lettre |F|). \indexcommand{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. +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 -Quand son argument est donné entre accolades, la commande |\piton| ne prend pas son argument en mode verbatim. Les -points suivants doivent être remarqués : +Quand son argument est donné entre accolades, la commande |\piton| ne prend \emph{pas} son +argument en mode verbatim. Les points suivants doivent être remarqués : \begin{itemize} -\item plusieurs espaces successives sont remplacées par une unique espace, ainsi que les retours à la ligne +\item plusieurs espaces successives sont remplacées par une unique espace, ainsi que les +retours à la ligne {\color{cyan} mais la commande |\|␣ est fournie pour forcer l'insertion d'une espace} ; @@ -287,11 +292,12 @@ points suivants doivent être remarqués : \item les accolades doivent apparaître par paires correctement imbriquées, -{\color{cyan} mais les commandes |\{| et |\}| sont aussi fournies pour insérer des accolades individuelles} ; +{\color{cyan} mais les commandes |\{| et |\}| sont aussi fournies pour insérer des + accolades individuelles} ; -\item les commandes LaTeX\footnote{Cela s'applique aux commandes commençant par une contre-oblique |\| mais - également aux caractères actifs, c'est-à-dire ceux de catcode~13.} sont complètement développées sans être -exécutées +\item les commandes LaTeX\footnote{Cela s'applique aux commandes commençant par une + contre-oblique |\| mais également aux caractères actifs, c'est-à-dire ceux de + catcode~13.} sont complètement développées sans être exécutées {\color{cyan} et on peut donc utiliser |\\| pour insérer une contre-oblique}. \end{itemize} @@ -316,16 +322,20 @@ et |@|) doivent être insérés sans contre-oblique. \end{tabular} \bigskip -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 +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'}.} +En revanche, comme son argument subit un développement (au sens de TeX), il faut prendre +soin à ne pas utiliser dans son argument de commandes fragiles (c'est-à-dire des commandes +qui ne sont ni \emph{protected} ni \emph{fully expandable}). + \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. +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 \begin{tabular}{>{\color{gray}}w{l}{75mm}@{\hspace*{1cm}}l} @@ -347,85 +357,114 @@ autre fonction. \section{Personnalisation} -Concernant la fonte de caractères utilisée dans les listings produits par l'extension \pkg{piton}, il s'agit -simplement de la fonte mono-chasse courante (\pkg{piton} utilise simplement en interne la commande LaTeX standard -|\ttfamily|). Pour la changer, le mieux est d'utiliser |\setmonofont| de \pkg{fontspec}. \subsection{Les clés de la commande \textbackslash PitonOptions} \indexcommand{PitonOptions} -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.} +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.} -Ces clés peuvent aussi être appliquées à un environnement |{Piton}| individuel (entre crochets). +Ces clés peuvent aussi être appliquées à un environnement |{Piton}| individuel (entre +crochets). \begin{itemize} -\item La clé \Definition{language} spécifie le langage informatique considéré (la casse n'est pas prise en compte). -Cinq valeurs sont possibles : |Python|, |OCaml|, |C|, |SQL| et |minimal|. La valeur initiale est |Python|. - -\item \index{path} La clé \Definition{path} indique un chemin où seront cherchés les fichiers inclus par -|\PitonInputFile|. - -\item \index{gobble}\label{gobble} 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 \index{auto-gobble}\index{gobble!auto-gobble} 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 \index{env-gobble}\index{gobble!env-gobble} 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 \index{write} La clé \Definition{write} prend en argument un nom de fichier (avec l'extension) et écrit le -contenu\footnote{En fait, il ne s'agit pas exactement du contenu de l'environnement mais de la valeur renvoyée par - l'instruction Lua - |piton.get_last_code()| qui en est une version sans les surcharges de formatage LaTeX (voir la partie \ref{API}, p.~\pageref{API}).} de l'environnement courant dans ce fichier. À la première utilisation du fichier par \pkg{piton}, celui-ci -est effacé. - -\item \index{path-write} La clé \Definition{path-write} indique un chemin où seront écrits les fichiers écrits par -l'emploi de la clé |write| précédente. - -\item \index{line-numbers} La clé \Definition{line-numbers} active la numérotation des lignes (en débordement à -gauche) dans les environnements |{Piton}| et dans les listings produits par la commande |\PitonInputFile|. +\item La clé \Definition{language} spécifie le langage informatique considéré (la casse +n'est pas prise en compte). On peut choisir l'un des six langages prédéfinis (|Python|, +|OCaml|, |C|, |SQL|, |minimal| et |verbatim|) ou bien le nom d'un langage défini par +l'utilisateur avec |\NewPitonLanguage| (voir partie~\ref{NewPitonLanguage}, +p.~\pageref{NewPitonLanguage}). + +La valeur initiale est |Python|. + +\item \index{font-command} +\colorbox{yellow!50}{\textbf{Nouveau 4.0}}\par\nobreak + +La clé \Definition{font-command} contient des instructions de fonte qui seront +insérées au début de chaque élément formaté par \pkg{piton}, que ce soit avec la commande +|\piton|, l'environnement |{Piton}| ou bien la commande |\PitonInputFile| (il n'y a que +les «commentaires LaTeX» pour lesquels ces instructions de fonte ne sont pas utilisées). + +La valeur initiale de ce paramètre |font-command| est |\ttfamily|, ce qui fait, que, par +défaut, \pkg{piton} utilise la fonte mono-chasse courante. + +\item \index{gobble}\label{gobble} 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 \index{auto-gobble}\index{gobble!auto-gobble} 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 \index{env-gobble}\index{gobble!env-gobble} 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 \index{write} La clé \Definition{write} prend en argument un nom de fichier (avec +l'extension) et écrit le contenu\footnote{En fait, il ne s'agit pas exactement du contenu + de l'environnement mais de la valeur renvoyée par l'instruction Lua + |piton.get_last_code()| qui en est une version sans les surcharges de formatage LaTeX + (voir la partie \ref{API}, p.~\pageref{API}).} de l'environnement courant dans ce +fichier. À la première utilisation du fichier par \pkg{piton}, celui-ci est effacé. + +{\bfseries Cette clé nécessite une compilation avec {\ttfamily lualatex -shell-escape}}. + +\item \index{path-write} La clé \Definition{path-write} indique un chemin où seront écrits +les fichiers écrits par l'emploi de la clé |write| précédente. + +\item \index{line-numbers} La clé \Definition{line-numbers} active la numérotation des +lignes (en débordement à gauche) dans les environnements |{Piton}| et dans les listings +produits par la commande |\PitonInputFile|. Cette clé propose en fait plusieurs sous-clés. \begin{itemize} -\item La clé \Definition{line-numbers/skip-empty-lines} demande que les lignes vides (qui ne contiennent que des -espaces) soient considérées comme non existantes en ce qui concerne la numérotation des lignes (si la clé -|/absolute|, décrite plus bas, est active, la clé |/skip-empty-lines| n'a pas d'effet dans |\PitonInputFile|). La -valeur initiale de cette clé est |true| (et non |false|).\footnote{Avec le langage Python, les lignes vides des \emph{docstrings} sont - prises en compte.} - -\item La clé \Definition{line-numbers/label-empty-lines} demande que les labels (c'est-à-dire les numéros) des -lignes vides soient affichés. Si la clé |/skip-empty-lines| est active, la clé |/label-empty-lines| est sans effet. -La valeur initiale de cette clé est |true|.\footnote{Quand la clé |split-on-empty-lines| est activée, les labels des +\item La clé \Definition{line-numbers/skip-empty-lines} demande que les lignes vides (qui +ne contiennent que des espaces) soient considérées comme non existantes en ce qui concerne +la numérotation des lignes (si la clé |/absolute|, décrite plus bas, est active, la clé +|/skip-empty-lines| n'a pas d'effet dans |\PitonInputFile|). La valeur initiale de cette +clé est |true| (et non |false|).\footnote{Avec le langage Python, les lignes vides des + \emph{docstrings} sont prises en compte.} + +\item La clé \Definition{line-numbers/label-empty-lines} demande que les labels +(c'est-à-dire les numéros) des lignes vides soient affichés. Si la clé |/skip-empty-lines| +est active, la clé |/label-empty-lines| est sans effet. La valeur initiale de cette clé +est |true|.\footnote{Quand la clé |split-on-empty-lines| est activée, les labels des lignes vides ne sont jamais imprimés.} -\item La clé \Definition{line-numbers/absolute} demande, pour les listings générés par |\PitonInputFile|, que les -numéros de lignes affichés soient absolus (c'est-à-dire ceux du fichier d'origine). Elle n'a d'intérêt que si on -n'insère qu'une partie du fichier (cf. partie~\ref{part-of-a-file}, p.~\pageref{part-of-a-file}). La clé -|/absolute| est sans effet dans les environnements |{Piton}|. +\item La clé \Definition{line-numbers/absolute} demande, pour les listings générés par +|\PitonInputFile|, que les numéros de lignes affichés soient absolus (c'est-à-dire ceux du +fichier d'origine). Elle n'a d'intérêt que si on n'insère qu'une partie du fichier (cf. +partie~\ref{part-of-a-file}, p.~\pageref{part-of-a-file}). La clé |/absolute| est sans +effet dans les environnements |{Piton}|. + +\item La clé \Definition{line-numbers/resume} reprend la numérotation là où elle avait été +laissée au dernier listing. En fait, la clé |line-numbers/resume| a un alias, qui est +|resume| tout court (car on peut être amené à l'utiliser souvent). + +\item La clé \Definition{line-numbers/start} impose que la numérotation commence à ce +numéro. -\item La clé \Definition{line-numbers/resume} reprend la numérotation là où elle avait été laissée au dernier -listing. En fait, la clé |line-numbers/resume| a un alias, qui est |resume| tout court (car on peut être amené à -l'utiliser souvent). +\item La clé \Definition{line-numbers/sep} est la distance horizontale entre les numéros +de lignes (insérés par |line-numbers|) et les lignes du code informatique. La valeur +initiale est 0.7~em. -\item La clé \Definition{line-numbers/start} impose que la numérotation commence à ce numéro. +\item La clé \Definition{line-numbers/format} est une liste de tokens qui est insérée +avant le numéro de ligne pour le formater. Il est possible de mettre \emph{en dernière + position} de cette liste une commande LaTeX à un argument comme |\fbox|. -\item La clé \Definition{line-numbers/sep} est la distance horizontale entre les numéros de lignes (insérés par -|line-numbers|) et les lignes du code informatique. La valeur initiale est 0.7~em. +La valeur initiale est |\footnotesize \color{gray}|. \end{itemize} -Pour la commodité, un dispositif de factorisation du préfixe |line-numbers| est disponible, c'est-à-dire que l'on -peut écrire : +Pour la commodité, un dispositif de factorisation du préfixe |line-numbers| est +disponible, c'est-à-dire que l'on peut écrire : \begin{Verbatim} \PitonOptions @@ -434,64 +473,79 @@ peut écrire : { skip-empty-lines = false , label-empty-lines = false , - sep = 1 em + sep = 1 em , + format = \footnotesize \color{blue} } } \end{Verbatim} -\item \index{left-margin} La clé \Definition{left-margin} fixe une marge sur la gauche. Cette clé peut être utile, en particulier, en -conjonction avec la clé |line-numbers| si on ne souhaite pas que les numéros de ligne soient dans une position en -débordement sur la gauche. +\item \index{left-margin} La clé \Definition{left-margin} fixe une marge sur la gauche. +Cette clé peut être utile, en particulier, en conjonction avec la clé |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 la clé |line-numbers| est utilisée. Voir un exemple à la -partie \ref{example-numbering} p.~\pageref{example-numbering}. +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 la clé +|line-numbers| est utilisée. Voir un exemple à la partie \ref{example-numbering} +p.~\pageref{example-numbering}. -\item \index{background-color} La clé \Definition{background-color} fixe la couleur de fond des environnements |{Piton}| et des listings -produits par |\PitonInputFile| (ce fond a une largeur que l'on peut fixer avec la clé |width| décrite ci-dessous). -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 \index{background-color} La clé \Definition{background-color} fixe la couleur de +fond des environnements |{Piton}| et des listings produits par |\PitonInputFile| (ce fond +a une largeur que l'on peut fixer avec la clé |width| décrite ci-dessous). 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}| \smallskip -La clé |background-color| accepte aussi en argument une \emph{liste} de couleurs. Les lignes sont alors coloriées -de manière cyclique avec ces couleurs. +La clé |background-color| accepte aussi en argument une \emph{liste} de couleurs. Les +lignes sont alors coloriées de manière cyclique avec ces couleurs. \emph{Exemple} : |\PitonOptions{background-color = {gray!5,white}}| -\item \index{prompt-background-color} 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-eval-print loop}). Pour un exemple d'utilisation de cette clé, voir la partie \ref{pythonrepl} -p.~\pageref{pythonrepl}. - -\item \index{width} La clé \Definition{width} fixe la largeur du listing produit. Cette largeur s'applique aux fonds colorés -spécifiés par les clés |background-color| et |prompt-background-color| et également quand une coupure automatique -des lignes est demandée par |break-lines| (cf.~\ref{line-breaks}, p.~\pageref{line-breaks}). - -Cette clé peut prendre comme valeur une longueur explicite mais aussi la valeur spéciale~|min|. Avec cette valeur, -la largeur sera calculée à partir de la largeur maximale des lignes de code. Attention : l'usage de cette valeur -spéciale~|min| requiert deux compilations LuaLaTeX\footnote{La largeur maximale est calculée lors de la première -compilation, écrite sur le fichier~|aux|, puis réutilisée lors de la compilation suivante. Certains outils comme -|latexmk| (utilisé par Overleaf) effectuent automatiquement un nombre suffisant de compilations.}. - -Pour un exemple d'utilisation de |width=min|, voir la partie~\ref{example-comments} sur les exemples, p.~\pageref{example-comments}. - -\item \index{show-spaces-in-strings} En activant la clé \Definition{show-spaces-in-strings}, les espaces dans les -chaînes de caractères\footnote{Pour le language Python, cela ne s'applique que pour les chaînes courtes, c'est-à-dire -celles délimitées par~\verb|'| ou~\verb|"|. En OCaml, cela ne s'applique pas pour les \emph{quoted strings}.} 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 + +\item \index{prompt-background-color} 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-eval-print loop}). Pour un exemple d'utilisation de cette clé, voir la partie +\ref{pythonrepl} p.~\pageref{pythonrepl}. + +\item \index{width} La clé \Definition{width} fixe la largeur du listing produit. Cette +largeur s'applique aux fonds colorés spécifiés par les clés |background-color| et +|prompt-background-color| et également quand une coupure automatique des lignes est +demandée par |break-lines| (cf.~\ref{line-breaks}, p.~\pageref{line-breaks}). + +Cette clé peut prendre comme valeur une longueur explicite mais aussi la valeur +spéciale~|min|. Avec cette valeur, la largeur sera calculée à partir de la largeur +maximale des lignes de code. Attention : l'usage de cette valeur spéciale~|min| requiert +deux compilations LuaLaTeX\footnote{La largeur maximale est calculée lors de la première + compilation, écrite sur le fichier~|aux|, puis réutilisée lors de la compilation + suivante. Certains outils comme |latexmk| (utilisé par Overleaf) effectuent + automatiquement un nombre suffisant de compilations.}. + +Pour un exemple d'utilisation de |width=min|, voir la partie~\ref{example-comments} sur +les exemples, p.~\pageref{example-comments}. + +\item \index{show-spaces-in-strings} En activant la clé +\Definition{show-spaces-in-strings}, les espaces dans les chaînes de +caractères\footnote{Pour le language Python, cela ne s'applique que pour les chaînes + courtes, c'est-à-dire celles délimitées par~\verb|'| ou~\verb|"|. En OCaml, cela ne + s'applique pas pour les \emph{quoted strings}.} 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{La valeur initial de |font-command| est |\ttfamily| + ce qui fait que, par défaut, l'extension \pkg{piton} utilise simplement la fonte + mono-chasse courante.}\par\nobreak % \begingroup \PitonOptions{show-spaces-in-strings} Exemple : \piton{my_string = 'Très bonne réponse'} \endgroup -\item \index{show-spaces} 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|\footnote{cf. - \ref{line-breaks} p.~\pageref{line-breaks}.} est active). Il faut néanmoins remarquer que les espaces en fin de -ligne sont tous supprimés par \pkg{piton}. Les tabulations de début de ligne sont représentées par des flèches. +\item \index{show-spaces} 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|\footnote{cf. \ref{line-breaks} + p.~\pageref{line-breaks}.} est active). Il faut néanmoins remarquer que les espaces en +fin de ligne sont tous supprimés par \pkg{piton}. Les tabulations de début de ligne sont +représentées par des flèches. \end{itemize} \bigskip @@ -516,7 +570,7 @@ ligne sont tous supprimés par \pkg{piton}. Les tabulations de début de ligne s if (!swapped) break; } } -\end{Piton} +~emphase&\end{Piton}@ \end{Verbatim} \endgroup @@ -544,8 +598,9 @@ ligne sont tous supprimés par \pkg{piton}. Les tabulations de début de ligne s \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}). +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} @@ -555,93 +610,102 @@ pages et des lignes p.~\pageref{breakable}). \subsubsection{Notion de style} -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.} +L'extension \pkg{piton} fournit la commande |\SetPitonStyle| pour personnaliser les +différents styles utilisés pour formater les éléments syntaxiques des listings +informatiques. 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 -\indexcommand{SetPitonStyle} -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. +\indexcommand{SetPitonStyle} 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. +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|). Elle utilise la commande |\highLight| de \pkg{lua-ul} (qui nécessite -lui-même le chargement de \pkg{luacolor}). +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|). Elle utilise la commande +|\highLight| de \pkg{lua-ul} (qui nécessite lui-même le chargement de \pkg{luacolor}). \begin{Verbatim} \SetPitonStyle - { Name.Function = \bfseries \hightLight[red!50] } + { Name.Function = \bfseries \hightLight[red!30] } \end{Verbatim} -Ici, |\highLight[red!50]| doit être considéré comme le nom d'une fonction LaTeX qui prend exactement un argument, -puisque, habituellement, elle est utilisée avec |\highLight[red!50]{|\texttt{\slshape text}|}|. +Ici, |\highLight[red!30]| doit être considéré comme le nom d'une fonction LaTeX qui prend +exactement un argument, puisque, habituellement, elle est utilisée avec +|\highLight[red!30]{|\texttt{\slshape text}|}|. \medskip \begingroup \SetPitonStyle - { Name.Function = \bfseries \highLight[red!50] } + { Name.Function = \bfseries \highLight[red!30] } Avec ce réglage, on obtient : \piton{def cube(x) : return x * x * x } \endgroup \bigskip -L'usage des différents styles suivant le langage informatique considéré est décrit dans la partie \ref{Semantic}, à -partir de la page \pageref{Semantic}. +L'usage des différents styles suivant le langage informatique considéré est décrit dans la +partie \ref{Semantic}, à partir de la page \pageref{Semantic}. \bigskip -\indexcommand{PitonStyle} -La commande \DefinitionCommand{PitonStyle} prend en argument le nom d'un style et permet de récupérer la valeur (en -tant que liste d'instructions LaTeX) de ce style. +\indexcommand{PitonStyle} La commande \DefinitionCommand{PitonStyle} prend en argument le +nom d'un style et permet de récupérer la valeur (en tant que liste d'instructions LaTeX) +de ce style. \smallskip -Par exemple, on peut écrire, dans le texte courant, |{\PitonStyle{Keyword}{function}}| et on aura -le mot {\PitonStyle{Keyword}{function}} formaté comme un mot-clé. +Par exemple, on peut écrire, dans le texte courant, |{\PitonStyle{Keyword}{function}}| et +on aura le mot {\PitonStyle{Keyword}{function}} formaté comme un mot-clé. \smallskip -La syntaxe |{\PitonStyle{|\textsl{\texttt{style}}|}{...}}| est nécessaire pour pouvoir tenir compte à la fois des commandes -semi-globales et des commandes à argument présentes dans la valeur courante du style \texttt{\textsl{style}}. +La syntaxe |{\PitonStyle{|\textsl{\texttt{style}}|}{...}}| est nécessaire pour pouvoir +tenir compte à la fois des commandes semi-globales et des commandes à argument présentes +dans la valeur courante du style \texttt{\textsl{style}}. \subsubsection{Styles locaux et globaux} -Un style peut être défini de manière globale avec la commande |\SetPitonStyle|. Cela veut dire qu'il s'appliquera -par défaut à tous les langages informatiques qui utilisent ce style. +Un style peut être défini de manière globale avec la commande |\SetPitonStyle|. Cela veut +dire qu'il s'appliquera par défaut à tous les langages informatiques qui utilisent ce +style. \medskip Par exemple, avec la commande \begin{Verbatim} \SetPitonStyle{Comment = \color{gray}} \end{Verbatim} -tous les commentaires (que ce soit en Python, en C, en OCaml, etc. ou dans un langage défini avec -|\NewPitonLanguage|) seront composés en gris. +tous les commentaires (que ce soit en Python, en C, en OCaml, etc. ou dans un langage +défini avec |\NewPitonLanguage|) seront composés en gris. \bigskip -Mais il est aussi possible de définir un style localement pour un certain langage informatique en passant le nom du -langage en argument optionnel (entre crochets) de la commande |\SetPitonStyle|.\footnote{On rappelle que, dans - \pkg{piton}, les noms des langages informatiques ne sont pas sensibles à la casse.} +Mais il est aussi possible de définir un style localement pour un certain langage +informatique en passant le nom du langage en argument optionnel (entre crochets) de la +commande |\SetPitonStyle|.\footnote{On rappelle que, dans \pkg{piton}, les noms des + langages informatiques ne sont pas sensibles à la casse.} \medskip Par exemple, avec la commande \begin{Verbatim} -\SetPitonStyle~emphase#[SQL]@{Keywords = \color[HTML]{006699} \bfseries \MakeUppercase} +\SetPitonStyle~emphase#[SQL]@{Keyword = \color[HTML]{006699} \bfseries \MakeUppercase} \end{Verbatim} -les mots-clés dans les listings SQL seront composés en lettres capitales, même s'ils s'apparaissent en minuscules -dans le fichier source LaTeX (on rappelle que, en SQL, les mot-clés ne sont pas sensibles à la casse et donc forcer -leur mise en capitales peut être envisagé). +les mots-clés dans les listings SQL seront composés en lettres capitales, même s'ils +s'apparaissent en minuscules dans le fichier source LaTeX (on rappelle que, en SQL, les +mot-clés ne sont pas sensibles à la casse et donc forcer leur mise en capitales peut être +envisagé). \medskip -Comme on s'en doute, si un langage informatique utilise un certain style et que ce style n'est pas défini -localement pour ce langage, c'est la version globale qui est utilisée. Cette notion de globalité n'a pas de -rapport avec la notion de liaison locale de TeX (notion de groupe TeX).\footnote{Du point de vue des groupes de - TeX, les liaisons faites par |\SetPitonStyle| sont toujours locales.} +Comme on s'en doute, si un langage informatique utilise un certain style et que ce style +n'est pas défini localement pour ce langage, c'est la version globale qui est utilisée. +Cette notion de globalité n'a pas de rapport avec la notion de liaison locale de TeX +(notion de groupe TeX).\footnote{Du point de vue des groupes de TeX, les liaisons faites + par |\SetPitonStyle| sont toujours locales.} \medskip Les styles fournis par défaut par \pkg{piton} sont tous définis globalement. @@ -652,16 +716,22 @@ Les styles fournis par défaut par \pkg{piton} sont tous définis globalement. \index{UserFunction (style)} \bigskip -Il existe un style spécial nommé |UserFunction|. Ce style s'applique aux noms des fonctions précédemment définies -par l'utilisateur (par exemple, avec le langage Python, ces noms de fonctions sont ceux qui apparaissent après le -mot-clé \piton{def} dans un listing Python précédent). La valeur initiale de ce style est nulle (=vide), ce qui -fait que ces noms de fonctions sont formatés comme du texte courant (en noir). Néanmoins, il est possible de -changer la valeur de ce style, comme tous les autres styles, avec la commande |\SetPitonStyle|. +Il existe un style spécial nommé |UserFunction|. Ce style s'applique aux noms des +fonctions précédemment définies par l'utilisateur (par exemple, avec le langage Python, +ces noms de fonctions sont ceux qui apparaissent après le mot-clé \piton{def} dans un +listing Python précédent). La valeur initiale de ce style est |\PitonStyle{Identifier}|, +ce qui fait que ces noms de fonctions sont formatés comme les autres identificateurs +(c'est-à-dire, par défaut, sans formatage particulier, si ce n'est celui donné par +|font-command|). + +Néanmoins, il est possible de changer la valeur de ce style, comme tous les autres styles, +avec la commande |\SetPitonStyle|. \medskip -Dans l'exemple suivant, on règle les styles |Name.Function| et |UserFunction| de manière à ce que, quand on clique -sur le nom d'une fonction Python précédemment définie par l'utilisateur, on soit renvoyé vers la définition -(informatique) de cette fonction. Cette programmation utilise les fonctions |\hypertarget| et |\hyperlink| de \pkg{hyperref}. +Dans l'exemple suivant, on règle les styles |Name.Function| et |UserFunction| de manière à +ce que, quand on clique sur le nom d'une fonction Python précédemment définie par +l'utilisateur, on soit renvoyé vers la définition (informatique) de cette fonction. Cette +programmation utilise les fonctions |\hypertarget| et |\hyperlink| de \pkg{hyperref}. \begingroup @@ -698,7 +768,8 @@ def passe(v): \end{Piton} \medskip -(Certains lecteurs de \textsc{pdf} affichent un cadre autour du mot |transpose| cliquable et d'autres non.) +(Certains lecteurs de \textsc{pdf} affichent un cadre autour du mot |transpose| cliquable +et d'autres non.) \endgroup @@ -707,12 +778,14 @@ def passe(v): \bigskip \begin{small} -Bien sûr, la liste des noms de fonctions Python précédemment définies est gardée en mémoire de LuaLaTeX (de manière -globale, c'est-à-dire indépendamment des groupes TeX). L'extension \pkg{piton} fournit une commande qui permet de -vider cette liste : c'est la commande \DefinitionCommand{PitonClearUserFunctions}. Quand elle est utilisée sans argument, cette -commande s'applique à tous les langages informatiques utilisées par l'utilisateur mais on peut spécifier en -argument optionnel (entre crochets) une liste de langages informatiques auxquels elle s'appliquera.\footnote{On - rappelle que, dans \pkg{piton}, les noms des langages informatiques ne sont pas sensibles à la casse. } +Bien sûr, la liste des noms de fonctions Python précédemment définies est gardée en +mémoire de LuaLaTeX (de manière globale, c'est-à-dire indépendamment des groupes TeX). +L'extension \pkg{piton} fournit une commande qui permet de vider cette liste : c'est la +commande \DefinitionCommand{PitonClearUserFunctions}. Quand elle est utilisée sans +argument, cette commande s'applique à tous les langages informatiques utilisées par +l'utilisateur mais on peut spécifier en argument optionnel (entre crochets) une liste de +langages informatiques auxquels elle s'appliquera.\footnote{On rappelle que, dans + \pkg{piton}, les noms des langages informatiques ne sont pas sensibles à la casse. } \end{small} @@ -722,24 +795,26 @@ argument optionnel (entre crochets) une liste de langages informatiques auxquels \label{NewPitonEnvironment} \indexcommand{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| (de LaTeX standard) et |\NewDocumentEnvironment| (de -LaTeX3). +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| (de LaTeX standard) et |\NewDocumentEnvironment| (de LaTeX3). -C'est pourquoi \pkg{piton} propose une commande |\NewPitonEnvironment|. Cette commande a la même syntaxe que la -commande classique |\NewDocumentEnvironment|.\footnote{Néanmoins, le spécificateur d'argument~|b|, qui sert à +C'est pourquoi \pkg{piton} propose une commande \DefinitionCommand{NewPitonEnvironment}. +Cette commande a la même syntaxe que la commande classique +|\NewDocumentEnvironment|.\footnote{Néanmoins, le spécificateur d'argument~|b|, qui sert à capter le corps de l'environnement comme un argument LaTeX, n'est pas autorisé.} \bigskip -Par exemple, avec l'instruction suivante, un nouvel environnement |{Python}| sera défini avec le même comportement -que l'environnement |{Piton}|: +Par exemple, avec l'instruction suivante, un nouvel environnement |{Python}| sera défini +avec le même comportement que l'environnement |{Piton}|: {\color{gray}|\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 (à condition, bien entendu, d'avoir chargé l'extension \pkg{tcolorbox}): +Si on souhaite un environnement |{Python}| qui compose le code inclus dans une boîte de +\pkg{tcolorbox}, on peut écrire (à condition, bien entendu, d'avoir chargé l'extension +\pkg{tcolorbox}): \begin{Verbatim} \NewPitonEnvironment{Python}{} @@ -774,27 +849,29 @@ def carré(x): \label{NewPitonLanguage} \index{listings@\pkg{listings} (extension)} -\colorbox{yellow!50}{\textbf{Nouveau 3.0}} - \medskip L'extension \pkg{listings} est une célèbre extension LaTeX pour formater des codes informatiques. \medskip -Elle propose une commande |\lstdefinelanguage| pour définir de nouveaux langages. Cette commande est aussi -utilisée en interne par \pkg{listings} pour sa définition des languages (en fait, pour cela, \pkg{listings} utilise -une commande nommée |\lst@definelanguage| mais celle-ci a la même syntaxe que |\lstdefinelanguage|). +Elle propose une commande |\lstdefinelanguage| pour définir de nouveaux langages. Cette +commande est aussi utilisée en interne par \pkg{listings} pour sa définition des languages +(en fait, pour cela, \pkg{listings} utilise une commande nommée |\lst@definelanguage| mais +celle-ci a la même syntaxe que |\lstdefinelanguage|). \medskip -L'extension \pkg{piton} propose une commande \DefinitionCommand{NewPitonLanguage} pour définir de nouveaux -langages (utilisables avec les outils de \pkg{piton}) avec quasiment la même syntaxe que |\lstdefinelanguage|. +L'extension \pkg{piton} propose une commande \DefinitionCommand{NewPitonLanguage} pour +définir de nouveaux langages (utilisables avec les outils de \pkg{piton}) avec quasiment +la même syntaxe que |\lstdefinelanguage|. \medskip -Précisons tout de suite que l'extension \pkg{piton} n'utilise \emph{pas} cette commande pour définir les langages -qu'elle propose nativement (Python, C, OCaml, \CC\ et |minimal|), ce qui permet de proposer des parseurs plus puissants. +Précisons tout de suite que l'extension \pkg{piton} n'utilise \emph{pas} cette commande +pour définir les langages qu'elle propose nativement (Python, C, OCaml, SQL, |minimal| et +|verbatim|), ce qui permet de proposer des parseurs plus puissants. \medskip -Par exemple, dans le fichier |lstlang1.sty|, qui est un des fichiers de definition des langages proposés par défaut -par \pkg{listings}, on trouve les instructions suivantes (dans la version 1.10a). +Par exemple, dans le fichier |lstlang1.sty|, qui est un des fichiers de definition des +langages proposés par défaut par \pkg{listings}, on trouve les instructions suivantes +(dans la version 1.10a). \begin{Verbatim}[formatcom=\small\color{gray}] \lst~@definelanguage{Java}% @@ -813,9 +890,10 @@ par \pkg{listings}, on trouve les instructions suivantes (dans la version 1.10a) \end{Verbatim} \medskip -Pour définir un language nommé |Java| pour \pkg{piton}, il suffit d'écrire le code suivant, -{\bfseries où le dernier argument de |\lst@definelanguage|, qui est entre crochets, a été supprimé} -(en fait, les symboles \verb+%+ pourraient être supprimés sans problème). +Pour définir un language nommé |Java| pour \pkg{piton}, il suffit d'écrire le code +suivant, {\bfseries où le dernier argument de |\lst@definelanguage|, qui est entre + crochets, a été supprimé} (en fait, les symboles \verb+%+ pourraient être supprimés sans +problème). \begin{Verbatim}[formatcom=\small\color{gray}] ~emphase#\NewPitonLanguage@{Java}% @@ -850,16 +928,18 @@ Pour définir un language nommé |Java| pour \pkg{piton}, il suffit d'écrire le \medskip -On peut alors utiliser le language Java comme n'importe quel autre langage prédéfini de \pkg{piton}. +On peut alors utiliser le language Java comme n'importe quel autre langage prédéfini de +\pkg{piton}. -Voici un exemple de code Java formaté dans un environnement~|{Piton}| avec la clé~|language=Java|.\footnote{On - rappelle que, pour \pkg{piton}, les noms de langages informatiques ne sont pas sensibles à la casse, ce qui fait - que l'on aurait pu aussi bien utiliser : |language=java|.} +Voici un exemple de code Java formaté dans un environnement~|{Piton}| avec la +clé~|language=Java|.\footnote{On rappelle que, pour \pkg{piton}, les noms de langages + informatiques ne sont pas sensibles à la casse, ce qui fait que l'on aurait pu aussi + bien utiliser : |language=java|.} \bigskip \begingroup \small -\PitonOptions{split-on-empty-lines} +\PitonOptions{splittable-on-empty-lines} \begin{Piton}[language = Java] public class Cipher { // cryptage par le chiffre de César public static void main(String[] args) { @@ -893,12 +973,14 @@ public class Cipher { // cryptage par le chiffre de César \endgroup \bigskip -Les clés de la commande |\lstdefinelanguage| de \pkg{listings} prises en charge par |\NewPitonLanguage| sont : -|morekeywords|, |otherkeywords|, |sensitive|, |keywordsprefix|, |moretexcs|, |morestring| (avec les lettres |b|, -|d|, |s| et |m|), |morecomment| (avec les lettres |i|, |l|, |s| et |n|), |moredelim| (avec les lettres |i|, -|l|, |s|, |*| et |**|), |moredirectives|, |tag|, |alsodigit|, |alsoletter| et |alsoother|. +Les clés de la commande |\lstdefinelanguage| de \pkg{listings} prises en charge par +|\NewPitonLanguage| sont : |morekeywords|, |otherkeywords|, |sensitive|, |keywordsprefix|, +|moretexcs|, |morestring| (avec les lettres |b|, |d|, |s| et |m|), |morecomment| (avec les +lettres |i|, |l|, |s| et |n|), |moredelim| (avec les lettres |i|, |l|, |s|, |*| et |**|), +|moredirectives|, |tag|, |alsodigit|, |alsoletter| et |alsoother|. -Pour la description de ces clés, on renvoie à la documentation de \pkg{listings} (taper |texdoc| |listings| dans un terminal). +Pour la description de ces clés, on renvoie à la documentation de \pkg{listings} (taper +|texdoc| |listings| dans un terminal). \bigskip Par exemple, pour formater du code LaTeX, on pourra créer le language suivant : @@ -907,170 +989,105 @@ Par exemple, pour formater du code LaTeX, on pourra créer le language suivant : \begin{verbatim} \NewPitonLanguage{LaTeX}{keywordsprefix = \ , alsoletter = @_ } \end{verbatim} -} -Initialement, les caractères |@| et |_| sont des considérés comme des lettres car de nombreux langages de -programmation les autorisent dans les mots-clés et les identificateurs. Avec \verb|alsoletter = @_|, on les retire -de la catégorie des lettres. - - -\section{Fonctionnalités avancées} - - -\subsection{Coupure des pages et des lignes} - -\label{breakable} - -\subsubsection{Coupure des pages} - -\index{splittable} -\index{split-on-empty-lines} -\index{split-separation} - -Par défaut, les listings produits par l'environnement |{Piton}| et par la commande |\PitonInputFile| sont -insécables. - - -Néanmoins, la commande |\PitonOptions| propose les clés |split-on-empty-lines| et |splittable| pour autoriser de -telles coupures. - -\begin{itemize} -\item La clé \Definition{split-on-empty-lines} autorise les coupures sur les lignes vides\footnote{Les lignes considérées - comme vides sont celles qui ne comportent que des espaces.} du listing. Dans les listings informatiques, les -lignes vides séparent le plus souvent les définitions des fonctions informatiques et il est donc souvent judicieux -de pouvoir couper au niveau de ces lignes. +} -Quand la clé |split-on-empty-lines| est activée, le travail effectué va en fait un peu plus loin : les lignes vides -successives sont supprimées et remplacées par le contenu du paramètre correspondant à la clé -\Definition{split-separation}. +Initialement, les caractères |@| et |_| sont considérés comme des lettres car de nombreux +langages de programmation les autorisent dans les mots-clés et les identificateurs. Avec +\verb|alsoletter = @_|, on les retire de la catégorie des lettres. -La valeur initiale de ce paramètre est |\vspace{\baselineskip}\vspace{-1.25pt}|, ce qui, au final, correspond à une -ligne vide dans le PDF produit (cet espace vertical est supprimé s'il tombe au niveau d'un saut de page). -\medskip -\item La clé |split-on-empty-lines| peut bien sûr être insuffisante et c'est pourquoi \pkg{piton} propose la clé -\Definition{splittable}. +\section{Fonctionnalités avancées} -Quand la clé |splittable| est utilisée avec la valeur numérique $n$ (qui doit être un entier naturel non nul) le -listing, ou bien chaque partie de ce listing située entre des lignes vides (quand |split-on-empty-lines| est -utilisée), pourra être coupé n'importe où avec cette exception qu'aucune coupure ne pourra avoir lieu entre les -$n$~premières lignes, ni entre les $n$~dernières. Par exemple, |splittable = 4| pourrait être un réglage raisonnable. -Employée sans argument, la clé |splittable| est équivalente à |splittable = 1|, et les listings sont alors sécables -n'importe où (ce n'est pas recommandable). +\subsection{Insertion d'un fichier} -\end{itemize} - -\medskip -\emph{Remarque}\par\nobreak +\label{PitonInputFile} -Même avec une couleur de fond (fixée avec |background-color|), les sauts de page sont possibles, à partir du moment -où |split-on-empty-lines| ou |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{La commande \textbackslash PitonInputFile} +\indexcommand{PitonInputFile} -\subsubsection{Coupure des lignes} - -\label{line-breaks} - -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 \index{break-lines!break-lines-in-piton} Avec la clé \Definition{break-lines-in-piton}, les coupures de ligne sont autorisées dans la commande -|\piton{...}| (mais pas dans la commande \verb+\piton|...|+, c'est-à-dire avec la syntaxe verbatim). +La commande \DefinitionCommand{PitonInputFile} permet d'insérer tout ou partie d'un +fichier extérieur dont le nom est passé en argument. Il existe aussi des commandes +\DefinitionCommand{PitonInputFileT}, \DefinitionCommand{PitonInputFileF} et +\DefinitionCommand{PitonInputFileTF} avec des arguments correspondant aux lettres |T| et +|F|, arguments qui seront exécutés dans le cas où le fichier a été trouvé (lettre |T|) ou +pas (lettre |F|). -\item \index{break-lines!break-lines-in-Piton} Avec la clé \Definition{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 les listings produits par |\PitonInputFile|. -\item \index{break-lines} La clé \Definition{break-lines} est la conjonction des deux clés précédentes. -\end{itemize} +\bigskip +\colorbox{yellow!50}{\textbf{Modification 4.0}}\par\nobreak -\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|. +\smallskip +\index{old-PitonInputFile} +La syntaxe pour les chemins absolus et relatifs a été changée pour être conforme aux +usages traditionnels. Il est toutefois possible d'utiliser la clé +\Definition{old-PitonInputFile} au chargement de l'extension (c'est-à-dire avec le +|\usepackage|) pour avoir l'ancien comportement de |\PitonInputFile| (néanmoins, cette clé +sera supprimée dans une prochaine version de \pkg{piton} !). +\smallskip +La syntaxe est maintenant la suivante : \begin{itemize} -\item \index{indent-broken-lines} Avec la clé \Definition{indent-broken-lines}, l'indentation de la ligne coupée est respectée à chaque retour -à la ligne. +\item Les chemins commençant par |/| sont des chemins absolus. -\item \index{end-of-broken-line} La clé \Definition{end-of-broken-line} correspond au symbole placé à la fin d'une ligne coupée. Sa valeur initiale est : -|\hspace*{0.5em}\textbackslash|. +\emph{Exemple} : |\PitonInputFile{/Users/joe/Documents/programme.py}| -\item \index{continuation-symbol} La clé \Definition{continuation-symbol} correspond au symbole placé à chaque retour de ligne dans la marge -gauche. Sa valeur initiale est : |+\;| (la commande |\;| insère un petit espace horizontal). +\item Les chemins ne commençant pas par |/| sont relatifs au répertoire courant. -\item \index{continuation-symbol-on-indentation} La clé \Definition{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\;$|. +\emph{Exemple} : |\PitonInputFile{les_listings/programme.py}| \end{itemize} -\bigskip -Le code suivant a été composé avec le réglage suivant : - -\begin{Verbatim} -\PitonOptions{width=12cm,break-lines,indent-broken-lines,background-color=gray!15} -\end{Verbatim} -\begin{center} -\PitonOptions{width=12cm,break-lines,indent-broken-lines,background-color=gray!15} -\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{center} +\index{path} +La clé \Definition{path} de la commande |\PitonOptions| permet de spécifier une +\emph{liste} de chemins où sera recherché le fichier à inclure (dans cette liste, les +chemins sont séparés par des virgules). Comme précédemment, les chemins absolus doivent +débuter par une oblique~|/|. -\bigskip -\subsection{Insertion d'une partie d'un fichier} +\subsubsection{Insertion d'une partie d'un fichier} \label{part-of-a-file} -\indexcommand{PitonInputFile} - -La commande |\PitonInputFile| permet d'insérer (avec formatage) le contenu d'un fichier. En fait, il existe des -mécanismes permettant de n'insérer qu'une partie du fichier en question. +En fait, il existe des mécanismes permettant de n'insérer qu'une partie du fichier en +question. \begin{itemize} -\item On peut spécifier la partie à insérer par les numéros de lignes (dans le fichier d'origine). +\item On peut spécifier la partie à insérer par les numéros de lignes (dans le fichier +d'origine). \item On peut aussi spécifier la partie à insérer par des marqueurs textuels. \end{itemize} -Dans les deux cas, si on souhaite numéroter les lignes avec les numéros des lignes du fichier d'origine, il -convient d'utiliser la clé |line-numbers/absolute|. - -\subsubsection{Avec les numéros de lignes absolus} +Dans les deux cas, si on souhaite numéroter les lignes avec les numéros des lignes du +fichier d'origine, il convient d'utiliser la clé |line-numbers/absolute|. -La commande |\PitonInputFile| propose les clés \Definition{first-line} et \Definition{last-line} pour n'insérer que -la partie du fichier comprise entre les lignes correspondantes. Ne pas confondre avec la clé |line-numbers/start| -qui demande un numérotage des lignes commençant à la valeur donnée à cette clé (en un sens |line-numbers/start| -concerne la sortie alors que |first-line| et |last-line| concernent l'entrée). +\bigskip +\textbf{Avec les numéros de lignes absolus}\par\nobreak +La commande |\PitonInputFile| propose les clés \Definition{first-line} et +\Definition{last-line} qui permettent de n'insérer que la partie du fichier comprise entre +les lignes correspondantes. Ne pas confondre avec la clé |line-numbers/start| qui demande +un numérotage des lignes commençant à la valeur donnée à cette clé (en un sens +|line-numbers/start| concerne la sortie alors que |first-line| et |last-line| concernent +l'entrée). -\subsubsection{Avec des marqueurs textuels} +\bigskip +\textbf{Avec des marqueurs textuels}\par\nobreak \index{marker/beginning} \index{marker/end} -Pour utiliser cette technique, il convient d'abord de spécifier le format des marqueurs marquant le début et la fin -de la partie du fichier à inclure. Cela se fait avec les deux clés \Definition{marker/beginning} et -\Definition{marker/end} (usuellement dans la commande |\PitonOptions|). +Pour utiliser cette technique, il convient d'abord de spécifier le format des marqueurs +marquant le début et la fin de la partie du fichier à inclure. Cela se fait avec les deux +clés \Definition{marker/beginning} et \Definition{marker/end} (usuellement dans la +commande |\PitonOptions|). \medskip Prenons d'abord un exemple. \medskip -Supposons que le fichier à inclure contienne des solutions à des exercices de programmation sur le modèle suivant : +Supposons que le fichier à inclure contienne des solutions à des exercices de +programmation sur le modèle suivant : \begin{Verbatim}[formatcom=\small\color{gray}] ~#[Exercice 1] Version itérative @@ -1087,25 +1104,27 @@ def fibo(n): ~#<Exercice 1> \end{Verbatim} -Les marqueurs de début de début et de fin sont les chaînes |#[Exercice 1]| et |#<Exercice 1>|. La chaîne -«|Exercice 1|» sera appelée le \emph{label} de l'exercice (ou de la partie du fichier à inclure). +Les marqueurs de début de début et de fin sont les chaînes |#[Exercice 1]| et +|#<Exercice 1>|. La chaîne «|Exercice 1|» sera appelée le \emph{label} de l'exercice (ou +de la partie du fichier à inclure). -Pour spécifier des marqueurs de cette sorte dans \pkg{piton}, on utilisera les clés |marker/beginning| et |marker/end| -de la manière suivante (le caractère |#| des commentaires de Python doit être inséré sous la forme échappée |\#|). +Pour spécifier des marqueurs de cette sorte dans \pkg{piton}, on utilisera les clés +|marker/beginning| et |marker/end| de la manière suivante (le caractère |#| des +commentaires de Python doit être inséré sous la forme échappée |\#|). \begin{Verbatim} \PitonOptions{ ~emphase#marker/beginning@ = \~#[~#1] , ~emphase#marker/end@ = \~#<~#1> } \end{Verbatim} -Comme on le voit, |marker/beginning| est une expression correspondant à la fonction mathématique qui, au nom du -label (par exemple |Exercice 1|), associe le marqueur de début (dans l'exemple |#[Exercice 1]|). La chaîne |#1| -correspond aux occurrences de l'argument de cette fonction (c'est la syntaxe habituelle de TeX). De même pour -|marker/end|. +Comme on le voit, |marker/beginning| est une expression correspondant à la fonction +mathématique qui, au nom du label (par exemple |Exercice 1|), associe le marqueur de début +(dans l'exemple |#[Exercice 1]|). La chaîne |#1| correspond aux occurrences de l'argument +de cette fonction (c'est la syntaxe habituelle de TeX). De même pour |marker/end|. \bigskip -Pour insérer une partie marquée d'un fichier, il suffit alors d'utiliser la clé \Definition{range} de -|\PitonInputFile|. +Pour insérer une partie marquée d'un fichier, il suffit alors d'utiliser la clé +\Definition{range} de |\PitonInputFile|. \smallskip \begin{Verbatim} @@ -1126,9 +1145,8 @@ def fibo(n): return v \end{Piton} -\vspace{1cm} -\index{marker/include-lines} -La clé \Definition{marker/include-lines} demande que les lignes contenant les marqueurs soient également insérées. +\vspace{1cm} \index{marker/include-lines} La clé \Definition{marker/include-lines} demande +que les lignes contenant les marqueurs soient également insérées. \begin{Verbatim} \PitonInputFile[~emphase#marker/include-lines@,range = Exercice 1]{~textsl#nom_du_fichier@} @@ -1151,13 +1169,12 @@ def fibo(n): \bigskip -\index{begin-range} -\index{end-range} -Il existe en fait aussi les clés \Definition{begin-range} et \Definition{end-range} pour insérer plusieurs -contenus marqués simultanément. +\index{begin-range} \index{end-range} Il existe en fait aussi les clés +\Definition{begin-range} et \Definition{end-range} pour insérer plusieurs contenus marqués +simultanément. -Par exemple, pour insérer les solutions des exercices 3 à 5, on pourra écrire (à condition que le fichier soit -structuré correctement!): +Par exemple, pour insérer les solutions des exercices 3 à 5, on pourra écrire (à condition +que le fichier soit structuré correctement!): \begin{Verbatim} \PitonInputFile[~emphase#begin-range = Exercice 3, end-range = Exercice 5@]{~textsl#nom_du_fichier@} @@ -1166,32 +1183,255 @@ structuré correctement!): +\subsection{Coupure des pages et des lignes} + +\label{breakable} + +\subsubsection{Coupure des lignes} + +\label{line-breaks} + +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 qui sont dans les chaînes de +caractères des langages informatiques). +\begin{itemize} +\item \index{break-lines!break-lines-in-piton} Avec la clé +\Definition{break-lines-in-piton}, les coupures de ligne sont autorisées dans la commande +|\piton{...}| (mais pas dans la commande \verb+\piton|...|+, c'est-à-dire avec la syntaxe +verbatim). + +\item \index{break-lines!break-lines-in-Piton} Avec la clé +\Definition{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 les listings +produits par |\PitonInputFile|. + +\item \index{break-lines} La clé \Definition{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 \index{indent-broken-lines} Avec la clé \Definition{indent-broken-lines}, +l'indentation de la ligne coupée est respectée à chaque retour à la ligne (à condition que +la fonte utilisée soit une fonte mono-chasse, ce qui est le cas par défaut puisque la +valeur initiale de |font-command| est |\ttfamily|). + +\item \index{end-of-broken-line} La clé \Definition{end-of-broken-line} correspond au +symbole placé à la fin d'une ligne coupée. Sa valeur initiale est : +|\hspace*{0.5em}\textbackslash|. + +\item \index{continuation-symbol} La clé \Definition{continuation-symbol} correspond au +symbole placé à chaque retour de ligne dans la marge gauche. Sa valeur initiale est : +|+\;| (la commande |\;| insère un petit espace horizontal). + +\item \index{continuation-symbol-on-indentation} La clé +\Definition{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é avec le réglage suivant : + +\begin{Verbatim} +\PitonOptions{width=12cm,break-lines,indent-broken-lines,background-color=gray!15} +\end{Verbatim} + + +\begin{center} +\PitonOptions{width=12cm,break-lines,indent-broken-lines,background-color=gray!15} +\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{center} + + +\bigskip +\colorbox{yellow!50}{\bfseries{Nouveau 4.1}}\par\nobreak + +\smallskip +Avec la clé \Definition{break-strings-anywhere}, les chaînes de caractères pourront être +coupées n'importe où (et pas seulement sur les espaces). + + +\subsubsection{Coupure des pages} + +\label{coupure-de-pages} +\index{splittable} +\index{splittable-on-empty-lines} + + +Par défaut, les listings produits par l'environnement |{Piton}| et par la commande +|\PitonInputFile| sont insécables. + + +Néanmoins, \pkg{piton} propose les clés |splittable-on-empty-lines| et |splittable| pour +autoriser de telles coupures. + +\begin{itemize} +\item La clé \Definition{splittable-on-empty-lines} autorise les coupures sur les lignes +vides du listing. Les lignes considérées comme vides sont celles qui ne comportent que des +espaces (et il aurait peut-être été plus habile de parler de lignes blanches). + +\medskip +\item La clé |splittable-on-empty-lines| peut bien sûr être insuffisante et c'est pourquoi +\pkg{piton} propose la clé \Definition{splittable}. + +Quand la clé |splittable| est utilisée avec la valeur numérique $n$ (qui doit être un +entier naturel non nul) le listing pourra être coupé n'importe où avec cette exception +qu'aucune coupure ne pourra avoir lieu entre les $n$~premières lignes, ni entre les +$n$~dernières.\footnote{Remarquer que l'on parle des lignes du listing d'origine, une + telle ligne pouvant être composée sur plusieurs lignes dans le \textsc{pdf} final si la + clé |break-lines-in-Piton| est utilisée.} + +Par exemple, |splittable = 4| pourrait être un réglage raisonnable. + +Employée sans argument, la clé |splittable| est équivalente à |splittable = 1|, et les +listings sont alors sécables n'importe où (ce n'est pas recommandable). + +La valeur initiale de la clé |splittable| vaut 100, ce qui fait que les listings ne sont +pas sécables. +\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ù |splittable-on-empty-lines| ou |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|.} + +\bigskip +\subsection{Découpe d'un listing en sous-listings} + +\index{split-on-empty-lines} +\label{split-on-empty-lines} +\index{split-separation} +\index{env-used-by-split} + +L'exension \pkg{piton} fournit la clé \Definition{split-on-empty-lines}, qui ne doit pas +être confondue avec la clé |splittable-on-empty-lines| définie précédemment. + +\smallskip +Pour comprendre le fonctionnement de la clé |split-on-empty-lines|, il faut imaginer que +l'on a à composer un fichier informatique qui contient une succession de définitions de +fonctions informatiques. Dans la plupart des langages informatiques, ces définitions +successives sont séparées par des lignes vides (ou plutôt des lignes blanches, +c'est-à-dire des lignes qui ne contiennent que des espaces). + +\smallskip +La clé |split-on-empty-lines| coupe le listing au niveau des lignes vides. Les lignes +vides successives sont supprimées et remplacées par le contenu du paramètre correspondant +à la clé \Definition{split-separation}. +\begin{itemize} +\item Ce paramètre doit contenir du matériel à insérer en \emph{mode vertical} de TeX. On +peut, par exemple, mettre la primmitive TeX |\hrule|. + +\item La valeur initiale de ce paramètre est |\vspace{\baselineskip}\vspace{-1.25pt}|, ce qui, +au final, correspond à une ligne vide dans le \textsc{pdf} produit (cet espace vertical +est supprimé s'il tombe au niveau d'un saut de page). +\end{itemize} + + +\colorbox{yellow!50}{\textbf{Nouveau 4.0}}\par\nobreak + +Chaque morceau du code informatique est formaté (de manière autonome) dans un +environnement dont le nom est donné par la clé \Definition{env-used-by-split}. La valeur +initiale de ce paramètre est, sans surprise, |Piton| et les différents morceaux sont donc +composés dans des environnements |{Piton}|. Si on décide de donner une autre valeur à la +clé |env-used-by-split|, on doit bien sûr donner le nom d'un environnement créé par +|\NewPitonEnvironment| (cf.~partie~\ref{NewPitonEnvironment}, +p.~\pageref{NewPitonEnvironment}). + +\smallskip +Chaque morceau du listing de départ étant composé dans son environnement, il dispose de sa +propre numérotation des lignes (si la clé |line-numbers| est active) et de son propre fond +coloré (si la clé |background-color| est utilisée), séparé des fonds des autres morceaux. +Si elle est active, la clé |splittable| s'applique de manière autonome dans chaque +morceau. Bien sûr, des sauts de page peuvent intervenir entre les différents morceaux du +code, quelle que soit la valeur de la clé |splittable|. + +\bigskip +\begin{Verbatim} +\begin{Piton}[~emphase#split-on-empty-lines@,background-color=gray!15,line-numbers] +def carré(x): + """Calcule le carré de x""" + return x*x + +def cube(x): + """Calcule le cube de x""" + return x*x*x +\end{Piton} +\end{Verbatim} + + +\begin{Piton}[split-on-empty-lines,background-color=gray!15,line-numbers] +def carré(x): + """Calcule le carré de x""" + return x*x + +def cube(x): + """Calcule le cube de x""" + return x*x*x +\end{Piton} + + +\bigskip +\textbf{Attention} : Comme chaque morceau est traité de manière indépendante, les +commandes spécifiées par |detected-commands| et les commandes et environnements de Beamer +automatiquement détectés par \pkg{piton} ne doivent pas enjamber les lignes vides du +listing de départ. + + +\bigskip \subsection{Mise en évidence d'identificateurs} \indexcommand{SetPitonIdentifier} \label{SetPitonIdentifier} -La commande \DefinitionCommand{SetPitonIdentifier} permet de changer le formatage de certains identificateurs. +La commande \DefinitionCommand{SetPitonIdentifier} permet de changer le formatage de +certains identificateurs. \smallskip Cette commande prend trois arguments : un optionnel et deux obligatoires. \begin{itemize} -\item L'argument optionnel (entre crochets) indique le langage (informatique) concerné ; si cet -argument est absent, les réglages faits par |\SetPitonIdentifier| s'appliqueront à tous les langages.\footnote{On rappelle que, dans \pkg{piton}, les noms des langages informatiques ne sont pas - sensibles à la casse.} +\item L'argument optionnel (entre crochets) indique le langage (informatique) concerné ; +si cet argument est absent, les réglages faits par |\SetPitonIdentifier| s'appliqueront à +tous les langages.\footnote{On rappelle que, dans \pkg{piton}, les noms des langages + informatiques ne sont pas sensibles à la casse.} -\item Le premier argument obligatoire est une liste de noms d'identificateurs séparés par des virgules. +\item Le premier argument obligatoire est une liste de noms d'identificateurs séparés par +des virgules. -\item Le deuxième argument obligatoire est une liste d'instructions LaTeX de formatage du même type que pour les -styles précédemment définis (cf. \ref{styles}, p.~\pageref{styles}). +\item Le deuxième argument obligatoire est une liste d'instructions LaTeX de formatage du +même type que pour les styles précédemment définis (cf. \ref{styles}, +p.~\pageref{styles}). \end{itemize} -\emph{Attention} : Seuls les identificateurs peuvent voir leur formatage affecté. Les mots-clés et les noms de -fonctions prédéfinies ne seront pas affectés, même s'ils figurent dans le premier argument de -|\SetPitonIdentifier|. +\emph{Attention} : Seuls les identificateurs peuvent voir leur formatage affecté. Les +mots-clés et les noms de fonctions prédéfinies ne seront pas affectés, même s'ils figurent +dans le premier argument de |\SetPitonIdentifier|. \begin{Verbatim} ~emphase#\SetPitonIdentifier{l1,l2}{\color{red}}@ @@ -1230,8 +1470,9 @@ def tri(l): \endgroup \bigskip -Avec la commande |\SetPitonIdentifiers|, on peut ajouter à un langage informatique de nouvelles fonctions -prédéfinies (ou de nouveaux mots-clés, etc.) qui seront détectées par \pkg{piton}. +Avec la commande |\SetPitonIdentifiers|, on peut ajouter à un langage informatique de +nouvelles fonctions prédéfinies (ou de nouveaux mots-clés, etc.) qui seront détectées par +\pkg{piton}. \begin{Verbatim} @@ -1272,16 +1513,18 @@ floor(5.4) 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 de demander à \pkg{piton} de détecter directement certaines commandes LaTeX avec leur argument. +\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 de demander à \pkg{piton} de détecter directement certaines +commandes LaTeX avec leur argument. \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 suivantes. \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}. +À 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»} @@ -1289,14 +1532,16 @@ la plupart des commandes et environnements de Beamer : voir la sous-section \ref \index{comment-latex} \index{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. +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é \Definition{comment-latex}, \emph{disponible uniquement dans le préambule du document}, qui permet de choisir les +\item Il est possible de changer le marquage syntaxique utilisé (qui vaut +initialement~|#>|). Pour ce faire, il existe une clé \Definition{comment-latex}, +\emph{disponible uniquement dans le préambule du document}, qui permet de choisir les caractères qui (précédés par~|#|) serviront de marqueur syntaxique. Par exemple, avec le réglage suivant (fait dans le préambule du document) : @@ -1305,18 +1550,18 @@ Par exemple, avec le réglage suivant (fait dans le préambule du document) : 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». +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|. +\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. +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 : +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 } @@ -1328,11 +1573,12 @@ p.~\pageref{example-comments}. \bigskip -Si l'utilisateur a demandé l'affichage des numéros de ligne avec |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.)} +Si l'utilisateur a demandé l'affichage des numéros de ligne avec |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.)} @@ -1341,15 +1587,17 @@ Si l'utilisateur a demandé l'affichage des numéros de ligne avec |line-numbers \index{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). +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é \Definition{math-comments} (\emph{qui ne peut être activée que dans le préambule du document}) active ce -comportement. +La clé \Definition{math-comments} (\emph{qui ne peut être activée que dans le préambule du + document}) active ce comportement. \bigskip -Dans l'exemple suivant, on suppose que |\PitonOptions{math-comments}| a été utilisé dans le préambule du document. +Dans l'exemple suivant, on suppose que |\PitonOptions{math-comments}| a été utilisé dans +le préambule du document. \begin{Verbatim} \begin{Piton} @@ -1369,23 +1617,26 @@ def carré(x): \index{detected-commands (key)} \label{detected-commands} -La clé \Definition{detected-commands} de |\PitonOptions| permet de spécifier une liste de noms de commandes LaTeX -qui seront directement détectées par \pkg{piton}. +La clé \Definition{detected-commands} de |\PitonOptions| permet de spécifier une liste de +noms de commandes LaTeX qui seront directement détectées par \pkg{piton}. \begin{itemize} -\item Cette clé |detected-commands| ne peut être utilisée que dans le préambule du document. +\item Cette clé |detected-commands| ne peut être utilisée que dans le préambule du +document. -\item Les noms de commandes LaTeX doivent apparaître sans la contre-oblique -(ex. : |detected-commands = { emph , textbf }|). +\item Les noms de commandes LaTeX doivent apparaître sans la contre-oblique (ex. : +|detected-commands = { emph , textbf }|). -\item Ces commandes doivent être des commandes LaTeX à un seul argument obligatoire entre accolades (et ces -accolades doivent apparaître explicitement dans le listing). +\item Ces commandes doivent être des commandes LaTeX à un seul argument obligatoire entre +accolades (et ces accolades doivent apparaître explicitement dans le listing). \end{itemize} \medskip -Dans l'exemple suivant, qui est une programmation récursive de la factorielle, on décide de surligner en jaune -l'appel récursif. La commande |\highLight| de \pkg{lua-ul} (cette extension requiert elle-même l'extension -\pkg{luacolor}) permet de le faire avec la syntaxe |\hightLight{...}|. +Dans l'exemple suivant, qui est une programmation récursive de la factorielle, on décide +de surligner en jaune l'appel récursif. La commande |\highLight| de +\pkg{lua-ul}\footnote{L'extension \pkg{lua-ul} requiert elle-même l'extension + \pkg{luacolor}.} permet de le faire facilement avec la +syntaxe |\highLight{...}|. \smallskip On suppose que l'on a mis dans le préambule du document LaTeX l'instruction suivante : @@ -1419,17 +1670,20 @@ def fact(n): \index{end-escape} \label{escape} -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 délimiteurs marquant l'échappement (le premier le commençant et le deuxième -le terminant) en utilisant les clés \Definition{begin-escape} et \Definition{end-escape} (\emph{qui ne sont accessibles -que dans le préambule du document}). Les deux délimiteurs peuvent être identiques. +Il est aussi possible de surcharger les listings informatiques 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 délimiteurs marquant l'échappement (le premier le commençant et le +deuxième le terminant) en utilisant les clés \Definition{begin-escape} et +\Definition{end-escape} (\emph{qui ne sont accessibles que dans le préambule du + document}). Les deux délimiteurs peuvent être identiques. \medskip -On reprend l'exemple précédent de la factorielle et on souhaite surligner en rose l'instruction qui contient l'appel -récursif. La commande |\highLight| de \pkg{lua-ul} permet de le faire avec la syntaxe |\highLight[LightPink]{...}|. -Du fait de la présence de l'argument optionnel entre crochets, on ne peut pas utiliser la clé |detected-commands| -comme précédemment mais on peut utiliser le mécanisme «escape». +On reprend l'exemple précédent de la factorielle et on souhaite surligner en rose +l'instruction qui contient l'appel récursif. La commande |\highLight| de \pkg{lua-ul} +permet de le faire avec la syntaxe |\highLight[LightPink]{...}|. Du fait de la présence de +l'argument optionnel entre crochets, on ne peut pas utiliser la clé |detected-commands| +comme précédemment mais on peut utiliser le mécanisme «escape» qui est plus général. \smallskip On suppose que le préambule du document contient l'instruction : @@ -1460,10 +1714,10 @@ def fact(n): \bigskip -\emph{Attention} : L'échappement vers LaTeX permis par les clés |begin-escape| et |end-escape| 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 -|#>|). +\emph{Attention} : Le mécanisme «escape» 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{Le mécanisme «escape-math»} @@ -1472,27 +1726,30 @@ LaTeX, c'est-à-dire ce qui est appelé dans ce document «commentaire LaTeX», \index{begin-escape-math} \index{end-escape-math} -Le mécanisme «|escape-math|» est très similaire au mécanisme «|escape|» puisque la seule différence est que les -éléments en échappement LaTeX y sont composés en mode mathématique. +Le mécanisme «escape-math» est très similaire au mécanisme «escape» puisque la seule +différence est que les éléments en échappement LaTeX y sont composés en mode mathématique. -On active ce mécanisme avec les clés \Definition{begin-escape-math} et \Definition{end-escape-math} (\emph{qui ne sont -accessibles que dans le préambule du document}). +On active ce mécanisme avec les clés \Definition{begin-escape-math} et +\Definition{end-escape-math} (\emph{qui ne sont accessibles que dans le préambule du + document}). \medskip -Malgré la proximité technique, les usages du mécanisme «|escape-math|» sont en fait assez différents de ceux du -mécanisme «|escape|». En effet, comme le contenu en échappement est composé en mode mathématique, il est en -particulier composé dans un groupe TeX et ne pourra donc pas servir à changer le formatage d'autres unités lexicales. +Malgré la proximité technique, les usages du mécanisme «escape-math» sont en fait assez +différents de ceux du mécanisme «escape». En effet, comme le contenu en échappement est +composé en mode mathématique, il est, en particulier, composé dans un groupe TeX et ne +pourra donc pas servir à changer le formatage d'autres unités lexicales. \medskip -Dans les langages où le caractère |$| ne joue pas un rôle syntaxique important, on peut assez naturellement -vouloir activer le mécanisme «|escape-math|» avec le caractère |$|: +Dans les langages où le caractère |$| ne joue pas un rôle syntaxique important, on peut +assez naturellement vouloir activer le mécanisme «escape-math» avec le caractère |$|: \begin{Verbatim} \PitonOptions{~emphase#begin-escape-math=$,end-escape-math=$@} \end{Verbatim} -Remarquer que le caractère |$| ne doit \emph{pas} être protégé par une contre-oblique. +Remarquer que le caractère |$| ne doit \emph{pas} être protégé par une contre-oblique. % $ \bigskip -Néanmoins, il est sans doute plus prudent d'utiliser |\(| et |\)|. +Néanmoins, il est sans doute plus prudent d'utiliser |\(| et |\)|, qui sont des +délimiteurs du mode mathématique proposés par LaTeX. \begin{Verbatim} \PitonOptions{~emphase#begin-escape-math=\(,end-escape-math=\)@} \end{Verbatim} @@ -1538,25 +1795,29 @@ def arctan(x,n=10): \index{Beamer@\cls{Beamer} (classe)} -\emph{Première remarque}\par\nobreak -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|, -c'est-à-dire débutant par |\begin{frame}[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).} +\emph{Première remarque}\par\nobreak + +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|, c'est-à-dire débutant par +|\begin{frame}[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 -Quand l'extension \pkg{piton} est utilisée dans la classe \cls{beamer}\footnote{L'extension \pkg{piton} détecte la - classe \cls{beamer} et l'extension \pkg{beamerarticle} si elle est chargée précédemment, 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. +Quand l'extension \pkg{piton} est utilisée dans la classe +\cls{beamer}\footnote{L'extension \pkg{piton} détecte la classe \cls{beamer} et + l'extension \pkg{beamerarticle} si elle est chargée précédemment, 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. +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 : @@ -1575,27 +1836,37 @@ ou aussi \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). +\index{detected-beamer-commands} + +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 obligatoires : |\alt| ; +\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| ; \newline +La clé \Definition{detected-beamer-commands} permet de rajouter à cette liste de nouveaux +noms de commandes (les noms de commandes ne doivent \emph{pas} être précédés de la +contre-oblique) ; +\item deux arguments obligatoires : |\alt| ; \item trois arguments obligatoires : |\temporal|. \end{itemize} \medskip -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). +Ces commandes doivent être utilisées précédées et suivies d'un espace. 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). \medskip -Concernant les fonctions |\alt| et |\temporal|, aucun retour à la ligne ne doit se trouver dans les arguments de ces fonctions. +Concernant les fonctions |\alt| et |\temporal|, aucun retour à la ligne ne doit se trouver +dans les arguments de ces fonctions. \medskip @@ -1618,22 +1889,29 @@ def string_of_list(l): \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). +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) : |{actionenv}|, |{alertenv}|, |{invisibleenv}|, |{onlyenv}|, |{uncoverenv}| -et |{visibleenv}|. +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) +: |{actionenv}|, |{alertenv}|, |{invisibleenv}|, |{onlyenv}|, |{uncoverenv}| et +|{visibleenv}|. +\smallskip +\index{detected-beamer-environments} +On peut ajouter de nouveaux environnements à cette liste d'environnements reconnus avec la +clé \Definition{detected-beamer-environments}. \medskip -Il y a néanmoins une restriction : ces environnements doivent englober des \emph{lignes entières de code Python}. +Il y a néanmoins une restriction : ces environnements doivent englober des \emph{lignes + entières de code Python}. Les instructions |\begin{...}| et |\end{...}| doivent être +seules sur leurs lignes. \medskip @@ -1657,25 +1935,29 @@ def carré(x): -\vspace{1cm} -\textbf{Remarque à propos de la commande \textbackslash alert et de l'environnement \{alertenv\} de Beamer}\par\nobreak +\vspace{1cm} +\textbf{Remarque à propos de la commande \textbackslash alert et de + l'environnement \{alertenv\} de Beamer}\par\nobreak \smallskip -Beamer propose un moyen aisé de changer la couleur utilisée par l'environnement |{alertenv}| (et par la commande -|\alert| qui s'appuie dessus). Par exemple, on peut écrire: +Beamer propose un moyen aisé de changer la couleur utilisée par l'environnement +|{alertenv}| (et par suite la commande |\alert| qui s'appuie dessus). Par exemple, on peut +écrire: \begin{Verbatim} \setbeamercolor{~emphase#alerted text@}{fg=blue} \end{Verbatim} -Néanmoins, dans le cas d'une utilisation à l'intérieur d'un environnement |{Piton}| un tel réglage n'est sans doute -pas pertinent, puisque, justement, \pkg{piton} va (le plus souvent) changer la couleur des élements selon leur -valeur lexicale. On préfèrera sans doute un environnement |{alertenv}| qui change la couleur de fond des -éléments à mettre en évidence. +Néanmoins, dans le cas d'une utilisation à l'intérieur d'un environnement |{Piton}| un tel +réglage n'est sans doute pas pertinent, puisque, justement, \pkg{piton} va (le plus +souvent) changer la couleur des élements selon leur valeur lexicale. On préfèrera sans +doute un environnement |{alertenv}| qui change la couleur de fond des éléments à mettre en +évidence. \smallskip -Voici un code qui effectuera ce travail en mettant un fond jaune. Ce code utilise la commande |\@highLight| de -l'extension \pkg{lua-ul} (cette extension nécessite elle-même l'extension \pkg{luacolor}). +Voici un code qui effectuera ce travail en mettant un fond jaune. Ce code utilise la +commande |\@highLight| de l'extension \pkg{lua-ul} (cette extension nécessite elle-même +l'extension \pkg{luacolor}). \begingroup \fvset{commandchars=\~\#\+,formatcom=\color{gray}} @@ -1688,12 +1970,9 @@ l'extension \pkg{lua-ul} (cette extension nécessite elle-même l'extension \pkg \end{Verbatim} \endgroup -Ce code redéfinit localement l'environnement |{alertenv}| à l'intérieur de l'environnement |{Piton}| (on rappelle -que la commande |\alert| s'appuie sur cet environnement |{alertenv}|). - - - -\bigskip +Ce code redéfinit localement l'environnement |{alertenv}| à l'intérieur de l'environnement +|{Piton}| (on rappelle que la commande |\alert| s'appuie sur cet environnement +|{alertenv}|). \bigskip @@ -1707,33 +1986,122 @@ que la commande |\alert| s'appuie sur cet environnement |{alertenv}|). \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 +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}. +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 \Definition{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. +Si \pkg{piton} est chargée avec l'option \Definition{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 \Definition{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. +Si \pkg{piton} est chargée avec l'option \Definition{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}. +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. +\textbf{Remarque importante} : Si vous utilisez Beamer, il faut savoir que Beamer a son +propre système d'extraction des notes de pied de page et vous n'avez donc pas à charger +\pkg{piton} avec la clé |footnote| ou bien la clé |footnotehyper|. + +\bigskip +Par défaut, une commande |\footnote| ne peut apparaître que dans un «commentaire LaTeX». +Mais on peut aussi ajouter la commande |\footnote| à la liste des +\emph{detected-commands} (cf.~partie~\ref{detected-commands}, +p.~\pageref{detected-commands}). + +\medskip +Dans ce document, l'extension \pkg{piton} a été chargée avec l'option |footnotehyper| et +on rajouté la commande |\footnote| aux \emph{detected-commands} avec le code suivant +dans la préambule du document LaTeX : + +\qquad \verb|\PitonOptions{detected-commands = footnote}| + +\begingroup +\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}} +\begin{Verbatim} +\PitonOptions{background-color=gray!15} +\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!15} +\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 \emph{pas} être coupée par un saut de page. + + +\begingroup +\fvset{commandchars=\~\&\@,formatcom=\small\color{gray}} +\begin{Verbatim} +\PitonOptions{background-color=gray!15} +\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!15} +\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 + + \subsection{Tabulations} @@ -1741,15 +2109,21 @@ peuvent être mises dans les environnements |{Piton}| : voir un exemple sur la p \index{tab-size} \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é \Definition{tab-size} de |\PitonOptions|. +Même s'il est sans doute recommandable d'indenter les listings informatiques avec des +espaces et non des tabulations\footnote{Voir, par exemple, pour le langage Piton, la note 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é \Definition{tab-size} de |\PitonOptions|. + +\smallskip +Il existe aussi une clé \Definition{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). \smallskip -Il existe aussi une clé \Definition{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). +La clé |env-gobble| n'est pas compatible avec les tabulations. \section{API pour les développeurs} @@ -1758,34 +2132,34 @@ sur des caractères U+0009 au lieu de caractères U+0020 (espaces). \index{piton.last@\texttt{piton.get\_last\_code} (fonction Lua)} \label{API} -La variable L3 |\l_piton_language_str| contient le nom du langage courant (en minuscules). +La variable L3 \DefinitionCommand{l_piton_language_str} contient le nom du langage courant +(en minuscules). \bigskip -\colorbox{yellow!50}{\textbf{Nouveau 2.6}}\par\nobreak - -L'extension \pkg{piton} fournit une fonction Lua |piton.get_last_code| sans argument permettant de récupérer le -code contenu dans le dernier environnement de \pkg{piton}. +L'extension \pkg{piton} fournit une fonction Lua \Definition{piton.get_last_code} sans +argument permettant de récupérer le code contenu dans le dernier environnement de \pkg{piton}. \begin{itemize} -\item Les retours à la ligne (présents dans l'environnement de départ) apparaissent comme des caractères |\r| -(c'est-à-dire des caractères U+000D). +\item Les retours à la ligne (présents dans l'environnement de départ) apparaissent comme +des caractères |\r| (c'est-à-dire des caractères U+000D). -\item Le code fourni par |piton.get_last_code()| tient compte de l'éventuelle application d'une clé |gobble| (cf. -p.~\pageref{gobble}). +\item Le code fourni par |piton.get_last_code()| tient compte de l'éventuelle application +d'une clé |gobble| (cf. p.~\pageref{gobble}). -\item Les surcharges du code (qui entraînent des échappements vers LaTeX) ont été retirées du code fourni par -|piton.get_last_code()|. Cela s'applique aux commandes LaTeX déclarées par la clé |detected-commands| (cf. -partie~\ref{detected-commands}) et aux éléments insérés avec le mécanisme «|escape|» (cf. partie~\ref{escape}). +\item Les surcharges du code (qui entraînent des échappements vers LaTeX) ont été retirées +du code fourni par |piton.get_last_code()|. Cela s'applique aux commandes LaTeX déclarées +par la clé |detected-commands| (cf. partie~\ref{detected-commands}) et aux éléments +insérés avec le mécanisme «|escape|» (cf. partie~\ref{escape}). -\item |piton.get_last_code| est une fonction Lua et non une chaîne de caractères : les traitements présentés -précédemment sont exécutés lorsque la fonction est appelée. De ce fait, il peut être judicieux de stocker la valeur -renvoyée par |piton.get_last_code()| dans une variable Lua si on doit l'utiliser plusieurs fois. +\item |piton.get_last_code| est une fonction Lua et non une chaîne de caractères : les +traitements présentés précédemment sont exécutés lorsque la fonction est appelée. De ce +fait, il peut être judicieux de stocker la valeur renvoyée par |piton.get_last_code()| +dans une variable Lua si on doit l'utiliser plusieurs fois. \end{itemize} \medskip -Pour un exemple d'utilisation, voir la partie concernant l'utilisation (standard) de \pkg{pyluatex}, -partie~\ref{pyluatex}, p.~\pageref{pyluatex}. - +Pour un exemple d'utilisation, voir la partie concernant l'utilisation (standard) de +\pkg{pyluatex}, partie~\ref{pyluatex}, p.~\pageref{pyluatex}. \section{Exemples} @@ -1794,18 +2168,21 @@ partie~\ref{pyluatex}, p.~\pageref{pyluatex}. \label{example-numbering} \index{numérotation des lignes de code|emph} -On rappelle que l'on peut demander la numérotation des lignes des listings avec la clé |line-numbers|. +On rappelle que l'on peut demander la numérotation des lignes des listings avec la clé +|line-numbers| (utilisée sans valeur). -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). +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). +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}@ +~emphase&\PitonOptions{background-color=gray!15, left-margin = auto, line-numbers}@ \begin{Piton} def arctan(x,n=10): if x < 0: @@ -1821,7 +2198,7 @@ def arctan(x,n=10): \begingroup -\PitonOptions{background-color=gray!10,left-margin = auto, line-numbers} +\PitonOptions{background-color=gray!15,left-margin = auto, line-numbers} \begin{Piton} def arctan(x,n=10): if x < 0: @@ -1841,13 +2218,13 @@ def arctan(x,n=10): \label{example-comments} \index{commentaires LaTeX|emph} -On peut modifier le style |Comment.LaTeX| (avec |\SetPitonStyle|) pour faire afficher les commentaires -LaTeX (qui débutent par |#>|) en butée à droite. +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} +\PitonOptions{background-color=gray!15} ~emphase&\SetPitonStyle{Comment.LaTeX = \hfill \normalfont\color{gray}}@ \begin{Piton} def arctan(x,n=10): @@ -1862,7 +2239,7 @@ def arctan(x,n=10): \endgroup \begingroup -\PitonOptions{background-color=gray!10} +\PitonOptions{background-color=gray!15} \SetPitonStyle{Comment.LaTeX = \hfill \normalfont\color{gray}} \begin{Piton} def arctan(x,n=10): @@ -1876,16 +2253,16 @@ def arctan(x,n=10): \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 la clé |width|. Dans l'exemple qui suit, on utilise la clé |width| avec la valeur -spéciale~|min|. Plusieurs compilations sont nécessaires. +\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 la clé |width|. Dans l'exemple +qui suit, on utilise la clé |width| avec la valeur spéciale~|min|. Plusieurs compilations +sont nécessaires. \begingroup \fvset{commandchars=\~\&\@,formatcom=\small\color{gray}} \begin{Verbatim} -\PitonOptions{width=min, background-color=gray!10} +\PitonOptions{width=min, background-color=gray!15} ~emphase&\NewDocumentCommand{\MyLaTeXCommand}{m}{\hfill \normalfont\itshape\rlap{\quad #1}}@ ~emphase&\SetPitonStyle{Comment.LaTeX = \MyLaTeXCommand}@ \begin{Piton} @@ -1906,7 +2283,7 @@ def arctan(x,n=10): \begingroup -\PitonOptions{width = min, background-color=gray!10} +\PitonOptions{width = min, background-color=gray!15} \NewDocumentCommand{\MyLaTeXCommand}{m}{\hfill \normalfont\itshape\rlap{\quad #1}} \SetPitonStyle{Comment.LaTeX = \MyLaTeXCommand} \begin{Piton} @@ -1925,105 +2302,18 @@ def arctan(x,n=10): \bigskip -\subsection{Notes dans les listings} - -\index{notes dans les listings|emph} - -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 - - -\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}. +On présente ici un réglage de ces styles adapté pour les documents en noir et blanc. -Ce réglage utilise la commande |\highLight| de \pkg{lua-ul} (cette extension nécessite elle-même l'extension \pkg{luacolor}). +Ce réglage utilise la commande |\highLight| de \pkg{lua-ul} (cette extension nécessite +elle-même l'extension \pkg{luacolor}). \begin{Verbatim} -\setmonofont[Scale=0.85]{DejaVu Sans Mono} - \SetPitonStyle { Number = , @@ -2044,16 +2334,14 @@ Ce réglage utilise la commande |\highLight| de \pkg{lua-ul} (cette extension n \end{Verbatim} -Dans ce réglage, de nombreuses valeurs fournies aux clés sont vides, ce qui signifie que le style correspondant -n'insèrera aucune instruction de formatage (l'élément sera composé dans la couleur standard, le plus souvent, en noir, -etc.). Ces entrées avec valeurs nulles sont néanmoins nécessaires car la valeur initiale de ces styles dans -\pkg{piton} n'est \emph{pas} vide. +Dans ce réglage, de nombreuses valeurs fournies aux clés sont vides, ce qui signifie que +le style correspondant n'insèrera aucune instruction de formatage (l'élément sera composé +dans la couleur standard, le plus souvent, en noir, etc.). Ces entrées avec valeurs nulles +sont néanmoins nécessaires car la valeur initiale de ces styles dans \pkg{piton} n'est +\emph{pas} vide. \begingroup - -\setmonofont[Scale=0.85]{DejaVu Sans Mono} - \SetPitonStyle { Number = , @@ -2105,11 +2393,13 @@ def arctan(x,n=10): \label{pyluatex} \index{pyluatex@{\pkg{pyluatex}} (extension)} -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|). +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. +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} @@ -2129,12 +2419,12 @@ affiche également dessous le résultat de l'exécution de ce code avec Python. \ignorespacesafterend} -On a utilisé la fonction Lua |piton.get_last_code| fournie dans l'API de \pkg{piton} : cf.~partie~\ref{API}, -p.~\pageref{API}. + On a utilisé la fonction Lua |piton.get_last_code| fournie dans l'API de \pkg{piton} : + cf.~partie~\ref{API}, p.~\pageref{API}. \bigskip -Cet environnement |{PitonExecute}| prend en argument optionnel (entre crochets) les options proposées par la -commande |\PitonOptions|. +Cet environnement |{PitonExecute}| prend en argument optionnel (entre crochets) les +options proposées par la commande |\PitonOptions|. \begin{Verbatim} \begin{~emphase#PitonExecute@}[background-color=gray!15] @@ -2162,23 +2452,26 @@ print(f'Le carré de 12 est {carré(12)}.') \index{pythonrepl@\texttt{\{pythonrepl\}} (environnement de \pkg{pyluatex})} -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 renvoyées par Python (et de ce qui a été -demandé d'être affiché avec des \piton{print} de Python). +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 renvoyé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|). +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 (pour des raisons techniques, le -|!| est ici obligatoire dans la signature de l'environnement). On ne peut pas procéder comme précédemment (dans -l'utilisation «standard» de \pkg{pyluatex}) car, bien sûr, c'est le retour fait par |{pythonrepl}| qui doit être -traité par \pkg{piton}. De ce fait, il ne sera pas possible de mettre des surcharges (avec |detected-commands| ou -le mécanisme |escape|) dans le code. +Voici la programmation d'un environnement |{PitonREPL}| qui effectue ce travail (pour des +raisons techniques, le |!| est ici obligatoire dans la signature de l'environnement). On +ne peut pas procéder comme précédemment (dans l'utilisation «standard» de \pkg{pyluatex}) +car, bien sûr, c'est le retour fait par |{pythonrepl}| qui doit être traité par +\pkg{piton}. De ce fait, il ne sera pas possible de mettre des surcharges (avec +|detected-commands| ou le mécanisme |escape|) dans le code. \begin{Verbatim} \ExplSyntaxOn @@ -2187,7 +2480,7 @@ le mécanisme |escape|) dans le code. \PitonOptions { background-color=white, - ~emphase#prompt-background-color = gray!10@, + ~emphase#prompt-background-color = gray!15@, ~#1 } \PyLTVerbatimEnv @@ -2214,7 +2507,7 @@ Voici un exemple d'utilisation de ce nouvel environnement |{PitonREPL}|. \begin{Verbatim} ~emphase#\begin{PitonREPL}@ def valeur_absolue(x): - "Renvoie la valeur absolue de x" + """Renvoie la valeur absolue de x""" if x > 0: return x else: @@ -2231,7 +2524,7 @@ Voici un exemple d'utilisation de ce nouvel environnement |{PitonREPL}|. \ExplSyntaxOn \NewDocumentEnvironment { PitonREPL } { } { - \PitonOptions{background-color=white,prompt-background-color = gray!10} + \PitonOptions{background-color=white,prompt-background-color = gray!15} \PyLTVerbatimEnv \begin{pythonrepl} } @@ -2250,7 +2543,7 @@ Voici un exemple d'utilisation de ce nouvel environnement |{PitonREPL}|. \begin{PitonREPL} def valeur_absolue(x): - "Renvoie la valeur absolue de x" + """Renvoie la valeur absolue de x""" if x > 0: return x else: @@ -2263,11 +2556,12 @@ Voici un exemple d'utilisation de ce nouvel environnement |{PitonREPL}|. \bigskip -En fait, il est possible de ne pas faire afficher les prompts eux-mêmes (c'est-à-dire les chaînes de caractères -|>>>| et |...|). En effet, \pkg{piton} propose un style pour ces éléments, qui est appelé |Prompt|. Par défaut, la -valeur de ce style est vide, ce qui fait qu'aucune action n'est exécutée sur ces éléments qui sont donc affichés -tels quels. En fournissant comme valeur une fonction qui se contente de gober son argument, on peut demander à ce -qu'ils ne soient pas affichés. +En fait, il est possible de ne pas faire afficher les prompts eux-mêmes (c'est-à-dire les +chaînes de caractères |>>>| et |...|). En effet, \pkg{piton} propose un style pour ces +éléments, qui est appelé |Prompt|. Par défaut, la valeur de ce style est vide, ce qui fait +qu'aucune action n'est exécutée sur ces éléments qui sont donc affichés tels quels. En +fournissant comme valeur une fonction qui se contente de gober son argument, on peut +demander à ce qu'ils ne soient pas affichés. \bigskip \begin{savenotes} @@ -2292,7 +2586,7 @@ L'exemple précédent donne alors : \begin{Verbatim} ~emphase#\begin{PitonREPL}@ def valeur_absolue(x): - "Renvoie la valeur absolue de x" + """Renvoie la valeur absolue de x""" if x > 0: return x else: @@ -2308,7 +2602,7 @@ L'exemple précédent donne alors : \begin{PitonREPL} def valeur_absolue(x): - "Renvoie la valeur absolue de x" + """Renvoie la valeur absolue de x""" if x > 0: return x else: @@ -2328,62 +2622,72 @@ L'exemple précédent donne alors : \subsection{Le langage Python} -Le langage par défaut de l'extension \pkg{piton} est Python. Si besoin est, on peut revenir au langage Python avec -|\PitonOptions{language=Python}|. +Le langage par défaut de l'extension \pkg{piton} est Python. Si besoin est, on peut +revenir au langage Python avec |\PitonOptions{language=Python}|. \bigskip -Les réglages initiaux effectués par \pkg{piton} dans |piton.sty| sont inspirés par le style \pkg{manni} de Pygments -tel qu'il est appliqué au langage Python par 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}}|} +Les réglages initiaux effectués par \pkg{piton} dans |piton.sty| sont inspirés par le +style \pkg{manni} de Pygments tel qu'il est appliqué au langage Python par +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}}|} \vspace{1cm} \begin{center} -\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 (qui sont gérées par |String.Doc|)\\ - 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{\}}) ; ce style hérite des styles |String.Short| et |String.Long| (suivant la chaîne où - apparaît l'interpolation)\\ - Interpol.Inside & le contenu des interpolations dans les f-strings (c'est-à-dire les éléments qui se trouvent entre - \texttt{\{} et~\texttt{\}} ; si l'utilisateur n'a pas fixé ce style, ces éléments sont analysés et formatés par \pkg{piton} - au même titre que le reste du code. \\ - Operator & les opérateurs suivants : \texttt{!= == << >> - \~{} + / * \% = < > \& .} \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.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| \\ - Name.Function & le nom des fonctions définies par l'utilisateur \emph{au moment de leur définition} (après le - mot-clé |def|) \\ - UserFunction & le nom des fonctions précédemment définies par l'utilisateur (la valeur initiale de ce paramètre est - vide et ces éléments sont affichés en noir --- ou plutôt dans la couleur courante) \\ - Exception & les exceptions prédéfinies (ex.: \texttt{SyntaxError}) \\ - InitialValues & les valeurs initiales (et le symbole |=| qui précède) des arguments optionnels dans les définitions - de fonctions ; si l'utilisateur n'a pas fixé ce style, ces éléments sont analysés et formatés par \pkg{piton} - au même titre que le reste du code.\\ - Comment & les commentaires commençant par \texttt{\#} \\ - Comment.LaTeX & les commentaires commençant par \texttt{\#>} qui sont composés par \pkg{piton} comme du code LaTeX (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 et yield from.\\ - \bottomrule +\begin{tabularx}{\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 (qui sont gérées par |String.Doc|)\\ +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{\}}) ; ce style hérite des styles + |String.Short| et |String.Long| (suivant la chaîne où apparaît + l'interpolation)\\ +Interpol.Inside & le contenu des interpolations dans les f-strings (c'est-à-dire les + éléments qui se trouvent entre \texttt{\{} et~\texttt{\}}) ; si + l'utilisateur n'a pas fixé ce style, ces éléments sont analysés et + formatés par \pkg{piton} au même titre que le reste du code. \\ +Operator & les opérateurs suivants : \texttt{!= == << >> - \~{} + / * \% = < > \& .} + \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.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| \\ +Name.Function & le nom des fonctions définies par l'utilisateur \emph{au moment de leur + définition} (après le mot-clé |def|) \\ +UserFunction & le nom des fonctions précédemment définies par l'utilisateur (la valeur + initiale de ce paramètre est {\ttfamily \textbackslash + PitonStyle\{Identifier\}}, ce qui fait que ces noms de fonctions sont + affichés comme les identifiants) \\ +Exception & les exceptions prédéfinies (ex.: \texttt{SyntaxError}) \\ +InitialValues & les valeurs initiales (et le symbole |=| qui précède) des arguments + optionnels dans les définitions de fonctions ; si l'utilisateur n'a pas + fixé ce style, ces éléments sont analysés et formatés par \pkg{piton} + au même titre que le reste du code.\\ +Comment & les commentaires commençant par \texttt{\#} \\ +Comment.LaTeX & les commentaires commençant par \texttt{\#>} qui sont composés par + \pkg{piton} comme du code LaTeX (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, in, lambda, non local, + pass, raise, return, try, while, + with, yield et yield from.\\ +Identifier & les identificateurs. \\ +\bottomrule \end{tabularx} \end{center} @@ -2392,23 +2696,10 @@ tel qu'il est appliqué au langage Python par Pygments.\footnote{Voir \url{https \subsection{Le langage OCaml} -On peut basculer vers le langage |OCaml| avec |\PitonOptions{language = OCaml}| - -\bigskip -On peut aussi choisir le langage |OCaml| pour un environnement |{Piton}| individuel : -% -\begin{Verbatim} -\begin{Piton}~emphase#[language=OCaml]@ -... -\end{Piton} -\end{Verbatim} +On peut basculer vers le langage |OCaml| avec la clé |language| : |language = OCaml| \bigskip -L'option est aussi disponible pour |\PitonInputFile| : |\PitonInputFile[language=OCaml]{...}| - - -\vspace{1cm} \begin{center} @@ -2421,30 +2712,32 @@ L'option est aussi disponible pour |\PitonInputFile| : |\PitonInputFile[language String.Long & les chaînes de caractères, entre |"| mais aussi les \emph{quoted-strings} \\ String & cette clé fixe à la fois |String.Short| et |String.Long| \\ Operator & les opérateurs, en particulier |+|, |-|, |/|, |*|, |@|, |!=|, |==|, |&&| \\ - Operator.Word & les opérateurs suivants : |and|, |asr|, |land|, |lor|, |lsl|, |lxor|, |mod| et |or| \\ + Operator.Word & les opérateurs suivants : |asr|, |land|, |lor|, |lsl|, |lxor|, + |mod| et |or| \\ Name.Builtin & les fonctions |not|, |incr|, |decr|, |fst| et |snd| \\ Name.Type & le nom des types OCaml \\ Name.Field & le nom d'un champ de module \\ Name.Constructor & le nom des constructeurs de types (qui débutent par une majuscule) \\ Name.Module & le nom des modules \\ - Name.Function & le nom des fonctions définies par l'utilisateur \emph{au moment de leur définition} (après le - mot-clé |let|) \\ - UserFunction & le nom des fonctions précédemment définies par l'utilisateur - (la valeur initiale de ce paramètre est - vide et ces éléments sont affichés en noir --- ou plutôt dans la couleur courante) \\ + Name.Function & le nom des fonctions définies par l'utilisateur \emph{au moment de leur + définition} (après le mot-clé |let|) \\ + UserFunction & le nom des fonctions précédemment définies par l'utilisateur (la valeur + initiale de ce paramètre est {\ttfamily \textbackslash + PitonStyle\{Identifier\}}, ce qui fait que ces noms de fonctions sont + affichés comme les identifiants) \\ Exception & les exceptions prédéfinies (ex. : |End_of_File|) \\ TypeParameter & les paramétreurs de type \\ Comment & les commentaires, entre |(*| et |*)| ; ces commentaires peuvent être imbriqués \\ Keyword.Constant & |true| et |false| \\ Keyword & les mots-clés suivants : - |assert|, |as|, |begin|, |class|, |constraint|, |done|, - |downto|, |do|, |else|, |end|, |exception|, |external|, - |for|, |function|, |functor|, |fun| , |if| - |include|, |inherit|, |initializer|, |in| , |lazy|, |let|, - |match|, |method|, |module|, |mutable|, |new|, |object|, - |of|, |open|, |private|, |raise|, |rec|, |sig|, - |struct|, |then|, |to|, |try|, |type|, - |value|, |val|, |virtual|, |when|, |while| et |with| \\ + |assert|, |as|, |done|, |downto|, |do|, |else|, |exception|, |for|, |function| , + |fun|, |if|, |lazy|, |match|, |mutable|, |new|, |of|, |private|, |raise|, + |then|, |to|, |try| , |virtual|, |when|, |while| et |with| \\ + Keyword.Governing & les mot-clés suivants : |and|, |begin|, |class|, |constraint|, + |end|, |external|, |functor|, |include|, |inherit|, |initializer|, + |in|, |let|, |method|, |module|, |object|, |open|, |rec|, |sig|, + |struct|, |type| et |val|. \\ + Identifier & les identificateurs. \\ \bottomrule \end{tabularx} \end{center} @@ -2454,21 +2747,10 @@ L'option est aussi disponible pour |\PitonInputFile| : |\PitonInputFile[language \subsection[Le langage C (et C++)]{Le langage C (et \CC)} -On peut basculer vers le langage |C| avec |\PitonOptions{language = C}| +On peut basculer vers le langage |C| avec la clé |language| : |language = C| -\bigskip -On peut aussi choisir le langage |C| pour un environnement |{Piton}| individuel : -% -\begin{Verbatim} -\begin{Piton}~emphase#[language=C]@ -... -\end{Piton} -\end{Verbatim} \bigskip -L'option est aussi disponible pour |\PitonInputFile| : |\PitonInputFile[language=C]{...}| - -\vspace{1cm} \begin{center} \begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}} @@ -2477,29 +2759,37 @@ L'option est aussi disponible pour |\PitonInputFile| : |\PitonInputFile[language \midrule Number & les nombres \\ String.Long & les chaînes de caractères (entre \texttt{"}) \\ -String.Interpol & les éléments \texttt{\%d}, \texttt{\%i}, \texttt{\%f}, \texttt{\%c}, etc. dans les chaînes de - caractères ; ce style hérite du style |String.Long| \\ +String.Interpol & les éléments \texttt{\%d}, \texttt{\%i}, \texttt{\%f}, \texttt{\%c}, + etc. dans les chaînes de caractères ; ce style hérite du style + |String.Long| \\ Operator & les opérateurs suivants : \texttt{!= == << >> - \~{} + / * \% = < > \& .} \verb+|+ |@| \\ -Name.Type & les types prédéfinis suivants : - |bool|, |char|, |char16_t|, |char32_t|, |double|, |float|, |int|, |int8_t|, |int16_t|, |int32_t|, - |int64_t|, |long|, |short|, |signed|, |unsigned|, |void| et |wchar_t| \\ -Name.Builtin & les fonctions prédéfinies suivantes : |printf|, |scanf|, |malloc|, |sizeof| et |alignof| \\ - Name.Class & le nom des classes au moment de leur définition, c'est-à-dire après le mot-clé |class| \\ -Name.Function & le nom des fonctions définies par l'utilisateur \emph{au moment de leur définition} \\ -UserFunction & le nom des fonctions précédemment définies par l'utilisateur (la valeur initiale de ce paramètre est - vide et ces éléments sont affichés en noir --- ou plutôt dans la couleur courante) \\ +Name.Type & les types prédéfinis suivants : |bool|, |char|, |char16_t|, |char32_t|, + |double|, |float|, |int|, |int8_t|, |int16_t|, |int32_t|, |int64_t|, |long|, + |short|, |signed|, |unsigned|, |void| et |wchar_t| \\ +Name.Builtin & les fonctions prédéfinies suivantes : |printf|, |scanf|, |malloc|, |sizeof| + et |alignof| \\ +Name.Class & le nom des classes au moment de leur définition, c'est-à-dire après le + mot-clé |class| \\ +Name.Function & le nom des fonctions définies par l'utilisateur \emph{au moment de leur + définition} \\ +UserFunction & le nom des fonctions précédemment définies par l'utilisateur (la valeur + initiale de ce paramètre est {\ttfamily \textbackslash + PitonStyle\{Identifier\}}, ce qui fait que ces noms de fonctions sont + affichés comme les identifiants) \\ Preproc & les instructions du préprocesseur (commençant par |#|) \\ Comment & les commentaires (commençant par \texttt{//} ou entre |/*| et |*/|) \\ -Comment.LaTeX & les commentaires commençant par \texttt{//>} qui sont composés par \pkg{piton} comme du code LaTeX (et - appelés simplement «commentaires LaTeX» dans ce document) \\ +Comment.LaTeX & les commentaires commençant par \texttt{//>} qui sont composés par + \pkg{piton} comme du code LaTeX (et appelés simplement «commentaires + LaTeX» dans ce document) \\ Keyword.Constant & |default|, |false|, |NULL|, |nullptr| et |true| \\ -Keyword & les mots-clés suivants : -|alignas|, |asm|, |auto|, |break|, |case|, |catch|, |class|, -|constexpr|, |const|, |continue|, |decltype|, |do|, |else|, |enum|, -|extern|, |for|, |goto|, |if|, |nexcept|, |private|, |public|, |register|, |restricted|, |try|, -|return|, |static|, |static_assert|, |struct|, |switch|, |thread_local|, |throw|, -|typedef|, |union|, |using|, |virtual|, |volatile| et |while| +Keyword & les mots-clés suivants : |alignas|, |asm|, |auto|, |break|, |case|, |catch|, + |class|, |constexpr|, |const|, |continue|, |decltype|, |do|, |else|, |enum|, + |extern|, |for|, |goto|, |if|, |nexcept|, |private|, |public|, |register|, + |restricted|, |try|, |return|, |static|, |static_assert|, |struct|, |switch|, + |thread_local|, |throw|, |typedef|, |union|, |using|, |virtual|, |volatile| et + |while| \\ +Identifier & les identificateurs. \\ \bottomrule \end{tabularx} \end{center} @@ -2509,22 +2799,10 @@ Keyword & les mots-clés suivants : \subsection{Le langage SQL} -On peut basculer vers le langage |SQL| avec |\PitonOptions{language = SQL}| +On peut basculer vers le langage |SQL| avec la clé |language| : |language = SQL| -\bigskip -On peut aussi choisir le langage |SQL| pour un environnement |{Piton}| individuel : -% -\begin{Verbatim} -\begin{Piton}~emphase#[language=SQL]@ -... -\end{Piton} -\end{Verbatim} \bigskip -L'option est aussi disponible pour |\PitonInputFile| : |\PitonInputFile[language=SQL]{...}| - - -\vspace{1cm} \begin{center} \begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}} @@ -2534,35 +2812,72 @@ L'option est aussi disponible pour |\PitonInputFile| : |\PitonInputFile[language Number & les nombres \\ String.Long & les chaînes de caractères (entre \texttt{'} et non entre \texttt{"} car les éléments entre \texttt{"} sont des noms de champs et formatés avec |Name.Field|) \\ -Operator & les opérateurs suivants : -\texttt{= != <> >= > < <= * + / } \\ +Operator & les opérateurs suivants : \texttt{= != <> >= > < <= * + / } \\ Name.Table & les noms des tables \\ Name.Field & les noms des champs des tables \\ -Name.Builtin & les fonctions prédéfinies suivantes (leur nom n'est \emph{pas} sensible à la casse) : - |avg|, |count|, |char_lenght|, |concat|, |curdate|, |current_date|, - |date_format|, |day|, |lower|, |ltrim|, |max|, |min|, |month|, |now|, - |rank|, |round|, |rtrim|, |substring|, |sum|, |upper| et |year|. \\ +Name.Builtin & les fonctions prédéfinies suivantes (leur nom n'est \emph{pas} sensible à + la casse) : |avg|, |count|, |char_lenght|, |concat|, |curdate|, + |current_date|, |date_format|, |day|, |lower|, |ltrim|, |max|, |min|, + |month|, |now|, |rank|, |round|, |rtrim|, |substring|, |sum|, |upper| et + |year|. \\ Comment & les commentaires (débutant par |--| ou bien entre |/*| et |*/|) \\ -Comment.LaTeX & les commentaires commençant par \texttt{-->} qui sont composés par \pkg{piton} comme du code LaTeX (et - appelés simplement «commentaires LaTeX» dans ce document) \\ -Keyword & les mots-clés suivants (leur nom n'est \emph{pas} sensible à la casse) : - |add|, |after|, |all|, |alter|, |and|, |as|, |asc|, |between|, |by|, - |change|, |column|, |create|, |cross join|, |delete|, |desc|, |distinct|, - |drop|, |from|, |group|, |having|, |in|, |inner|, |insert|, |into|, |is|, - |join|, |left|, |like|, |limit|, |merge|, |not|, |null|, |on|, |or|, - |order|, |over|, |right|, |select|, |set|, |table|, |then|, |truncate|, - |union|, |update|, |values|, |when|, |where| et |with|. \\ +Comment.LaTeX & les commentaires commençant par \texttt{-->} qui sont composés par + \pkg{piton} comme du code LaTeX (et appelés simplement «commentaires + LaTeX» dans ce document) \\ +Keyword & les mots-clés suivants (leur nom n'est \emph{pas} sensible à la casse) : |add|, + |after|, |all|, |alter|, |and|, |as|, |asc|, |between|, |by|, |change|, + |column|, |create|, |cross join|, |delete|, |desc|, |distinct|, |drop|, |from|, + |group|, |having|, |in|, |inner|, |insert|, |into|, |is|, |join|, |left|, + |like|, |limit|, |merge|, |not|, |null|, |on|, |or|, |order|, |over|, |right|, + |select|, |set|, |table|, |then|, |truncate|, |union|, |update|, |values|, + |when|, |where| et |with|. \\ \bottomrule \end{tabularx} \end{center} \bigskip -Si on souhaite que les mots-clés soient capitalisés automatiquement, on peut modifier le style |Keywords| -localement pour le langage SQL avec l'instruction : +Si on souhaite que les mots-clés soient capitalisés automatiquement, on peut modifier le +style |Keywords| localement pour le langage SQL avec l'instruction : \begin{Verbatim} \SetPitonStyle~emphase#[SQL]@{Keywords = \bfseries \MakeUppercase} \end{Verbatim} +\newpage + +\subsection{Les langages définis par la commande \textbackslash NewPitonLanguage} + +\indexcommand{NewPitonLanguage} + +\vspace{1cm} +La commande |\NewPitonLanguage|, qui permet de définir de nouveaux langages en utilisant +la syntaxe de l'extension \pkg{listings}, a été présentée p.~\pageref{NewPitonLanguage}. + +Tous les langages définis avec la commande |\NewPitonLanguage| partagent les mêmes styles. + +\vspace{1cm} + +\begin{center} +\begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}} +\toprule +\normalfont Style & Usage \\ +\midrule +Number & les nombres \\ +String.Long & les chaînes de caractères définies dans |\NewPitonLanguage| par la clé + |morestring| \\ +Comment & les commentaires définis dans |\NewPitonLanguage| par la clé |morecomment| \\ +Comment.LaTeX & les commentaires qui sont composés par \pkg{piton} comme du code LaTeX (et + appelés simplement «commentaires LaTeX» dans ce document) \\ +Keyword & les mots-clés, définis dans |\NewPitonLanguage| par les clés |morekeywords| et + |moretexcs| (et également la clé |sensitive| qui indique si les mots-clés sont + sensibles à la casse) \\ +Directive & les directives définies dans |\NewPitonLanguage| par la clé |moredirectives| \\ +Tag & les «tags» définis par la clé |tag| (les lexèmes détectés à l'intérieur d'un tag + seront aussi composés avec leur propre style) \\ +Identifier & les identificateurs. \\ +\bottomrule +\end{tabularx} +\end{center} + \newpage @@ -2573,22 +2888,10 @@ localement pour le langage SQL avec l'instruction : \label{minimal} \index{minimal (langage «minimal»)} -On peut basculer vers le langage «|minimal|» avec |\PitonOptions{language = minimal}| +On peut basculer vers le langage «|minimal|» avec la clé |language| : |language = minimal| -\bigskip -On peut aussi choisir le langage «|minimal|» pour un environnement |{Piton}| individuel : -% -\begin{Verbatim} -\begin{Piton}~emphase#[language=minimal]@ -... -\end{Piton} -\end{Verbatim} \bigskip -L'option est aussi disponible pour |\PitonInputFile| : |\PitonInputFile[language=minimal]{...}| - - -\vspace{1cm} \begin{center} \begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}} @@ -2598,51 +2901,56 @@ L'option est aussi disponible pour |\PitonInputFile| : |\PitonInputFile[language Number & les nombres \\ String & les chaînes de caractères (qui sont entre \texttt{"}) \\ Comment & les commentaires (qui débutent par |#|) \\ -Comment.LaTeX & les commentaires commençant par \texttt{\#>} qui sont composés par \pkg{piton} comme du code LaTeX (et - appelés simplement «commentaires LaTeX» dans ce document) \\ +Comment.LaTeX & les commentaires commençant par \texttt{\#>} qui sont composés par + \pkg{piton} comme du code LaTeX (et appelés simplement «commentaires + LaTeX» dans ce document) \\ +Identifier & les identificateurs. \\ \bottomrule \end{tabularx} \end{center} \bigskip -Ce langage «|minimal|» est proposé par \pkg{piton} à l'utilisateur final pour qu'il puisse y ajouter des -formatages de mots-clés avec la commande |\SetPitonIdentifier| (cf. \ref{SetPitonIdentifier}, -p.~\pageref{SetPitonIdentifier}) et créer par exemple un langage pour pseudo-code. +Ce langage «|minimal|» est proposé par \pkg{piton} à l'utilisateur final pour qu'il puisse +y ajouter des formatages de mots-clés avec la commande |\SetPitonIdentifier| (cf. +\ref{SetPitonIdentifier}, p.~\pageref{SetPitonIdentifier}) et créer par exemple un langage +pour pseudo-code. +\vspace{2cm} -\newpage +\subsection{Le langage «verbatim»} -\subsection{Les langages définis par la commande \textbackslash NewPitonLanguage} -\indexcommand{NewPitonLanguage} +\label{verbatim} +\index{verbatim (langage «verbatim»)} -\vspace{1cm} -La commande |\NewPitonLanguage|, qui permet de définir de nouveaux langages en utilisant la syntaxe de l'extension -\pkg{listings}, a été présentée p.~\pageref{NewPitonLanguage}. -Tous les langages définis avec la commande |\NewPitonLanguage| partagent les mêmes styles. +\colorbox{yellow!50}{\textbf{Nouveau 4.1}} -\vspace{1cm} + +\bigskip + +On peut basculer vers le langage «|verbatim|» avec la clé |language| : |language = verbatim| + +\bigskip \begin{center} \begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}} \toprule \normalfont Style & Usage \\ \midrule -Number & les nombres \\ -String.Long & les chaînes de caractères définies dans |\NewPitonLanguage| par la clé |morestring| \\ -Comment & les commentaires définis dans |\NewPitonLanguage| par la clé |morecomment| \\ -Comment.LaTeX & les commentaires qui sont composés par \pkg{piton} comme du code LaTeX (et - appelés simplement «commentaires LaTeX» dans ce document) \\ -Keyword & les mots-clés, définis dans |\NewPitonLanguage| par les clés |morekeywords| et |moretexcs| (et également - la clé |sensitive| qui indique si les mots-clés sont sensibles à la casse) \\ -Directive & les directives définies dans |\NewPitonLanguage| par la clé |moredirectives| \\ -Tag & les «tags» définis par la clé |tag| (les lexèmes détectés à l'intérieur d'un tag seront - aussi composés avec leur propre style) \\ +\emph{rien...} & \\ \bottomrule \end{tabularx} \end{center} +\bigskip +Le language «|verbatim|» ne propose aucun style et ne fait donc aucun formatage +syntaxique. On peut néanmoins y utiliser le mécanisme |detected-commands| (cf. partie +\ref{detected-commands}, p.~\pageref{detected-commands}) ainsi que le +mécanisme de détection des commandes et des environnements de Beamer. + + + \newpage |