summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/lualatex/piton/piton-french.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/lualatex/piton/piton-french.tex')
-rw-r--r--Master/texmf-dist/doc/lualatex/piton/piton-french.tex264
1 files changed, 210 insertions, 54 deletions
diff --git a/Master/texmf-dist/doc/lualatex/piton/piton-french.tex b/Master/texmf-dist/doc/lualatex/piton/piton-french.tex
index 47be2f57abf..6041a29e08c 100644
--- a/Master/texmf-dist/doc/lualatex/piton/piton-french.tex
+++ b/Master/texmf-dist/doc/lualatex/piton/piton-french.tex
@@ -126,6 +126,8 @@ d'installer \pkg{piton} avec une distribution TeX comme MiKTeX, TeX~Live ou MacT
\section{Utilisation de l'extension}
+\subsection{Chargement de l'extension}
+
L'extension \pkg{piton} se charge simplement avec la commande |\usepackage| : |\usepackage{piton}|.
On a néanmoins deux remarques à formuler :
@@ -137,29 +139,106 @@ On a néanmoins deux remarques à formuler :
|pdflatex| ou |xelatex|) est utilisé, une erreur fatale sera levée.
\end{itemize}
+\subsection{Les commandes et environnements à la disposition de l'utilisateur}
-\medskip
-L'extension \pkg{piton} fournit trois outils pour composer du code Python: la commande |\piton|, l'environnement
-|{Piton}| et la commande |\PitonInputFile|.
+L'extension \pkg{piton} fournit plusieurs outils pour composer du code Python: les commandes |\piton|,
+l'environnement |{Piton}| et la commande |\PitonInputFile|.
-\begin{itemize}
-\item La commande |\piton| doit être utilisée pour composer de petits éléments de code à l'intérieur d'un
-paragraphe. \emph{Attention} : Cette fonction prend son argument en mode \emph{verbatim} (comme la commande
-\verb|\verb|) et, de ce fait, cette fonction ne peut pas être utilisée à l'intérieur d'un argument d'une autre
-fonction (on peut néanmoins l'utiliser à l'intérieur d'un environnement).
+\begin{itemize} \setlength{\fboxsep}{1pt}
+\item La commande \colorbox{gray!20}{\ttfamily \textbackslash piton} doit être utilisée pour composer de petits éléments de code à l'intérieur d'un
+paragraphe. Par exemple :
+
+{\color{gray}\verb|\piton{def carré(x): return x*x}|}\qquad
+\piton{def carré(x): return x*x}
+
+La syntaxe et les particularités de la commande sont détaillées ci-après.
-\item L'environnement |{Piton}| doit être utilisé pour composer des codes de plusieurs lignes. Pour les besoins de
-personnalisation, il est possible de définir de nouveaux environnements similaires à |{Piton}| en utilisant la
-commande |\NewPitonEnvironment| : cf. partie \ref{NewPitonEnvironment} p.~\pageref{NewPitonEnvironment}.
-\item La commande |\PitonInputFile| doit être utilisée pour insérer et composer un fichier extérieur.
+\item L'environnement \colorbox{gray!20}{\ttfamily \{Piton\}} doit être utilisé pour composer des codes de
+plusieurs lignes. Comme cet environnement prend son argument selon un mode verbatim, il ne peut pas être utilisé
+dans l'argument d'une commande LaTeX. Pour les besoins de personnalisation, il est possible de définir de nouveaux
+environnements similaires à |{Piton}| en utilisant la commande |\NewPitonEnvironment| : cf. partie
+\ref{NewPitonEnvironment} p.~\pageref{NewPitonEnvironment}.
-\colorbox{yellow!50}{\textbf{Nouveau 0.95}}\enskip La commande |\PitonInputFile| prend en argument optionnel entre
-crochets deux clés |first-line| et |last-line| qui permettent de n'insérer que la partie du fichier comprise entre
-les lignes correspondantes.
+\item La commande \colorbox{gray!20}{\ttfamily \textbackslash PitonInputFile} doit être utilisée pour insérer et
+composer un fichier extérieur.
+
+Cette commande prend en argument optionnel entre crochets deux clés |first-line| et |last-line| qui permettent de
+n'insérer que la partie du fichier comprise entre les lignes correspondantes.
\end{itemize}
+\subsection{La syntaxe de la commande \textbackslash piton}
+
+
+La commande |\piton| possède en fait une syntaxe double. Elle est peut être utilisée comme une commande standard de
+LaTeX prenant son argument entre accolades (|\piton{...}|), ou bien selon la syntaxe de la commande |\verb| où l'argument est
+délimité entre deux caractères identiques (par ex. : \verb!\piton|...|!). On détaille maintenant ces deux syntaxes.
+
+\bigskip
+\begin{itemize}
+\item {\color{blue} \textsf{Syntaxe} \verb|\piton{...}|}\par\nobreak
+
+Quant son argument est donné entre accolades, la commande |\piton| ne prend pas son argument en mode verbatim. Les
+points suivants doivent être remarqués :
+
+\begin{itemize}
+\item plusieurs espaces successifs sont remplacés par un unique espace ;
+\item il n'est pas possible d'utiliser le caractère |%| à l'intérieur ;
+\item les accolades doivent apparaître par paires correctement imbriquées;
+\item les commandes LaTeX (celles commençant par une contre-oblique |\| mais également les caractères actifs) sont
+complètement développées (mais non exécutées).
+\end{itemize}
+
+Un mécanisme d'échappement est fourni : les commandes |\\|, |\%|, |\{| et |\}| insèrent les caractères
+correspondants |\|, |%|,
+|{| et |}|. Ces deux dernières commandes ne sont nécessaires que si on a besoin d'insérer des accolades
+non équilibrées.
+
+Les autres caractères (y compris |#|, |^|, |_|, |&|, |$| % $
+et |@|) doivent être insérés sans contre-oblique.
+
+Exemples :
+
+\begin{tabular}{>{\color{gray}}l@{\hspace*{1cm}}l}
+\verb|\piton{ma_chaîne = '\\n'}| &
+\piton{ma_chaîne = '\\n' } \\
+\verb|\piton{def pair(n): return n\%2==0}| &
+\piton{def pair(n): return n\%2==0 } \\
+\verb|\piton{c="#" # une affectation }| &
+\piton{c="#" # une affectation } \\
+\verb|\piton{my_dict = {'a': 3, 'b': 4}}| &
+\piton{my_dict = {'a': 3, 'b': 4}}
+\end{tabular}
+
+\smallskip
+La commande |\piton| avec son argument entre accolades peut être utilisée dans les arguments des autres commandes LaTeX.\footnote{La commande
+ |\piton| peut par exemple être
+ utilisée dans une note de bas de page. Exemple : \piton{s = 'Une chaîne'}.}
+
+\bigskip
+\item {\color{blue} \textsf{Syntaxe} \verb!\piton|...|!}\par\nobreak
+
+Quand la commande |\piton| prend son argument entre deux caractères identiques, cet argument est pris \emph{en mode
+ verbatim}. De ce fait, avec cette syntaxe, la commande |\piton| ne peut \emph{pas} être utilisée dans l'argument d'une
+autre fonction.
+
+\medskip
+Exemples :
+
+\begin{tabular}{>{\color{gray}}l@{\hspace*{1cm}}l}
+\verb!\piton|ma_chaîne = '\n'|! &
+\piton|ma_chaîne = '\n'| \\
+\verb|\piton!def pair(n): return n%2==0!| &
+\piton!def pair(n): return n%2==0! \\
+\verb|\piton+c="#" # une affectation +| &
+\piton+c="#" # une affectation + \\
+\verb|\piton?my_dict = {'a': 3, 'b': 4}?| &
+\piton!my_dict = {'a': 3, 'b': 4}!
+\end{tabular}
+
+\end{itemize}
+
\section{Personnalisation}
\subsection{La commande \textbackslash PitonOptions}
@@ -192,41 +271,25 @@ par la commande |\PitonInputFile|.
avec l'une des clés |line-numbers| et |all-line-numbers| si on ne souhaite pas que les numéros de ligne soient dans
une position en débordement sur la gauche.
-\colorbox{yellow!50}{\textbf{Nouveau 0.95}}\enskip Il est possible de donner à la clé |left-margin| la valeur
-spéciale~|auto|. Avec cette valeur, une marge est insérée automatiquement pour les numéros de ligne quand l'une des
-clés |line-numbers| ou |all-line-numbers| est utilisée. Voir un exemple à la partie \ref{example-numbering}
-p.~\pageref{example-numbering}.
+Il est possible de donner à la clé |left-margin| la valeur spéciale~|auto|. Avec cette valeur, une marge est
+insérée automatiquement pour les numéros de ligne quand l'une des clés |line-numbers| ou |all-line-numbers| est
+utilisée. Voir un exemple à la partie \ref{example-numbering} p.~\pageref{example-numbering}.
\item Avec la clé |resume|, le compteur de lignes n'est pas remis à zéro comme il l'est normalement au début d'un
environnement |{Piton}| ou bien au début d'un listing produit par |\PitonInputFile|. Cela permet de poursuivre la
numérotation d'un environnement à l'autre.
-\item La clé |splittable| autorise un saut de page dans les environnements |{Piton}| et les listings produits par
-|\PitonInputFile|.
-
-\smallskip
-On peut donner comme valeur à la clé |splittable| un entier naturel~$n$. Avec une telle valeur, les environnements
-|{Piton}| et les listings produits par |\PitonInputFile| sont sécables mais aucune coupure ne pourra avoir lieu
-entre les $n$~premières lignes, ni entre les $n$~dernières. La valeur par défaut de la clé |splittable| vaut en
-fait $1$, qui autorise les sauts de page partout.
-
\item La clé |background-color| fixe la couleur de fond des environnements |{Piton}| et des listings produits par
-|\PitonInputFile| (ce fond a une largeur égale à la valeur courante de |\linewidth|). Même avec une couleur de
-fond, les sauts de page sont possibles, à partir du moment où la clé |splittable| est utilisée.\footnote{Avec la
- clé |splittable|, un environnement |{Piton}| est sécable même dans un environnement de \pkg{tcolorbox} (à partir
- du moment où la clé |breakable| de \pkg{tcolorbox} est utilisée). On précise cela parce que, en revanche, un
- environnement de \pkg{tcolorbox} inclus dans un autre environnement de \pkg{tcolorbox} n'est pas sécable, même
- quand les deux utilisent la clé |breakable|.}
-\item \colorbox{yellow!50}{\textbf{Nouveau 0.95}}\enskip En activant la clé |show-spaces|, les espaces dans
-les chaînes courtes (c'est-à-dire celles délimitées par |'| ou |"|) sont matérialisés par le caractère ␣ (U+2423 :
-\textsc{open box}). Bien sûr, le caractère U+2423 doit être présent dans la fonte mono-chasse
-utilisée.\footnote{L'extension \pkg{piton} utilise simplement la fonte mono-chasse courante. Pour la changer, le
- mieux est d'utiliser |\setmonofont| de \pkg{fontspec}.}
-
+|\PitonInputFile| (ce fond a une largeur égale à la valeur courante de |\linewidth|).
+\item En activant la clé |show-spaces|, les espaces dans les chaînes courtes (c'est-à-dire celles délimitées par
+|'| ou |"|) sont matérialisés par le caractère ␣ (U+2423 : \textsc{open box}). Bien sûr, le caractère U+2423 doit
+être présent dans la fonte mono-chasse utilisée.\footnote{L'extension \pkg{piton} utilise simplement la fonte
+ mono-chasse courante. Pour la changer, le mieux est d'utiliser |\setmonofont| de \pkg{fontspec}.}\par\nobreak
+%
\begingroup
\PitonOptions{show-spaces}
-Exemple : \piton|my_string = 'Très bonne réponse'|
+Exemple : \piton{my_string = 'Très bonne réponse'}
\endgroup
\end{itemize}
@@ -282,6 +345,11 @@ Exemple : \piton|my_string = 'Très bonne réponse'|
\endgroup
+\bigskip
+La commande |\PitonOptions| propose d'autres clés qui seront décrites plus loin (voir en particulier la coupure des
+pages et des lignes p.~\pageref{breakable}).
+
+
\subsection{Les styles}
\label{styles}
@@ -425,10 +493,9 @@ caractères, et jusqu'à la fin de la ligne, sera composé comme du code LaTeX s
Il y a deux outils pour personnaliser ces commentaires.
\begin{itemize}
-\item \colorbox{yellow!50}{\bfseries Nouveau 0.95}\enskip Il est possible de changer le marquage syntaxique utilisé
-(qui vaut initialement~|#>|). Pour ce faire, il existe une clé |comment-latex|, disponible seulement au chargement
-de \pkg{piton} (c'est-à-dire au moment du |\usepackage|), qui permet de choisir les caractères qui (précédés
-par~|#|) serviront de marqueur syntaxique.
+\item Il est possible de changer le marquage syntaxique utilisé (qui vaut initialement~|#>|). Pour ce faire, il
+existe une clé |comment-latex|, disponible seulement au chargement de \pkg{piton} (c'est-à-dire au moment du
+|\usepackage|), qui permet de choisir les caractères qui (précédés par~|#|) serviront de marqueur syntaxique.
Par exemple, avec le chargement suivant :
@@ -446,6 +513,13 @@ fait des «commentaires LaTeX».
Par exemple, avec |\SetPitonStyle{Comment.LaTeX = \normalfont\color{blue}}|, les commentaires LaTeX seront composés
en bleu.
+Si on souhaite qu'un croisillon (|#|) soit affiché en début de commantaire dans le \textsc{pdf}, on peut régler
+|Comment.LaTeX| de la manière suivante :
+
+\begin{Verbatim}
+\SetPitonStyle{Comment.LaTeX = \color{gray}\~#\normalfont\space }
+\end{Verbatim}
+
Pour d'autres exemples de personnalisation des commentaires LaTeX, voir la partie \ref{example-comments}
p.~\pageref{example-comments}.
\end{itemize}
@@ -453,9 +527,9 @@ p.~\pageref{example-comments}.
\subsubsection{La clé «math-comments»}
-\colorbox{yellow!50}{\textbf{Nouveau 0.95}}\enskip Il est possible de demander que, dans les commentaires Python
-normaux, c'est-à-dire débutant par |#| (et non par |#>|), les élements 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é |math-comments|, qui n'est disponible qu'au chargement de \pkg{piton} (c'est-à-dire au moment du
|\usepackage|), active ce comportement.
@@ -478,11 +552,11 @@ def carré(x):
\subsubsection{Le mécanisme «espace-inside»}
-Il est aussi possible de surcharger les listings Python pour y insérer du code LaTeX à peu près n'importe où. Cette
-fonctionnalité n'est pas activée par défaut par \pkg{piton}. Pour l'utiliser, il faut spécifier les deux caractères
-marquant l'échappement (le premier le commençant et le deuxième le terminant) en utilisant la clé |escape-inside|
-au chargement de \pkg{piton} (c'est-à-dire au moment du |\usepackage|). Les deux caractères peuvent être
-identiques.
+Il est aussi possible de surcharger les listings Python pour y insérer du code LaTeX à peu près n'importe où (mais
+entre deux lexèmes, bien entendu). Cette fonctionnalité n'est pas activée par défaut par \pkg{piton}. Pour
+l'utiliser, il faut spécifier les deux caractères marquant l'échappement (le premier le commençant et le deuxième
+le terminant) en utilisant la clé |escape-inside| au chargement de \pkg{piton} (c'est-à-dire au moment du
+|\usepackage|). Les deux caractères peuvent être identiques.
\bigskip
@@ -520,6 +594,88 @@ c'est-à-dire ce qui est
appelé dans ce document «commentaire LateX», il suffit de le faire débuter par |#>|).
+\bigskip
+\subsection{Coupure des pages et des lignes}
+
+\label{breakable}
+
+\subsubsection{Coupure des pages}
+
+Par défaut les listings produits par l'environnement |{Piton}| et par la commande |\PitonInputFile| sont
+insécables.
+
+Néanmoins, la commande |\PitonOptions| propose la clé |splittable| pour autoriser et autoriser de telles coupures.
+
+\begin{itemize}
+\item Si la clé |splittable| est utilisée sans valeur, les listings sont sécables n'importe où.
+
+\item Si la clé |splittable| est utilisée avec une valeur numérique $n$ (qui doit être un entier naturel non nul),
+alors les listings seront sécables mais aucune coupure ne pourra avoir lieu entre les $n$~premières lignes, ni
+entre les $n$~dernières. De ce fait, |splittable=1| est équivalent à |splittable|.
+\end{itemize}
+
+\medskip
+\emph{Remarque}\par\nobreak
+
+Même avec une couleur de fond (fixée avec |background-color|), les sauts de page sont possibles, à partir du moment
+où la clé |splittable| est utilisée.\footnote{Avec la clé |splittable|, un environnement |{Piton}| est sécable même dans un environnement de
+ \pkg{tcolorbox} (à partir du moment où la clé |breakable| de \pkg{tcolorbox} est utilisée). On précise cela parce
+ que, en revanche, un environnement de \pkg{tcolorbox} inclus dans un autre environnement de \pkg{tcolorbox} n'est
+ pas sécable, même quand les deux utilisent la clé |breakable|.}
+
+\subsubsection{Coupure des lignes}
+
+Par défaut les lignes dans les listings produits par |{Piton}| et commande |\PitonInputFile| ne
+sont pas sécables.
+
+\medskip
+\colorbox{yellow!50}{\textbf{Nouveau 0.99}}\enskip Il existe néanmoins des clés (disponibles dans |\PitonOptions|)
+pour autoriser ces coupures.
+
+\begin{itemize}
+\item La clé |break-lines| active la coupure des lignes. Les seuls points de coupure possibles sont les espaces (y compris
+dans les chaînes de caractères).
+
+\item Avec la clé |indent-broken-lines|, l'indentation de la ligne coupée est respectée à chaque retour à la ligne.
+
+\item La clé |end-of-broken-line| correspond au symbole placé à la fin d'une ligne coupée. Sa valeur initiale est :
+|\hspace*{0.5em}\textbackslash|.
+
+\item La clé |continuation-symbol| correspond au symbole placé à chaque retour de ligne dans la marge gauche. Sa
+valeur initiale est : |+\;|.
+
+\item La clé |continuation-symbol-on-indentation| correspond au symbole placé à chaque retour de ligne au niveau de
+l'indentation (uniquement dans le cas où la clé |indent-broken-lines| est active). Sa valeur initiale est :
+|$\hookrightarrow\;$|.
+\end{itemize}
+
+\bigskip
+Le code suivant a été composé dans une |{minipage}| de largeur 12~cm avec le réglage suivant :
+
+\begin{Verbatim}
+\PitonOptions{break-lines,indent-broken-lines,background-color=gray!15}
+\end{Verbatim}
+
+\begin{center}
+\PitonOptions{break-lines,indent-broken-lines,background-color=gray!15}
+\begin{minipage}{12cm}
+\begin{Piton}
+def dict_of_liste(liste):
+ """Convertit une liste de subrs et de descriptions de glyphes en dictionnaire"""
+ dict = {}
+ for liste_lettre in liste:
+ if (liste_lettre[0][0:3] == 'dup'): # si c'est un subr
+ nom = liste_lettre[0][4:-3]
+ print("On traite le subr de numéro " + nom)
+ else:
+ nom = liste_lettre[0][1:-3] # si c'est un glyphe
+ print("On traite le glyphe du caractère " + nom)
+ dict[nom] = [traite_ligne_Postscript(k) for k in liste_lettre[1:-1]]
+ return dict
+\end{Piton}
+\end{minipage}
+\end{center}
+
\bigskip
\subsection{Notes de pied de page dans les environnements de piton}
@@ -912,7 +1068,7 @@ def arctan(x,n=10):
\section{Utilisation avec pyluatex}
-L'extension \pkg{pyluatex} est une extension iqui permet l'exécution de code Python à partir |lualatex| (pourvu
+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