summaryrefslogtreecommitdiff
path: root/macros/luatex/latex/piton/piton.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2022-10-24 03:03:39 +0000
committerNorbert Preining <norbert@preining.info>2022-10-24 03:03:39 +0000
commit74697976d2ffe935077542593ccbb18a00603251 (patch)
treeca88ce389275df22be5c2c843de613d8003bf684 /macros/luatex/latex/piton/piton.dtx
parent588d4f81788b3a24bd9bd480ec40bb55be4d1da1 (diff)
CTAN sync 202210240303
Diffstat (limited to 'macros/luatex/latex/piton/piton.dtx')
-rw-r--r--macros/luatex/latex/piton/piton.dtx857
1 files changed, 756 insertions, 101 deletions
diff --git a/macros/luatex/latex/piton/piton.dtx b/macros/luatex/latex/piton/piton.dtx
index 4aeabac72b..7d7a94fa1d 100644
--- a/macros/luatex/latex/piton/piton.dtx
+++ b/macros/luatex/latex/piton/piton.dtx
@@ -1,5 +1,4 @@
-% \iffalse -*- coding: utf-8 ; -*- \fi
-% \iffalse meta-comment
+% \iffalse -*- coding: utf-8 ; -*- \fi \iffalse meta-comment
%
% Copyright (C) 2022 by F. Pantigny
% -----------------------------------
@@ -16,8 +15,8 @@
%
% \fi
% \iffalse
-\def\myfileversion{0.7}
-\def\myfiledate{2022/10/08}
+\def\myfileversion{0.8}
+\def\myfiledate{2022/10/23}
%
%
%<*batchfile>
@@ -57,38 +56,13 @@ version 2005/12/01 or later.
\fvset{commandchars=\~\#\@,formatcom=\color{gray}}
\captionsetup{labelfont = bf}
\usepackage{ragged2e}
-\usepackage[escape-inside=$$]{piton} % $$
+\usepackage[footnotehyper,escape-inside=$$]{piton} % $$
\def\interitem{\vskip 7mm plus 2 mm minus 3mm}
\parindent 0pt
\skip\footins = 2\bigskipamount
-\begin{filecontents}[noheader,overwrite]{example1.txt}
-from math import pi
-
-def arctan(x,n=10):
- """Compute the value of arctan(x)
- n is the number of terms if the sum"""
- if x < 0:
- return -arctan(-x) # recursive call
- elif x > 1:
- return pi/2 - arctan(1/x)
- ## (we have used that $\arctan(x)+\arctan(1/x)=\frac{\pi}{2}$ for $x>0$)\footnote{This LaTeX escape has been done by beginning the comment by \ttfamily\#\#.}
- else
- s = 0
- for k in range(n):
- s += (-1)**k/(2*k+1)*x**(2*k+1)
- return s
-\end{filecontents}
-
-\begin{filecontents}[noheader,overwrite]{example2.txt}
-def fact(n):
- if n==0:
- return 1
- else:
- $\colorbox{yellow!50}{$return n*fact(n-1)$}$
-\end{filecontents}
-
+\PitonOptions{gobble=2}
\EnableCrossrefs
@@ -126,8 +100,25 @@ def fact(n):
% Here is an exemple of code typeset by \pkg{piton}, with the environment |{Piton}|.
%
% \bigskip
-% \PitonInputFile{Example1.txt}
%
+% \begin{Piton}
+% from math import pi
+%
+% def arctan(x,n=10):
+% '''Compute the value of arctan(x)
+% n is the number of terms of the sum'''
+% if x < 0:
+% return -arctan(-x) # recursive call
+% elif x > 1:
+% return pi/2 - arctan(1/x)
+% ## (we have used that $\arctan(x)+\arctan(1/x)=\frac{\pi}{2}$ for $x>0$)\footnote{This LaTeX escape has been done by beginning the comment by \ttfamily\#\#.}
+% else:
+% s = 0
+% for k in range(n):
+% s += (-1)**k/(2*k+1)*x**(2*k+1)
+% return s
+% \end{Piton}
+%
%
% \bigskip
%
@@ -139,10 +130,20 @@ def fact(n):
%
% \section{Use of the package}
%
-% In order to use the package \pkg{piton}, one has only to load the package in
-% its document with the standard command |\usepackage| and remember that the
-% compilation must be done with |lualatex| (and no other LaTeX engine).
+% The package \pkg{piton} should be loaded with the classical command
+% |\usepackage|: |\usepackage{piton}|.
%
+% \smallskip
+% Nevertheless, we have two remarks:
+% \begin{itemize}
+% \item the package \pkg{piton} uses the package \pkg{xcolor} (but \pkg{piton}
+% does \emph{not} load \pkg{xcolor}: if \pkg{xcolor} is not loaded before the
+% |\begin{document}|, a fatal error will be raised).
+% \item the package \pkg{piton} must be used with LuaLaTeX exclusively: if
+% another LaTeX engine (|latex|, |pdflatex|, |xelatex|,\dots ) is used, a
+% fatal error will be raised.
+% \end{itemize}
+%
% \medskip
% The package \pkg{piton} provides three tools to typeset Python code: the
% command |\piton|, the environment |{Piton}| and the command |\PitonInputFile|.
@@ -153,15 +154,18 @@ def fact(n):
% \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|:
+% cf.~\ref{NewPitonEnvironment} p.~\pageref{NewPitonEnvironment}.
% \item The command |\PitonInputFile| is used to insert and typeset a whole
-% external file.
+% external file.
% \end{itemize}
%
% \bigskip
-% It's possible to compose comments in LaTeX by beginning with |##| (it's a
+% It's possible to compose comments in LaTeX by beginning them with |##| (it's a
% ``LaTeX escape''). The characters |##| themselves won't be printed and the
-% spaces after |##| are removed.
+% spaces after |##| are removed. These comments will be called ``LaTeX
+% comments'' in this document.
%
% \section{Customization}
%
@@ -169,7 +173,8 @@ def fact(n):
%
% The command |\PitonOptions| takes in as argument a comma-separated list of
% \textsl{key=value} pairs. The scope of the settings done by that command is
-% the current TeX group.
+% the current TeX group.\footnote{We remind that an LaTeX environment is, in
+% particular, a TeX group.}
%
% \begin{itemize}
% \item The key |gobble| takes in as value a positive integer~$n$: the first $n$
@@ -194,23 +199,27 @@ def fact(n):
% \item With the key |all-line-numbers|, \emph{all} the lines are numbered,
% including the empty ones.
%
-% \item \colorbox{yellow!50}{\textbf{New 0.7}}\enskip By default, the counter of
-% lines is set to zero at the beginning of each environment |{Piton}| or use of
-% |\PitonInputFile|. With the key |resume|, that reinitialisation is not done.
+% \item By default, the counter of lines is set to zero at the beginning of each
+% environment |{Piton}| or use of |\PitonInputFile|. With the key |resume|, that
+% reinitialisation is not done.
%
-% \item \colorbox{yellow!50}{\textbf{New 0.7}}\enskip The key |splittable| allows
-% pages breaks within the environments |{Piton}| and the listings produced by
+% \item The key |splittable| allows pages breaks within the environments
+% |{Piton}| and the listings produced by
% |\PitonInputFile|.
%
-% \item \colorbox{yellow!50}{\textbf{New 0.7}}\enskip 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{The environments \texttt{\{Piton\}} are breakable,
-% even whithin 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}.}
+% \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{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}.}
+%
+% \item \colorbox{yellow!50}{\textbf{New 0.8}}\enskip The key |left-margin|
+% corresponds to a margin on the left. That key may be useful in conjonction
+% with the key |line-numbers| or the key |line-all-numbers| if one does not want
+% the numbers in an overlapping position on the left.
% \end{itemize}
%
% \bigskip
@@ -223,26 +232,41 @@ def fact(n):
% from math import pi
%
% def arctan(x,n=10):
-% """Compute the value of arctan(x)
-% n is the number of terms if the sum"""
+% '''Compute the value of arctan(x)
+% n is the number of terms of the sum'''
% if x < 0:
-% return -arctan(-x) # recursive call
+% return -arctan(-x) # recursive call
% elif x > 1:
-% return pi/2 - arctan(1/x)
-% ## (we have used that $\arctan(x)+\arctan(1/x)=\frac{\pi}{2}$ pour $x>0$)
+% return pi/2 - arctan(1/x)
+% ## (we have used that $\arctan(x)+\arctan(1/x)=\frac{\pi}{2}$ pour $x>0$)
% else
-% s = 0
-% for k in range(n):
-% s += (-1)**k/(2*k+1)*x**(2*k+1)
-% return s
+% s = 0
+% for k in range(n):
+% s += (-1)**k/(2*k+1)*x**(2*k+1)
+% return s
% \end{Piton}
% \end{Verbatim}
% \endgroup
%
-%
% \begingroup
-% \PitonOptions{line-numbers,auto-gobble,background-color = gray!15}
-% \PitonInputFile{Example1.txt}
+% \PitonOptions{line-numbers,background-color = gray!15}
+% \begin{Piton}
+% from math import pi
+%
+% def arctan(x,n=10):
+% '''Compute the value of arctan(x)
+% n is the number of terms of the sum'''
+% if x < 0:
+% return -arctan(-x) # recursive call
+% elif x > 1:
+% return pi/2 - arctan(1/x)
+% ## (we have used that $\arctan(x)+\arctan(1/x)=\frac{\pi}{2}$ for $x>0$)
+% else
+% s = 0
+% for k in range(n):
+% s += (-1)**k/(2*k+1)*x**(2*k+1)
+% return s
+% \end{Piton}
% \endgroup
%
% \subsection{The key escape-inside}
@@ -251,7 +275,7 @@ def fact(n):
% (that is to say in the instruction |\usepackage|). For technical reasons, it
% can't be used in the command |\PitonOptions|. That option takes in as value
% two characters which will be used to delimit pieces of code which will
-% thrown directly to LaTeX (and composed by LaTeX).e
+% thrown directly to LaTeX (and composed by LaTeX).
%
% \medskip
% In the following example, we assume that the extension \pkg{piton} has been
@@ -275,21 +299,31 @@ def fact(n):
% \end{Piton}
% \end{Verbatim}
%
-% \PitonInputFile{Example2.txt}
-%
+% \begin{Piton}
+% def fact(n):
+% if n==0:
+% return 1
+% else:
+% $\colorbox{yellow!50}{$return n*fact(n-1)$}$
+% \end{Piton}
+%
% \bigskip
%
% \emph{Caution} : The escape to LaTeX allowed by the characters of
% |escape-inside| is not active in the strings nor in the Python comments
% (however, it's possible to have a whole Python comment composed in LaTeX by
-% beginning it with |##|).
+% beginning it with |##|; such comments are merely called ``LaTeX comments'' in
+% this document).
%
%
% \subsection{The styles}
%
+% \label{styles}
+%
% The package \pkg{piton} provides the command |\SetPitonStyle| to customize the
% different styles used to format the syntactic elements of the Python listings.
-% The customizations done by that command are limited to the current TeX group.
+% The customizations done by that command are limited to the current TeX
+% group.\footnote{We remind that an LaTeX environment is, in particuilar, a TeX group.}
%
% \bigskip
% The command |\SetPitonStyle| takes in as argument a comma-separated list of
@@ -323,8 +357,12 @@ def fact(n):
% With that setting, we will have : \piton{def cube(x) : return x * x * x }
% \endgroup
%
-% \medskip
-% The different styles are described in the table \ref{Semantic}.
+% \bigskip
+% The different styles are described in the table \ref{Semantic}. The initial
+% settings done by \pkg{piton} in |piton.sty| are inspired by the style
+% \pkg{manni} de Pygments.\footnote{See: \url{https://pygments.org/styles/}.
+% Remark that, by default, Pygments provides for its style \pkg{manni} a colored
+% background whose color is the HTML color \texttt{\#F0F3F3}.}
%
%
%
@@ -355,8 +393,8 @@ def fact(n):
% Name.Class & the name of the classes at the point of their definition \\
% Exception & the names of the exceptions (eg: \texttt{SyntaxError}) \\
% Comment & the comments beginning with \verb|#| \\
-% LaTeX & the comments beginning by \verb|##| which are composed in LaTeX by
-% \pkg{piton} (\verb|##| is an espace sequence to LaTeX) \\
+% Comment.LaTeX & the comments beginning by \verb|##| which are composed in LaTeX by
+% \pkg{piton} (and called merely ``LaTeX comments'' in this document) \\
% Keyword.Constant & |True|, |False| and |None| \\
% Keyword & the following keywords :
% \ttfamily assert, break, case, continue, del,
@@ -373,9 +411,12 @@ def fact(n):
%
% \subsection{Creation of new environments}
%
+% \label{NewPitonEnvironment}
+%
% Since the environment |{Piton}| has to catch its body in a special way (more
% or less as verbatim text), it's not possible to construct new environments
-% directly over the environment |{Piton}|
+% directly over the environment |{Piton}| with the classical commands
+% |\newenvironment| or |\NewDocumentEnvironment|.
%
% That's why \pkg{piton} provides a command |\NewPitonEnvironment|. That
% command takes in three mandatory arguments.
@@ -387,7 +428,14 @@ def fact(n):
% With the following instruction, a new environment |{Python}| will be
% constructed with the same behaviour as |{Piton}|:
%
-% \verb|\NewPitonEnvironment{Python}{}{}{}|
+% {\color{gray}\verb|\NewPitonEnvironment{Python}{}{}{}|}
+%
+% \bigskip
+% If one wishes an environment |{Python}| with takes in as optional argument
+% (between square brackets) the keys of the command |\PitonOptions|, it's
+% possible to program as follows:
+%
+% {\color{gray}\verb|\NewPitonEnvironment{Python}{O{}}{\PitonOptions{#1}}{}|}
%
% \bigskip
% If one wishes to format Python code in a box of \pkg{tcolorbox}, it's possible
@@ -400,6 +448,397 @@ def fact(n):
% \end{verbatim}
%
%
+% \section{Advanced features}
+%
+% \subsection{Footnotes in the environments of piton}
+%
+% \label{footnote}
+% If you want to put footnotes in an environment |{Piton}| or
+% (or, more unlikely, in a listing produced by |\PitonInputFile|), you can use a
+% pair |\footnotemark|--|\footnotetext|.
+%
+% \smallskip
+% It's also possible to extract the footnotes with the help of the package
+% \pkg{footnote} or the package \pkg{footnotehyper}.
+%
+% \smallskip
+% If \pkg{piton} is loaded with the option |footnote| (with
+% |\usepackage[footnote]{piton}| or with |\PassOptionsToPackage|), the
+% package \pkg{footnote} is loaded (if it is not yet loaded) and it is used to
+% extract the footnotes.
+%
+% \smallskip
+% If \pkg{piton} is loaded with the option |footnotehyper|, the package
+% \pkg{footnotehyper} is loaded (if it is not yet loaded) ant it is used to
+% extract footnotes.
+%
+% \smallskip
+% Caution: The packages \pkg{footnote} and \pkg{footnotehyper} are incompatible.
+% The package \pkg{footnotehyper} is the successor of the package \pkg{footnote}
+% and should be used preferently. The package \pkg{footnote} has some drawbacks,
+% in particular: it must be loaded after the package \pkg{xcolor} and it is not
+% perfectly compatible with \pkg{hyperref}.
+%
+% \medskip
+% In this document, the package \pkg{piton} has been loaded with the option
+% |footnotehyper|: see the first page of this document for an example of a
+% footnote in an environment |{Piton}|.
+%
+%
+% \section{Examples}
+%
+%
+% \subsection{Line numbering}
+%
+% By default, the numbers of the lines are composed by \pkg{piton} in an
+% overlapping position on the left (by using internally the command |\llap| of LaTeX).
+%
+% In order to avoid that overlapping, it's necessary to reserve a place for the
+% number of the lines with the key |left-margin|.
+%
+%
+%
+% \begingroup
+% \fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
+% \begin{Verbatim}
+% ~emphase&\PitonOptions{background-color=gray!10, left-margin = 5mm, line-numbers}@
+% \begin{Piton}
+% def arctan(x,n=10):
+% if x < 0:
+% return -arctan(-x) ## (appel récursif)
+% elif x > 1:
+% return pi/2 - arctan(1/x) ## (autre appel récursif)
+% else:
+% return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
+% \end{Piton}
+% \end{Verbatim}
+% \endgroup
+%
+%
+%
+% \begingroup
+% \PitonOptions{background-color=gray!10,left-margin = 5mm, line-numbers}
+% \begin{Piton}
+% def arctan(x,n=10):
+% if x < 0:
+% return -arctan(-x) ## (appel récursif)
+% elif x > 1:
+% return pi/2 - arctan(1/x) ## (autre appel récursif)
+% else:
+% return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
+% \end{Piton}
+% \endgroup
+%
+%
+%
+%
+% \subsection{Formatting of the LaTeX comments}
+%
+% It's possible to modify the style |Comment.LaTeX| (with |\SetPitonStyle|) in
+% order to display the LaTeX comments (which begin with |##|) aligned on the
+% right margin.
+%
+%
+% \begingroup
+% \fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
+% \begin{Verbatim}
+% \PitonOptions{background-color=gray!10}
+% ~emphase&\SetPitonStyle{Comment.LaTeX = \hfill \normalfont\color{gray}}@
+% \begin{Piton}
+% def arctan(x,n=10):
+% if x < 0:
+% return -arctan(-x) ## appel récursif
+% elif x > 1:
+% return pi/2 - arctan(1/x) ## autre appel récursif
+% else:
+% return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
+% \end{Piton}
+% \end{Verbatim}
+% \endgroup
+%
+% \begingroup
+% \PitonOptions{background-color=gray!10}
+% \SetPitonStyle{Comment.LaTeX = \hfill \normalfont\color{gray}}
+% \begin{Piton}
+% def arctan(x,n=10):
+% if x < 0:
+% return -arctan(-x) ## appel récursif
+% elif x > 1:
+% return pi/2 - arctan(1/x) ## autre appel récursif
+% else:
+% return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
+% \end{Piton}
+% \endgroup
+%
+%
+% \vspace{1cm}
+% It's also possible to display these LaTeX comments in a kind of second column
+% by limiting the width of the Python code by an environment |{minipage}| of LaTeX.
+%
+%
+% \begingroup
+% \fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
+% \begin{Verbatim}
+% \PitonOptions{background-color=gray!10}
+% ~emphase&\NewDocumentCommand{\MyLaTeXCommand}{m}{\hfill \normalfont\itshape\rlap{\quad #1}}@
+% ~emphase&\SetPitonStyle{Comment.LaTeX = \MyLaTeXCommand}@
+% ~emphase&\begin{minipage}{12cm}@
+% \begin{Piton}
+% def arctan(x,n=10):
+% if x < 0:
+% return -arctan(-x) ## appel récursif
+% elif x > 1:
+% return pi/2 - arctan(1/x) ## autre appel récursif
+% else:
+% s = 0
+% for k in range(n):
+% s += (-1)**k/(2*k+1)*x**(2*k+1)
+% return s
+% \end{Piton}
+% ~emphase&\end{minipage}@
+% \end{Verbatim}
+% \endgroup
+%
+%
+%
+% \begingroup
+% \PitonOptions{background-color=gray!10}
+% \NewDocumentCommand{\MyLaTeXCommand}{m}{\hfill \normalfont\itshape\rlap{\quad #1}}
+% \SetPitonStyle{Comment.LaTeX = \MyLaTeXCommand}
+% \begin{minipage}{12cm}
+% \begin{Piton}
+% def arctan(x,n=10):
+% if x < 0:
+% return -arctan(-x) ## appel récursif
+% elif x > 1:
+% return pi/2 - arctan(1/x) ## autre appel récursif
+% else:
+% s = 0
+% for k in range(n):
+% s += (-1)**k/(2*k+1)*x**(2*k+1)
+% return s
+% \end{Piton}
+% \end{minipage}
+% \endgroup
+%
+%
+%
+% \subsection{Notes in the listings}
+%
+% In order to be able to extract the notes (which are typeset with the command
+% |\footnote|, the extension \pkg{piton} must be loaded with the key |footnote|
+% or the key |footenotehyper| as explained in the section \ref{footnote}
+% p.~\pageref{footnote}. In this document, the extension \pkg{piton} has been
+% loaded with the key |footnotehyper|.
+%
+% Of course, in an environment |{Piton}|, a command |\footnote| may appear only
+% within a LaTeX comment (which begins with |##|). It's possible to have comments
+% which contain only that command |\footnote|. That's the case in the following example.
+%
+%
+%
+% \begingroup
+% \fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
+% \begin{Verbatim}
+% \PitonOptions{background-color=gray!10}
+% \begin{Piton}
+% def arctan(x,n=10):
+% if x < 0:
+% return -arctan(-x)~emphase&##\footnote{First recursive call.}]@
+% elif x > 1:
+% return pi/2 - arctan(1/x)~emphase&##\footnote{Second recursive call.}@
+% else:
+% return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
+% \end{Piton}
+% \end{Verbatim}
+% \endgroup
+%
+% \begingroup
+% \PitonOptions{background-color=gray!10}
+% \begin{Piton}
+% def arctan(x,n=10):
+% if x < 0:
+% return -arctan(-x)##\footnote{First recursive call.}
+% elif x > 1:
+% return pi/2 - arctan(1/x)##\footnote{Second recursive call.}
+% else:
+% return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
+% \end{Piton}
+% \endgroup
+%
+%
+% \vspace{1cm}
+%
+% If an environment |{Piton}| is used in an environment |{minipage}| of LaTeX,
+% the notes are composed, of course, at the foot of the environment
+% |{minipage}|. Recall that such |{minipage}| can't be broken by a page break.
+
+%
+% \begingroup
+% \fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
+% \begin{Verbatim}
+% \PitonOptions{background-color=gray!10}
+% \emphase\begin{minipage}{\linewidth}
+% \begin{Piton}
+% def arctan(x,n=10):
+% if x < 0:
+% return -arctan(-x)~emphase&##\footnote{First recursive call.}@
+% elif x > 1:
+% return pi/2 - arctan(1/x)~emphase&##\footnote{Second recursive call.}@
+% else:
+% return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
+% \end{Piton}
+% \end{minipage}
+% \end{Verbatim}
+% \endgroup
+%
+% \begingroup
+% \PitonOptions{background-color=gray!10}
+% \begin{minipage}{\linewidth}
+% \begin{Piton}
+% def arctan(x,n=10):
+% if x < 0:
+% return -arctan(-x)##\footnote{First recursive call.}
+% elif x > 1:
+% return pi/2 - arctan(1/x)##\footnote{Second recursive call.}
+% else:
+% return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
+% \end{Piton}
+% \end{minipage}
+% \endgroup
+%
+%
+% \vspace{1cm}
+% If one embed an environment |{Piton}| in an environment |{minipage}|
+% (typically in order to limit the width of a colored background), it's
+% necessary to embed the whole environment |{minipage}| in an environment
+% |{savenotes}| (of \pkg{footnote} or \pkg{footnotehyper}) in order to have the
+% footnotes composed at the bottom of the page.
+%
+% \begingroup
+% \fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
+% \begin{Verbatim}
+% \PitonOptions{background-color=gray!10}
+% ~emphase&\begin{savenotes}@
+% \begin{minipage}{13cm}
+% \begin{Piton}
+% def arctan(x,n=10):
+% if x < 0:
+% return -arctan(-x)~emphase&##\footnote{First recursive call.}@
+% elif x > 1:
+% return pi/2 - arctan(1/x)~emphase&##\footnote{Second recursive call.}@
+% else:
+% return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
+% \end{Piton}
+% \end{minipage}
+% ~emphase&\end{savenotes}@
+% \end{Verbatim}
+% \endgroup
+%
+%
+%
+% \begin{savenotes}
+% \PitonOptions{background-color=gray!10}
+% \begin{minipage}{13cm}
+% \begin{Piton}
+% def arctan(x,n=10):
+% if x < 0:
+% return -arctan(-x)##\footnote{First recursive call.}
+% elif x > 1:
+% return pi/2 - arctan(1/x)##\footnote{Second recursive call.}
+% else:
+% return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
+% \end{Piton}
+% \end{minipage}
+% \end{savenotes}
+%
+%
+% \subsection{An example of tuning of the styles}
+%
+% The graphical styles have been presented in the section \ref{styles},
+% p.~\pageref{styles}.
+%
+% \smallskip
+% We present now an example of tuning of these styles adapted to the documents
+% in black and white. We use the font \emph{DejaVu Sans Mono}\footnote{See:
+% \url{https://dejavu-fonts.github.io}} specified by the command |\setmonofont| of
+% \pkg{fontspec}.
+%
+%
+% \begin{Verbatim}
+% \setmonofont[Scale=0.85]{DejaVu Sans Mono}
+%
+% \SetPitonStyle
+% {
+% Number = ,
+% String = \itshape ,
+% String.Doc = \color{gray} \slshape ,
+% Operator = ,
+% Operator.Word = \bfseries ,
+% Name.Builtin = ,
+% Name.Function = \bfseries \colorbox{gray!20} ,
+% Comment = \color{gray} ,
+% Comment.LaTeX = \color{gray},
+% Keyword = \bfseries ,
+% Name.Namespace = ,
+% Name.Class = ,
+% Name.Type = ,
+% InitialValues = \color{gray}
+% }
+% \end{Verbatim}
+%
+%
+% \begingroup
+%
+% \setmonofont[Scale=0.85]{DejaVu Sans Mono}
+%
+% \PitonOptions{splittable}
+%
+% \SetPitonStyle
+% {
+% Number = ,
+% String = \itshape ,
+% String.Doc = \color{gray} \slshape ,
+% Operator = ,
+% Operator.Word = \bfseries ,
+% Name.Builtin = ,
+% Name.Function = \bfseries \colorbox{gray!20} ,
+% Comment = \color{gray} ,
+% Comment.LaTeX = \color{gray} ,
+% Keyword = \bfseries ,
+% Name.Namespace = ,
+% Name.Class = ,
+% Name.Type = ,
+% InitialValues = \color{gray}
+% }
+%
+%
+% \bigskip
+%
+% \begin{Piton}
+% from math import pi
+%
+% def arctan(x,n=10):
+% '''Compute the value of arctan(x)
+% n is the number of terms if the sum'''
+% if x < 0:
+% return -arctan(-x) # appel récursif
+% elif x > 1:
+% return pi/2 - arctan(1/x)
+% ## (we have used that $\arctan(x)+\arctan(1/x)=\pi/2$ for $x>0$)
+% else:
+% s = 0
+% for k in range(n):
+% s += (-1)**k/(2*k+1)*x**(2*k+1)
+% return s
+% \end{Piton}
+%
+% \endgroup
+%
+%
+% \bigskip
+% The previous example has been composed while the key |splittable| (of
+% |\PitonOptions|) is in force. That's why a page break may have occurred.
% \clearpage
%
% \section{Implementation}
@@ -427,10 +866,27 @@ def fact(n):
% \end{macrocode}
%
% \bigskip
+% The boolean |\c_@@_footnotehyper_bool| will indicate if the option
+% |footnotehyper| is used.
+% \begin{macrocode}
+\bool_new:N \c_@@_footnotehyper_bool
+% \end{macrocode}
+%
+% \medskip
+% The boolean |\c_@@_footnote_bool| will indicate if the option |footnote| is
+% used, but quicky, it will also be set to |true| if the option |footnotehyper|
+% is used.
+% \begin{macrocode}
+\bool_new:N \c_@@_footnote_bool
+% \end{macrocode}
+%
+% \bigskip
% We define a set of keys for the options at load-time.
% \begin{macrocode}
\keys_define:nn { piton / package }
{
+ footnote .bool_set:N = \c_@@_footnote_bool ,
+ footnotehyper .bool_set:N = \c_@@_footnotehyper_bool ,
escape-inside .tl_set:N = \c_@@_escape_inside_tl ,
escape-inside .initial:n = ,
unknown .code:n = \msg_error:nn { piton } { unknown~key~for~package }
@@ -441,9 +897,9 @@ def fact(n):
\msg_new:nnn { piton } { unknown~key~for~package }
{
Unknown~key.\\
- You~have~used~the~key~'\l_keys_key_str'~but~the~only~key~available~here~
- is~the~key~'escape-inside'.~Other~keys~are~available~in~\token_to_str:N
- \PitonOptions.\\
+ You~have~used~the~key~'\l_keys_key_str'~but~the~only~keys~available~here~
+ are~'escape-inside',~'footnote'~and~'footnotehyper'.~Other~keys~are~
+ available~in~\token_to_str:N \PitonOptions.\\
That~key~will~be~ignored.
}
% \end{macrocode}
@@ -490,10 +946,79 @@ def fact(n):
% \end{macrocode}
%
%
+% \begin{macrocode}
+\msg_new:nnn { piton } { footnote~with~footnotehyper~package }
+ {
+ Footnote~forbidden.\\
+ You~can't~use~the~option~'footnote'~because~the~package~
+ footnotehyper~has~already~been~loaded.~
+ If~you~want,~you~can~use~the~option~'footnotehyper'~and~the~footnotes~
+ within~the~environments~of~piton~will~be~extracted~with~the~tools~
+ of~the~package~footnotehyper.\\
+ If~you~go~on,~the~package~footnote~won't~be~loaded.
+ }
+% \end{macrocode}
+%
+% \begin{macrocode}
+\msg_new:nnn { piton } { footnotehyper~with~footnote~package }
+ {
+ You~can't~use~the~option~'footnotehyper'~because~the~package~
+ footnote~has~already~been~loaded.~
+ If~you~want,~you~can~use~the~option~'footnote'~and~the~footnotes~
+ within~the~environments~of~piton~will~be~extracted~with~the~tools~
+ of~the~package~footnote.\\
+ If~you~go~on,~the~package~footnotehyper~won't~be~loaded.
+ }
+% \end{macrocode}
+%
+% \medskip
+% \begin{macrocode}
+\bool_if:NT \c_@@_footnote_bool
+ {
+% \end{macrocode}
+% The class \cls{beamer} has its own system to extract footnotes and that's why
+% we have nothing to do if \cls{beamer} is used.
+% \begin{macrocode}
+ \@ifclassloaded { beamer }
+ { \bool_set_false:N \c_@@_footnote_bool }
+ {
+ \@ifpackageloaded { footnotehyper }
+ { \@@_error:n { footnote~with~footnotehyper~package } }
+ { \usepackage { footnote } }
+ }
+ }
+% \end{macrocode}
+%
+% \begin{macrocode}
+\bool_if:NT \c_@@_footnotehyper_bool
+ {
+% \end{macrocode}
+% The class \cls{beamer} has its own system to extract footnotes and that's why
+% we have nothing to do if \cls{beamer} is used.
+% \begin{macrocode}
+ \@ifclassloaded { beamer }
+ { \bool_set_false:N \c_@@_footnote_bool }
+ {
+ \@ifpackageloaded { footnote }
+ { \@@_error:n { footnotehyper~with~footnote~package } }
+ { \usepackage { footnotehyper } }
+ \bool_set_true:N \c_@@_footnote_bool
+ }
+ }
+% \end{macrocode}
+% The flag |\c_@@_footnote_bool| is raised and so, we will only have to test
+% |\c_@@_footnote_bool| in order to know if we have to insert an environment
+% |{savenotes}|.
%
% \medskip
% \subsection{Parameters}
%
+% The following token list will contains the (potential) informations to write
+% on the |aux| (to be used in the next compilation).
+% \begin{macrocode}
+\tl_new:N \g_@@_aux_tl
+% \end{macrocode}
+%
% \medskip
% The following flag corresponds to the key |splittable| of |\PitonOptions|.
% \begin{macrocode}
@@ -501,11 +1026,41 @@ def fact(n):
% \end{macrocode}
%
% \medskip
-% The following string corresponds to the key |background-color|.
+% The following string corresponds to the key |background-color| of |\PitonOptions|.
% \begin{macrocode}
\str_new:N \l_@@_background_color_str
% \end{macrocode}
+%
+% \medskip
+% We will compute the maximal width of the lines of an environment |{Piton}| in
+% |\l_@@_width_dim|.
+% \begin{macrocode}
+\dim_new:N \l_@@_width_dim
+% \end{macrocode}
+% The value of that dimension as written on the |aux| file will be stored in
+% |\l_@@_width_on_aux_dim|.
+% \begin{macrocode}
+\dim_new:N \l_@@_width_on_aux_dim
+% \end{macrocode}
+%
+% \medskip
+% We will count the environments |{Piton}| (and, in fact, also the commands
+% |\PitonInputFile|, despite the name |\g_@@_env_int|).
+% \begin{macrocode}
+\int_new:N \g_@@_env_int
+% \end{macrocode}
%
+% \medskip
+% The following boolean corresponds to the key |slim| of |\PitonOptions|.
+% \begin{macrocode}
+\bool_new:N \l_@@_slim_bool
+% \end{macrocode}
+%
+% \medskip
+% The following dimension corresponds to the key |left-margin| of |\PitonOptions|.
+% \begin{macrocode}
+\dim_new:N \l_@@_left_margin_dim
+% \end{macrocode}
%
% \subsection{The gobbling mechanism}
%
@@ -531,14 +1086,24 @@ def fact(n):
% \begin{macrocode}
\cs_set_protected:Npn \@@_begin_line: #1 \@@_end_line:
{
+ \bool_lazy_and:nnT \l_@@_splittable_bool \c_@@_footnote_bool
+ { \begin { savenotes } }
% \end{macrocode}
-% Be careful: the following |\hbox_set:Nn| et |\hbox_set_to_wd:Nnn| take in an
-% argument by curryfication.
+%
+% Be careful: there is curryfication in the following lines.
% \begin{macrocode}
- \str_if_empty:NTF \l_@@_background_color_str
+ \bool_if:NTF \l_@@_slim_bool
{ \hbox_set:Nn \l_tmpa_box }
- { \hbox_set_to_wd:Nnn \l_tmpa_box \linewidth }
{
+ \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 } }
+ }
+ }
+ {
+ \skip_horizontal:N \l_@@_left_margin_dim
\bool_if:NT \l_@@_line_numbers_bool
{
\bool_if:NF \l_@@_all_line_numbers_bool
@@ -547,26 +1112,35 @@ def fact(n):
}
\strut
\str_if_empty:NF \l_@@_background_color_str \space
- #1 \hfill
+ #1 \hfil
}
- \box_set_dp:Nn \l_tmpa_box { \box_dp:N \l_tmpa_box + 1 pt }
- \box_set_ht:Nn \l_tmpa_box { \box_ht:N \l_tmpa_box + 1.5 pt }
+% \end{macrocode}
+% We compute in |\l_@@_width_dim| the maximal width of the lines of the
+% environments.
+% \begin{macrocode}
+ \dim_compare:nNnT { \box_wd:N \l_tmpa_box } > \l_@@_width_dim
+ { \dim_set:Nn \l_@@_width_dim { \box_wd:N \l_tmpa_box } }
+ \box_set_dp:Nn \l_tmpa_box { \box_dp:N \l_tmpa_box + 1.25 pt }
+ \box_set_ht:Nn \l_tmpa_box { \box_ht:N \l_tmpa_box + 1.25 pt }
\tl_if_empty:NTF \l_@@_background_color_str
{ \box_use_drop:N \l_tmpa_box }
{
\vbox_top:n
{
- \hbox_to_wd:nn \linewidth
+ \hbox:n
{
\exp_args:NV \color \l_@@_background_color_str
\vrule height \box_ht:N \l_tmpa_box
depth \box_dp:N \l_tmpa_box
- width \linewidth
+ width \l_@@_width_on_aux_dim
}
\skip_vertical:n { - \box_ht_plus_dp:N \l_tmpa_box }
- \box_use_drop:N \l_tmpa_box
+ \box_set_wd:Nn \l_tmpa_box \l_@@_width_on_aux_dim
+ \box_use_drop:N \l_tmpa_box
}
}
+ \bool_lazy_and:nnT \l_@@_splittable_bool \c_@@_footnote_bool
+ { \end { savenotes } }
\vspace { - 2.5 pt }
}
% \end{macrocode}
@@ -610,10 +1184,14 @@ def fact(n):
all-line-numbers .value_forbidden:n = true ,
resume .bool_set:N = \l_@@_resume_bool ,
resume .value_forbidden:n = true ,
- splittable .bool_set:N = \l_@@_splittable_bool ,
- splittable .default:n = true ,
+ splittable .bool_set:N = \l_@@_splittable_bool ,
+ splittable .default:n = true ,
background-color .str_set:N = \l_@@_background_color_str ,
background-color .value_required:n = true ,
+ slim .bool_set:N = \l_@@_slim_bool ,
+ slim .default:n = true ,
+ left-margin .dim_set:N = \l_@@_left_margin_dim ,
+ left-margin .value_required:n = true ,
unknown .code:n =
\msg_error:nn { piton } { Unknown~key~for~PitonOptions }
}
@@ -626,7 +1204,7 @@ def fact(n):
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,~
- line-numbers,~resume~and~splittable.\\
+ left-margin,~line-numbers,~resume,~slim~and~splittable.\\
If~you~go~on,~that~key~will~be~ignored.
}
% \end{macrocode}
@@ -655,12 +1233,49 @@ def fact(n):
\hbox_overlap_left:n
{
{ \color { gray } \footnotesize \int_to_arabic:n \g_@@_line_int }
- \quad
+ \skip_horizontal:n { 0.4 em }
}
}
% \end{macrocode}
%
%
+% \medskip
+% \subsection{The command to write on the aux file}
+%
+%
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_write_aux:
+ {
+ \tl_if_empty:NF \g_@@_aux_tl
+ {
+ \iow_now:Nn \@mainaux { \ExplSyntaxOn }
+ \iow_now:Nx \@mainaux
+ {
+ \tl_gset:cn { c_@@_ \int_use:N \g_@@_env_int _ tl }
+ { \exp_not:V \g_@@_aux_tl }
+ }
+ \iow_now:Nn \@mainaux { \ExplSyntaxOff }
+ }
+ \tl_gclear:N \g_@@_aux_tl
+ }
+% \end{macrocode}
+%
+% \begin{macrocode}
+\cs_new_protected:Npn \@@_width_to_aux:
+ {
+ \bool_if:NT \l_@@_slim_bool
+ {
+ \str_if_empty:NF \l_@@_background_color_str
+ {
+ \tl_gput_right:Nx \g_@@_aux_tl
+ {
+ \dim_set:Nn \l_@@_width_on_aux_dim
+ { \dim_use:N \l_@@_width_dim + 0.5 em }
+ }
+ }
+ }
+ }
+% \end{macrocode}
%
% \medskip
% \subsection{The main commands and environments for the final user}
@@ -695,12 +1310,24 @@ def fact(n):
% \begin{macrocode}
\NewDocumentCommand { \PitonInputFile } { m }
{
+ \int_gincr:N \g_@@_env_int
+ \tl_gclear:N \g_@@_aux_tl
+ \tl_if_exist:cT { c_@@ _ \int_use:N \g_@@_env_int _ tl }
+ { \use:c { c_@@ _ \int_use:N \g_@@_env_int _ tl } }
+ \bool_if:NF \l_@@_splittable_bool
+ { \bool_if:NT \c_@@_footnote_bool { \begin { savenotes } } }
+ \dim_compare:nNnT \l_@@_width_on_aux_dim = \c_zero_dim
+ { \dim_set_eq:NN \l_@@_width_on_aux_dim \linewidth }
\bool_if:NF \l_@@_resume_bool { \int_gzero:N \g_@@_line_int }
\group_begin:
\dim_set_eq:NN \parindent \c_zero_dim
\ttfamily
\lua_now:e { ParseFile(token.scan_argument()) } { #1 }
+ \@@_width_to_aux:
\group_end:
+ \@@_write_aux:
+ \bool_if:NF \l_@@_splittable_bool
+ { \bool_if:NT \c_@@_footnote_bool { \end { savenotes } } }
}
% \end{macrocode}
%
@@ -708,7 +1335,8 @@ def fact(n):
% \bigskip
% \begin{macrocode}
\NewDocumentCommand { \NewPitonEnvironment } { m m m m }
- {
+ {
+ \dim_zero:N \parindent
% \end{macrocode}
% We construct a TeX macro which will catch as argument all the tokens until
% |\end{|\texttt{\textsl{name_env}}|}| with, in that
@@ -725,8 +1353,17 @@ def fact(n):
}
{
\group_end:
- \mode_if_vertical:TF \mode_leave_vertical: \newline
- \bool_if:NF \l_@@_splittable_bool \vbox_top:n
+ \mode_if_vertical:TF
+ { \mode_leave_vertical: }
+ \newline
+% \end{macrocode}
+% Be careful: there is curryfication in the following code.
+% \begin{macrocode}
+ \bool_if:NF \l_@@_splittable_bool
+ {
+ \bool_if:NT \c_@@_footnote_bool { \begin { savenotes } }
+ \vbox_top:n
+ }
{
\ttfamily
\dim_zero:N \lineskip
@@ -748,12 +1385,16 @@ def fact(n):
}
{ ##1 }
\vspace { 2.5 pt }
+ \@@_width_to_aux:
}
+ \bool_if:NF \l_@@_splittable_bool
+ { \bool_if:NT \c_@@_footnote_bool { \end { savenotes } } }
% \end{macrocode}
% The following |\end{#1}| is only for the groups and the stack of
% environments of LaTeX.
% \begin{macrocode}
\end { #1 }
+ \@@_write_aux:
}
% \end{macrocode}
%
@@ -766,6 +1407,12 @@ def fact(n):
\NewDocumentEnvironment { #1 } { #2 }
{
#3
+ \int_gincr:N \g_@@_env_int
+ \tl_gclear:N \g_@@_aux_tl
+ \tl_if_exist:cT { c_@@ _ \int_use:N \g_@@_env_int _ tl }
+ { \use:c { c_@@ _ \int_use:N \g_@@_env_int _ tl } }
+ \dim_compare:nNnT \l_@@_width_on_aux_dim = \c_zero_dim
+ { \dim_set_eq:NN \l_@@_width_on_aux_dim \linewidth }
\bool_if:NF \l_@@_resume_bool { \int_gzero:N \g_@@_line_int }
\group_begin:
\box_clear:N \l_tmpa_box
@@ -999,7 +1646,10 @@ lpeg.locale(lpeg) -- mandatory
local alpha , digit , space , punct = lpeg.alpha , lpeg.digit , lpeg.space , lpeg.punct
-local letter = alpha + S"âàçéèêëïîôûüÂÀÇÉÈÊËÏÎÔÛÜ_"
+-- Remember that à, â, ç, etc. are strings of length 2 (2 bytes)
+local letter = alpha + P "_"
+ + P "â" + P "à" + P "ç" + P "é" + P "è" + P "ê" + P "ë" + P "ï" + P "î" + P "ô" + P "û" + P "ü" +
+ P "Â" + P "À" + P "Ç" + P "É" + P "È" + P "Ê" + P "Ë" + P "Ï" + P "Î" + P "Ô" + P "Û" + P "Ü"
local alphanum = letter + digit
@@ -1310,7 +1960,6 @@ local Set = C ( P "{" )
* ItemOfSet * ( C ( P "," ) * ItemOfSet ) ^ 0
* C ( P "}" )
-
local Operator = K ( P "!=" + P "==" + P "<<" + P ">>" + S "-~+/*%=<>&.@|" , 'Operator')
local OperatorWord = K ( P "in" + P "is" + P "and" + P "or" + P "not" , 'Operator.Word')
@@ -1450,8 +2099,14 @@ end
% New keys |resume|, |splittable| and |background-color| in |\PitonOptions|.
%
% The file |piton.lua| has been embedded in the file |piton.sty|. That means
-% that the extension \pkg{piton} is now enterily contained in the file |piton.sty|.
+% that the extension \pkg{piton} is now entirely contained in the file |piton.sty|.
+%
+% \subsection*{Changes between versions 0.7 and 0.8}
%
+% New keys |footnote| and |footnotehyper| at load-time.
+%
+% New key |left-margin|.
+%
% \end{document}
%
%