texlive[65143] Master/texmf-dist: piton (29nov22)
commits+karl at tug.org
commits+karl at tug.org
Tue Nov 29 22:09:19 CET 2022
Revision: 65143
http://tug.org/svn/texlive?view=revision&revision=65143
Author: karl
Date: 2022-11-29 22:09:19 +0100 (Tue, 29 Nov 2022)
Log Message:
-----------
piton (29nov22)
Modified Paths:
--------------
trunk/Master/texmf-dist/doc/lualatex/piton/piton-french.pdf
trunk/Master/texmf-dist/doc/lualatex/piton/piton-french.tex
trunk/Master/texmf-dist/doc/lualatex/piton/piton.pdf
trunk/Master/texmf-dist/source/lualatex/piton/piton.dtx
trunk/Master/texmf-dist/tex/lualatex/piton/piton.sty
Modified: trunk/Master/texmf-dist/doc/lualatex/piton/piton-french.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/lualatex/piton/piton-french.tex
===================================================================
--- trunk/Master/texmf-dist/doc/lualatex/piton/piton-french.tex 2022-11-29 21:09:04 UTC (rev 65142)
+++ trunk/Master/texmf-dist/doc/lualatex/piton/piton-french.tex 2022-11-29 21:09:19 UTC (rev 65143)
@@ -126,6 +126,8 @@
\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 @@
|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} \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 \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}.
+
+\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 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).
+\item {\color{blue} \textsf{Syntaxe} \verb|\piton{...}|}\par\nobreak
-\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}.
+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 :
-\item La commande |\PitonInputFile| doit être utilisée pour insérer et composer un fichier extérieur.
+\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}
-\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.
+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 @@
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 @@
\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 @@
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 @@
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 @@
\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 @@
\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,8 +594,90 @@
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}
\label{footnote}
@@ -912,7 +1068,7 @@
\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
Modified: trunk/Master/texmf-dist/doc/lualatex/piton/piton.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/source/lualatex/piton/piton.dtx
===================================================================
--- trunk/Master/texmf-dist/source/lualatex/piton/piton.dtx 2022-11-29 21:09:04 UTC (rev 65142)
+++ trunk/Master/texmf-dist/source/lualatex/piton/piton.dtx 2022-11-29 21:09:19 UTC (rev 65143)
@@ -15,8 +15,8 @@
%
% \fi
% \iffalse
-\def\myfileversion{0.95}
-\def\myfiledate{2022/11/09}
+\def\myfileversion{0.99}
+\def\myfiledate{2022/11/29}
%
%
%<*batchfile>
@@ -135,6 +135,9 @@
%
% \section{Use of the package}
%
+%
+% \subsection{Loading the package}
+%
% The package \pkg{piton} should be loaded with the classical command
% |\usepackage|: |\usepackage{piton}|.
%
@@ -149,28 +152,106 @@
% fatal error will be raised.
% \end{itemize}
%
-% \medskip
-% The package \pkg{piton} provides three tools to typeset Python code: the
+% \subsection{The tools provided to the user}
+%
+% The package \pkg{piton} provides several tools to typeset Python code: the
% command |\piton|, the environment |{Piton}| and the command |\PitonInputFile|.
%
-% \begin{itemize}
-% \item The command |\piton| should be used to typeset small pieces of code
-% inside a paragraph. \emph{Caution}: That fonction takes in its argument
-% \emph{verbatim}. Therefore, it cannot be used in the argument of another
-% command (however, it can be used within an environment).
-% \item The environment |{Piton}| should be used to typeset multi-lines code.
-% For sake of customization, it's possible to define new environments similar to
-% the environment |{Piton}| with the command |\NewPitonEnvironment|:
+% \begin{itemize}\setlength{\fboxsep}{1pt}
+% \item The command \colorbox{gray!20}{\texttt\textbackslash piton} should be
+% used to typeset small pieces of code inside a paragraph. For example:
+%
+% {\color{gray}\verb|\piton{def square(x): return x*x}|}\qquad
+% \piton{def square(x): return x*x}
+%
+% The syntax and particularities of the command |\piton| are detailed below.
+%
+% \item The environment \colorbox{gray!20}{\ttfamily\{Piton\}} should be used to
+% typeset multi-lines code. Since it takes its argument in a verbatim mode, it
+% can't be used within the argument of a LaTeX command. For sake of
+% customization, it's possible to define new environments similar to the
+% environment |{Piton}| with the command |\NewPitonEnvironment|:
% cf.~\ref{NewPitonEnvironment} p.~\pageref{NewPitonEnvironment}.
-% \item The command |\PitonInputFile| is used to insert and typeset a whole
-% external file.
%
-% \colorbox{yellow!50}{\textbf{New 0.95}}\enskip The command |\PitonInputFile|
-% takes in as optional argument (between square brackets) two keys |first-line|
-% and |last-line|: only the part between the corresponding lines will be inserted.
+% \item The command \colorbox{gray!20}{\ttfamily\textbackslash PitonInputFile}
+% is used to insert and typeset a whole external file.
+%
+% That command takes in as optional argument (between square brackets) two keys
+% |first-line| and |last-line|: only the part between the corresponding lines
+% will be inserted.
% \end{itemize}
%
+% \subsection{The syntax of the command \textbackslash piton}
%
+% In fact, the command |\piton| is provided with a double syntax. It may be used
+% as a standard command of LaTeX taking its argument between curly braces
+% (|\piton{...}|) but it may also be used with a syntax similar to the syntax of
+% the command
+% |\verb|, that is to say with the argument delimited by two identical characters (e.g.: \verb!\piton|...|!).
+%
+% \begin{itemize}
+% \item {\color{blue} \textsf{Syntax} \verb|\piton{...}|}\par\nobreak
+% When its argument is given between curly braces, the command |\piton| does not
+% take its argument in verbatim mode. In particular:
+% \begin{itemize}
+% \item several consecutive spaces will be replaced by only one space;
+% \item it's not possible to use |%| inside the argument;
+% \item the braces must be appear by pairs correctly nested;
+% \item the LaTeX commands (those beginning with a backslash |\| but also the
+% active characters) are fully expanded (but not executed).
+% \end{itemize}
+%
+% An escaping mechanism is provided: the commands |\\|, |\%|, |\{| and |\}|
+% insert the corresponding characters |\|, |%|, |{| and |}|. The last two
+% commands are necessary only if one need to insert braces which are not
+% balanced.
+%
+% The other characters (including |#|, |^|, |_|, |&|, |$| and |@|)
+% must be inserted without backslash.
+%
+% Examples:
+%
+%\begin{tabular}{>{\color{gray}}l@{\hspace*{1cm}}l}
+% \verb|\piton{MyString = '\\n'}| &
+% \piton{MyString = '\\n'} \\
+% \verb|\piton{def even(n): return n\%2==0}| &
+% \piton{def even(n): return n\%2==0} \\
+% \verb|\piton{c="#" # an affectation }| &
+% \piton{c="#" # an affectation } \\
+% \verb|\piton{MyDict = {'a': 3, 'b': 4 }}| &
+% \piton{MyDict = {'a': 3, 'b': 4 }}
+% \end{tabular}
+%
+%
+% It's possible to use the command |\piton| in the arguments of a
+% LaTeX command.\footnote{For example, it's possible to use the command
+% \texttt{\textbackslash piton} in a footnote. Example :
+% \piton{s = 'A string'}.}
+%
+% \bigskip
+% \item {\color{blue} \textsf{Syntaxe} \verb!\piton|...|!}\par\nobreak
+%
+% When the argument of the command |\piton| is provided between two identical
+% characters, that argument is taken in a \emph{verbatim mode}. Therefore, with
+% that syntax, the command |\piton| can't be used within the argument of another
+% command.
+%
+% \medskip
+% Exemples :
+%
+% \begin{tabular}{>{\color{gray}}l@{\hspace*{1cm}}l}
+% \verb!\piton|MyString = '\n'|! &
+% \piton|MyString = '\n'| \\
+% \verb|\piton!def even(n): return n%2==0!| &
+% \piton!def even(n): return n%2==0! \\
+% \verb|\piton+c="#" # an affectation +| &
+% \piton+c="#" # an affectation + \\
+% \verb|\piton?MyDict = {'a': 3, 'b': 4}?| &
+% \piton!MyDict = {'a': 3, 'b': 4}!
+% \end{tabular}
+%
+% \end{itemize}
+%
% \section{Customization}
%
% \subsection{The command \textbackslash PitonOptions}
@@ -218,45 +299,23 @@
% |line-all-numbers| if one does not want the numbers in an overlapping position
% on the left.
%
-% \colorbox{yellow!50}{\textbf{New 0.95}}\enskip It's possible to use the key
-% |left-margin| with the value |auto|. With that value, if the key
-% |line-numbers| or the key |all-line-numbers| is used, a margin will be
-% automatically inserted to fit the numbers of lines. See an example part
-% \ref{example-numbering} on page~\pageref{example-numbering}.
+% It's possible to use the key |left-margin| with the value |auto|. With that
+% value, if the key |line-numbers| or the key |all-line-numbers| is used, a
+% margin will be automatically inserted to fit the numbers of lines. See an
+% example part \ref{example-numbering} on page~\pageref{example-numbering}.
%
-% \item The key |splittable| allows page breaks within the environments
-% |{Piton}| and the listings produced by
-% |\PitonInputFile|.
-%
-% \smallskip
-% It's possible to give as value to the key |splittable| a positive integer~$n$.
-% With that value, the environments |{Piton}| and the listings produced by
-% |\PitonInputFile| are splittable but no page break can occur within the first
-% $n$ lines and within the last $n$ lines. The default value of the key
-% |splittable| is, in fact, $1$, which allows pages breaks everywhere.
-%
% \item The key |background-color| sets the background color of the environments
% |{Piton}| and the listings produced by |\PitonInputFile| (that background has
-% a width of |\linewidth|). Even with a background color, the pages breaks are
-% allowed, as soon as the key |splittable| is in force.\footnote{With the key
-% |splittable|, the environments \texttt{\{Piton\}} are breakable, even within a
-% (breakable) environment of \pkg{tcolorbox}. Remind that an environment of
-% \pkg{tcolorbox} included in another environment of \pkg{tcolorbox} is
-% \emph{not} breakable, even when both environments use the key |breakable| of
-% \pkg{tcolorbox}.}
+% a width of |\linewidth|).
%
-% \item \colorbox{yellow!50}{\textbf{New 0.95}}\enskip When the key
-% |show-spaces| is activated, the spaces in the short strings (that is to say
-% those delimited by |'| or |"|) are replaced by the character~␣ (U+2423 :
-% \textsc{open box}). Of course, that character~U+2423 must be present in the
-% monospaced font which is used.\footnote{The package \pkg{piton} simply uses
-% the current monospaced font. The best way to change that font is to use the
-% command \texttt{\textbackslash setmonofont} of \pkg{fontspec}.}
-%
-% \begingroup
-% \PitonOptions{show-spaces}
-% Example : \piton|my_string = 'Very good answer'|
-% \endgroup
+% \item When the key |show-spaces| is activated, the spaces in the short strings
+% (that is to say those delimited by |'| or |"|) are replaced by the character~␣
+% (U+2423 : \textsc{open box}). Of course, that character~U+2423 must be present
+% in the monospaced font which is used.\footnote{The package \pkg{piton} simply
+% uses the current monospaced font. The best way to change that font is to use
+% the command \texttt{\textbackslash setmonofont} of
+% \pkg{fontspec}.}\par\nobreak \begingroup \PitonOptions{show-spaces} Example :
+% \piton|my_string = 'Very good answer'| \endgroup
% \end{itemize}
%
% \bigskip
@@ -309,8 +368,11 @@
% \end{Piton}
% \endgroup
%
+% \bigskip
+% The command |\PitonOptions| provides in fact several other keys which will be
+% described further (see in particular the ``Pages breaks and line breaks''
+% p.~\pageref{breakable}).
%
-%
% \subsection{The styles}
%
% \label{styles}
@@ -480,13 +542,19 @@
% comments (which begins by |#|) will, in fact, be ``LaTeX comments''.
%
% \smallskip
-% \item \colorbox{yellow!50}{\bfseries New 0.95}\enskip It's possible to change
-% the formatting of the LaTeX comment itself by changing the \pkg{piton} style
-% |Comment.LaTeX|.
+% \item It's possible to change the formatting of the LaTeX comment itself by
+% changing the \pkg{piton} style |Comment.LaTeX|.
%
% For example, with |\SetPitonStyle{Comment.LaTeX = \normalfont\color{blue}}|,
% the LaTeX comments will be composed in blue.
%
+% If you want to have a character |#| at the beginning of the LaTeX comment in
+% the \textsc{pdf}, you can use set |Comment.LaTeX| as follows:
+%
+% \begin{Verbatim}
+% \SetPitonStyle{Comment.LaTeX = \color{gray}\~#\normalfont\space }
+% \end{Verbatim}
+%
% For other examples of customization of the LaTeX comments, see the part
% \ref{example-comments} p.~\pageref{example-comments}
% \end{itemize}
@@ -493,10 +561,10 @@
%
% \subsubsection{The key ``math-comments''}
%
-% \colorbox{yellow!50}{\textbf{New 0.95}}\enskip It's possible to request that,
-% in the standard Python comments (that is to say those beginning by |#| and not
-% |#>|), the elements between \texttt{\$} be composed in LaTeX mathematical mode
-% (the other elements of the comment being composed verbatim).
+% It's possible to request that, in the standard Python comments (that is to say
+% those beginning by |#| and not |#>|), the elements between \texttt{\$} be
+% composed in LaTeX mathematical mode (the other elements of the comment being
+% composed verbatim).
%
% That feature is activated by the key |math-comments| at load-time (that is to
% say with the |\usepackage|).
@@ -520,8 +588,8 @@
% \subsubsection{The mechanism ``escape-inside''}
%
% It's also possible to overwrite the Python listings to insert LaTeX code
-% almost everywhere. By default, \pkg{piton} does not fix any character for that
-% kind of escape.
+% almost everywhere (but between lexical units, of course). By default,
+% \pkg{piton} does not fix any character for that kind of escape.
%
% In order to use this mechanism, it's necessary to specify two characters which
% will delimit the escape (one for the beginning and one for the end) by using
@@ -566,6 +634,94 @@
% beginning it with |#>|; such comments are merely called ``LaTeX comments'' in
% this document).
%
+%
+% \subsection{Page breaks and line breaks}
+%
+% \label{breakable}
+%
+% \subsubsection{Page breaks}
+%
+% By default, the listings produced by the environment |{Piton}| and the command
+% |\PitonInputFile| are not breakable.
+%
+% However, the command |\PitonOptions| provides the key |splittable| to allow such
+% breaks.
+%
+% \begin{itemize}
+% \item If the key |splittable| is used without any value, the listings are
+% breakable everywhere.
+% \item If the key |splittable| is used with a numeric value~$n$ (which must be
+% a non-negative integer number), the listings are breakable but no break will
+% occur within the first $n$ lines and within the last $n$ lines. Therefore,
+% |splittable=1| is equivalent to |splittable|.
+% \end{itemize}
+%
+% \medskip
+% Even with a background color (set by |background-color|), the pages breaks are
+% allowed, as soon as the key |splittable| is in force.\footnote{With the key
+% |splittable|, the environments \texttt{\{Piton\}} are breakable, even within a
+% (breakable) environment of \pkg{tcolorbox}. Remind that an environment of
+% \pkg{tcolorbox} included in another environment of \pkg{tcolorbox} is
+% \emph{not} breakable, even when both environments use the key |breakable| of
+% \pkg{tcolorbox}.}
+%
+% \subsubsection{Line breaks}
+%
+% By default, the lines of the listings produced by |{Piton}| and
+% |\PitonInputFile| are not breakable.
+%
+% \smallskip
+% \colorbox{yellow!50}{\textbf{New 0.99}}\enskip There exist several keys
+% (available in |\PitonOptions|) to allow and control such line breaks.
+%
+% \begin{itemize}
+% \item The key |break-lines| actives the lines breaks. Only the spaces (even in
+% the strings) are allowed break points.
+%
+% \item With the key |indent-broken-lines|, the indentation of a broken line is
+% respected at carriage return.
+%
+% \item The key |end-of-broken-line| corresponds to the symbol placed at the end
+% of a broken line. The initial value is: |\hspace*{0.5em}\textbackslash|.
+%
+% \item The key |continuation-symbol| corresponds to the symbol placed at each
+% carriage return. The initial value is: |+\;|.
+%
+% \item The key |continuation-symbol-on-indentation| coresponds to the symbol
+% placed at each carriage return, on the position of the indentation (only when
+% the key |indent-broken-line| is in force). The initial value is:
+% |$\hookrightarrow\;$|.
+% \end{itemize}
+%
+%
+% \bigskip
+% The following code has been composed in a |{minipage}| of width 12~cm with the
+% following tuning:
+%
+% \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_list(l):
+% """Converts a list of subrs and descriptions of glyphs in a dictionary"""
+% our_dict = {}
+% for list_letter in l:
+% if (list_letter[0][0:3] == 'dup'): # if it's a subr
+% name = list_letter[0][4:-3]
+% print("We treat the subr of number " + name)
+% else:
+% name = list_letter[0][1:-3] # if it's a glyph
+% print("We treat the glyph of number " + name)
+% our_dict[name] = [treat_Postscript_line(k) for k in list_letter[1:-1]]
+% return dict
+% \end{Piton}
+% \end{minipage}
+% \end{center}
+%
% \subsection{Footnotes in the environments of piton}
%
% \label{footnote}
@@ -1417,6 +1573,36 @@
% \end{macrocode}
%
% \medskip
+% The following booleans correspond to the keys |break-lines| and
+% |indent-broken-lines| of |\PitonOptions|.
+% \begin{macrocode}
+\bool_new:N \l_@@_break_lines_bool
+\bool_new:N \l_@@_indent_broken_lines_bool
+% \end{macrocode}
+%
+% \medskip
+% The following token list corresponds to the key |continuation-symbol|.
+% \begin{macrocode}
+\tl_new:N \l_@@_continuation_symbol_tl
+\tl_set:Nn \l_@@_continuation_symbol_tl { + }
+% \end{macrocode}
+%
+% \medskip
+% \begin{macrocode}
+% The following token list corresponds to the key
+% |continuation-symbol-on-indentation|. The name has been shorten to |csoi|.
+\tl_new:N \l_@@_csoi_tl
+\tl_set:Nn \l_@@_csoi_tl { $ \hookrightarrow \; $ }
+% \end{macrocode}
+%
+% \medskip
+% The following token list corresponds to the key |end-of-broken-line|.
+% \begin{macrocode}
+\tl_new:N \l_@@_end_of_broken_line_tl
+\tl_set:Nn \l_@@_end_of_broken_line_tl { \hspace*{0.5em} \textbackslash }
+% \end{macrocode}
+%
+% \medskip
% The following boolean corresponds to the key |slim| of |\PitonOptions|.
% \begin{macrocode}
\bool_new:N \l_@@_slim_bool
@@ -1424,13 +1610,19 @@
%
% \medskip
% The following dimension corresponds to the key |left-margin| of
-% |\PitonOptions|. By convention, when the final user will uses
-% |left-margin=auto|, |\l_@@_left_margin_dim| will be equal to -1~cm.
+% |\PitonOptions|.
% \begin{macrocode}
\dim_new:N \l_@@_left_margin_dim
% \end{macrocode}
%
% \medskip
+% The following boolean correspond will be set when the key |left-margin=auto|
+% is used.
+% \begin{macrocode}
+\bool_new:N \l_@@_left_margin_auto_bool
+% \end{macrocode}
+%
+% \medskip
% The tabulators will be replaced by the content of the following token list.
% \begin{macrocode}
\tl_new:N \l_@@_tab_tl
@@ -1459,9 +1651,24 @@
\tl_set:Nn \l_@@_space_tl { ~ }
% \end{macrocode}
%
+%
+% \medskip
+% At each line, the following counter will count the spaces at the beginning.
+% \begin{macrocode}
+\int_new:N \g_@@_indentation_int
+% \end{macrocode}
+%
+% \medskip
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_an_indentation_space:
+ { \int_gincr:N \g_@@_indentation_int }
+% \end{macrocode}
+%
% \bigskip
% \subsubsection{Treatment of a line of code}
%
+%
+% \bigskip
% In the contents provided by Lua, each line of the Python code will be
% surrounded by |\@@_begin_line:| and |\@@_end_line:|.
%
@@ -1468,21 +1675,47 @@
% \begin{macrocode}
\cs_set_protected:Npn \@@_begin_line: #1 \@@_end_line:
{
+ \int_gzero:N \g_@@_indentation_int
% \end{macrocode}
%
+%
% Be careful: there is curryfication in the following lines.
% \begin{macrocode}
\bool_if:NTF \l_@@_slim_bool
- { \hbox_set:Nn \l_tmpa_box }
+ { \hcoffin_set:Nn \l_tmpa_coffin }
{
\str_if_empty:NTF \l_@@_background_color_str
- { \hbox_set_to_wd:Nnn \l_tmpa_box \linewidth }
{
- \hbox_set_to_wd:Nnn \l_tmpa_box
- { \dim_eval:n { \linewidth - 0.5 em } }
+ \vcoffin_set:Nnn \l_tmpa_coffin
+ { \dim_eval:n { \linewidth - \l_@@_left_margin_dim } }
}
+ {
+ \vcoffin_set:Nnn \l_tmpa_coffin
+ { \dim_eval:n { \linewidth - \l_@@_left_margin_dim - 0.5 em } }
+ }
}
{
+ \language = -1
+ \raggedright
+ \strut
+ \tl_set:Nn \l_tmpa_tl { #1 }
+% \end{macrocode}
+% If the key |break-lines| is in force, we replace all the characters U+0032
+% (that is to say the spaces) by |\@@_breakable_space:|. Remark that, except the
+% spaces inserted in the LaTeX comments (and maybe in the math comments), all
+% these spaces are of catcode ``other'' (=12) and are unbreakable.
+% \begin{macrocode}
+ \bool_if:NT \l_@@_break_lines_bool
+ {
+ \regex_replace_all:nnN
+ { \x20 }
+ { \c { @@_breakable_space: } }
+ \l_tmpa_tl
+ }
+ \l_tmpa_tl \strut \hfil
+ }
+ \hbox_set:Nn \l_tmpa_box
+ {
\skip_horizontal:N \l_@@_left_margin_dim
\bool_if:NT \l_@@_line_numbers_bool
{
@@ -1490,13 +1723,13 @@
{ \tl_if_empty:nF { #1 } }
\@@_print_number:
}
- \strut
- \str_if_empty:NF \l_@@_background_color_str \space
- #1 \hfil
- }
+ \str_if_empty:NF \l_@@_background_color_str
+ { \skip_horizontal:n { 0.5 em } }
+ \coffin_typeset:Nnnnn \l_tmpa_coffin T l \c_zero_dim \c_zero_dim
+ }
% \end{macrocode}
% We compute in |\g_@@_width_dim| the maximal width of the lines of the
-% environments.
+% environment.
% \begin{macrocode}
\dim_compare:nNnT { \box_wd:N \l_tmpa_box } > \g_@@_width_dim
{ \dim_gset:Nn \g_@@_width_dim { \box_wd:N \l_tmpa_box } }
@@ -1542,6 +1775,36 @@
}
}
% \end{macrocode}
+%
+% \bigskip
+% \begin{macrocode}
+\cs_set_protected:Npn \@@_breakable_space:
+ {
+ \discretionary
+ { \hbox:n { \color { gray } \l_@@_end_of_broken_line_tl } }
+ {
+ \hbox_overlap_left:n
+ {
+ {
+ \normalfont \footnotesize \color { gray }
+ \l_@@_continuation_symbol_tl
+ }
+ \skip_horizontal:n { 0.3 em }
+ \str_if_empty:NF \l_@@_background_color_str
+ { \skip_horizontal:n { 0.5 em } }
+ }
+ \bool_if:NT \l_@@_indent_broken_lines_bool
+ {
+ \hbox:n
+ {
+ \prg_replicate:nn { \g_@@_indentation_int } { ~ }
+ { \color { gray } \l_@@_csoi_tl }
+ }
+ }
+ }
+ { \hbox { ~ } }
+ }
+% \end{macrocode}
%
% \bigskip
% \subsubsection{PitonOptions}
@@ -1589,7 +1852,10 @@
slim .default:n = true ,
left-margin .code:n =
\str_if_eq:nnTF { #1 } { auto }
- { \dim_set:Nn \l_@@_left_margin_dim { -1cm } }
+ {
+ \dim_zero:N \l_@@_left_margin_dim
+ \bool_set_true:N \l_@@_left_margin_auto_bool
+ }
{ \dim_set:Nn \l_@@_left_margin_dim { #1 } } ,
left-margin .value_required:n = true ,
tab-size .code:n = \@@_set_tab_tl:n { #1 } ,
@@ -1596,6 +1862,16 @@
tab-size .value_required:n = true ,
show-spaces .code:n = \tl_set:Nn \l_@@_space_tl { ␣ } , % U+2423
show-spaces .value_forbidden:n = true ,
+ break-lines .bool_set:N = \l_@@_break_lines_bool ,
+ break-lines .default:n = true ,
+ indent-broken-lines .bool_set:N = \l_@@_indent_broken_lines_bool ,
+ indent-broken-lines .default:n = true ,
+ end-of-broken-line .tl_set:N = \l_@@_end_of_broken_line_tl ,
+ end-of-broken-line .value_required:n = true ,
+ continuation-symbol .tl_set:N = \l_@@_continuation_symbol_tl ,
+ continuation-symbol .value_required:n = true ,
+ continuation-symbol-on-indentation .tl_set:N = \l_@@_csoi_tl ,
+ continuation-symbol-on-indentation .value_required:n = true ,
unknown .code:n =
\msg_error:nn { piton } { Unknown~key~for~PitonOptions }
}
@@ -1604,14 +1880,31 @@
%
% \bigskip
% \begin{macrocode}
-\msg_new:nnn { piton } { Unknown~key~for~PitonOptions }
+\msg_new:nnnn { piton } { Unknown~key~for~PitonOptions }
{
Unknown~key. \\
- The~key~'\l_keys_key_str'~is~unknown~for~\token_to_str:N \PitonOptions.~The~
- available~keys~are:~all-line-numbers,~auto-gobble,~env-gobble,~gobble,~
- left-margin,~line-numbers,~resume,~show-spaces,~slim,~splittable~and~tab-size.\\
- If~you~go~on,~that~key~will~be~ignored.
+ The~key~'\l_keys_key_str'~is~unknown~for~\token_to_str:N \PitonOptions.~
+ It~will~be~ignored.\\
+ For~a~list~of~the~available~keys,~type~H~<return>.
}
+ {
+ The~available~keys~are~(in~alphabetic~order):~
+ all-line-numbers,~
+ auto-gobble,~
+ break-lines,~
+ continuation-symbol,~
+ continuation-symbol-on-indentation,~
+ end-of-broken-line,~
+ env-gobble,~gobble,~
+ left-margin,~
+ indent-broken-lines,~
+ line-numbers,~
+ resume,~
+ show-spaces,~
+ slim,~
+ splittable~
+ and~tab-size.\\
+ }
% \end{macrocode}
%
% \bigskip
@@ -1686,27 +1979,54 @@
% \bigskip
% \subsubsection{The main commands and environments for the final user}
%
+% \medskip
% \begin{macrocode}
-\NewDocumentCommand { \piton } { v }
+\NewDocumentCommand { \piton } { }
+ { \peek_meaning:NTF \bgroup \@@_piton_standard \@@_piton_verbatim }
+% \end{macrocode}
+%
+% \begin{macrocode}
+\NewDocumentCommand { \@@_piton_standard } { m }
{
\group_begin:
+ \ttfamily
+ \cs_set_eq:NN \\ \c_backslash_str
+ \cs_set_eq:NN \% \c_percent_str
+ \cs_set_eq:NN \{ \c_left_brace_str
+ \cs_set_eq:NN \} \c_right_brace_str
+ \cs_set_eq:NN \$ \c_dollar_str
+ \cs_set_protected:Npn \@@_begin_line: { }
+ \cs_set_protected:Npn \@@_end_line: { }
+ \lua_now:n { piton.pitonParse(token.scan_string()) } { #1 }
+ \group_end:
+ }
+% \end{macrocode}
+%
+%
+% \begin{macrocode}
+\NewDocumentCommand { \@@_piton_verbatim } { v }
+ {
+ \group_begin:
\ttfamily
\cs_set_protected:Npn \@@_begin_line: { }
\cs_set_protected:Npn \@@_end_line: { }
- \lua_now:n { piton.Parse(token.scan_argument()) } { #1 }
+ \lua_now:n { piton.Parse(token.scan_string()) } { #1 }
\group_end:
}
% \end{macrocode}
%
-% \medskip
-% The command |\@@_piton:n| does \emph{not} take in its argument verbatim.
+% \bigskip
+% The following command is not a user command. It will be used when you will
+% have to ``rescan'' some chunks of Python code. For example, if will be the
+% initial value of the Piton style |InitialValues| (the default values of the
+% arguments of a Python function).
% \begin{macrocode}
\cs_new_protected:Npn \@@_piton:n #1
{
\group_begin:
- \cs_set_protected:Npn \@@_begin_line: { }
- \cs_set_protected:Npn \@@_end_line: { }
- \lua_now:n { piton.Parse(token.scan_argument()) } { #1 }
+ \cs_set_protected:Npn \@@_begin_line: { }
+ \cs_set_protected:Npn \@@_end_line: { }
+ \lua_now:n { piton.Parse(token.scan_string()) } { #1 }
\group_end:
}
% \end{macrocode}
@@ -1761,34 +2081,27 @@
% If the final user has used both |left-margin=auto| and |line-numbers| or
% |all-line-numbers|, we have to compute the width of the maximal number of
% lines at the end of the composition of the listing to fix the correct value to
-% |left-margin|. Par convention, when |left-margin=auto|, the dimension
-% |\l_@@_left_margin_dim| is set to -1~cm.
+% |left-margin|.
% \begin{macrocode}
- \dim_compare:nNnT \l_@@_left_margin_dim < \c_zero_dim
+ \bool_lazy_and:nnT \l_@@_left_margin_auto_bool \l_@@_line_numbers_bool
{
- \bool_if:NT \l_@@_line_numbers_bool
- {
- \hbox_set:Nn \l_tmpa_box
+ \hbox_set:Nn \l_tmpa_box
+ {
+ \footnotesize
+ \bool_if:NTF \l_@@_all_line_numbers_bool
{
- \footnotesize
- \bool_if:NTF \l_@@_all_line_numbers_bool
- {
- \int_to_arabic:n
- { \g_@@_visual_line_int + \l_@@_nb_lines_int }
- }
- {
- \lua_now:n
- { piton.CountNonEmptyLinesFile(token.scan_argument()) }
- { #2 }
- \int_to_arabic:n
- {
- \g_@@_visual_line_int +
- \l_@@_nb_non_empty_lines_int
- }
- }
+ \int_to_arabic:n
+ { \g_@@_visual_line_int + \l_@@_nb_lines_int }
+ }
+ {
+ \lua_now:n
+ { piton.CountNonEmptyLinesFile(token.scan_argument()) }
+ { #2 }
+ \int_to_arabic:n
+ { \g_@@_visual_line_int + \l_@@_nb_non_empty_lines_int }
}
- \dim_set:Nn \l_@@_left_margin_dim { \box_wd:N \l_tmpa_box + 0.5em }
}
+ \dim_set:Nn \l_@@_left_margin_dim { \box_wd:N \l_tmpa_box + 0.5em }
}
% \end{macrocode}
% Now, the main job.
@@ -1844,36 +2157,30 @@
% to compute the width of the maximal number of lines at the end of the
% environment to fix the correct value to |left-margin|.
% \begin{macrocode}
- \dim_compare:nNnT \l_@@_left_margin_dim < \c_zero_dim
+ \bool_lazy_and:nnT \l_@@_left_margin_auto_bool \l_@@_line_numbers_bool
{
- \bool_if:NT \l_@@_line_numbers_bool
+ \bool_if:NTF \l_@@_all_line_numbers_bool
{
- \bool_if:NTF \l_@@_all_line_numbers_bool
- {
- \hbox_set:Nn \l_tmpa_box
- {
- \footnotesize
- \int_to_arabic:n
- { \g_@@_visual_line_int + \l_@@_nb_lines_int }
- }
+ \hbox_set:Nn \l_tmpa_box
+ {
+ \footnotesize
+ \int_to_arabic:n
+ { \g_@@_visual_line_int + \l_@@_nb_lines_int }
}
- {
- \lua_now:n
- { piton.CountNonEmptyLines(token.scan_argument()) }
- { ##1 }
- \hbox_set:Nn \l_tmpa_box
- {
- \footnotesize
- \int_to_arabic:n
- {
- \g_@@_visual_line_int +
- \l_@@_nb_non_empty_lines_int
- }
- }
+ }
+ {
+ \lua_now:n
+ { piton.CountNonEmptyLines(token.scan_argument()) }
+ { ##1 }
+ \hbox_set:Nn \l_tmpa_box
+ {
+ \footnotesize
+ \int_to_arabic:n
+ { \g_@@_visual_line_int + \l_@@_nb_non_empty_lines_int }
}
- \dim_set:Nn \l_@@_left_margin_dim
- { \box_wd:N \l_tmpa_box + 0.5 em }
}
+ \dim_set:Nn \l_@@_left_margin_dim
+ { \box_wd:N \l_tmpa_box + 0.5 em }
}
% \end{macrocode}
% Now, the main job.
@@ -2087,7 +2394,7 @@
% If the key |math-comments| has been used at load-time, we change the style
% |Comment.Math| which should be considered only at an ``internal style''.
% However, maybe we will document in a future version the possibility to write
-% change the style \emph{locally} in a document).
+% change the style \emph{locally} in a document)].
% \begin{macrocode}
\bool_if:NT \c_@@_math_comments_bool
{ \SetPitonStyle { Comment.Math } }
@@ -2326,6 +2633,12 @@
% \end{macrocode}
%
% \bigskip
+% \begin{macrocode}
+local SpaceIndentation =
+ Lc ( '\\@@_an_indentation_space:' ) * K " "
+% \end{macrocode}
+%
+% \bigskip
% The following \textsc{lpeg} |EOL| is for the end of lines.
% \begin{macrocode}
local EOL =
@@ -2343,6 +2656,8 @@
% \begin{macrocode}
Lc ( '\\@@_end_line: \\@@_newline: \\@@_begin_line:' )
)
+ *
+ SpaceIndentation ^ 0
% \end{macrocode}
%
% \bigskip
@@ -2429,7 +2744,7 @@
% style |Name.Class|).
%
% \smallskip
-% Example:\enskip \piton|class myclass:|
+% Example:\enskip \piton{class myclass:}
% \begin{macrocode}
local DefClass =
K ( P "class" , 'Keyword' ) * Space * K ( identifier , 'Name.Class' )
@@ -2446,7 +2761,7 @@
% module and its alias must be formatted with the \pkg{piton} style |Name.Namespace|.
%
% \smallskip
-% Example:\enskip \piton|import numpy as np|
+% Example:\enskip \piton{import numpy as np}
%
% \smallskip
% Moreover, after the keyword |import|, it's possible to have a comma-separated
@@ -2453,7 +2768,7 @@
% list of modules (if the keyword |as| is not used).
%
% \smallskip
-% Example:\enskip \piton|import math, numpy|
+% Example:\enskip \piton{import math, numpy}
% \begin{macrocode}
local ImportAs =
K ( P "import" , 'Keyword' )
@@ -2477,7 +2792,7 @@
% |Keyword| and must \emph{not} be catched by the \textsc{lpeg} |ImportAs|.
%
% \smallskip
-% Example:\enskip \piton|from math import pi|
+% Example:\enskip \piton{from math import pi}
%
% \smallskip
% \begin{macrocode}
@@ -2514,7 +2829,7 @@
% style of the encompassing string, that is to say |String.Short| or
% |String.Long|.} in that interpolation:
%
-% \piton|f'Total price: {total+1:.2f} €'|
+% \piton{f'Total price: {total+1:.2f} €'}
%
% \medskip
% The following \textsc{lpeg} |SingleShortInterpol| (and the three variants)
@@ -2797,7 +3112,7 @@
% parameters (that is to say the \emph{argspec}) in the definition of a Python
% function. For example, in the line of code
% \begin{center}
-% \piton|def MyFunction(a,b,x=10,n:int): return n|
+% \piton{def MyFunction(a,b,x=10,n:int): return n}
% \end{center}
% the \textsc{lpeg} |Params| will be used to catch the chunk\enskip |a,b,x=10,n:int|.
%
@@ -2874,7 +3189,7 @@
% \medskip
% \begingroup
% \SetPitonStyle{Dict.Value = \color{black}}
-% \piton|mydict = { 'name' : 'Paul', 'sex' : 'male', 'age' : 31 } |
+% \piton{mydict = { 'name' : 'Paul', 'sex' : 'male', 'age' : 31 } }
% \endgroup
%
% \medskip
@@ -2909,6 +3224,7 @@
% \begin{macrocode}
Lc ( '\\@@_begin_line:' ) *
( ( space - P "\r" ) ^0 * P "\r" ) ^ -1 *
+ SpaceIndentation ^ 0 *
( ( space^1 * -1 )
+ EOL
+ Tab
@@ -2933,7 +3249,7 @@
+ DefClass
+ Keyword * ( Space + Punct + Delim + EOL + -1)
+ Decorator
- + OperatorWord
+ + OperatorWord * ( Space + Punct + Delim + EOL + -1)
+ Builtin * ( Space + Punct + Delim + EOL + -1)
+ Identifier
+ Number
@@ -2963,7 +3279,18 @@
end
% \end{macrocode}
%
+%
% \bigskip
+% The following command will be used by the user commands |\piton|.
+% For that command, we have to undo the duplication of the symbols |#|.
+% \begin{macrocode}
+function piton.pitonParse(code)
+ local s = ( Cs ( ( P '##' / '#' + 1 ) ^ 0 ) ) : match ( code )
+ return piton.Parse(s)
+end
+% \end{macrocode}
+%
+% \bigskip
% The function |ParseFile| will be used by the LaTeX command |\PitonInputFile|.
% That function merely reads the whole file (that is to say all its lines) and
% then apply the function~|Parse| to the resulting Lua string.
@@ -3178,6 +3505,11 @@
%
% New keys |first-line| and |last-line| for the command |\InputPitonFile|.
%
+% \subsection*{Changes between versions 0.95 and 0.99}
+%
+% New key |break-lines| to allow breaks of the lines of code (and other keys to
+% customize the appearance).
+%
% \end{document}
%
%
Modified: trunk/Master/texmf-dist/tex/lualatex/piton/piton.sty
===================================================================
--- trunk/Master/texmf-dist/tex/lualatex/piton/piton.sty 2022-11-29 21:09:04 UTC (rev 65142)
+++ trunk/Master/texmf-dist/tex/lualatex/piton/piton.sty 2022-11-29 21:09:19 UTC (rev 65143)
@@ -18,8 +18,8 @@
%% and version 1.3 or later is part of all distributions of
%% LaTeX version 2005/12/01 or later.
%%
-\def\myfileversion{0.95}
-\def\myfiledate{2022/11/09}
+\def\myfileversion{0.99}
+\def\myfiledate{2022/11/29}
@@ -131,8 +131,17 @@
\dim_new:N \g__piton_width_dim
\dim_new:N \l__piton_width_on_aux_dim
\int_new:N \g__piton_env_int
+\bool_new:N \l__piton_break_lines_bool
+\bool_new:N \l__piton_indent_broken_lines_bool
+\tl_new:N \l__piton_continuation_symbol_tl
+\tl_set:Nn \l__piton_continuation_symbol_tl { + }
+\tl_new:N \l__piton_csoi_tl
+\tl_set:Nn \l__piton_csoi_tl { $ \hookrightarrow \; $ }
+\tl_new:N \l__piton_end_of_broken_line_tl
+\tl_set:Nn \l__piton_end_of_broken_line_tl { \hspace*{0.5em} \textbackslash }
\bool_new:N \l__piton_slim_bool
\dim_new:N \l__piton_left_margin_dim
+\bool_new:N \l__piton_left_margin_auto_bool
\tl_new:N \l__piton_tab_tl
\cs_new_protected:Npn \__piton_set_tab_tl:n #1
{
@@ -144,19 +153,41 @@
\int_new:N \l__piton_gobble_int
\tl_new:N \l__piton_space_tl
\tl_set:Nn \l__piton_space_tl { ~ }
+\int_new:N \g__piton_indentation_int
+\cs_new_protected:Npn \__piton_an_indentation_space:
+ { \int_gincr:N \g__piton_indentation_int }
\cs_set_protected:Npn \__piton_begin_line: #1 \__piton_end_line:
{
+ \int_gzero:N \g__piton_indentation_int
\bool_if:NTF \l__piton_slim_bool
- { \hbox_set:Nn \l_tmpa_box }
+ { \hcoffin_set:Nn \l_tmpa_coffin }
{
\str_if_empty:NTF \l__piton_background_color_str
- { \hbox_set_to_wd:Nnn \l_tmpa_box \linewidth }
{
- \hbox_set_to_wd:Nnn \l_tmpa_box
- { \dim_eval:n { \linewidth - 0.5 em } }
+ \vcoffin_set:Nnn \l_tmpa_coffin
+ { \dim_eval:n { \linewidth - \l__piton_left_margin_dim } }
}
+ {
+ \vcoffin_set:Nnn \l_tmpa_coffin
+ { \dim_eval:n { \linewidth - \l__piton_left_margin_dim - 0.5 em } }
+ }
}
{
+ \language = -1
+ \raggedright
+ \strut
+ \tl_set:Nn \l_tmpa_tl { #1 }
+ \bool_if:NT \l__piton_break_lines_bool
+ {
+ \regex_replace_all:nnN
+ { \x20 }
+ { \c { __piton_breakable_space: } }
+ \l_tmpa_tl
+ }
+ \l_tmpa_tl \strut \hfil
+ }
+ \hbox_set:Nn \l_tmpa_box
+ {
\skip_horizontal:N \l__piton_left_margin_dim
\bool_if:NT \l__piton_line_numbers_bool
{
@@ -164,9 +195,9 @@
{ \tl_if_empty:nF { #1 } }
\__piton_print_number:
}
- \strut
- \str_if_empty:NF \l__piton_background_color_str \space
- #1 \hfil
+ \str_if_empty:NF \l__piton_background_color_str
+ { \skip_horizontal:n { 0.5 em } }
+ \coffin_typeset:Nnnnn \l_tmpa_coffin T l \c_zero_dim \c_zero_dim
}
\dim_compare:nNnT { \box_wd:N \l_tmpa_box } > \g__piton_width_dim
{ \dim_gset:Nn \g__piton_width_dim { \box_wd:N \l_tmpa_box } }
@@ -207,6 +238,32 @@
}
}
}
+\cs_set_protected:Npn \__piton_breakable_space:
+ {
+ \discretionary
+ { \hbox:n { \color { gray } \l__piton_end_of_broken_line_tl } }
+ {
+ \hbox_overlap_left:n
+ {
+ {
+ \normalfont \footnotesize \color { gray }
+ \l__piton_continuation_symbol_tl
+ }
+ \skip_horizontal:n { 0.3 em }
+ \str_if_empty:NF \l__piton_background_color_str
+ { \skip_horizontal:n { 0.5 em } }
+ }
+ \bool_if:NT \l__piton_indent_broken_lines_bool
+ {
+ \hbox:n
+ {
+ \prg_replicate:nn { \g__piton_indentation_int } { ~ }
+ { \color { gray } \l__piton_csoi_tl }
+ }
+ }
+ }
+ { \hbox { ~ } }
+ }
\bool_new:N \l__piton_line_numbers_bool
\bool_new:N \l__piton_all_line_numbers_bool
\bool_new:N \l__piton_resume_bool
@@ -234,7 +291,10 @@
slim .default:n = true ,
left-margin .code:n =
\str_if_eq:nnTF { #1 } { auto }
- { \dim_set:Nn \l__piton_left_margin_dim { -1cm } }
+ {
+ \dim_zero:N \l__piton_left_margin_dim
+ \bool_set_true:N \l__piton_left_margin_auto_bool
+ }
{ \dim_set:Nn \l__piton_left_margin_dim { #1 } } ,
left-margin .value_required:n = true ,
tab-size .code:n = \__piton_set_tab_tl:n { #1 } ,
@@ -241,17 +301,44 @@
tab-size .value_required:n = true ,
show-spaces .code:n = \tl_set:Nn \l__piton_space_tl { ␣ } , % U+2423
show-spaces .value_forbidden:n = true ,
+ break-lines .bool_set:N = \l__piton_break_lines_bool ,
+ break-lines .default:n = true ,
+ indent-broken-lines .bool_set:N = \l__piton_indent_broken_lines_bool ,
+ indent-broken-lines .default:n = true ,
+ end-of-broken-line .tl_set:N = \l__piton_end_of_broken_line_tl ,
+ end-of-broken-line .value_required:n = true ,
+ continuation-symbol .tl_set:N = \l__piton_continuation_symbol_tl ,
+ continuation-symbol .value_required:n = true ,
+ continuation-symbol-on-indentation .tl_set:N = \l__piton_csoi_tl ,
+ continuation-symbol-on-indentation .value_required:n = true ,
unknown .code:n =
\msg_error:nn { piton } { Unknown~key~for~PitonOptions }
}
-\msg_new:nnn { piton } { Unknown~key~for~PitonOptions }
+\msg_new:nnnn { piton } { Unknown~key~for~PitonOptions }
{
Unknown~key. \\
- The~key~'\l_keys_key_str'~is~unknown~for~\token_to_str:N \PitonOptions.~The~
- available~keys~are:~all-line-numbers,~auto-gobble,~env-gobble,~gobble,~
- left-margin,~line-numbers,~resume,~show-spaces,~slim,~splittable~and~tab-size.\\
- If~you~go~on,~that~key~will~be~ignored.
+ The~key~'\l_keys_key_str'~is~unknown~for~\token_to_str:N \PitonOptions.~
+ It~will~be~ignored.\\
+ For~a~list~of~the~available~keys,~type~H~<return>.
}
+ {
+ The~available~keys~are~(in~alphabetic~order):~
+ all-line-numbers,~
+ auto-gobble,~
+ break-lines,~
+ continuation-symbol,~
+ continuation-symbol-on-indentation,~
+ end-of-broken-line,~
+ env-gobble,~gobble,~
+ left-margin,~
+ indent-broken-lines,~
+ line-numbers,~
+ resume,~
+ show-spaces,~
+ slim,~
+ splittable~
+ and~tab-size.\\
+ }
\NewDocumentCommand \PitonOptions { } { \keys_set:nn { PitonOptions } }
\int_new:N \g__piton_visual_line_int
\cs_new_protected:Npn \__piton_print_number:
@@ -291,21 +378,37 @@
}
}
}
-\NewDocumentCommand { \piton } { v }
+\NewDocumentCommand { \piton } { }
+ { \peek_meaning:NTF \bgroup \__piton_piton_standard \__piton_piton_verbatim }
+\NewDocumentCommand { \__piton_piton_standard } { m }
{
\group_begin:
+ \ttfamily
+ \cs_set_eq:NN \\ \c_backslash_str
+ \cs_set_eq:NN \% \c_percent_str
+ \cs_set_eq:NN \{ \c_left_brace_str
+ \cs_set_eq:NN \} \c_right_brace_str
+ \cs_set_eq:NN \$ \c_dollar_str
+ \cs_set_protected:Npn \__piton_begin_line: { }
+ \cs_set_protected:Npn \__piton_end_line: { }
+ \lua_now:n { piton.pitonParse(token.scan_string()) } { #1 }
+ \group_end:
+ }
+\NewDocumentCommand { \__piton_piton_verbatim } { v }
+ {
+ \group_begin:
\ttfamily
\cs_set_protected:Npn \__piton_begin_line: { }
\cs_set_protected:Npn \__piton_end_line: { }
- \lua_now:n { piton.Parse(token.scan_argument()) } { #1 }
+ \lua_now:n { piton.Parse(token.scan_string()) } { #1 }
\group_end:
}
\cs_new_protected:Npn \__piton_piton:n #1
{
\group_begin:
- \cs_set_protected:Npn \__piton_begin_line: { }
- \cs_set_protected:Npn \__piton_end_line: { }
- \lua_now:n { piton.Parse(token.scan_argument()) } { #1 }
+ \cs_set_protected:Npn \__piton_begin_line: { }
+ \cs_set_protected:Npn \__piton_end_line: { }
+ \lua_now:n { piton.Parse(token.scan_string()) } { #1 }
\group_end:
}
\cs_new:Npn \__piton_pre_env:
@@ -338,31 +441,25 @@
\__piton_pre_env:
\mode_if_vertical:TF \mode_leave_vertical: \newline
\lua_now:n { piton.CountLinesFile(token.scan_argument()) } { #2 }
- \dim_compare:nNnT \l__piton_left_margin_dim < \c_zero_dim
+ \bool_lazy_and:nnT \l__piton_left_margin_auto_bool \l__piton_line_numbers_bool
{
- \bool_if:NT \l__piton_line_numbers_bool
- {
- \hbox_set:Nn \l_tmpa_box
+ \hbox_set:Nn \l_tmpa_box
+ {
+ \footnotesize
+ \bool_if:NTF \l__piton_all_line_numbers_bool
{
- \footnotesize
- \bool_if:NTF \l__piton_all_line_numbers_bool
- {
- \int_to_arabic:n
- { \g__piton_visual_line_int + \l__piton_nb_lines_int }
- }
- {
- \lua_now:n
- { piton.CountNonEmptyLinesFile(token.scan_argument()) }
- { #2 }
- \int_to_arabic:n
- {
- \g__piton_visual_line_int +
- \l__piton_nb_non_empty_lines_int
- }
- }
+ \int_to_arabic:n
+ { \g__piton_visual_line_int + \l__piton_nb_lines_int }
+ }
+ {
+ \lua_now:n
+ { piton.CountNonEmptyLinesFile(token.scan_argument()) }
+ { #2 }
+ \int_to_arabic:n
+ { \g__piton_visual_line_int + \l__piton_nb_non_empty_lines_int }
}
- \dim_set:Nn \l__piton_left_margin_dim { \box_wd:N \l_tmpa_box + 0.5em }
}
+ \dim_set:Nn \l__piton_left_margin_dim { \box_wd:N \l_tmpa_box + 0.5em }
}
\ttfamily
\bool_if:NT \c__piton_footnote_bool { \begin { savenotes } }
@@ -393,36 +490,30 @@
\group_end:
\mode_if_vertical:TF \mode_leave_vertical: \newline
\lua_now:n { piton.CountLines(token.scan_argument()) } { ##1 }
- \dim_compare:nNnT \l__piton_left_margin_dim < \c_zero_dim
+ \bool_lazy_and:nnT \l__piton_left_margin_auto_bool \l__piton_line_numbers_bool
{
- \bool_if:NT \l__piton_line_numbers_bool
+ \bool_if:NTF \l__piton_all_line_numbers_bool
{
- \bool_if:NTF \l__piton_all_line_numbers_bool
+ \hbox_set:Nn \l_tmpa_box
{
- \hbox_set:Nn \l_tmpa_box
- {
- \footnotesize
- \int_to_arabic:n
- { \g__piton_visual_line_int + \l__piton_nb_lines_int }
- }
+ \footnotesize
+ \int_to_arabic:n
+ { \g__piton_visual_line_int + \l__piton_nb_lines_int }
}
+ }
+ {
+ \lua_now:n
+ { piton.CountNonEmptyLines(token.scan_argument()) }
+ { ##1 }
+ \hbox_set:Nn \l_tmpa_box
{
- \lua_now:n
- { piton.CountNonEmptyLines(token.scan_argument()) }
- { ##1 }
- \hbox_set:Nn \l_tmpa_box
- {
- \footnotesize
- \int_to_arabic:n
- {
- \g__piton_visual_line_int +
- \l__piton_nb_non_empty_lines_int
- }
- }
+ \footnotesize
+ \int_to_arabic:n
+ { \g__piton_visual_line_int + \l__piton_nb_non_empty_lines_int }
}
- \dim_set:Nn \l__piton_left_margin_dim
- { \box_wd:N \l_tmpa_box + 0.5 em }
}
+ \dim_set:Nn \l__piton_left_margin_dim
+ { \box_wd:N \l_tmpa_box + 0.5 em }
}
\ttfamily
\bool_if:NT \c__piton_footnote_bool { \begin { savenotes } }
@@ -636,6 +727,8 @@
local Punct = K ( S ".,:;!" )
local Tab = P "\t" * Lc ( '\\l__piton_tab_tl' )
+local SpaceIndentation =
+ Lc ( '\\__piton_an_indentation_space:' ) * K " "
local EOL =
P "\r"
*
@@ -644,6 +737,8 @@
+
Lc ( '\\__piton_end_line: \\__piton_newline: \\__piton_begin_line:' )
)
+ *
+ SpaceIndentation ^ 0
local Delim = K ( S "[()]" )
local Operator =
K ( P "!=" + P "<>" + P "==" + P "<<" + P ">>" + P "<=" + P ">=" + P ":="
@@ -938,6 +1033,7 @@
local SyntaxPythonAux =
Lc ( '\\__piton_begin_line:' ) *
( ( space - P "\r" ) ^0 * P "\r" ) ^ -1 *
+ SpaceIndentation ^ 0 *
( ( space^1 * -1 )
+ EOL
+ Tab
@@ -959,7 +1055,7 @@
+ DefClass
+ Keyword * ( Space + Punct + Delim + EOL + -1)
+ Decorator
- + OperatorWord
+ + OperatorWord * ( Space + Punct + Delim + EOL + -1)
+ Builtin * ( Space + Punct + Delim + EOL + -1)
+ Identifier
+ Number
@@ -970,6 +1066,10 @@
local t = SyntaxPython : match ( code ) -- match is a method of the LPEG
for _ , s in ipairs(t) do tex.tprint(s) end
end
+function piton.pitonParse(code)
+ local s = ( Cs ( ( P '##' / '#' + 1 ) ^ 0 ) ) : match ( code )
+ return piton.Parse(s)
+end
function piton.ParseFile(name,first_line,last_line)
s = ''
local i = 0
More information about the tex-live-commits
mailing list.