diff options
Diffstat (limited to 'Master/texmf-dist/doc/lualatex/piton/piton-french.tex')
-rw-r--r-- | Master/texmf-dist/doc/lualatex/piton/piton-french.tex | 264 |
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 |