summaryrefslogtreecommitdiff
path: root/macros/luatex/latex/piton/piton-french.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/latex/piton/piton-french.tex')
-rw-r--r--macros/luatex/latex/piton/piton-french.tex170
1 files changed, 146 insertions, 24 deletions
diff --git a/macros/luatex/latex/piton/piton-french.tex b/macros/luatex/latex/piton/piton-french.tex
index 1e074de47a..7a9c5f2adc 100644
--- a/macros/luatex/latex/piton/piton-french.tex
+++ b/macros/luatex/latex/piton/piton-french.tex
@@ -91,8 +91,8 @@ version~\myfileversion\space de \pkg{piton}, à la date du~\myfiledate.}}
\maketitle
\begin{abstract}
-L'extension \pkg{piton} propose des outils pour composer des codes informatiques en Python, OCaml et C avec une
-coloration syntaxique en utilisant la bibliothèque Lua LPEG. L'extension \pkg{piton} nécessite l'emploi de
+L'extension \pkg{piton} propose des outils pour composer des codes informatiques en Python, OCaml, C et SQL avec
+une coloration syntaxique en utilisant la bibliothèque Lua LPEG. L'extension \pkg{piton} nécessite l'emploi de
LuaLaTeX.
\end{abstract}
@@ -102,7 +102,7 @@ LuaLaTeX.
L'extension \pkg{piton} utilise la librairie Lua nommée LPEG\footnote{LPEG est une librairie de capture de motifs
(\emph{pattern-matching} en anglais) pour Lua, écrite en C, fondée sur les PEG (\emph{parsing expression
- grammars}): \url{http://www.inf.puc-rio.br/~roberto/lpeg/}} pour «parser» le code Python, OCaml ou C et le
+ grammars}): \url{http://www.inf.puc-rio.br/~roberto/lpeg/}} pour «parser» le code Python, OCaml, C ou SQL et le
composer avec un coloriage syntaxique. Comme elle utilise du code Lua, elle fonctionne uniquement avec |lualatex|
(et ne va pas fonctionner avec les autres moteurs de compilation LaTeX, que ce soit |latex|, |pdflatex| ou
|xelatex|). Elle n'utilise aucun programme extérieur et la compilation ne requiert donc pas |--shell-escape|. La
@@ -148,7 +148,7 @@ d'installer \pkg{piton} avec une distribution TeX comme MiKTeX, TeX~Live ou MacT
\subsection{Choix du langage}
-L'extension \pkg{piton} prend en charge trois langages informatiques : Python, OCaml et C, ou plutôt \CC.
+L'extension \pkg{piton} prend en charge quatre langages informatiques : Python, OCaml, SQL et C, ou plutôt \CC.
\smallskip
Par défaut, le language est Python.
@@ -201,7 +201,12 @@ environnements similaires à |{Piton}| en utilisant la commande |\NewPitonEnviro
\item La commande \colorbox{gray!20}{\ttfamily \textbackslash PitonInputFile} doit être utilisée pour insérer et
composer un fichier extérieur.
-Il est possible de n'insérer qu'une partie du fichier : cf. partie~\ref{part-of-a-file}, p.~\pageref{part-of-a-file}.
+Il est possible de n'insérer qu'une partie du fichier : cf. partie~\ref{part-of-a-file},
+p.~\pageref{part-of-a-file}.
+
+\colorbox{yellow!50}{\textbf{Nouveau 2.2}}\enskip La clé |path| de la commande |\PitonOptions| permet de spécifier
+un chemin de recherche pour le fichier à inclure. En fait, on peut spécifier plusieurs chemins, séparés par des
+virgules.
\end{itemize}
@@ -308,7 +313,10 @@ Ces clés peuvent aussi être appliquées à un environnement |{Piton}| individu
\begin{itemize}
\item La clé \Definition{language} spécifie le langage informatique considéré (la casse n'est pas prise en compte).
-Trois valeurs sont possibles : |Python|, |OCaml| et |C|. La valeur initiale est |Python|.
+Quatre valeurs sont possibles : |Python|, |OCaml|, |C| et |SQL|. La valeur initiale est |Python|.
+
+\item La clé \Definition{path} indique un chemin où seront cherchés prioritairement les fichiers inclus par
+|\PitonInputFile|. En fait, on peut spécifier plusieurs chemins, séparés par des virgules.
\item La clé \Definition{gobble} prend comme valeur un entier positif $n$ : les $n$ premiers caractères de chaque
ligne sont alors retirés (avant formatage du code) dans les environnements |{Piton}|. Ces $n$ caractères ne sont
@@ -339,7 +347,7 @@ soient affichés. Si la clé \verb|/skip-empty-lines| est active, la clé \verb|
valeur initiale de cette clé est \verb|true|.
\item La clé \Definition{line-numbers/absolute} demande, pour les listings générés par \verb|\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 insère qu'une
+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. part~\ref{part-of-a-file}, p.~\pageref{part-of-a-file}). La clé |/absolute| est sans effet dans les environnements \verb|{Piton}|.
\item La clé \Definition{line-numbers/resume} reprend la numérotation là où elle avait été laissée au dernier listing. En fait,
@@ -415,9 +423,9 @@ caractère U+2423 doit être présent dans la fonte mono-chasse utilisée.\footn
Exemple : \piton{my_string = 'Très bonne réponse'}
\endgroup
-\smallskip
-Avec la clé \Definition{show-spaces}, tous les espaces sont matérialisés (et aucune coupure de ligne ne peut plus
-intervenir sur ces espaces matérialisés, même si la clé |break-lines|\footnote{cf. \ref{line-breaks} p.~\pageref{line-breaks}.} est active).
+\item 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).
\end{itemize}
\bigskip
@@ -478,6 +486,8 @@ pages et des lignes p.~\pageref{breakable}).
\label{styles}
+\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.}
@@ -513,11 +523,9 @@ Avec ce réglage, on obtient : \piton{def cube(x) : return x * x * x }
\bigskip
-Les différents styles sont décrits dans la table \ref{Semantic}. Les réglages initiaux effectués par \pkg{piton}
-dans |piton.sty| sont inspirés par le style \pkg{manni} de Pygments.\footnote{Voir
- \url{https://pygments.org/styles/}. À remarquer que, par défaut, Pygments propose pour le style \pkg{manni} un
- fond coloré dont la couleur est la couleur HTML |#F0F3F3|. Il est possible d'avoir la même couleur dans |{Piton}|
- avec l'instruction : |\PitonOptions{background-color = [HTML]{F0F3F3}}|}
+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
@@ -533,12 +541,50 @@ La syntaxe |{\PitonStyle{|\textsl{\texttt{style}}|}{...}}| est nécessaire pour
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.
+
+\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.) seront composés en gris.
+
\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 via une instruction Python \piton{def} dans l'un des listings précédents. 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|.
+\colorbox{yellow!50}{\textbf{Nouveau 2.2}}\enskip 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}
+\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 minuscule 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 à la notion de liaison locale de TeX (notion de groupe TeX).
+
+\medskip
+Les styles fournis par défaut par \pkg{piton} sont tous définis globalement.
+
+\bigskip
+\subsubsection{Le style UserFunction}
+
+\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|.
\medskip
@@ -571,12 +617,18 @@ def passe(v):
Comme on le voit, le nom |transpose| a été mis en évidence comme étant le nom d'une fonction définie précédemment
par l'utilisateur (d'où le nom |UserFunction| pour ce style).
-\PitonClearUserFunctions
+\PitonClearUserFunctions[Python]
\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 |\PitonClearUserFunctions|.
+vider cette liste : c'est la commande |\PitonClearUserFunctions|. Quand elle est utilisée sans argument, cette
+commande s'applique à tous les languages informatiques utilisées par l'utilisateur mais on peut spécifier en
+argument optionnel (entre crochets) une liste de languages informatiques auquels elle s'appliquera.\footnote{On
+ rappelle que, dans \pkg{piton}, les noms des langages informatiques ne sont pas sensibles à la casse. }
+\end{small}
+
\subsection{Définition de nouveaux environnements}
@@ -585,7 +637,8 @@ vider cette liste : c'est la commande |\PitonClearUserFunctions|.
Comme l'environnement |{Piton}| a besoin d'absorber son contenu d'une manière spéciale (à peu près comme du texte
verbatim), il n'est pas possible de définir de nouveaux environnements directement au-dessus de l'environnement
-|{Piton}| avec les commandes classiques |\newenvironment| et |\NewDocumentEnvironment|.
+|{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|.
@@ -850,7 +903,8 @@ structuré correctement!):
\subsection{Mise en évidence d'identificateurs}
On peut demander le changement de formatage de certains identificateurs avec la clé |identifiers| de
-|\PitonOptions|.
+|\PitonOptions|.\footnote{Cette fonctionnalité n'est pas disponible avec le langage SQL car, en SQL, il n'y a pas
+ d'identificateurs (il n'y a que des noms de tables et des noms de champs).}
\smallskip
Cette clé prend en argument une valeur au format suivant :
@@ -1961,8 +2015,17 @@ L'exemple précédent donne alors :
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 language 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
@@ -2023,6 +2086,10 @@ On peut aussi choisir le langage |OCaml| pour un environnement |{Piton}| individ
\end{Verbatim}
+\bigskip
+L'option est aussi disponible pour |\PitonInputFile| : |\PitonInputFile[language=OCaml]{...}|
+
+
\vspace{1cm}
@@ -2080,6 +2147,8 @@ On peut aussi choisir le langage |C| pour un environnement |{Piton}| individuel
\end{Piton}
\end{Verbatim}
+\bigskip
+L'option est aussi disponible pour |\PitonInputFile| : |\PitonInputFile[language=C]{...}|
\vspace{1cm}
@@ -2117,6 +2186,59 @@ Keyword & les mots-clés suivants :
\end{tabularx}
\end{center}
+
+\newpage
+
+\subsection{Le langage SQL}
+
+On peut basculer vers le langage |SQL| avec |\PitonOptions{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@{}}
+\toprule
+\normalfont Style & Usage \\
+\midrule
+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{= != <> >= > < <= * + / } \\
+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|. \\
+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|. \\
+\bottomrule
+\end{tabularx}
+\end{center}
+
+
\newpage
\section*{Autre documentation}