diff options
Diffstat (limited to 'macros/luatex/latex/piton/piton-french.tex')
-rw-r--r-- | macros/luatex/latex/piton/piton-french.tex | 170 |
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} |