Debian Codegraph @

texmf-dist/doc/lualatex/piton/piton.tex

raw
1 % -*- coding: utf-8 ; -*- This file should be compiled with LuaLaTeX only
2 \listfiles
3 \documentclass{article}
4
5 \usepackage{geometry}
6 \geometry{left=2.8cm,right=2.8cm,top=2.5cm,bottom=2.5cm,papersize={21cm,29.7cm}}
7 \usepackage{fontspec}
8 \usepackage[dvipsnames,svgnames]{xcolor}
9 \usepackage{caption,tabularx,luacolor,lua-ul,upquote,varwidth}
10 \usepackage[framemethod=tikz]{mdframed}
11 \usepackage{tcolorbox}
12 \tcbuselibrary{skins,breakable}
13 \tcbset{enhanced}
14 \def\emphase{\bgroup\color{RoyalPurple}\let\next=}
15
16 % We use \MakeShortVerb of shortvrb and not \DefineShortVerb of fancyvrb
17 % because we don't want small elements in verbatim to be colored in gray
18 \usepackage{shortvrb}
19 \MakeShortVerb{\|}
20
21 \usepackage{fancyvrb}
22 \fvset{commandchars=\~\#\@,formatcom=\color{gray}}
23
24 \usepackage[executable=python3.exe]{pyluatex}
25
26 \usepackage{underscore}
27
28 \usepackage{booktabs}
29
30 \captionsetup{labelfont = bf}
31 \usepackage{ragged2e}
32
33 \NewDocumentCommand {\pkg} {m} {\textsf{#1}}
34 \NewDocumentCommand {\cls} {m} {\textsf{#1}}
35
36 \usepackage[footnotehyper]{piton}
37 \PitonOptions
38 {
39 splittable = 4 ,
40 math-comments ,
41 begin-escape = ! ,
42 end-escape = ! ,
43 begin-escape-math = \( ,
44 end-escape-math = \) ,
45 detected-commands = { \highLight , \footnote , \emph , \textsl , \textbackslash } ,
46 vertical-detected-commands = \newpage ,
47 raw-detected-commands = { \NameTable , \rowcolor }
48 }
49
50 \ExplSyntaxOn
51
52 \dim_new:N \l__pantigny_width_dim
53
54 \keys_define:nn { pantigny }
55 { width .dim_set:N = \l__pantigny_width_dim }
56
57 \NewPitonEnvironment { Code } { O { } }
58 {
59 \SetPitonStyle{ Number = , Comment = , String = }
60 \PitonOptions{language = minimal}
61 \char_set_catcode_other:N |
62 \cs_set_eq:NN \emph \emphase
63 \dim_zero:N \l__pantigny_width_dim
64 \keys_set:nn { pantigny } { #1 }
65 \color{gray}
66 \dim_compare:nNnT \l__pantigny_width_dim > \c_zero_dim
67 {
68 \PitonOptions { width = \l__pantigny_width_dim }
69 \begin{minipage}[c]{\l__pantigny_width_dim}
70 }
71 }
72 { \dim_compare:nNnT \l__pantigny_width_dim > \c_zero_dim
73 { \end{minipage} }
74 }
75
76 \ExplSyntaxOff
77
78
79 \parindent 0pt
80 \skip\footins = 2\bigskipamount
81
82 \def\CC{{C\nolinebreak[4]\hspace{-.05em}\raisebox{.4ex}{\tiny\bfseries ++}}}
83
84 \usepackage{makeidx}
85 \makeindex
86
87 \NewDocumentCommand{\indexcommand}{m}{\index{#1@\texttt{\textbackslash #1}}}
88
89 \NewDocumentCommand{\indexenv}{m}{\index{#1@\texttt{\{#1\}}}}
90
91 \NewDocumentCommand{\Definition}{m}
92 {{\setlength{\fboxsep}{1pt}\colorbox{gray!20}{\ttfamily \vphantom{gl}#1}}}
93
94 \NewDocumentCommand{\DefinitionCommand}{m}
95 {{\setlength{\fboxsep}{1pt}\colorbox{gray!20}{\ttfamily
96 \vphantom{gl}\textbackslash #1}}}
97
98 \usepackage[hyperfootnotes = false]{hyperref}
99 \usepackage{bookmark}
100
101 \VerbatimFootnotes
102
103 \catcode`\" = 11
104
105 \begin{document}
106
107 \title{The package \pkg{piton}\thanks{This document corresponds to the
108 version~\PitonFileVersion\space of \pkg{piton}, at the date of~\PitonFileDate.}}
109 \author{F. Pantigny \\ \texttt{[email protected]}}
110
111 \maketitle
112
113 \begin{abstract}
114 The package \pkg{piton} provides tools to typeset computer listings, with
115 syntactic highlighting, by using the Lua library LPEG. It requires LuaLaTeX.
116 \end{abstract}
117
118
119 \section{Presentation}
120
121
122
123 The package \pkg{piton} uses the Lua library LPEG\footnote{LPEG is a
124 pattern-matching library for Lua, written in C, based on \emph{parsing
125 expression grammars}:
126 \url{http://www.inf.puc-rio.br/~roberto/lpeg/}} for parsing computer
127 listings and typesets them with syntactic highlighting. Since it uses the Lua
128 of LuaLaTeX, it works with |lualatex| only (and won't work with the other
129 engines: |latex|, |pdflatex| and |xelatex|). It does not use external program
130 and the compilation does not require |--shell-escape|. The compilation is very
131 fast since all the parsing is done by the library LPEG, written in C.
132
133 \bigskip
134 Here is an example of code typeset by \pkg{piton}, with the environment |{Piton}|.
135
136 \bigskip
137
138 \begin{Piton}
139 from math import pi
140
141 def arctan(x,n:int=10):
142 """Compute the mathematical value of arctan(x)
143
144 n is the number of terms in the sum
145 """
146 if x < 0:
147 return -arctan(-x) # recursive call
148 elif x > 1:
149 return pi/2 - arctan(1/x)
150 #> (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\#>.}
151 else:
152 s = 0
153 for k in range(n):
154 s += (-1)**k/(2*k+1)*x**(2*k+1)
155 return s
156 \end{Piton}
157
158
159 \medskip
160 The main alternatives to the package \pkg{piton} are probably the packages
161 \pkg{listings} and \pkg{minted}.
162
163 \medskip
164 The name of this extension (\pkg{piton}) has been chosen arbitrarily by
165 reference to the pitons used by the climbers in mountaineering.
166
167
168 \section{Installation}
169
170 The package \pkg{piton} is contained in two files: |piton.sty| and |piton.lua|
171 (the LaTeX file |piton.sty| loaded by |\usepackage| will load the Lua file
172 |piton.lua|). Both files must be in a repertory where LaTeX will be able to
173 find them, for instance in a |texmf| tree. However, the best is to install
174 \pkg{piton} with a TeX distribution such as MiKTeX, TeX Live or MacTeX.
175
176 \medskip
177 Note that the character \emph{quote} (U+0027 : \verb|'|) is never transformed by
178 \pkg{piton} in an apostrophe U+2019. There is no point loading the package
179 \pkg{upquote}.
180
181 \section{Use of the package}
182
183 The package \pkg{piton} must be used with \textbf{LuaLaTeX exclusively}: if
184 another LaTeX engine (|latex|, |pdflatex|, |xelatex|,\dots ) is used, a fatal
185 error will be raised.
186
187 \subsection{Loading the package}
188
189 The package \pkg{piton} should be loaded by: |\usepackage{piton}|.
190
191 \smallskip
192 The package \pkg{piton} uses and \emph{loads} the package \pkg{xcolor}. It
193 does not use any exterior program.
194
195 \subsection{Choice of the computer language}
196
197 The package \pkg{piton} supports two kinds of languages:
198 \begin{itemize}
199 \item the languages natively supported by \pkg{piton}, which are Python, OCaml,
200 C~(in fact \CC), SQL and two special languages called |minimal| and |verbatim|;
201 \item the languages defined by the end user by using the built-in command
202 |\NewPitonLanguage| described p.~\pageref{NewPitonLanguage} (the parsers of
203 those languages can't be as precise as those of the languages supported
204 natively by \pkg{piton}).
205 \end{itemize}
206
207
208
209 \smallskip
210 By default, the language used is Python.
211
212 \smallskip
213 \index{language (key)}
214 It's possible to change the current language with the command |\PitonOptions|
215 and its key \Definition{language}: |\PitonOptions{language = OCaml}|.
216
217 \smallskip
218 In fact, for \pkg{piton}, the names of the computer languages are always
219 \textbf{case-insensitive}. In this example, we might have written |Ocaml| or
220 |ocaml|.
221
222 \smallskip
223 For the developers, let's say that the name of the current language is stored
224 (in lower case) in the L3 public variable |\l_piton_language_str|.
225
226 \smallskip
227 In what follows, we will speak of Python, but the features described also
228 apply to the other languages.
229
230 \subsection{The tools provided to the user}
231
232 \indexenv{Piton}
233
234 The package \pkg{piton} provides several tools to typeset computer listings: the
235 command |\piton|, the environment |{Piton}| and the command |\PitonInputFile|.
236
237 \begin{itemize}
238 \item The command \DefinitionCommand{piton} should be used to typeset small
239 pieces of code inside a paragraph. For example:
240
241 {\color{gray}\verb|\piton{def square(x): return x*x}|}\qquad
242 \piton{def square(x): return x*x}
243
244 The syntax and particularities of the command |\piton| are detailed below.
245
246 \item The environment \Definition{\{Piton\}} should be used to
247 typeset multi-lines code. Since it takes its argument in a verbatim mode, it
248 can't be used within the argument of a LaTeX command. For sake of
249 customization, it's possible to define new environments similar to the
250 environment |{Piton}| with the command |\NewPitonEnvironment| or its friends:
251 cf.~\ref{NewPitonEnvironment} p.~\pageref{NewPitonEnvironment}.
252
253 \item The command \DefinitionCommand{PitonInputFile} is used to insert and
254 typeset an external file: cf.~\ref{PitonInputFile}
255 p.~\pageref{PitonInputFile}.
256
257
258 \end{itemize}
259
260 \subsection{The double syntax of the command \texttt{\textbackslash piton}}
261
262 \indexcommand{piton}
263
264 In fact, the command |\piton| is provided with a double syntax. It may be used
265 as a standard command of LaTeX taking its argument between curly braces
266 (|\piton{...}|) but it may also be used with a syntax similar to the syntax of
267 the LaTeX command |\verb|, that is to say with the argument delimited by two identical
268 characters (e.g.: \verb!\piton|...|! or \verb!\piton+...+!).
269
270 \begin{itemize}
271 \item {\color{blue} \textsf{Syntax} \verb|\piton{...}|}
272
273 \nobreak
274 When its argument is given between curly braces, the command |\piton| does not
275 take its argument in verbatim mode. In particular:
276 \begin{itemize}
277 \item several consecutive spaces will be replaced by only one space (and also
278 the character of end of line),
279
280 {\color{cyan} but the command |\|␣ is provided to force the insertion of a space};
281
282 \item it's not possible to use |%| inside the argument,
283
284 {\color{cyan} but the command |\%| is provided to insert a |%|};
285
286 \item the braces must be appear by pairs correctly nested
287
288 {\color{cyan} but the commands |\{| and |\}| are provided for individual braces};
289
290 \item the LaTeX commands\footnote{That concerns the commands beginning with a
291 backslash but also the active characters (with catcode equal to 13). } of the
292 argument are fully expanded (in the TeX meaning) and not executed,
293
294 {\color{cyan} so, it's possible to use |\\| to insert a backslash}.
295 \end{itemize}
296
297
298 The other characters (including |#|, |^|, |_|, |&|, |$| and |@|) %$
299 must be inserted without backslash.
300
301 \bigskip
302 \begin{tabular}{>{\color{gray}}w{l}{75mm}@{\hspace*{1cm}}l}
303 \omit Examples : \hfil \\
304 \noalign{\vskip1mm}
305 \verb|\piton{MyString = '\\n'}| &
306 \piton{MyString = '\\n'} \\
307 \verb|\piton{def even(n): return n\%2==0}| &
308 \piton{def even(n): return n\%2==0} \\
309 \verb|\piton{c="#" # an affectation }| &
310 \piton{c="#" # an affectation } \\
311 \verb|\piton{c="#" \ \ \ # an affectation }| &
312 \piton{c="#" \ \ \ # an affectation } \\
313 \verb|\piton{MyDict = {'a': 3, 'b': 4 }}| &
314 \piton{MyDict = {'a': 3, 'b': 4 }}
315 \end{tabular}
316
317 \bigskip
318 It's possible to use the command |\piton| with that syntax in the arguments of
319 a LaTeX command.\footnote{For example, it's possible to use the command
320 |\piton| in a footnote. Example : \piton{s = 123}.}
321
322 However, since the argument is expanded (in the TeX sens), one should take
323 care not using in its argument \emph{fragile} commands (that is to say
324 commands which are neither \emph{protected} nor \emph{fully expandable}).
325
326 \bigskip
327 \item {\color{blue} \textsf{Syntax} \verb!\piton|...|!}
328
329 \nobreak
330 When the argument of the command |\piton| is provided between two identical
331 characters (all the characters are allowed except |%|, |\|, |#|, |{|, |}| and
332 the space), that argument is taken in a \emph{verbatim mode}. Therefore, with
333 that syntax, the command |\piton| can't be used within the argument of another
334 command.
335
336 \medskip
337
338 \begin{tabular}{>{\color{gray}}w{l}{75mm}@{\hspace*{1cm}}l}
339 \omit Examples : \hfil \\
340 \noalign{\vskip1mm}
341 \verb!\piton|MyString = '\n'|! &
342 \piton|MyString = '\n'| \\
343 \verb|\piton!def even(n): return n%2==0!| &
344 \piton!def even(n): return n%2==0! \\
345 \verb|\piton+c="#" # an affectation +| &
346 \piton+c="#" # an affectation + \\
347 \verb|\piton?MyDict = {'a': 3, 'b': 4}?| &
348 \piton!MyDict = {'a': 3, 'b': 4}!
349 \end{tabular}
350
351 \end{itemize}
352
353 \section{Customization}
354
355
356 \subsection{The keys of the command \texttt{\textbackslash PitonOptions}}
357
358
359 \indexcommand{PitonOptions}
360
361 The command |\PitonOptions| takes in as argument a comma-separated list of
362 \textsl{key=value} pairs. The scope of the settings done by that command is
363 the current TeX group.\footnote{We remind that a LaTeX environment is, in
364 particular, a TeX group.}
365
366 These keys may also be applied to an individual environment |{Piton}| (between
367 square brackets).
368
369 \begin{itemize}
370 \item The key \Definition{language} specifies which computer language is
371 considered (that key is case-insensitive). It's possible to use the name of
372 the six built-in languages (|Python|, |OCaml|, |C|, |SQL|, |minimal| and
373 |verbatim|) or the name of a language defined by the user with
374 |\NewPitonLanguage| (cf.~part~\ref{NewPitonLanguage},
375 p.~\pageref{NewPitonLanguage}).
376
377 The initial value is |Python|.
378
379 \item \index{font-command}
380 The key \Definition{font-command} contains instructions of font which will be
381 inserted at the beginning of all the elements composed by \pkg{piton} (without
382 surprise, these instructions are not used for the so-called ``LaTeX comments'').
383
384 The initial value is |\ttfamily| and, thus, \pkg{piton} uses by default the
385 current monospace font.
386
387 The key |font-command| has also an ``additive syntax''. That means that it's
388 possible to write |font-command +=| $\langle$\textsl{instructions}$\rangle$
389 and the tokens $\langle$\textsl{instructions}$\rangle$ will be added
390 on the right of the current value of the parameter.
391
392 In that case, the new formating instructions are added at the right of the current
393 value of the parameter.
394
395 \item \index{gobble}\label{gobble} The key \Definition{gobble} takes in as
396 value a positive integer~$n$: the first $n$ characters are discarded (before
397 the process of highlighting of the code) for each line of the environment
398 |{Piton}|. These characters are not necessarily spaces.
399
400 When the key |gobble| is used without value, it is equivalent to the key
401 |auto-gobble|, that we describe now.
402
403 \item \index{auto-gobble}\index{gobble!auto-gobble} When the key
404 \Definition{auto-gobble} is in force, the extension \pkg{piton} computes the
405 minimal value $n$ of the number of consecutive spaces beginning each (non
406 empty) line of the environment |{Piton}| and applies |gobble| with that value
407 of~$n$.
408
409 \item \index{env-gobble}\index{gobble!env-gobble}
410 When the key \Definition{env-gobble} is in force, \pkg{piton} analyzes the last
411 line of the environment |{Piton}|, that is to say the line which contains
412 |\end{Piton}| and determines whether that line contains only spaces followed
413 by the |\end{Piton}|. If we are in that situation, \pkg{piton} computes the
414 number~$n$ of spaces on that line and applies |gobble| with that value of~$n$.
415 The name of that key comes from \emph{environment gobble}: the effect of
416 gobble is set by the position of the commands
417 \texttt{\textbackslash begin\{Piton\}}
418 and \texttt{\textbackslash end\{Piton\}} which delimit the current environment.
419
420 \item \index{line-numbers} The key \Definition{line-numbers} activates the
421 line numbering in the environments |{Piton}| and in the listings resulting
422 from the use of |\PitonInputFile|.
423
424 In fact, the key |line-numbers| has several subkeys.
425 \begin{itemize}
426 \item With the key \Definition{line-numbers/skip-empty-lines}, the empty lines
427 (which contains only spaces) are considered as non existent for the line
428 numbering (if the key |/absolute|, described below, is in force, the key
429 |/skip-empty-lines| is no-op in |\PitonInputFile|). The initial value of that
430 key is |true| (and not |false|).\footnote{For the language Python, the empty
431 lines in the docstrings are taken into account (by design).}
432
433 \item The key \Definition{line-numbers/step} should be used when we don't want
434 to print all the numbers of line. If $n$ is the value of that key, only one
435 number out of~$n$ will be printed. Of course, the initial value is 1.
436
437 \item With the key \Definition{line-numbers/label-empty-lines}, the labels
438 (that is to say the numbers) of the empty lines are displayed. If the key
439 |/skip-empty-line| is in force, the clé |/label-empty-lines| is no-op. The
440 initial value of that key is~|true|.\footnote{When the key
441 |split-on-empty-lines| is in force, the labels of the empty lines are never printed.}
442
443 \item With the key \Definition{line-numbers/absolute}, in the listings
444 generated in |\PitonInputFile|, the numbers of the lines displayed are
445 \emph{absolute} (that is to say: they are the numbers of the lines in the
446 file). That key may be useful when |\PitonInputFile| is used to insert only a
447 part of the file (cf. part~\ref{part-of-a-file}, p.~\pageref{part-of-a-file}).
448 The key |/absolute| is no-op in the environments |{Piton}| and those created
449 by |\NewPitonEnvironment|.
450
451 \item The key \Definition{line-numbers/start} requires that the line numbering
452 begins to the value of the key.
453
454 \item With the key \Definition{line-numbers/resume}, the counter of lines is
455 not set to zero at the beginning of each environment |{Piton}| or use of
456 |\PitonInputFile| as it is otherwise. That allows a numbering of the lines
457 across several environments.
458
459 \item The key \Definition{line-numbers/sep} is the horizontal distance between
460 the numbers of lines (inserted by |line-numbers|) and the beginning of the
461 lines of code. The initial value is 0.7~em.
462
463 \item The key \Definition{line-numbers/format} is a list of tokens which are inserted before
464 the number of line in order to format it. It's possible to put, \emph{at the
465 end} of the list, a LaTeX command with one argument, such as, for example,
466 |\fbox|.
467
468 The initial value is |\footnotesize\color{gray}|.
469
470 \item \colorbox{yellow!50}{\textbf{New 4.11}}
471
472 \nobreak
473 The key \Definition{line-numbers/position} specifies the position of the numbers.
474 Two values are possible: |left| and |right|. The initial value is |left|.
475
476
477 \item \colorbox{yellow!50}{\textbf{New 4.13}}
478
479 \nobreak
480 With the key \Definition{line-numbers/lmmono10-drawn}, the numbers of lines use the
481 font \emph{Latin Modern Mono 10}, but the numbers are drawn and are not displayed as text.
482 Therefore, during a copy-paste, the \textsc{pdf} readers won't catch those numbers of lines.
483
484 \end{itemize}
485
486 For convenience, a mechanism of factorisation of the prefix |line-numbers| is
487 provided. That means that it is possible, for instance, to write:
488
489 \begin{Code}
490 \PitonOptions
491 {
492 line-numbers =
493 {
494 skip-empty-lines = false ,
495 label-empty-lines = false ,
496 sep = 1 em ,
497 format = \footnotesize \color{blue}
498 }
499 }
500 \end{Code}
501
502 Be careful : the previous code is not enough to print the numbers of lines.
503 For that, one also has to use the key |line-numbers| is a absolute way, that
504 is to say without value.
505
506 \item \index{left-margin} The key \Definition{left-margin} corresponds to a
507 margin on the left. That key may be useful in conjunction with the key
508 |line-numbers| if one does not want the numbers in an overlapping position on
509 the left.
510
511 It's possible to use the key |left-margin| with the special value |auto|. With that
512 value, if the key |line-numbers| is in force, a margin will be automatically
513 inserted to fit the numbers of lines. See an example part
514 \ref{example-numbering} on page~\pageref{example-numbering}.
515
516
517 \item \index{right-margin}
518 \colorbox{yellow!50}{\textbf{Nouveau 4.11}}
519
520 \nobreak
521 The key |right-margin| is similar to the previous one, but for the margin on the
522 right.
523
524 \item \index{background-color} \label{background-color} The key
525 \Definition{background-color} sets the background color of the environments
526 |{Piton}| and the listings produced by |\PitonInputFile| (it's possible to fix
527 the width of that background with the key |width| or the key |max-width|
528 described below).
529
530 The key |background-color| accepts a color
531 defined «on the fly». For example, it's possible to write
532 |background-color = [cmyk]{0.1,0.05,0,0}|.
533
534 \smallskip
535 The key |background-color| supports also as value a \emph{list} of colors. In
536 this case, the successive rows are colored by using the colors of the list in
537 a cyclic way.
538
539 \smallskip
540 In that list, the special color \Definition{none} may be used to specify no
541 color at all.
542
543 \emph{Example} : |\PitonOptions{background-color = {gray!15,none}}|
544
545 \item \index{rounded-corners}
546 It's possible to use the key \Definition{rounded-corners} to require rounded
547 corners for the colored panels drawn by the key |background-color| The initial
548 value of that is $0$~pt, which means that the corners are not rounded. If the
549 key |rounded-corners| is used, the extension \pkg{tikz} must be loaded because
550 those rounded corners are drawn by using \pkg{tikz}. If \pkg{tikz} is not
551 loaded, an error will be raised at the first use of the key |rounded-corners|.
552
553 The default value of the key |rounded-corners| is $4$~pt.\footnote{This value is the
554 initial value of the \emph{rounded corners} of TikZ.}
555
556 \item \index{prompt-background-color} With the key
557 \Definition{prompt-background-color}, \pkg{piton} adds a
558 color background to the lines beginning with the prompt ``|>>>|'' (and its
559 continuation ``|...|'') characteristic of the Python consoles with
560 \textsc{repl} (\emph{read-eval-print loop}).
561
562 The initial value is: |gray!15|
563
564 \item \index{width} \label{width} The key \Definition{width} fixes the width
565 of the listing in the \textsc{pdf}. The initial value of that parameter
566 is the current value of |\linewidth| (LaTeX parameter which corresponds to the
567 width of the lines of text).
568
569 That parameter is used for:
570 \begin{itemize}
571 \item the breaking the lines which are too long (except, of course, when the key
572 |break-lines| is set to false: cf.~p.~\pageref{line-breaks});
573 \item the width of the backgrounds specified by the keys |background-color| and
574 |prompt-background-color| described below;
575 \item the width of the colored backgrounds added by |\rowcolor|
576 (cf.~p.~\pageref{rowcolor});
577 \item the width of the LaTeX box created by the key |box| (cf. p.~\pageref{box});
578 \item the width of the graphical box created by the key |tcolorbox|
579 (cf.~p.~\pageref{tcolorbox}).
580 \end{itemize}
581
582 \item \index{max-width}
583
584 The key \Definition{max-width} is similar to the key |width| but it fixes the
585 \emph{maximal} width of the lines. If all the lines of the listing are shorter
586 than the value provided to |max-width|, the parameter |width| will be equal to
587 the maximal length of the lines of the listing, that is to say the natural width of
588 the listing.
589
590 For legibility of the code, |width=min| is a shortcut for |max-width=\linewidth|.
591
592
593 \item \index{show-spaces-in-strings} When the key
594 \Definition{show-spaces-in-strings} is activated, the spaces in the
595 strings of characters\footnote{With the language Python that feature applies
596 only to the short strings (delimited by~\verb|'| or~\verb|"|) and, in
597 particular, it does not apply for the \emph{doc strings}. In OCaml, that
598 feature does not apply to the \emph{quoted strings}.} are replaced by the
599 character~␣ (U+2423 : \textsc{open box}). Of course, that character~U+2423
600 must be present in the monospace font which is used.\footnote{The initial
601 value of |font-command| is |\ttfamily| and, thus, by default, \pkg{piton}
602 merely uses the current monospace font.}
603
604 \nobreak
605 \begingroup
606 \PitonOptions{show-spaces-in-strings} Example :
607 \piton|my_string = 'Very good answer'| \endgroup
608
609 With the key \index{show-spaces} \Definition{show-spaces}, all the spaces are
610 replaced by U+2423 (and no line break can occur on those ``visible spaces'',
611 even when the key |break-lines|\footnote{cf. \ref{line-breaks}
612 p.~\pageref{line-breaks}} is in force). By the way, one should remark that all
613 the trailing spaces (at the end of a line) are deleted by \pkg{piton} --- and,
614 therefore, won't be represented by~␣. Moreover, when the key |show-spaces| is
615 in force, the tabulations at the beginning of the lines are represented by arrows.
616 \end{itemize}
617
618 \bigskip
619 \begingroup
620 \small
621 \fvset{commandchars=\~\&\@}
622 \begin{Verbatim}
623 ~emphase&\begin{Piton}[language=C,line-numbers,gobble,background-color=gray!15@
624 ~emphase& rounded-corners,width=min,splittable=4]@
625 void bubbleSort(int arr[], int n) {
626 int temp;
627 int swapped;
628 for (int i = 0; i < n-1; i++) {
629 swapped = 0;
630 for (int j = 0; j < n - i - 1; j++) {
631 if (arr[j] > arr[j + 1]) {
632 temp = arr[j];
633 arr[j] = arr[j + 1];
634 arr[j + 1] = temp;
635 swapped = 1;
636 }
637 }
638 if (!swapped) break;
639 }
640 }
641 ~emphase&~textbackslash&@end{Piton}@
642 \end{Verbatim}
643 \endgroup
644
645 \begingroup
646 \PitonOptions{language=C,line-numbers,gobble=4,background-color = gray!15,
647 rounded-corners,width=min}
648 \begin{Piton}
649 void bubbleSort(int arr[], int n) {
650 int temp;
651 int swapped;
652 for (int i = 0; i < n-1; i++) {
653 swapped = 0;
654 for (int j = 0; j < n - i - 1; j++) {
655 if (arr[j] > arr[j + 1]) {
656 temp = arr[j];
657 arr[j] = arr[j + 1];
658 arr[j + 1] = temp;
659 swapped = 1;
660 }
661 }
662 if (!swapped) break;
663 }
664 }
665 \end{Piton}
666 \endgroup
667
668
669 \bigskip
670 The command |\PitonOptions| provides in fact several other keys which will be
671 described further (see in particular the ``Pages breaks and line breaks'',
672 p.~\pageref{breakable}).
673
674 \subsection{The styles}
675
676 \label{styles}
677 \index{styles (concept of \pkg{piton})}
678
679 \subsubsection{Notion of style}
680
681 The package \pkg{piton} provides the command
682 \DefinitionCommand{SetPitonStyle} to customize the different styles used to
683 format the syntactic elements of the computer listings. The customizations done
684 by that command are limited to the current TeX group.\footnote{We remind that
685 a LaTeX environment is, in particular, a TeX group.}
686
687 \bigskip
688 \indexcommand{SetPitonStyle}
689 The command |\SetPitonStyle| takes in as argument a comma-separated list of
690 \textsl{key=value} pairs. The keys are names of styles and the value are LaTeX
691 formatting instructions.
692
693 \bigskip
694 These LaTeX instructions must be formatting instructions such as
695 |\color{ }|, |\bfseries|, |\slshape|, etc. (the commands of this kind are
696 sometimes called \emph{semi-global} commands). It's also possible to put,
697 \emph{at the end of the list of instructions}, a LaTeX command taking exactly
698 one argument.
699
700 \bigskip
701 Here an example which changes the style used to highlight, in the definition
702 of a Python function, the name of the function which is defined. That code
703 uses the command |\highLight| of \pkg{lua-ul} (that package requires also the
704 package \pkg{luacolor}).
705
706 \begin{Code}
707 \SetPitonStyle
708 { Name.Function = \bfseries \highLight[red!30] }
709 \end{Code}
710
711 In that example, |\highLight[red!30]| must be considered as the name of a
712 LaTeX command which takes in exactly one argument, since, usually, it is used
713 with |\highLight[red!30]{...}|.
714
715 \medskip
716 \begingroup
717 \SetPitonStyle
718 { Name.Function = \bfseries \highLight[red!30] }
719 With that setting, we will have : \piton{def cube(x) : return x * x * x }
720 \endgroup
721
722 \bigskip
723 The different styles, and their use by \pkg{piton} in the different languages
724 which it supports (Python, OCaml, C, SQL, ``|minimal|'' and ``|verbatim|''),
725 are described in the part \ref{Semantic}, starting at the page
726 \pageref{Semantic}.
727
728
729 \bigskip
730 \indexcommand{PitonStyle}
731 The command \DefinitionCommand{PitonStyle} takes in as argument the name of a
732 style and allows to retrieve the value (as a list of LaTeX instructions) of
733 that style. That command is \emph{fully expandable} (in the TeX sens).
734
735 \smallskip
736 For example, it's possible to write |{\PitonStyle{Keyword}{function}}| and we
737 will have the word {\PitonStyle{Keyword}{function}} formatted as a keyword.
738
739 \smallskip
740 The syntax |{\PitonStyle{|\textsl{\texttt{style}}|}{...}}| is mandatory in
741 order to be able to deal both with the semi-global commands and the commands
742 with arguments which may be present in the definition of the style
743 \texttt{\textsl{style}}.
744
745 \bigskip
746 \subsubsection{Global styles and local styles}
747
748 A style may be defined globally with the command |\SetPitonStyle|. That means
749 that it will apply to all the computer languages that use that style.
750
751 \bigskip
752 For example, with the command
753 \begin{Verbatim}
754 \SetPitonStyle{Comment = \color{gray}}
755 \end{Verbatim}
756 all the comments will be composed in gray in all the listings, whatever
757 computer language they use (Python, C, OCaml, etc. or a language defined by
758 the command |\NewPitonLanguage|).
759
760 \bigskip
761 But it's also possible to define a style locally for a given computer
762 language by providing the name of that language as optional argument (between
763 square brackets) to the command |\SetPitonStyle|.\footnote{We recall, that, in
764 the package \pkg{piton}, the names of the computer languages are
765 case-insensitive.}
766
767 \bigskip
768 For example, with the command
769 \begin{Verbatim}
770 \SetPitonStyle~emphase#[SQL]@{Keyword = \color[HTML]{006699} \bfseries \MakeUppercase}
771 \end{Verbatim}
772 the keywords in the SQL listings will be composed in capital letters, even if
773 they appear in lower case in the LaTeX source (we recall that, in SQL, the
774 keywords are case-insensitive).
775
776 \bigskip
777 As expected, if a computer language uses a given style and if that style has
778 no local definition for that language, the global version is used. That notion
779 of ``global style'' has no link with the notion of global definition in TeX
780 (the notion of \emph{group} in TeX).\footnote{As regards the TeX groups, the
781 definitions done by \texttt{\textbackslash SetPitonStyle} are always local.}
782
783 \bigskip
784 The package \pkg{piton} itself (that is to say the file |piton.sty|) defines
785 all the styles globally.
786
787 \bigskip
788
789 \bigskip
790 \subsubsection{The command \textbackslash rowcolor}
791
792 \label{rowcolor}
793 \indexcommand{rowcolor}
794
795 \medskip
796 The extension \pkg{piton} provides the command \DefinitionCommand{rowcolor} which adds
797 a colored background to the current line (the \emph{whole} line and not only the part with
798 text) which may be used in the styles.
799
800 \smallskip
801 The command |\rowcolor| has a syntax similar to the classical command |\color|. For example,
802 it's possible to write |\rowcolor[rgb]{0.9,1,0.9}|.
803
804 \smallskip
805 The command |\rowcolor| is protected against the TeX expansions.
806
807 \smallskip
808 Here is an example for the language Python where we modify the style |String.Doc|
809 of the ``documentation strings'' in order to have a colored background.
810
811 % here, don't use {Code}
812 \begin{Verbatim}
813 ~emphase#\SetPitonStyle{String.Doc = \rowcolor{gray!15}\color{black!80}}@
814 \begin{Piton}[width=min]
815 def square(x):
816 """Computes the square of x
817 Second line of the documentation"""
818 return x*x
819 \end{Piton}
820 \end{Verbatim}
821
822
823 \bigskip
824 \begingroup
825 \SetPitonStyle{String.Doc = \rowcolor{gray!15}\color{black!80}}
826 \begin{Piton}[width=min]
827 def square(x):
828 """Computes the square of x
829 Second line of the documentation"""
830 return x*x
831 \end{Piton}
832 \endgroup
833
834
835 \bigskip
836 If the command |\rowcolor| appears (through a style of \pkg{piton}) inside a
837 command |\piton|, it is no-op (as expected).
838
839
840 \subsubsection{The style UserFunction}
841
842 \index{UserFunction (style)}
843
844 The extension \pkg{piton} provides a special style called~|UserFunction|.
845 That style applies to the names of the functions previously defined by the user
846 (for example, in Python, these names are those following the keyword \piton{def}
847 in a previous listing). The initial value of that style |\PitonStyle{Identifier}|
848 and, therefore, the names of the functions are formatted like the other identifiers
849 (that is to say, by default, with no special formatting except the features provided
850 in |font-command|). However, it's possible to change the value of that style, as any
851 other style, with the command |\SetPitonStyle|.
852
853 \medskip
854 In the following example, we tune the styles |Name.Function| and |UserFunction|
855 so as to have clickable names of functions linked to the definition of the function.
856
857 \begingroup
858
859 \NewDocumentCommand{\MyDefFunction}{m}{\hypertarget{piton:#1}{\color[HTML]{CC00FF}{#1}}}
860 \NewDocumentCommand{\MyUserFunction}{m}{\hyperlink{piton:#1}{#1}}
861
862 \SetPitonStyle
863 {
864 Name.Function = \MyDefFunction ,
865 UserFunction = \MyUserFunction
866 }
867
868 \medskip
869 \begin{Code}
870 \NewDocumentCommand{\MyDefFunction}{m}
871 {\hypertarget{piton:#1}{\color[HTML]{CC00FF}{#1}}}
872 \NewDocumentCommand{\MyUserFunction}{m}{\hyperlink{piton:#1}{#1}}
873
874 \SetPitonStyle{Name.Function = \MyDefFunction, \emph{UserFunction} = \MyUserFunction}
875 \end{Code}
876
877 \smallskip
878
879 \begin{Piton}
880 def transpose(v,i,j):
881 x = v[i]
882 v[i] = v[j]
883 v[j] = x
884
885 def passe(v):
886 for in in range(0,len(v)-1):
887 if v[i] > v[i+1]:
888 transpose(v,i,i+1)
889 \end{Piton}
890
891 \endgroup
892
893
894 \PitonClearUserFunctions[Python]
895
896 \bigskip
897 \begin{small}
898 Of course, the list of the names of Python functions previously défined is
899 kept in the memory of LuaLaTeX (in a global way, that is to say independently
900 of the TeX groups). The extension \pkg{piton} provides a command to clear that
901 list: it's the command \DefinitionCommand{PitonClearUserFunctions}. When it
902 is used without argument, that command is applied to all the computer
903 languages used by the user but it's also possible to use it with an optional
904 argument (between square brackets) which is a list of computer languages to
905 which the command will be applied.\footnote{We remind that, in \pkg{piton},
906 the name of the computer languages are case-insensitive.}
907 \end{small}
908
909 \subsection{Creation of new environments}
910
911 \label{NewPitonEnvironment}
912 \indexcommand{NewPitonEnvironment}
913 \indexcommand{RenewPitonEnvironment}
914 \indexcommand{DeclarePitonEnvironment}
915 \indexcommand{ProvidePitonEnvironment}
916
917
918 Since the environment |{Piton}| has to catch its body in a special way (more
919 or less as verbatim text), it's not possible to construct new environments
920 directly over the environment |{Piton}| with the classical commands
921 |\newenvironment| (of standard LaTeX) or |\NewDocumentEnvironment| (of
922 LaTeX3).
923
924 It's possible to use |\NewEnvironmentCopy| on the environment |{Piton}| but
925 it's not very powerful.
926
927 That's why \pkg{piton} provides a command
928 \DefinitionCommand{NewPitonEnvironment}. That command takes in three mandatory
929 arguments.
930
931 That command has the same syntax as the classical environment
932 |\NewDocumentEnvironment|.\footnote{However, the specifier of argument |b|
933 (used to catch the body of the environment as a LaTeX argument) is
934 not allowed (of course)}
935
936 \medskip
937 There also exist three other commands \DefinitionCommand{RenewPitonEnvironment},
938 \DefinitionCommand{DeclarePitonEnvironment} and
939 \DefinitionCommand{ProvidePitonEnvironment}, similar to the corresponding
940 commands of L3.
941
942 \bigskip
943 With the following instruction, a new environment |{Python}| will be
944 constructed with the same behaviour as |{Piton}|:
945
946 \medskip
947 \begin{Code}
948 \emph{\NewPitonEnvironment}{Python}{O{}}{\PitonOptions{#1}}{}
949 \end{Code}
950
951 \bigskip
952 If one wishes to format Python code in a box of \pkg{mdframed}, it's possible
953 to define an environment |{Python}| with the following code.
954
955 \begin{footnotesize}
956 \begin{Verbatim}
957 \usepackage[framemethod=tikz]{mdframed} % in the preamble
958 \end{Verbatim}
959 \end{footnotesize}
960
961 \begin{Code}
962 \emph{\NewPitonEnvironment}{Python}{}
963 {\begin{mdframed}[roundcorner=3mm]}
964 {\end{mdframed}}
965 \end{Code}
966
967 \bigskip
968 With this new environment |{Python}|, it's possible to write:
969
970 \begin{Code}
971 \emph{\begin{Python}}
972 def square(x):
973 """Compute the square of x"""
974 return x*x
975 \emph{\end{Python}}
976 \end{Code}
977
978 \NewPitonEnvironment{Python}{}
979 {\begin{mdframed}[roundcorner=3mm]}
980 {\end{mdframed}}
981
982 \begin{Python}
983 def square(x):
984 """Compute the square of x"""
985 return x*x
986 \end{Python}
987
988 \bigskip
989 It's possible to a similar construction with an environment of \pkg{tcolorbox}.
990 However, for a better cooperation between \pkg{piton} and \pkg{tcolorbox}, the
991 extension \pkg{piton} provides a key \pkg{tcolorbox}: cf.~p.~\pageref{tcolorbox}.
992
993
994 \section{Definition of new languages with the syntax of listings}
995
996 \indexcommand{NewPitonLanguage}
997 \label{NewPitonLanguage}
998 \index{listings@\pkg{listings} (extension)}
999
1000 \medskip
1001 The package \pkg{listings} is a famous LaTeX package to format computer
1002 listings.
1003
1004 That package provides a command |\lstdefinelanguage| which allows the user to
1005 define new languages. That command is also used by \pkg{listings} itself to
1006 provide the definition of the predefined languages in \pkg{listings} (in fact,
1007 for this task, \pkg{listings} uses a command called |\lst@definelanguage| but
1008 that command has the same syntax as |\lstdefinelanguage|).
1009
1010 \medskip
1011 The package \pkg{piton} provides a command
1012 \DefinitionCommand{NewPitonLanguage} to define new languages (available in
1013 |\piton|, |{Piton}|, etc.) with a syntax which is almost the same as the
1014 syntax of~|\lstdefinelanguage|.
1015
1016 Let's precise that \pkg{piton} does \emph{not} use that command to define the
1017 languages provided natively (Python, OCaml, C, SQL, |minimal| and |verbatim|),
1018 which allows more powerful parsers.
1019
1020 \medskip
1021 For example, in the file |lstlang1.sty|, which is one of the definition files
1022 of \pkg{listings}, we find the following instructions (in version 1.10a).
1023
1024 \begin{small}
1025 \begin{Verbatim}
1026 \lst~@definelanguage{Java}%
1027 {morekeywords={abstract,boolean,break,byte,case,catch,char,class,%
1028 const,continue,default,do,double,else,extends,false,final,%
1029 finally,float,for,goto,if,implements,import,instanceof,int,%
1030 interface,label,long,native,new,null,package,private,protected,%
1031 public,return,short,static,super,switch,synchronized,this,throw,%
1032 throws,transient,true,try,void,volatile,while},%
1033 sensitive,%
1034 morecomment=[l]//,%
1035 morecomment=[s]{/*}{*/},%
1036 morestring=[b]",%
1037 morestring=[b]',%
1038 }[keywords,comments,strings]
1039 \end{Verbatim}
1040 \end{small}
1041
1042 \medskip
1043 In order to define a language called |Java| for \pkg{piton}, one has only to
1044 write the following code {\bfseries where the last argument of
1045 |\lst@definelanguage|, between square brackets, has been discarded} (in fact,
1046 the symbols \verb+%+ may be deleted without any problem).
1047
1048 \begin{small}
1049 \begin{Verbatim}
1050 ~emphase#\NewPitonLanguage@{Java}%
1051 {morekeywords={abstract,boolean,break,byte,case,catch,char,class,%
1052 const,continue,default,do,double,else,extends,false,final,%
1053 finally,float,for,goto,if,implements,import,instanceof,int,%
1054 interface,label,long,native,new,null,package,private,protected,%
1055 public,return,short,static,super,switch,synchronized,this,throw,%
1056 throws,transient,true,try,void,volatile,while},%
1057 sensitive,%
1058 morecomment=[l]//,%
1059 morecomment=[s]{/*}{*/},%
1060 morestring=[b]",%
1061 morestring=[b]',%
1062 }
1063 \end{Verbatim}
1064 \end{small}
1065
1066
1067 \NewPitonLanguage{Java}
1068 {morekeywords={abstract,boolean,break,byte,case,catch,char,class,
1069 const,continue,default,do,double,else,extends,false,final,
1070 finally,float,for,goto,if,implements,import,instanceof,int,
1071 interface,label,long,native,new,null,package,private,protected,
1072 public,return,short,static,super,switch,synchronized,this,throw,
1073 throws,transient,true,try,void,volatile,while},
1074 sensitive,
1075 morecomment=[l]//,
1076 morecomment=[s]{/*}{*/},
1077 morestring=[b]",
1078 morestring=[b]',
1079 }
1080
1081 \medskip
1082 It's possible to use the language Java like any other language defined by
1083 \pkg{piton}.
1084
1085 Here is an example of code formatted in an environment |{Piton}| with
1086 the key |language=Java|.\footnote{We recall that, for \pkg{piton}, the names
1087 of the computer languages are case-insensitive. Hence, it's possible to
1088 write, for instance, |language=java|.}
1089
1090
1091 \bigskip
1092 \begingroup
1093 \small
1094 \PitonOptions{splittable-on-empty-lines}
1095 \begin{Piton}[language = java]
1096 public class Cipher { // Caesar cipher
1097 public static void main(String[] args) {
1098 String str = "The quick brown fox Jumped over the lazy Dog";
1099 System.out.println( Cipher.encode( str, 12 ));
1100 System.out.println( Cipher.decode( Cipher.encode( str, 12), 12 ));
1101 }
1102
1103 public static String decode(String enc, int offset) {
1104 return encode(enc, 26-offset);
1105 }
1106
1107 public static String encode(String enc, int offset) {
1108 offset = offset % 26 + 26;
1109 StringBuilder encoded = new StringBuilder();
1110 for (char i : enc.toCharArray()) {
1111 if (Character.isLetter(i)) {
1112 if (Character.isUpperCase(i)) {
1113 encoded.append((char) ('A' + (i - 'A' + offset) % 26 ));
1114 } else {
1115 encoded.append((char) ('a' + (i - 'a' + offset) % 26 ));
1116 }
1117 } else {
1118 encoded.append(i);
1119 }
1120 }
1121 return encoded.toString();
1122 }
1123 }
1124 \end{Piton}
1125 \endgroup
1126
1127 \bigskip
1128
1129 The keys of the command |\lstdefinelanguage| of \pkg{listings} supported by |\NewPitonLanguage| are:
1130 |morekeywords|, |otherkeywords|, |sensitive|, |keywordsprefix|, |moretexcs|,
1131 |morestring| (with the letters |b|,
1132 |d|, |s| and |m|), |morecomment| (with the letters |i|, |l|, |s|, |n| and |f|\footnote{For the letter |f|, only a specification for a comment beginning in the first column is allowed.}),
1133 |moredelim| (with the letters |i|,
1134 |l|, |s|, |*| and |**|), |moredirectives|, |tag|, |alsodigit|, |alsoletter|
1135 and |alsoother|.
1136
1137 For the description of those keys, we redirect the reader to the documentation
1138 of the package \pkg{listings} (type |texdoc| |listings| in a terminal).
1139
1140 \bigskip
1141 For example, here is a language called ``LaTeX'' to format LaTeX chunks of codes:
1142
1143 \begin{Verbatim}
1144 \NewPitonLanguage{LaTeX}{keywordsprefix = \ , alsoother = ~@_ }
1145 \end{Verbatim}
1146
1147 Initially, the characters |@| and |_| are considered as letters (in the
1148 sens of \pkg{listings}) because, in many computer languages, they are
1149 allowed in the keywords and the names of the identifiers.
1150 With \verb|alsoother = @_|, we retrieve them from the
1151 category of the letters.
1152
1153 \section{Import and export}
1154
1155
1156 \subsection{Importation of a listing}
1157
1158 \label{PitonInputFile}
1159
1160 \subsubsection{The command \textbackslash PitonInputFile}
1161
1162 \indexcommand{PitonInputFile}
1163
1164 The command \DefinitionCommand{PitonInputFile} includes the content of the
1165 file specified in argument (or only a part of that file: see below). The
1166 extension \pkg{piton} also provides the commands
1167 \DefinitionCommand{PitonInputFileT}, \DefinitionCommand{PitonInputFileF} and
1168 \DefinitionCommand{PitonInputFileTF} with supplementary arguments
1169 corresponding to the letters~|T| and~|F|. Those arguments will be executed if
1170 the file to include has been found (letter~|T|) or not found (letter~|F|).
1171
1172 \smallskip
1173 The syntax for the paths (absolute or relative) is the following one:
1174 \begin{itemize}
1175 \item The paths beginning by |/| are absolute.
1176
1177 \emph{Example} : |\PitonInputFile{/Users/joe/Documents/program.py}|
1178
1179 \item The paths which do not begin with |/| are relative to the current
1180 repertory.
1181
1182 \emph{Example} : |\PitonInputFile{my_listings/program.py}|
1183 \end{itemize}
1184
1185 \index{path}
1186 The key \Definition{path} of the command |\PitonOptions| specifies a
1187 \emph{list} of paths where the files included by |\PitonInputFile| will be
1188 searched. That list is comma separated.
1189
1190 As previously, the absolute paths must begin with |/|.
1191
1192 \bigskip
1193 \subsubsection{Insertion of a part of a file}
1194
1195 \label{part-of-a-file}
1196 \indexcommand{PitonInputFile}
1197
1198 The command |\PitonInputFile| inserts (with formatting) the content of a file.
1199 In fact, it's possible to insert only \emph{a part} of that file. Two
1200 mechanisms are provided in this aim.
1201 \begin{itemize}
1202 \item It's possible to specify the part that we want to insert by the numbers
1203 of the lines (in the original file).
1204 \item It's also possible to specify the part to insert with textual markers.
1205 \end{itemize}
1206 In both cases, if we want to number the lines with the numbers of the
1207 lines in the file, we have to use the key |line-numbers/absolute|.
1208
1209 \bigskip
1210 \textbf{With line numbers}
1211
1212 \nobreak
1213 The command |\PitonInputFile| supports the keys \Definition{first-line} and
1214 \Definition{last-line} in order to insert only the part of file between the
1215 corresponding lines. Not to be confused with the key |line-numbers/start|
1216 which fixes the first line number for the line numbering. In one sense,
1217 |line-numbers/start| deals with the output whereas |first-line| and
1218 |last-line| deal with the input.
1219
1220 \bigskip
1221 \textbf{With textual markers}
1222
1223 \nobreak
1224 \index{marker/beginning}
1225 \index{marker/end}
1226
1227 In order to use that feature, we first have to specify the format of the
1228 markers (for the beginning and the end of the part to include) with the keys
1229 \Definition{marker-beginning} and \Definition{marker-end} (usually with the
1230 command |\PitonOptions|).
1231
1232
1233 \medskip
1234 Let us take a practical example.
1235
1236 \medskip
1237 We assume that the file to include contains solutions to exercises of
1238 programming on the following model.
1239
1240 \begin{small}
1241 \begin{Verbatim}
1242 ~#[Exercise 1] Iterative version
1243 def fibo(n):
1244 if n==0: return 0
1245 else:
1246 u=0
1247 v=1
1248 for i in range(n-1):
1249 w = u+v
1250 u = v
1251 v = w
1252 return v
1253 ~#<Exercise 1>
1254 \end{Verbatim}
1255 \end{small}
1256
1257 The markers of the beginning and the end are the strings |#[Exercise 1]| and
1258 |#<Exercise 1>|. The string ``|Exercise 1|'' will be called the \emph{label}
1259 of the exercise (or of the part of the file to be included).
1260
1261 In order to specify such markers in \pkg{piton}, we will use the keys
1262 |marker/beginning| and |marker/end| with the following instruction (the
1263 character |#| of the comments of Python must be inserted with the protected
1264 form |\#|).
1265
1266 \begin{Verbatim}
1267 \PitonOptions{ ~emphase#marker/beginning@ = \~#[~#1] , ~emphase#marker/end@ = \~#<~#1> }
1268 \end{Verbatim}
1269
1270 As one can see, |marker/beginning| is an expression corresponding to the
1271 mathematical function which transforms the label (here |Exercise 1|) into the
1272 the beginning marker (here |#[Exercise 1]|). The string |#1|
1273 corresponds to the occurrences of the argument of that function, which the
1274 classical syntax in TeX. Idem for |marker/end|.\footnote{In regard to LaTeX,
1275 both functions must be \emph{fully expandable}.}
1276
1277 \bigskip
1278 Now, you only have to use the key \Definition{range} of |\PitonInputFile| to
1279 insert a marked content of the file.
1280
1281 \smallskip
1282 \begin{Verbatim}
1283 \PitonInputFile[~emphase#range = Exercise 1@]{~textsl#file_name@}
1284 \end{Verbatim}
1285
1286 \medskip
1287 \begin{Piton}
1288 def fibo(n):
1289 if n==0: return 0
1290 else:
1291 u=0
1292 v=1
1293 for i in range(n-1):
1294 w = u+v
1295 u = v
1296 v = w
1297 return v
1298 \end{Piton}
1299
1300 \vspace{1cm}
1301 \index{marker/include-lines}
1302 The key \Definition{marker/include-lines} requires the insertion of the lines
1303 containing the markers.
1304
1305 \begin{Verbatim}
1306 \PitonInputFile[~emphase#marker/include-lines@,range = Exercise 1]{~textsl#file_name@}
1307 \end{Verbatim}
1308
1309 \begin{Piton}
1310 #[Exercise 1] Iterative version
1311 def fibo(n):
1312 if n==0: return 0
1313 else:
1314 u=0
1315 v=1
1316 for i in range(n-1):
1317 w = u+v
1318 u = v
1319 v = w
1320 return v
1321 #<Exercise 1>
1322 \end{Piton}
1323
1324
1325 \bigskip
1326 \index{begin-range}
1327 \index{end-range}
1328 In fact, there exist also the keys \Definition{begin-range} and
1329 \Definition{end-range} to insert several marked contents at the same time.
1330
1331 For example, in order to insert the solutions of the exercises~3 to~5, we will
1332 write (if the file has the correct structure!):
1333
1334
1335 \begin{Verbatim}
1336 \PitonInputFile[~emphase#begin-range = Exercise 3, end-range = Exercise 5@]{~textsl#file_name@}
1337 \end{Verbatim}
1338
1339
1340 \subsection{Exportation of a listing}
1341
1342 Alongside the command |\PitonInputFile|, which allows the final user to import a
1343 listing from an external file, \pkg{piton} provides tools to export some listings
1344 included in the \textsc{pdf} file to an external file or as joined files embedded in
1345 \textsc{pdf} generated by LuaLaTeX.
1346
1347 \bigskip
1348 \begin{itemize}
1349 \item \index{write} The key \Definition{write} takes in as argument a name of
1350 file (with its extension) and write the content\footnote{In fact, it's not
1351 exactly the body of the environment but the value of |piton.get_last_code()|
1352 which is the body without the overwritten LaTeX formatting instructions (cf.
1353 the part~\ref{API}, p.~\pageref{API}).} of the current environment in
1354 that file. At the first use of a file by \pkg{piton} (during a given
1355 compilation done by LuaLaTeX), it is erased. In fact, the file is written once at
1356 the end of the compilation of the file by LuaLaTeX.
1357
1358 For legibility, \pkg{piton} provides the key \Definition{no-write} (without value)
1359 as alias for |write={}|.
1360
1361 \item \index{path-write} The key \Definition{path-write} specifies a path
1362 where the files written by the key |write| will be written.
1363
1364 \item \index{join (key)}
1365
1366 The key \Definition{join} is similar to the key |write| but the files which
1367 are created are joined (as \emph{joined files}) in the \textsc{pdf}. Be
1368 careful: Some \textsc{pdf} readers don't provide any tool to access to these
1369 joined files.
1370
1371 For legibility, \pkg{piton} provides the key \Definition{no-join} (without value)
1372 as alias for |join={}|.
1373
1374 \item \index{print}
1375 The key \Definition{print} controls whether the content of the environment is
1376 actually printed (with the syntactic formating) in the \textsc{pdf}. Of
1377 course, the initial value of |print| is |true|. However, it may be useful to
1378 use |print=false| in some circumstancies (for example, when the key |write| or
1379 the key |join| is used).
1380
1381 \item \index{paperclip (key)}
1382 The key \Definition{paperclip} will, for each environment |{Piton}|, add in the right
1383 margin a \textsc{pdf} annotation linked with a file joined in the \textsc{pdf}
1384 corresponding to the listing of the environment.
1385
1386 The value provided to the key |paperclip| is the name that will be given to the embedded
1387 file. If no value is provided, the file will have the name \texttt{listing_\textsl{i}.txt}
1388 where \textsl{i} is a counter incremented by \pkg{piton} each time that a new file is
1389 created by use of |paperclip| without value.
1390
1391 \medskip
1392 \begin{Code}
1393 \begin{Piton}[\emph{paperclip},background-color=gray!15]
1394 def square(x):
1395 """Computes the square of x"""
1396 return x*x
1397 \end{Piton}
1398 \end{Code}
1399
1400 \medskip
1401 \begin{Piton}[paperclip,background-color=gray!15]
1402 def square(x):
1403 """Computes the square of x"""
1404 return x*x
1405 \end{Piton}
1406
1407
1408 \item \index{annotation (key)}
1409 The key \Definition{annotation} will, for each environment |{Piton}|, add in the right
1410 margin a \textsc{pdf} annotation whose content is directly the body of the
1411 environment |{Piton}|.
1412
1413 \medskip
1414 \begin{Code}
1415 \begin{Piton}[\emph{annotation},background-color=gray!15]
1416 def square(x):
1417 """Computes the square of x"""
1418 return x*x
1419 \end{Piton}
1420 \end{Code}
1421
1422 \medskip
1423 \begin{Piton}[annotation,background-color=gray!15]
1424 def square(x):
1425 """Computes the square of x"""
1426 return x*x
1427 \end{Piton}
1428
1429
1430 \end{itemize}
1431
1432 \section{Advanced features}
1433
1434 \subsection{The key ``box''}
1435
1436 \label{box}
1437 \index{box (key)}
1438
1439 If one wishes to compose a listing in a box of LaTeX, he should use the key
1440 |box|. That key takes in as value |c|, |t| or |b| corresponding to the parameter
1441 of vertical position (as for the envionment |{minipage}| of LaTeX which creates also
1442 a LaTeX box). The default value is |c| (as for |{minipage}|).
1443
1444 When the key |box| is used, |width=min| is activated (except, of course, when the
1445 key |width| or the key |max-width| is explicitly used). For the keys |width| and
1446 |max-width|, cf.~p.~\pageref{width}.
1447
1448
1449 \smallskip
1450 \begin{Code}
1451 \begin{center}
1452 \PitonOptions{\emph{box},background-color=gray!15}
1453 \begin{Piton}
1454 def square(x):
1455 return x*x
1456 \end{Piton}
1457 \hspace{1cm}
1458 \begin{Piton}
1459 def cube(x):
1460 return x*x*x
1461 \end{Piton}
1462 \end{center}
1463 \end{Code}
1464
1465 \begin{center}
1466 \PitonOptions{box,background-color=gray!15}
1467 \begin{Piton}
1468 def square(x):
1469 return x*x
1470 \end{Piton}
1471 \hspace{1cm}
1472 \begin{Piton}
1473 def cube(x):
1474 return x*x*x
1475 \end{Piton}
1476 \end{center}
1477
1478 \vspace{1cm}
1479 It's possible to use the key |box| with a numerical value for the key |width|.
1480
1481
1482 \smallskip
1483
1484 \begin{Code}
1485 \begin{center}
1486 \PitonOptions{\emph{box,width=5cm},background-color=gray!15}
1487 \begin{Piton}
1488 def square(x):
1489 return x*x
1490 \end{Piton}
1491 \hspace{1cm}
1492 \begin{Piton}
1493 def cube(x):
1494 return x*x*x
1495 \end{Piton}
1496 \end{center}
1497 \end{Code}
1498
1499 \begin{center}
1500 \PitonOptions{box,width=5cm,background-color=gray!15}
1501 \begin{Piton}
1502 def square(x):
1503 return x*x
1504 \end{Piton}
1505 \hspace{1cm}
1506 \begin{Piton}
1507 def cube(x):
1508 return x*x*x
1509 \end{Piton}
1510 \end{center}
1511
1512 \vspace{1cm}
1513 Here is an example with the key |max-width|, equal to 7~cm for both listings.
1514
1515 \smallskip
1516
1517 \begin{Code}
1518 \begin{center}
1519 \PitonOptions{\emph{box=t,max-width=7cm},background-color=gray!15}
1520 \begin{Piton}
1521 def square(x):
1522 return x*x
1523 \end{Piton}
1524 \hspace{1cm}
1525 \begin{Piton}
1526 def P(x):
1527 return 24*x**8 - 7*x**7 + 12*x**6 -4*x**5 + 4*x**3 + x**2 - 5*x + 2
1528 \end{Piton}
1529 \end{center}
1530 \end{Code}
1531
1532 \begin{center}
1533 \PitonOptions{box=t,max-width=7cm,background-color=gray!15}
1534 \begin{Piton}
1535 def square(x):
1536 return x*x
1537 \end{Piton}
1538 \hspace{1cm}
1539 \begin{Piton}
1540 def P(x):
1541 return 24*x**8 - 7*x**7 + 12*x**6 -4*x**5 + 4*x**3 + x**2 - 5*x + 2
1542 \end{Piton}
1543 \end{center}
1544
1545 \subsection{The key ``tcolorbox''}
1546
1547 \label{tcolorbox}
1548 \index{tcolorbox (key)}
1549
1550 The extension \pkg{piton} provides a key \Definition{tcolorbox} in order to
1551 ease the use of the extension \pkg{tcolorbox} in conjunction with the extension
1552 \pkg{piton}. However, the extension \pkg{piton} does not load \pkg{tcolorbox} and
1553 the end user should have loaded it. Moreover, he must load the library |breakable|
1554 of \pkg{tcolorbox} with |\tcbuselibrary{breakable}| in the preamble of the LaTeX document.
1555 If this is not the case, an error will be raised at the first use of the key
1556 |tcolorbox|.
1557
1558 \bigskip
1559 When the key |tcolorbox| is used, the listing formated by \pkg{piton} is
1560 included in an environment |{tcolorbox}|. That applies both to the command
1561 |\PitonInputFile| and the environment |{Piton}| (or, more generally, an
1562 environment created by the dedicated command |\NewPitonEnvironment|:
1563 cf.~p.~\pageref{NewPitonEnvironment}). If the key |splittable| of \pkg{piton}
1564 is used (cf. p.~\pageref{page breaks}), the graphical box created by
1565 \pkg{tcolorbox} will be splittable by a change of page.
1566
1567 \bigskip
1568 In the present document, we have loaded, besides \pkg{tcolorbox} and its library
1569 |breakable|, the library |skins| of \pkg{tcolorbox} and we have activated the
1570 ``\emph{skin}'' |enhanced|, in order to have a better appearance at the page break.
1571
1572
1573 \begin{footnotesize}
1574 \begin{Verbatim}
1575 \tcbuselibrary{skins,breakable} % in the preamble
1576 \tcbset{enhanced} % in the preamble
1577 \end{Verbatim}
1578 \end{footnotesize}
1579
1580 \begin{Verbatim}
1581 \begin{Piton}~emphase#[tcolorbox,splittable=3]@
1582 def square(x):
1583 """Computes the square of x"""
1584 return x*x
1585 ...
1586 def square(x):
1587 """Computes the square of x"""
1588 return x*x
1589 \end{Piton}
1590 \end{Verbatim}
1591
1592 \begin{Piton}[tcolorbox,splittable=3]
1593 def square(x):
1594 """Computes the square of x"""
1595 return x*x
1596 def square(x):
1597 """Computes the square of x"""
1598 return x*x
1599 def square(x):
1600 """Computes the square of x"""
1601 return x*x
1602 def square(x):
1603 """Computes the square of x"""
1604 return x*x
1605 def square(x):
1606 """Computes the square of x"""
1607 return x*x
1608 def square(x):
1609 """Computes the square of x"""
1610 return x*x
1611 def square(x):
1612 """Computes the square of x"""
1613 return x*x
1614 def square(x):
1615 """Computes the square of x"""
1616 return x*x
1617 def square(x):
1618 """Computes the square of x"""
1619 return x*x
1620 def square(x):
1621 """Computes the square of x"""
1622 return x*x
1623 def square(x):
1624 """Computes the square of x"""
1625 return x*x
1626 def square(x):
1627 """Computes the square of x"""
1628 return x*x
1629 def square(x):
1630 """Computes the square of x"""
1631 return x*x
1632 def square(x):
1633 """Computes the square of x"""
1634 return x*x
1635 def square(x):
1636 """Computes the square of x"""
1637 return x*x
1638 def square(x):
1639 """Computes the square of x"""
1640 return x*x
1641 def square(x):
1642 """Computes the square of x"""
1643 return x*x
1644 def square(x):
1645 """Computes the square of x"""
1646 return x*x
1647 def square(x):
1648 """Computes the square of x"""
1649 return x*x
1650 def square(x):
1651 """Computes the square of x"""
1652 return x*x
1653 def square(x):
1654 """Computes the square of x"""
1655 return x*x
1656 def square(x):
1657 """Computes the square of x"""
1658 return x*x
1659 def square(x):
1660 """Computes the square of x"""
1661 return x*x
1662 def square(x):
1663 """Computes the square of x"""
1664 return x*x
1665 def square(x):
1666 """Computes the square of x"""
1667 return x*x
1668 \end{Piton}
1669
1670 Of course, if we want to change the color of the background, we won't use the key
1671 |background-color| of \pkg{piton} but the tools provided by \pkg{tcolorbox}
1672 (the key |colback| for the color of the background).
1673
1674 \bigskip
1675 If we want to adjust the width of the graphical box to its content, we only
1676 have to use the key |width=min| provided by \pkg{piton} (cf.
1677 p.~\pageref{width}). It's also possible to use |width| or |max-width| with a
1678 numerical value. The environment is splittable if the key |splittable| is used (cf.
1679 p.~\pageref{page breaks}).
1680
1681 \begin{Verbatim}
1682 \begin{Piton}~emphase#[tcolorbox,width=min,splittable=3]@
1683 def square(x):
1684 """Computes the square of x"""
1685 return x*x
1686 ...
1687 def square(x):
1688 """Computes the square of x"""
1689 return x*x
1690 \end{Piton}
1691 \end{Verbatim}
1692
1693 \begin{Piton}[tcolorbox,width=min,splittable=3]
1694 def square(x):
1695 """Computes the square of x"""
1696 return x*x
1697 def square(x):
1698 """Computes the square of x"""
1699 return x*x
1700 def square(x):
1701 """Computes the square of x"""
1702 return x*x
1703 def square(x):
1704 """Computes the square of x"""
1705 return x*x
1706 def square(x):
1707 """Computes the square of x"""
1708 return x*x
1709 def square(x):
1710 """Computes the square of x"""
1711 return x*x
1712 def square(x):
1713 """Computes the square of x"""
1714 return x*x
1715 def square(x):
1716 """Computes the square of x"""
1717 return x*x
1718 def square(x):
1719 """Computes the square of x"""
1720 return x*x
1721 def square(x):
1722 """Computes the square of x"""
1723 return x*x
1724 def square(x):
1725 """Computes the square of x"""
1726 return x*x
1727 def square(x):
1728 """Computes the square of x"""
1729 return x*x
1730 def square(x):
1731 """Computes the square of x"""
1732 return x*x
1733 def square(x):
1734 """Computes the square of x"""
1735 return x*x
1736 def square(x):
1737 """Computes the square of x"""
1738 return x*x
1739 def square(x):
1740 """Computes the square of x"""
1741 return x*x
1742 \end{Piton}
1743
1744 \bigskip
1745 If we want an output composed in a LaTeX box (despites its name, an environment
1746 of \pkg{tcolorbox} does not always create a LaTeX box), we only have to use,
1747 in conjunction with the key |tcolorbox|, the key |box| provided by \pkg{piton}
1748 (cf. p.~\pageref{box}). Of course, such LaTeX box, as all the LaTeX boxes, can't
1749 be broken by a change of page, even if the key |splittable| (cf.~p.~\pageref{splittable})
1750 is in force.
1751
1752 We recall that, when the key |box| is used, |width=min| is activated (except,
1753 when the key |width| or the key |max-width| is explicitly used).
1754
1755
1756 \smallskip
1757 \begin{Verbatim}
1758 \begin{center}
1759 \PitonOptions{~emphase#tcolorbox,box=t@}
1760 \begin{Piton}
1761 def square(x):
1762 return x*x
1763 \end{Piton}
1764 \hspace{1cm}
1765 \begin{Piton}
1766 def cube(x):
1767 """The cube of x"""
1768 return x*x*x
1769 \end{Piton}
1770 \end{center}
1771 \end{Verbatim}
1772
1773 \begin{center}
1774 \PitonOptions{tcolorbox,box=t}%
1775 \begin{Piton}
1776 def square(x):
1777 return x*x
1778 \end{Piton}
1779 \hspace{1cm}
1780 \begin{Piton}
1781 def cube(x):
1782 """The cube of x"""
1783 return x*x*x
1784 \end{Piton}
1785 \end{center}
1786
1787
1788
1789 \bigskip
1790 For a more sophisticated example of use of the key |tcolorbox|, see the example
1791 given at the page~\pageref{examples-tcolorbox}.
1792
1793
1794
1795 \bigskip
1796 \subsection{Line breaks and page breaks}
1797
1798 \label{breakable}
1799
1800 \subsubsection{Line breaks}
1801
1802 \label{line-breaks}
1803
1804 There are keys to control the line breaks (the possible breaking points are
1805 the spaces, even the spaces which appear in the strings of the computer
1806 languages).
1807 \begin{itemize}
1808 \item \index{break-lines!break-lines-in-piton} With the key
1809 \Definition{break-lines-in-piton}, the line breaks are allowed in the command
1810 |\piton{...}| (but not in the command \verb+\piton|...|+, that is to say the
1811 command |\piton| in verbatim mode).
1812 \item \index{break-lines!break-lines-in-Piton} With the key
1813 \Definition{break-lines-in-Piton}, the line breaks are allowed in the
1814 environment |{Piton}| (hence the capital letter |P| in the name) and in the
1815 listings produced by |\PitonInputFile|. {\bfseries The initial value of that parameter is
1816 |true| (and not |false|).}
1817 \item \index{break-lines} The key \Definition{break-lines} is a conjunction of
1818 the two previous keys.
1819 \end{itemize}
1820
1821 \bigskip
1822 The package \pkg{piton} provides also several keys to control the appearance
1823 on the line breaks allowed by |break-lines-in-Piton|.
1824
1825 \begin{itemize}
1826 \item \index{indent-broken-lines} With the key
1827 \Definition{indent-broken-lines}, the indentation of a
1828 broken line is respected at carriage return (on the condition that the used
1829 font is a monospace font and this is the case by default since the initial
1830 value of |font-command| is |\ttfamily|).
1831
1832 \item The key \Definition{end-of-broken-line} corresponds to the symbol placed
1833 at the end of a broken line. The initial value is:
1834 |\hspace*{0.5em}\textbackslash|.
1835
1836 \item \index{continuation-symbol} The key \Definition{continuation-symbol}
1837 corresponds to the symbol placed at each carriage return. The initial value
1838 is: |+\;| (the command |\;| inserts a small horizontal space).
1839
1840 \item \index{continuation-symbol-on-indentation}
1841 The key \Definition{continuation-symbol-on-indentation} corresponds to
1842 the symbol placed at each carriage return, on the position of the indentation
1843 (only when the key |indent-broken-line| is in force). The initial value is:
1844 |$\hookrightarrow\;$|.
1845 \end{itemize}
1846
1847
1848 \bigskip
1849 The following code has been composed with the following tuning:
1850
1851 \begin{Verbatim}
1852 \PitonOptions{width=12cm,indent-broken-lines,background-color=gray!15}
1853 \end{Verbatim}
1854
1855 \begin{center}
1856 \PitonOptions{width=12cm,break-lines,indent-broken-lines,background-color=gray!15}
1857 \begin{Piton}
1858 def dict_of_list(l):
1859 """Converts a list of subrs and descriptions of glyphs in a dictionary"""
1860 our_dict = {}
1861 for list_letter in l:
1862 if (list_letter[0][0:3] == 'dup'): # if it's a subr
1863 name = list_letter[0][4:-3]
1864 print("We treat the subr of number " + name)
1865 else:
1866 name = list_letter[0][1:-3] # if it's a glyph
1867 print("We treat the glyph of number " + name)
1868 our_dict[name] = [treat_Postscript_line(k) for k in list_letter[1:-1]]
1869 return dict
1870 \end{Piton}
1871 \end{center}
1872
1873 \bigskip
1874 With the key \Definition{break-strings-anywhere}, the strings may be broken
1875 anywhere (and not only on the spaces).
1876
1877 \bigskip
1878 With the key \Definition{break-numbers-anywhere}, the numbers may be broken
1879 anywhere.
1880
1881 \subsubsection{Page breaks}
1882 \label{page breaks}
1883 \label{splittable}
1884 \index{splittable}
1885 \index{splittable-on-empty-lines}
1886
1887 By default, the listings produced by the environment |{Piton}| and the command
1888 |\PitonInputFile| are not breakable.
1889
1890 However, \pkg{piton} provides the keys |splittable-on-empty-lines| and
1891 |splittable| to allow such breaks.
1892
1893 \begin{itemize}
1894 \item The key \Definition{splittable-on-empty-lines} allows breaks on the empty
1895 lines. The ``empty lines'' are in fact the lines which contains only spaces.
1896
1897 \item Of course, the key |splittable-on-empty-lines| may not be sufficient and
1898 that's why \pkg{piton} provides the key \Definition{splittable}.
1899
1900 When the key |splittable| is used with the numeric value~$n$ (which must be a
1901 positive integer) the listing, or each part of the listing delimited by empty
1902 lines (when |split-on-empty-lines| is in force) may be broken anywhere with
1903 the restriction that no break will occur within the $n$ first lines of
1904 the listing or within the $n$ last lines.\footnote{Remark that we speak of thes
1905 lines of the original computer listing and such line may be composed on
1906 several lines in the final \textsc{pdf} when the key |break-lines-in-Piton| is
1907 in force.}
1908
1909 For example, a tuning with |splittable = 4| may be a good choice.
1910
1911 When used without value, the key |splittable| is equivalent to
1912 |splittable = 1| and the listings may be broken anywhere (it's probably
1913 not recommandable).
1914
1915 The initial value of the key |splittable| is equal to 100 (by default, the
1916 listings are not breakable at all).
1917 \end{itemize}
1918
1919 \medskip
1920 \begin{tcolorbox}[breakable]
1921 Even with a background color (set by the key |background-color|), the pages
1922 breaks are allowed, as soon as the key |split-on-empty-lines| or the key
1923 |splittable| is in force.
1924
1925 \medskip
1926 With the key |splittable|, the environments
1927 \texttt{\{Piton\}} are breakable, even within a (breakable) environment of
1928 \pkg{tcolorbox}. Remind that an environment of \pkg{tcolorbox} included in
1929 another environment of \pkg{tcolorbox} is \emph{not} breakable, even when both
1930 environments use the key |breakable| of \pkg{tcolorbox}.
1931
1932 \medskip
1933 We illustrate that point with the following code (the current environment
1934 |{tcolorbox}| uses the key |breakable|).
1935
1936 \begin{Verbatim}
1937 ~emphase#\begin{Piton}[background-color=gray!30,rounded-corners,width=min,splittable=4]@
1938 def square(x):
1939 """Computes the square of x"""
1940 return x*x
1941 ...
1942 def square(x):
1943 """Computes the square of x"""
1944 return x*x
1945 ~emphase#~textbackslash#@end{Piton}@
1946 \end{Verbatim}
1947
1948 \bigskip
1949 \begin{Piton}[background-color=gray!30,rounded-corners,width=min,splittable=4]
1950 def square(x):
1951 """Computes the square of x"""
1952 return x*x
1953 def square(x):
1954 """Computes the square of x"""
1955 return x*x
1956 def square(x):
1957 """Computes the square of x"""
1958 return x*x
1959 def square(x):
1960 """Computes the square of x"""
1961 return x*x
1962 def square(x):
1963 """Computes the square of x"""
1964 return x*x
1965 def square(x):
1966 """Computes the square of x"""
1967 return x*x
1968 def square(x):
1969 """Computes the square of x"""
1970 return x*x
1971 def square(x):
1972 """Computes the square of x"""
1973 return x*x
1974 def square(x):
1975 """Computes the square of x"""
1976 return x*x
1977 def square(x):
1978 """Computes the square of x"""
1979 return x*x
1980 def square(x):
1981 """Computes the square of x"""
1982 return x*x
1983 def square(x):
1984 """Computes the square of x"""
1985 return x*x
1986 \end{Piton}
1987
1988 \end{tcolorbox}
1989
1990 \subsection{Splitting of a listing in sub-listings}
1991
1992 \index{split-on-empty-lines}
1993 \label{split-on-empty-lines}
1994 \index{split-separation}
1995 \index{add-to-split-separation}
1996
1997 The extension \pkg{piton} provides the key \Definition{split-on-empty-lines},
1998 which should not be confused with the key |splittable-on-empty-lines|
1999 previously defined.
2000
2001 \smallskip
2002 In order to understand the behaviour of the key |split-on-empty-lines|, one
2003 should imagine that he has to compose an computer listing which contains
2004 several definitions of computer functions. Usually, in the computer
2005 languages, those definitions of functions are separated by empty lines.
2006
2007 \smallskip
2008 The key |split-on-empty-lines| splits the listings on the empty lines. Several
2009 empty lines are deleted and replaced by the content of the parameter
2010 corresponding to the key \Definition{split-separation}.
2011 \begin{itemize}
2012 \item That parameter must contain elements allowed to be inserted in
2013 \emph{vertical mode} of TeX. For example, it's possible to put the TeX
2014 primitive |\hrule|.
2015
2016 \item The initial value of this parameter is
2017 |\vspace{\baselineskip}\vspace{-1.25pt}| which corresponds eventually to an
2018 empty line in the final \textsc{pdf} (this vertical space is deleted if it
2019 occurs on a page break). If the key |background-color| is in force, no
2020 background color is added to that empty line.
2021
2022 \item In fact, the extension \pkg{piton} provides also the key
2023 \Definition{split-separation~+} to add elements on the right of the parameter
2024 |split-separation|. The name of that key contains a space in order to be able
2025 to write, for example, |split-separation += \hrule|.
2026 \end{itemize}
2027
2028
2029 Each chunk of the computer listing is composed in an environment whose name
2030 is given by the key \Definition{env-used-by-split}. The initial value of that
2031 parameter is, not surprisingly, |Piton| and, hence, the different chunks are
2032 composed in several environments |{Piton}|. If one decides to change the value
2033 of |env-used-by-split|, he should use the name of an environment created by
2034 |\NewPitonEnvironment| (cf.~part~\ref{NewPitonEnvironment},
2035 p.~\pageref{NewPitonEnvironment}).
2036
2037 Each chunk of the computer listing is formated in its own environment.
2038 Therefore, it has its own line numbering (if the key
2039 |line-numbers| is in force) and its own colored background (when the key
2040 |background-color| is in force), separated from the background color of the
2041 other chunks. When used, the key |splittable| applies in each chunk
2042 (independently of the other chunks). Of course, a page break may occur between
2043 the chunks of code, regardless of the value of |splittable|.
2044
2045 \bigskip
2046 \begin{Verbatim}
2047 \begin{Piton}[~emphase#split-on-empty-lines@,background-color=gray!15,line-numbers]
2048 def square(x):
2049 """Computes the square of x"""
2050 return x*x
2051
2052 def cube(x):
2053 """Calcule the cube of x"""
2054 return x*x*x
2055 \end{Piton}
2056 \end{Verbatim}
2057
2058
2059 \begin{Piton}[split-on-empty-lines,background-color=gray!15,line-numbers]
2060 def square(x):
2061 """Computes the square of x"""
2062 return x*x
2063
2064 def cube(x):
2065 """Calcule the cube of x"""
2066 return x*x*x
2067 \end{Piton}
2068
2069
2070 \bigskip
2071 If we wish to have a continuity of the line numbers between the sublistings
2072 it's possible to add |\PitonOptions{resume}| to the parameter |split-separation|.
2073
2074 \bigskip
2075 \begin{Verbatim}
2076 \begin{Piton}[
2077 split-on-empty-lines, ~emphase#split-separation += \PitonOptions{resume}@ , background-color=gray!15, line-numbers ]
2078 def square(x):
2079 """Computes the square of x"""
2080 return x*x
2081
2082 def cube(x):
2083 """Computes the square of x"""
2084 return x*x*x
2085 \end{Piton}
2086 \end{Verbatim}
2087
2088 \begin{Piton}[
2089 split-on-empty-lines,
2090 split-separation += \PitonOptions{resume} ,
2091 background-color = gray!15,
2092 line-numbers
2093 ]
2094 def square(x):
2095 """Computes the square of x"""
2096 return x*x
2097
2098 def cube(x):
2099 """Computes the square of x"""
2100 return x*x*x
2101 \end{Piton}
2102
2103
2104 \bigskip
2105 \textbf{Caution}: Since each chunk is treated independently of the others, the
2106 commands specified by |detected-commands| or |raw-detected-commands|
2107 (cf.~p.~\pageref{detected-commands}) and the commands and environments of
2108 Beamer automatically detected by \pkg{piton} must not cross the empty lines of
2109 the original listing.
2110
2111 \subsection{Highlighting some identifiers}
2112
2113 \label{SetPitonIdentifier}
2114
2115 The command \DefinitionCommand{SetPitonIdentifier} allows to automatically
2116 change the formatting of some identifiers. That change is only based on the
2117 name of those indentifiers.
2118
2119 \smallskip
2120 That command takes in three arguments:
2121
2122 \begin{itemize}
2123 \item The optional argument (within square brackets) specifies the computer
2124 language. If this argument is not present, the tunings done by
2125 |\SetPitonIdentifier| will apply to all the computer languages of
2126 \pkg{piton}.\footnote{We recall, that, in the package \pkg{piton}, the
2127 names of the computer languages are case-insensitive.}
2128
2129 \item The first mandatory argument is a comma-separated list of names of
2130 identifiers.
2131
2132 \item The second mandatory argument is a list of LaTeX instructions of the
2133 same type as \pkg{piton} ``styles'' previously presented (cf.~\ref{styles}
2134 p.~\pageref{styles}).
2135 \end{itemize}
2136
2137 \emph{Caution}: Only the identifiers may be concerned by that key. The
2138 keywords and the built-in functions won't be affected, even if their name
2139 appear in the first argument of |\SetPitonIdentifier|.
2140
2141 \begin{Verbatim}
2142 ~emphase#\SetPitonIdentifier{l1,l2}{\color{red}}@
2143 \begin{Piton}
2144 def tri(l):
2145 """Segmentation sort"""
2146 if len(l) <= 1:
2147 return l
2148 else:
2149 a = l[0]
2150 l1 = [ x for x in l[1:] if x < a ]
2151 l2 = [ x for x in l[1:] if x >= a ]
2152 return tri(l1) + [a] + tri(l2)
2153 \end{Piton}
2154 \end{Verbatim}
2155
2156
2157 \bigskip
2158
2159 \begingroup
2160
2161 \SetPitonIdentifier{l1,l2}{\color{red}}
2162
2163 \begin{Piton}
2164 def tri(l):
2165 """Segmentation sort"""
2166 if len(l) <= 1:
2167 return l
2168 else:
2169 a = l[0]
2170 l1 = [ x for x in l[1:] if x < a ]
2171 l2 = [ x for x in l[1:] if x >= a ]
2172 return tri(l1) + [a] + tri(l2)
2173 \end{Piton}
2174
2175 \endgroup
2176
2177 \bigskip
2178 By using the command |\SetPitonIdentifier|, it's possible to add other
2179 built-in functions (or other new keywords, etc.) that will be detected by
2180 \pkg{piton}.
2181
2182
2183 \begin{Verbatim}
2184 ~emphase#\SetPitonIdentifier[Python]@
2185 {cos, sin, tan, floor, ceil, trunc, pow, exp, ln, factorial}
2186 {\PitonStyle{Name.Builtin}}
2187
2188 \begin{Piton}
2189 from math import *
2190 cos(pi/2)
2191 factorial(5)
2192 ceil(-2.3)
2193 floor(5.4)
2194 \end{Piton}
2195 \end{Verbatim}
2196
2197 \begingroup
2198
2199 \SetPitonIdentifier[Python]
2200 {cos, sin, tan, floor, ceil, trunc, pow, exp, ln, factorial}
2201 {\PitonStyle{Name.Builtin}}
2202
2203 \begin{Piton}
2204 from math import *
2205 cos(pi/2)
2206 factorial(5)
2207 ceil(-2.3)
2208 floor(5.4)
2209 \end{Piton}
2210
2211
2212 \endgroup
2213
2214
2215 \subsection{Mechanisms to escape to LaTeX}
2216
2217 \label{LaTeX-escapes}
2218 \index{escapes to LaTeX}
2219
2220 The package \pkg{piton} provides several mechanisms for escaping to LaTeX:
2221 \begin{itemize}
2222 \item It's possible to compose comments entirely in LaTeX.
2223 \item It's possible to have the elements between \texttt{\$} in the comments
2224 composed in LateX mathematical mode.
2225 \item It's possible to ask \pkg{piton} to detect automatically some LaTeX
2226 commands, thanks to the keys |detected-commands|, |raw-detected-commands| and
2227 |vertical-detected-commands|.
2228 \item It's also possible to insert LaTeX code almost everywhere in a Python listing.
2229 \end{itemize}
2230
2231 One should also remark that, when the extension \pkg{piton} is used with the
2232 class \cls{beamer}, \pkg{piton} detects in |{Piton}| many commands and
2233 environments of Beamer: cf. \ref{beamer} p.~\pageref{beamer}.
2234
2235 \subsubsection{The ``LaTeX comments''}
2236
2237 \index{comment-latex}
2238
2239 In this document, we call ``LaTeX comments'' the comments which begins by
2240 |#>|. The code following those characters, until the end of the line, will be
2241 composed as standard LaTeX code. There is two tools to customize those
2242 comments.
2243
2244 \begin{itemize}
2245 \item It's possible to change the syntactic mark (which, by default, is |#>|).
2246 For this purpose, there is a key \Definition{comment-latex} available only in
2247 the preamble of the document, allows to choice the characters which, preceded
2248 by |#|, will be the syntactic marker.
2249
2250 For example, if the preamble contains the following instruction:
2251
2252 \quad \verb|\PitonOptions{comment-latex = LaTeX}|
2253
2254 the LaTeX comments will begin by |#LaTeX|.
2255
2256 If the key |comment-latex| is used with the empty value, all the Python
2257 comments (which begins by |#|) will, in fact, be ``LaTeX comments''.
2258
2259 \smallskip
2260 \item It's possible to change the formatting of the LaTeX comment itself by
2261 changing the \pkg{piton} style |Comment.LaTeX|.
2262
2263 For example, with |\SetPitonStyle{Comment.LaTeX = \normalfont\color{blue}}|,
2264 the LaTeX comments will be composed in blue.
2265
2266 If you want to have a character |#| at the beginning of the LaTeX comment in
2267 the \textsc{pdf}, you can use set |Comment.LaTeX| as follows:
2268
2269 \begin{Verbatim}
2270 \SetPitonStyle{Comment.LaTeX = \color{gray}\~#\normalfont\space }
2271 \end{Verbatim}
2272
2273 For other examples of customization of the LaTeX comments, see the part
2274 \ref{example-comments} p.~\pageref{example-comments}
2275 \end{itemize}
2276
2277 \bigskip
2278 If the user has required line numbers (with the key |line-numbers|), it's
2279 possible to refer to a number of line with the command |\label| used in a
2280 LaTeX comment.\footnote{That feature is implemented by using a redefinition of
2281 the standard command \texttt{\textbackslash label} in the environments
2282 \texttt{\{Piton\}}. Therefore, incompatibilities may occur with extensions
2283 which redefine (globally) that command \texttt{\textbackslash label} (for
2284 example: \pkg{varioref}, \pkg{refcheck}, \pkg{showlabels}, etc.).} The same goes
2285 for the |\zlabel| command from the \pkg{zref} package.\footnote{Using the
2286 command \texttt{\textbackslash zcref} command from \pkg{zref-clever} is also
2287 supported.}
2288
2289 \subsubsection{The key ``label-as-zlabel''}
2290
2291 \index{label-as-zlabel}
2292
2293 The key |label-as-zlabel| will be used to indicate if the user wants |\label|
2294 inside |Piton| environments to be replaced by a |\zlabel|-compatible command
2295 (which is the default behavior of \pkg{zref} outside of such environments).
2296
2297 That feature is activated by the key \Definition{label-as-zlabel}, \emph{which is
2298 available only in the preamble of the document}.
2299
2300 \subsubsection{The key ``math-comments''}
2301
2302 \index{math-comments}
2303
2304 It's possible to request that, in the standard Python comments (that is to say
2305 those beginning by |#| and not |#>|), the elements between \texttt{\$} be
2306 composed in LaTeX mathematical mode (the other elements of the comment being
2307 composed verbatim).
2308
2309 That feature is activated by the key \Definition{math-comments}, \emph{which is
2310 available only in the preamble of the document}.
2311
2312 \nobreak
2313 \begin{footnotesize}
2314 \begin{Verbatim}
2315 \PitonOptions{math-comment} % in the preamble
2316 \end{Verbatim}
2317 \end{footnotesize}
2318
2319 \begin{Verbatim}
2320 \begin{Piton}
2321 def square(x):
2322 return x*x ~# compute $x^2$
2323 \end{Piton}
2324 \end{Verbatim}
2325
2326 \begin{Piton}
2327 def square(x):
2328 return x*x # compute $x^2$
2329 \end{Piton}
2330
2331 \subsubsection{The key ``detected-commands'' and its variants}
2332
2333 \index{raw-detected-commands (key)}
2334 \label{raw-detected-commands}
2335 \index{vertical-detected-commands (key)}
2336 \label{vertical-detected-commands}
2337 \index{detected-commands (key)}
2338 \label{detected-commands}
2339
2340 The key \Definition{detected-commands} of |\PitonOptions| allows to specify a
2341 (comma-separated) list of names of LaTeX commands that will be detected
2342 directly by \pkg{piton}.
2343
2344 \begin{itemize}
2345 \item The key |detected-commands| must be used in the preamble of the LaTeX document.
2346
2347 \item The names of the LaTeX commands may appear \emph{with} or \emph{without}
2348 the leading backslash (eg. |detected-commands = { \emph, textbf }|).
2349
2350 \item These commands must be LaTeX commands with only one (mandatory) argument
2351 between braces (and these braces must appear explicitly in the computer
2352 listing).
2353
2354 \item These commands must be \textbf{protected}\footnote{We recall that the
2355 command \texttt{\textbackslash NewDocumentCommand} creates protected commands,
2356 unlike the historical LaTeX command \texttt{\textbackslash newcommand} (and
2357 unlike the command \texttt{\textbackslash def} of TeX).} against expansion in
2358 the TeX sens (because the command |\piton| expands its arguments before
2359 throwing it to Lua for syntactic analysis).
2360 \end{itemize}
2361
2362 \bigskip
2363 In the following example, which is a recursive programming in C of the
2364 factorial function, we decide to highlight the recursive call. The command
2365 |\highLight| of \pkg{lua-ul}\footnote{The package \pkg{lua-ul} requires itself
2366 the package \pkg{luacolor}.} directly does the job.
2367
2368 \medskip
2369 \begin{footnotesize}
2370 \begin{Verbatim}
2371 \PitonOptions{~emphase#detected-commands@ = \highLight} % in the preamble
2372 \end{Verbatim}
2373 \end{footnotesize}
2374
2375 \begin{Verbatim}
2376 \begin{Piton}[language=C]
2377 int factorielle(int n)
2378 {
2379 if (n > 0) ~emphase#\highLight{return n * factorielle(n - 1)}@ ;
2380 else return 1;
2381 }
2382 \end{Piton}
2383 \end{Verbatim}
2384
2385 \begin{Piton}[language=C]
2386 int factorielle(int n)
2387 {
2388 if (n > 0) \highLight{return n * factorielle(n - 1)} ;
2389 else return 1;
2390 }
2391 \end{Piton}
2392
2393 \bigskip
2394 The key \Definition{raw-detected-commands} is similar to the key
2395 |detected-commands| but \pkg{piton} won't do any syntactic analysis of the
2396 arguments of the LaTeX commands which are detected.
2397
2398 If there is a line break within the argument of a command detected by the mean
2399 of |raw-detected-commands|, that line break is replaced by a space (as does
2400 LaTeX by default).
2401
2402 \medskip
2403 Imagine, for example, that we wish, in the main text of a document about
2404 databases, introduce some specifications of tables of the language
2405 \textsc{sql} by the the name of the table, followed, between brackets, by the
2406 names of its fields (ex. : |client(name,town)|).
2407
2408 If we insert that element in a command |\piton|, the word \emph{client} won't
2409 be recognized as a name of table but as a name of field. It's possible to
2410 define a personal command |\NomTable| which we will apply by hand to the names
2411 of the tables. In that aim, we declare that command with
2412 |raw-detected-commands| and, thus, its argument won't be re-analyzed by
2413 \pkg{piton} (that second analysis would format it as a name of field).
2414
2415 \medskip
2416 In the preamble of the LaTeX document, we insert the following lines:
2417
2418 \begin{Verbatim}
2419 \NewDocumentCommand{\NameTable}{m}{{\PitonStyle{Name.Table}{~#1}}}
2420 \PitonOptions{language=SQL, ~emphase#raw-detected-commands = \NameTable@}
2421 \end{Verbatim}
2422
2423 In the main document, the instruction:
2424
2425 \begin{Verbatim}
2426 Exemple : \piton{\NameTable{client} (name, town)}
2427 \end{Verbatim}
2428
2429 \NewDocumentCommand{\NameTable}{m}{{\PitonStyle{Name.Table}{#1}}}
2430
2431 produces the following output :
2432
2433 \smallskip
2434 \begingroup
2435 \PitonOptions{language=SQL}%
2436 Exemple : \piton{\NameTable{client} (nom, prénom)}
2437 \endgroup
2438
2439 \bigskip
2440 The key \Definition{vertical-detected-commands} is similar to the key |raw-detected-commands|
2441 but the commands which are detected by this key must be LaTeX commands (with one argument)
2442 which are executed in \emph{vertical} mode between the lines of the code.
2443
2444 \smallskip
2445 For example, it's possible to detect the command |\newpage| by
2446
2447 \begin{Verbatim}
2448 \PitonOptions{~emphase#vertical-detected-commands@ = \newpage}
2449 \end{Verbatim}
2450
2451 and ask in a listing a mandatory break of page with |\newpage{}| (the pair of braces |{}|
2452 is mandatory because the commands detected by \pkg{piton} are meant to be LaTeX commands
2453 with one mandatory argument, written between explicit braces).
2454
2455 \begin{Code}
2456 \begin{Piton}
2457 def square(x):
2458 return x*x \emph{\textbackslash{}newpage{}}
2459 def cube(x):
2460 return x*x*x
2461 \end{Piton}
2462 \end{Code}
2463
2464 \medskip
2465 It would also be possible to require the detection of the command |\vspace|.
2466
2467 \subsubsection{The mechanism ``escape''}
2468
2469 \label{escape}
2470
2471 It's also possible to overwrite the computer listings to insert LaTeX code
2472 almost everywhere (but between lexical units, of course). By default,
2473 \pkg{piton} does not fix any delimiters for that kind of escape.
2474
2475 In order to use this mechanism, it's necessary to specify the delimiters which
2476 will delimit the escape (one for the beginning and one for the end) by using
2477 the keys \Definition{begin-escape} and \Definition{end-escape}, \emph{available only
2478 in the preamble of the document}.
2479
2480 \medskip
2481 We consider once again the previous example of a recursive programming of
2482 the factorial. We want to highlight in pink the instruction containing the
2483 recursive call. With the package \pkg{lua-ul}, we can use the syntax
2484 |\highLight[LightPink]{...}|. Because of the optional argument between square
2485 brackets, it's not possible to use the key |detected-commands| but it's
2486 possible to achieve our goal with the more general mechanism ``escape''.
2487
2488 \medskip
2489 We assume that the preamble of the document contains the following
2490 instruction:
2491
2492 \begin{Verbatim}
2493 \PitonOptions{~emphase#begin-escape=!,end-escape=!@}
2494 \end{Verbatim}
2495
2496 \medskip
2497 Then, it's possible to write:
2498 \begin{Verbatim}
2499 \begin{Piton}
2500 def fact(n):
2501 if n==0:
2502 return 1
2503 else:
2504 ~emphase#!\highLight[LightPink]{!@return n*fact(n-1)~emphase#!}!@
2505 \end{Piton}
2506 \end{Verbatim}
2507
2508 \begin{Piton}
2509 def fact(n):
2510 if n==0:
2511 return 1
2512 else:
2513 !\highLight[LightPink]{!return n*fact(n-1)!}!
2514 \end{Piton}
2515
2516
2517
2518 \bigskip
2519 \emph{Caution} : The mechanism ``escape'' is not active in the strings nor in
2520 the comments (however, it's possible to have a whole Python comment
2521 composed in LaTeX by beginning it with |#>|; such comments are merely called
2522 ``LaTeX comments'' in this document).
2523
2524
2525 \subsubsection{The mechanism ``escape-math''}
2526
2527 The mechanism ``escape-math'' is very similar to the mechanism ``escape''
2528 since the only difference is that the elements sent to LaTeX are composed in
2529 the math mode of LaTeX.
2530
2531 This mechanism is activated with the keys \Definition{begin-escape-math} and
2532 \Definition{end-escape-math} (\emph{which are available only in the preamble of the
2533 document}).
2534
2535 Despite the technical similarity, the use of the the mechanism
2536 ``escape-math'' is in fact rather different from that of the mechanism
2537 ``escape''. Indeed, since the elements are composed in a mathematical mode
2538 of LaTeX, they are, in particular, composed within a TeX group and, therefore,
2539 they can't be used to change the formatting of other lexical units.
2540
2541 In the languages where the character \verb|$| does not play a important role,
2542 it's possible to activate that mechanism ``escape-math'' with the character
2543 \verb|$|:
2544 \begin{Verbatim}
2545 \PitonOptions{~emphase#begin-escape-math=$,end-escape-math=$@}
2546 \end{Verbatim}
2547 Note: the character \verb|$| must \emph{not} be protected by a backslash.
2548
2549 \bigskip
2550 However, it's probably more prudent to use |\(| et |\)|, which are delimiters
2551 of the mathematical mode provided by LaTeX.
2552 \begin{Verbatim}
2553 \PitonOptions{~emphase#begin-escape-math=\(,end-escape-math=\)@}
2554 \end{Verbatim}
2555
2556 \bigskip
2557 Here is an example of use.
2558
2559 \medskip
2560 \begin{Verbatim}
2561 \begin{Piton}[line-numbers]
2562 def arctan(x,n=10):
2563 if ~emphase#\(x < 0\)@ :
2564 return ~emphase#\(-\arctan(-x)\)@
2565 elif ~emphase#\(x > 1\)@ :
2566 return ~emphase#\(\pi/2 - \arctan(1/x)\)@
2567 else:
2568 s = ~emphase#\(0\)@
2569 for ~emphase#\(k\)@ in range(~emphase#\(n\)@): s += ~emphase#\(\smash{\frac{(-1)^k}{2k+1} x^{2k+1}}\)@
2570 return s
2571 \end{Piton}
2572 \end{Verbatim}
2573
2574
2575 \bigskip
2576
2577 \begin{Piton}[line-numbers]
2578 def arctan(x,n=10):
2579 if \(x < 0\) :
2580 return \(-\arctan(-x)\)
2581 elif \(x > 1\) :
2582 return \(\pi/2 - \arctan(1/x)\)
2583 else:
2584 s = \(0\)
2585 for \(k\) in range(\(n\)): s += \(\smash{\frac{(-1)^k}{2k+1} x^{2k+1}}\)
2586 return s
2587 \end{Piton}
2588
2589
2590
2591
2592 \subsection{Behaviour in the class Beamer}
2593
2594 \label{beamer}
2595 \index{Beamer@\cls{Beamer} (class)}
2596
2597 \emph{First remark}
2598
2599 \nobreak
2600 Since the environment |{Piton}| catches its body with a verbatim mode, it's
2601 necessary to use the environments |{Piton}| within environments |{frame}| of
2602 Beamer protected by the key |fragile|, i.e. beginning with
2603 |\begin{frame}[fragile]|.\footnote{Remind that for an environment
2604 |{frame}| of Beamer using the key |fragile|, the instruction
2605 |\end{frame}| must be alone on a single line (except
2606 for any leading whitespace).}
2607
2608 Note that, if the frame contains only one slide, it's recommended to write
2609
2610 |\begin{frame}[fragile=singleslide]|.
2611
2612 \bigskip
2613 When the package \pkg{piton} is used within the class
2614 \cls{beamer}\footnote{The extension \pkg{piton} detects the class \cls{beamer}
2615 and the package \pkg{beamerarticle} if it is loaded previously
2616 but, if needed, it's also possible to activate that mechanism with the key
2617 |beamer| provided by \pkg{piton} at load-time:
2618 |\usepackage[beamer]{piton}|}, the behaviour of \pkg{piton} is slightly
2619 modified, as described now. This is done via an environment |{actionenv}| of
2620 Beamer.
2621
2622 \subsubsection{\{Piton\} and \textbackslash PitonInputFile are
2623 ``overlay-aware''}
2624
2625 When \pkg{piton} is used in the class \cls{beamer}, the command
2626 |\PitonInputFile| and the environment |{Piton}| (but not the environments
2627 created by |\NewPitonEnvironment|) accept the optional argument |<...>| of
2628 Beamer for the overlays which are involved.
2629
2630 For example, it's possible to write:
2631
2632 \begin{Verbatim}
2633 \begin{Piton}~emphase#<2-5>@
2634 ...
2635 \end{Piton}
2636 \end{Verbatim}
2637
2638 and
2639
2640 \begin{Verbatim}
2641 \PitonInputFile~emphase#<2-5>@{my_file.py}
2642 \end{Verbatim}
2643
2644 \subsubsection{Commands of Beamer allowed in \{Piton\} and \textbackslash PitonInputFile}
2645
2646 \index{detected-beamer-commands}
2647
2648 When \pkg{piton} is used in the class \cls{beamer}, the following commands of
2649 \cls{beamer} (classified upon their number of arguments) are automatically
2650 detected in the environments |{Piton}| (and in the listings processed by
2651 |\PitonInputFile|):
2652 \begin{itemize}
2653 \item no mandatory argument : |\pause|\footnote{One should remark that it's
2654 also possible to use the command |\pause| in a ``LaTeX
2655 comment'', that is to say by writing |#> \pause|. By
2656 this way, if the code is copied, it's still executable}. ;
2657 \item one mandatory argument : |\action|, |\alert|, |\invisible|, |\only|,
2658 |\uncover| and |\visible| ; \newline
2659 % It's possible to add new commands to that list with the key
2660 \Definition{detected-beamer-commands} (the names of the commands must
2661 \emph{not} be preceded by a backslash).
2662 \item two mandatory arguments : |\alt| ;
2663 \item three mandatory arguments : |\temporal|.
2664 \end{itemize}
2665
2666 \medskip
2667 These commands must be used preceded and following by a space. In the
2668 mandatory arguments of these commands, the braces must be balanced. However,
2669 the braces included in short strings\footnote{The short strings of Python are
2670 the strings delimited by characters |'| or the characters |"|
2671 and not |'''| nor |"""|. In Python, the short strings can't
2672 extend on several lines.} of Python are not considered.
2673
2674 \medskip
2675 Regarding the functions |\alt| and |\temporal|, there should be no carriage
2676 return in the mandatory arguments of these functions.
2677
2678 \medskip
2679 Here is a complete example of file:
2680
2681 \begin{small}
2682 \begin{Code}
2683 \documentclass{beamer}
2684 \usepackage{piton}
2685 \begin{document}
2686 \begin{frame}[fragile]
2687 \begin{Piton}
2688 def string_of_list(l):
2689 """Convert a list of numbers in string"""
2690 \emph{\only<2->{s = "{" + str(l[0])}}
2691 \emph{\only<3->{for x in l[1:]: s = s + "," + str(x)}}
2692 \emph{\only<4->{s = s + "}"}}
2693 return s
2694 \end{Piton}
2695 \end{frame}
2696 \end{document}
2697 \end{Code}
2698 \end{small}
2699
2700 In the previous example, the braces in the Python strings |"{"| and |"}"| are
2701 correctly interpreted (without any escape character).
2702
2703
2704
2705
2706 \bigskip
2707 \subsubsection{Environments of Beamer allowed in \{Piton\} and \textbackslash PitonInputFile}
2708
2709 When \pkg{piton} is used in the class \pkg{beamer}, the following environments
2710 of Beamer are directly detected in the environments |{Piton}| (and in the
2711 listings processed by |\PitonInputFile|): |{actionenv}|, |{alertenv}|,
2712 |{invisibleenv}|, |{onlyenv}|, |{uncoverenv}| and |{visibleenv}|.
2713
2714 \smallskip
2715 \index{detected-beamer-environments}
2716 It's possible to add new environments to that list with the key
2717 \Definition{detected-beamer-environments}.
2718
2719 \smallskip
2720
2721 However, there is a restriction: these environments must contain only \emph{whole
2722 lines of code} in their body. The instructions |\begin{...}| and
2723 |\end{...}| must be alone on their lines.
2724
2725 \medskip
2726 Here is an example:
2727
2728 \begin{small}
2729 \begin{Code}
2730 \documentclass{beamer}
2731 \usepackage{piton}
2732 \begin{document}
2733 \begin{frame}[fragile]
2734 \begin{Piton}
2735 def square(x):
2736 """Compute the square of its argument"""
2737 \emph{\begin{uncoverenv}<2>}
2738 return x*x
2739 \emph{\end{uncoverenv}}
2740 \end{Piton}
2741 \end{frame}
2742 \end{document}
2743 \end{Code}
2744 \end{small}
2745
2746
2747 \vspace{1cm}
2748 \textbf{Remark concerning the command \textbackslash alert and the environment
2749 \{alertenv\} of Beamer}
2750
2751 \nobreak
2752 \smallskip
2753 Beamer provides an easy way to change the color used by the environment
2754 |{alertenv}| (and by the command |\alert| which relies upon it) to highlight
2755 its argument. Here is an example:
2756
2757 \begin{Verbatim}
2758 \setbeamercolor{~emphase#alerted text@}{fg=blue}
2759 \end{Verbatim}
2760
2761 However, when used inside an environment |{Piton}|, such tuning will probably
2762 not be the best choice because \pkg{piton} will, by design, change (most of
2763 the time) the color the different elements of text. One may prefer an environment
2764 |{alertenv}| that will change the background color for the elements to be
2765 highlighted.
2766
2767 \smallskip
2768 Here is a code that will do that job and add a yellow background. That code
2769 uses the command |\@highLight| of \pkg{lua-ul} (that extension requires also
2770 the package \pkg{luacolor}).
2771
2772 \begingroup
2773 \small
2774 \fvset{commandchars=\~\#\+}
2775 \begin{Verbatim}
2776 \setbeamercolor{alerted text}{bg=yellow!50}
2777 \makeatletter
2778 \AddToHook{env/Piton/begin}
2779 {\renewenvironment<>{alertenv}{\only~#1{~emphase#\@highLight+[alerted text.bg]}}{}}
2780 \makeatother
2781 \end{Verbatim}
2782 \endgroup
2783
2784 That code redefines locally the environment |{alertenv}| within the
2785 environments |{Piton}| (we recall that the command |\alert| relies upon that
2786 environment |{alertenv}|).
2787
2788
2789 \subsection{Footnotes in the environments of piton}
2790
2791 \index{footnote@\pkg{footnote} (extension)}
2792 \index{footnote (key)}
2793 \index{footnotehyper@\pkg{footnotehyper} (extension)}
2794 \index{footnotehyper (key)}
2795
2796 \label{footnote}
2797 If you want to put footnotes in an environment |{Piton}| or
2798 (or, more unlikely, in a listing produced by |\PitonInputFile|), you can use a
2799 pair |\footnotemark|--|\footnotetext|.
2800
2801 \smallskip
2802 However, it's also possible to extract the footnotes with the help of the
2803 package \pkg{footnote} or the package \pkg{footnotehyper}.
2804
2805 \smallskip
2806 If \pkg{piton} is loaded with the option \Definition{footnote} (with
2807 |\usepackage[footnote]{piton}|), the package \pkg{footnote} is loaded (if it is
2808 not yet loaded) and it is used to extract the footnotes.
2809
2810 \smallskip
2811 If \pkg{piton} is loaded with the option \Definition{footnotehyper}, the
2812 package \pkg{footnotehyper} is loaded (if it is not yet loaded) ant it is used
2813 to extract footnotes.
2814
2815 \smallskip
2816 Caution: The packages \pkg{footnote} and \pkg{footnotehyper} are incompatible.
2817 The package \pkg{footnotehyper} is the successor of the package \pkg{footnote}
2818 and should be used preferably. The package \pkg{footnote} has some drawbacks,
2819 in particular: it must be loaded after the package \pkg{xcolor} and it is not
2820 perfectly compatible with \pkg{hyperref}.
2821
2822
2823 \medskip
2824 \textbf{Important remark} : If you use Beamer, you should know that Beamer has
2825 its own system to extract the footnotes. Therefore, \pkg{piton} must be loaded
2826 in that class without the option |footnote| nor the option |footnotehyper|.
2827
2828
2829 \bigskip
2830 By default, in an environment |{Piton}|, a command |\footnote| may appear only
2831 within a ``LaTeX comment''. But it's also possible to add the command
2832 |\footnote| to the list of the ``\emph{detected-commands}''
2833 (cf.~part~\ref{detected-commands}, p.~\pageref{detected-commands}).
2834
2835 \medskip
2836 In this document, the package \pkg{piton} has been loaded with the
2837 option |footnotehyper| dans we added the command |\footnote| to the list of
2838 the ``\emph{detected-commands}'' with the following instruction in the
2839 preamble of the LaTeX document.
2840
2841 \qquad \verb|\PitonOptions{detected-commands = footnote}|
2842
2843
2844 \begingroup
2845 \small
2846 \fvset{commandchars=\~\&\@}
2847 \begin{Verbatim}
2848 \PitonOptions{background-color=gray!15}
2849 \begin{Piton}
2850 def arctan(x,n=10):
2851 if x < 0:
2852 return -arctan(-x)~emphase&\footnote{First recursive call.}]@
2853 elif x > 1:
2854 return pi/2 - arctan(1/x)~emphase&\footnote{Second recursive call.}@
2855 else:
2856 return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
2857 \end{Piton}
2858 \end{Verbatim}
2859 \endgroup
2860
2861 \begingroup
2862 \PitonOptions{background-color=gray!15}
2863 \begin{Piton}
2864 def arctan(x,n=10):
2865 if x < 0:
2866 return -arctan(-x)\footnote{First recursive call.}
2867 elif x > 1:
2868 return pi/2 - arctan(1/x)\footnote{Second recursive call.}
2869 else:
2870 return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
2871 \end{Piton}
2872 \endgroup
2873
2874
2875 \vspace{1cm}
2876
2877 If an environment |{Piton}| is used in an environment |{minipage}| of LaTeX,
2878 the notes are composed, of course, at the foot of the environment
2879 |{minipage}|. Recall that such |{minipage}| can't be broken by a page break.
2880
2881
2882 \begingroup
2883 \small
2884 \fvset{commandchars=\~\&\@}
2885 \begin{Verbatim}
2886 \PitonOptions{background-color=gray!15}
2887 ~emphase&\begin{minipage}{\linewidth}@
2888 \begin{Piton}
2889 def arctan(x,n=10):
2890 if x < 0:
2891 return -arctan(-x)~emphase&\footnote{First recursive call.}@
2892 elif x > 1:
2893 return pi/2 - arctan(1/x)~emphase&\footnote{Second recursive call.}@
2894 else:
2895 return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
2896 \end{Piton}
2897 ~emphase&\end{minipage}@
2898 \end{Verbatim}
2899 \endgroup
2900
2901 \begingroup
2902 \PitonOptions{background-color=gray!15}
2903 \begin{minipage}{\linewidth}
2904 \begin{Piton}
2905 def arctan(x,n=10):
2906 if x < 0:
2907 return -arctan(-x)\footnote{First recursive call.}
2908 elif x > 1:
2909 return pi/2 - arctan(1/x)\footnote{Second recursive call.}
2910 else:
2911 return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
2912 \end{Piton}
2913 \end{minipage}
2914 \endgroup
2915
2916
2917 \subsection{Tabulations}
2918
2919 \index{tabulations}
2920 \index{tab-size}
2921
2922 \smallskip
2923 Even though it's probably recommended to indent the computers listings with
2924 spaces and not tabulations\footnote{For the language Python, see the note %
2925 PEP~8.}, \pkg{piton} accepts the characters of tabulation (that is to say the
2926 characters U+0009) at the beginning of the lines. Each character U+0009 is
2927 replaced by $n$~spaces. The initial value of $n$ is $4$ but it's possible to
2928 change it with the key \Definition{tab-size} of |\PitonOptions|.
2929
2930 \smallskip
2931 There exists also a key \Definition{tabs-auto-gobble} which computes the
2932 minimal value $n$ of the number of consecutive characters U+0009 beginning
2933 each (non empty) line of the environment |{Piton}| and applies |gobble| with
2934 that value of~$n$ (before replacement of the tabulations by spaces, of
2935 course). Hence, that key is similar to the key |auto-gobble| but acts on
2936 U+0009 instead of U+0020 (spaces).
2937
2938 The key |env-gobble| is not compatible with the tabulations.
2939
2940
2941 \bigskip
2942 \section{API for the developpers}
2943
2944 \label{API}
2945
2946 The L3 variable \DefinitionCommand{l_piton_language_str} contains the name of
2947 the current language of \pkg{piton} (in lower case).
2948
2949 \bigskip
2950
2951 The extension \pkg{piton} provides a Lua function
2952 \Definition{piton.get_last_code} without argument which returns the code in
2953 the latest environment of \pkg{piton}.
2954 \begin{itemize}
2955 \item The carriage returns (which are present in the initial environment)
2956 appears as characters |\r| (i.e. U+000D).
2957
2958 \item The code returned by |piton.get_last_code()| takes into account the
2959 potential application of a key |gobble|, |auto-gobble| or |env-gobble|
2960 (cf.~p.~\pageref{gobble}).
2961
2962 \item The extra formatting elements added in the code are deleted by
2963 |piton.get_last_code()|. That concerns the LaTeX commands declared by the key
2964 |detected-commands| and its variants (cf. part~\ref{detected-commands}) and the
2965 elements inserted by the mechanism ``|escape|'' (cf. part~\ref{escape}).
2966
2967 \item |piton.get_last_code| is a Lua function and not a Lua string: the
2968 treatments outlined above are executed when the function is called. Therefore,
2969 it might be judicious to store the value returned by |piton.get_last_code()|
2970 in a variable of Lua if it will be used several times.
2971 \end{itemize}
2972
2973 \medskip
2974 For an example of use, see the part concerning |pyluatex|, part~\ref{pyluatex},
2975 p.~\pageref{pyluatex}.
2976
2977
2978 \section{Examples}
2979
2980
2981 \subsection{An example of tuning of the styles}
2982
2983 The graphical styles have been presented in the section \ref{styles},
2984 p.~\pageref{styles}.
2985
2986 \smallskip
2987 We present now an example of tuning of these styles adapted to the documents
2988 in black and white.
2989
2990 That tuning uses the command |\highLight| of \pkg{lua-ul} (that package
2991 requires itself the package \pkg{luacolor}).
2992
2993 \begin{Verbatim}
2994 \SetPitonStyle
2995 {
2996 Number = ,
2997 String = \itshape ,
2998 String.Doc = \color{gray} \slshape ,
2999 Operator = ,
3000 Operator.Word = \bfseries ,
3001 Name.Builtin = ,
3002 Name.Function = \bfseries \highLight[gray!20] ,
3003 Comment = \color{gray} ,
3004 Comment.LaTeX = \normalfont \color{gray},
3005 Keyword = \bfseries ,
3006 Name.Namespace = ,
3007 Name.Class = ,
3008 Name.Type = ,
3009 InitialValues = \color{gray}
3010 }
3011 \end{Verbatim}
3012
3013 In that tuning, many values given to the keys are empty: that means that the
3014 corresponding style won't insert any formatting instruction, except those in
3015 the value of the parameter |font-command|, whose initial value is |\ttfamily|
3016 (the element will be composed in the standard color, usually in black, etc.).
3017 Nevertheless, those entries are mandatory because the initial value of those
3018 keys in \pkg{piton} is \emph{not} empty.
3019
3020 \begingroup
3021 \PitonOptions{splittable}
3022
3023 \SetPitonStyle
3024 {
3025 Number = ,
3026 String = \itshape ,
3027 String.Doc = \color{gray} \slshape ,
3028 Operator.Word = \bfseries ,
3029 Operator = ,
3030 Name.Builtin = ,
3031 Name.Function = \bfseries \highLight[gray!20] ,
3032 Comment = \color{gray} ,
3033 Comment.LaTeX = \normalfont \color{gray} ,
3034 Keyword = \bfseries ,
3035 Name.Namespace = ,
3036 Name.Class = ,
3037 Name.Type = ,
3038 InitialValues = \color{gray}
3039 }
3040
3041
3042 \bigskip
3043
3044 \begin{Piton}
3045 from math import pi
3046
3047 def arctan(x,n=10):
3048 """Compute the mathematical value of arctan(x)
3049
3050 n is the number of terms in the sum
3051 """
3052 if x < 0:
3053 return -arctan(-x) # recursive call
3054 elif x > 1:
3055 return pi/2 - arctan(1/x)
3056 #> (we have used that $\arctan(x)+\arctan(1/x)=\pi/2$ for $x>0$)
3057 else:
3058 s = 0
3059 for k in range(n):
3060 s += (-1)**k/(2*k+1)*x**(2*k+1)
3061 return s
3062 \end{Piton}
3063
3064 \endgroup
3065
3066
3067 \subsection{Line numbering}
3068
3069 \label{example-numbering}
3070 \index{numbers of the lines de code|emph}
3071
3072 We remind that it's possible to have an automatic numbering of the lines in
3073 the computer listings by using the key |line-numbers| (used without value).
3074
3075 By default, the numbers of the lines are composed by \pkg{piton} in an
3076 overlapping position on the left (by using internally the command |\llap| of LaTeX).
3077
3078 \begingroup
3079 \small
3080 \fvset{commandchars=\~\&\@}
3081 \begin{Verbatim}
3082 ~emphase&\PitonOptions{background-color=gray!15, line-numbers}@
3083 \begin{Piton}
3084 def arctan(x,n=10):
3085 if x < 0:
3086 return -arctan(-x) #> (recursive call)
3087 elif x > 1:
3088 return pi/2 - arctan(1/x) #> (other recursive call)
3089 else:
3090 s = 0.0
3091 for k in range(n):
3092 s = s + (-1)**k/(2*k+1)*x**(2*k+1)
3093 return s
3094 \end{Piton}
3095 \end{Verbatim}
3096 \endgroup
3097
3098
3099
3100 \begingroup
3101 \PitonOptions{background-color=gray!15, line-numbers}
3102 \begin{Piton}
3103 def arctan(x,n=10):
3104 if x < 0:
3105 return -arctan(-x) #> (recursive call)
3106 elif x > 1:
3107 return pi/2 - arctan(1/x) #> (other recursive call)
3108 else:
3109 s = 0.0
3110 for k in range(n):
3111 s = s + (-1)**k/(2*k+1)*x**(2*k+1)
3112 return s
3113 \end{Piton}
3114 \endgroup
3115
3116 \bigskip
3117 In order to avoid that overlapping, it's possible to use the option |left-margin=auto|
3118 which will insert automatically a margin adapted to the numbers of lines that
3119 will be written (that margin is larger when the numbers are greater than~10).
3120
3121
3122 \begingroup
3123 \small
3124 \fvset{commandchars=\~\&\@}
3125 \begin{Verbatim}
3126 ~emphase&\PitonOptions{background-color=gray!15, left-margin = auto, line-numbers}@
3127 \begin{Piton}
3128 def arctan(x,n=10):
3129 if x < 0:
3130 return -arctan(-x) #> (recursive call)
3131 elif x > 1:
3132 return pi/2 - arctan(1/x) #> (other recursive call)
3133 else:
3134 s = 0.0
3135 for k in range(n):
3136 s = s + (-1)**k/(2*k+1)*x**(2*k+1)
3137 return s
3138 \end{Piton}
3139 \end{Verbatim}
3140 \endgroup
3141
3142
3143
3144 \begingroup
3145 \PitonOptions{background-color=gray!15,left-margin = auto, line-numbers}
3146 \begin{Piton}
3147 def arctan(x,n=10):
3148 if x < 0:
3149 return -arctan(-x) #> (recursive call)
3150 elif x > 1:
3151 return pi/2 - arctan(1/x) #> (other recursive call)
3152 else:
3153 s = 0.0
3154 for k in range(n):
3155 s = s + (-1)**k/(2*k+1)*x**(2*k+1)
3156 return s
3157 \end{Piton}
3158 \endgroup
3159
3160 \bigskip
3161 It's possible to have the numbers of lines on the right with
3162 |line-numbers/position=right| (the initial value of the parameter
3163 |line-numbers/position| is, without surprise, |left|). In that case, it is good
3164 to provide a positive value to |right-margin| (it's possible to use
3165 |right-margin=auto| but the actual value computed for |right-margin| will be
3166 probably appear to be too small if there is long broken lines of code.
3167
3168 \begingroup
3169 \fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
3170 \begin{Verbatim}
3171 \PitonOptions
3172 {
3173 background-color=gray!15,
3174 ~emphase&line-numbers/position = right@,
3175 ~emphase&right-margin = 1cm@,
3176 ~emphase&line-numbers@
3177 }
3178 \begin{Piton}
3179 def arctan(x,n=10):
3180 if x < 0:
3181 return -arctan(-x) #> (recursive call)
3182 elif x > 1:
3183 return pi/2 - arctan(1/x) #> (other recursive call)
3184 else:
3185 s = 0.0
3186 for k in range(n):
3187 s = s + (-1)**k/(2*k+1)*x**(2*k+1)
3188 return s
3189 \end{Piton}
3190 \end{Verbatim}
3191 \endgroup
3192
3193
3194
3195 \begingroup
3196 \PitonOptions
3197 {
3198 background-color=gray!15,
3199 line-numbers/position = right,
3200 right-margin = 1cm,
3201 line-numbers
3202 }
3203 \begin{Piton}
3204 def arctan(x,n=10):
3205 if x < 0:
3206 return -arctan(-x) #> (recursive call)
3207 elif x > 1:
3208 return pi/2 - arctan(1/x) #> (other recursive call)
3209 else:
3210 s = 0.0
3211 for k in range(n):
3212 s = s + (-1)**k/(2*k+1)*x**(2*k+1)
3213 return s
3214 \end{Piton}
3215 \endgroup
3216
3217 \bigskip
3218 The same example with the key |width=min|.
3219
3220
3221 \begingroup
3222 \fvset{commandchars=\~\&\@,formatcom=\small\color{gray}}
3223 \begin{Verbatim}
3224 \PitonOptions
3225 {
3226 background-color=gray!15,
3227 ~emphase&line-numbers/position = right@,
3228 ~emphase&right-margin = 1cm@,
3229 ~emphase&line-numbers@,
3230 ~emphase&width=min@
3231 }
3232 \begin{Piton}
3233 def arctan(x,n=10):
3234 if x < 0:
3235 return -arctan(-x) #> (recursive call)
3236 elif x > 1:
3237 return pi/2 - arctan(1/x) #> (other recursive call)
3238 else:
3239 s = 0.0
3240 for k in range(n):
3241 s = s + (-1)**k/(2*k+1)*x**(2*k+1)
3242 return s
3243 \end{Piton}
3244 \end{Verbatim}
3245 \endgroup
3246
3247
3248
3249 \begingroup
3250 \PitonOptions
3251 {
3252 background-color=gray!15,
3253 line-numbers/position = right,
3254 right-margin = 1cm,
3255 line-numbers,
3256 width=min
3257 }
3258 \begin{Piton}
3259 def arctan(x,n=10):
3260 if x < 0:
3261 return -arctan(-x) #> (recursive call)
3262 elif x > 1:
3263 return pi/2 - arctan(1/x) #> (other recursive call)
3264 else:
3265 s = 0.0
3266 for k in range(n):
3267 s = s + (-1)**k/(2*k+1)*x**(2*k+1)
3268 return s
3269 \end{Piton}
3270 \endgroup
3271
3272
3273
3274
3275 \bigskip
3276 \subsection{Formatting of the LaTeX comments}
3277
3278 \label{example-comments}
3279
3280 It's possible to modify the style |Comment.LaTeX| (with |\SetPitonStyle|) in
3281 order to display the LaTeX comments (which begin with |#>|) aligned on the
3282 right margin.
3283
3284
3285 \begingroup
3286 \small
3287 \fvset{commandchars=\~\&\@}
3288 \begin{Verbatim}
3289 \PitonOptions{background-color=gray!15}
3290 ~emphase&\SetPitonStyle{Comment.LaTeX = \hfill \normalfont\color{gray}}@
3291 \begin{Piton}
3292 def arctan(x,n=10):
3293 if x < 0:
3294 return -arctan(-x) #> recursive call
3295 elif x > 1:
3296 return pi/2 - arctan(1/x) #> other recursive call
3297 else:
3298 return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
3299 \end{Piton}
3300 \end{Verbatim}
3301 \endgroup
3302
3303 \begingroup
3304 \PitonOptions{background-color=gray!15}
3305 \SetPitonStyle{Comment.LaTeX = \hfill \normalfont\color{gray}}
3306 \begin{Piton}
3307 def arctan(x,n=10):
3308 if x < 0:
3309 return -arctan(-x) #> recursive call
3310 elif x > 1:
3311 return pi/2 - arctan(1/x) #> another recursive call
3312 else:
3313 return sum( (-1)**k/(2*k+1)*x**(2*k+1) for k in range(n) )
3314 \end{Piton}
3315 \endgroup
3316
3317
3318 \vspace{1cm}
3319 It's also possible to display these LaTeX comments in a kind of second column
3320 by limiting the width of the listing with the key |width|.
3321
3322 \begingroup
3323 \small
3324 \fvset{commandchars=\~\&\@}
3325 \begin{Verbatim}
3326 \PitonOptions{background-color=gray!15, width=9cm}
3327 ~emphase&\NewDocumentCommand{\MyLaTeXCommand}{m}{\hfill \normalfont\itshape\rlap{\quad #1}}@
3328 ~emphase&\SetPitonStyle{Comment.LaTeX = \MyLaTeXCommand}@
3329 \begin{Piton}
3330 def arctan(x,n=10):
3331 if x < 0:
3332 return -arctan(-x) #> recursive call
3333 elif x > 1:
3334 return pi/2 - arctan(1/x) #> another recursive call
3335 else:
3336 s = 0
3337 for k in range(n):
3338 s += (-1)**k/(2*k+1)*x**(2*k+1)
3339 return s
3340 \end{Piton}
3341 \end{Verbatim}
3342 \endgroup
3343
3344
3345
3346 \begingroup
3347 \PitonOptions{background-color=gray!15, width=9cm}
3348 \NewDocumentCommand{\MyLaTeXCommand}{m}{\hfill \normalfont\itshape\rlap{\quad #1}}
3349 \SetPitonStyle{Comment.LaTeX = \MyLaTeXCommand}
3350 \begin{Piton}
3351 def arctan(x,n=10):
3352 if x < 0:
3353 return -arctan(-x) #> recursive call
3354 elif x > 1:
3355 return pi/2 - arctan(1/x) #> another recursive call
3356 else:
3357 s = 0
3358 for k in range(n):
3359 s += (-1)**k/(2*k+1)*x**(2*k+1)
3360 return s
3361 \end{Piton}
3362 \endgroup
3363
3364
3365 \subsection{The command \texttt{\textbackslash rowcolor}}
3366
3367 \indexcommand{rowcolor}
3368
3369
3370 The command |\rowcolor| has been presented in the part \ref{rowcolor}, at the
3371 page~\pageref{rowcolor}. We recall that this command adds a colored background
3372 to the current line (the \emph{whole} line, and not only the part with text).
3373
3374 It's possible to use that command in a style of \pkg{piton}, as shown in
3375 p.~\pageref{rowcolor}, but maybe we wish to use it directly in a listing. In that aim,
3376 it's mandatory to use one of the mechanisms to escape to LaTeX provided by \pkg{piton}.
3377 In the following example, we use the key |raw-detected-commands|
3378 (cf.~p.~\pageref{raw-detected-commands}). Since the ``detected commands'' are commands
3379 with only one argument, it won't be possible to write (for example)
3380 |\rowcolor[rgb]{0.9,1,0.9}| but the syntax |\rowcolor{[rgb]{0.9,1,0.9}}| will be
3381 allowed.
3382
3383 \bigbreak
3384 \begin{footnotesize}
3385 \begin{Verbatim}
3386 \PitonOptions{raw-detected-commands = rowcolor} % in the preamble
3387 \end{Verbatim}
3388 \end{footnotesize}
3389
3390 \medskip
3391
3392 \begin{BVerbatim}[boxwidth=87mm,baseline=c]
3393 \begin{Piton}[width=min]
3394 def fact(n):
3395 if n==0:
3396 return 1 ~emphase#\rowcolor{yellow!50}@
3397 else:
3398 return n*fact(n-1)
3399 \end{Piton}
3400 \end{BVerbatim}
3401 \hspace{1cm}
3402 \begin{Piton}[width=min,box]
3403 def fact(n):
3404 if n==0:
3405 return 1 \rowcolor{yellow!50}
3406 else:
3407 return n*fact(n-1)
3408 \end{Piton}
3409
3410
3411 \bigbreak
3412 Here is now the same example with the use of the key |background-color|
3413 (cf. p.~\pageref{background-color}).
3414
3415 \medskip
3416 \begin{BVerbatim}[boxwidth=92mm,baseline=c]
3417 \begin{Piton}[width=min,~emphase#background-color=gray!15@]
3418 def fact(n):
3419 if n==0:
3420 return 1 ~emphase#\rowcolor{yellow!50}@
3421 else:
3422 return n*fact(n-1)
3423 \end{Piton}
3424 \end{BVerbatim}
3425 \hspace{5mm}
3426 \begin{Piton}[width=min,box,background-color=gray!15]
3427 def fact(n):
3428 if n==0:
3429 return 1 \rowcolor{yellow!50}
3430 else:
3431 return n*fact(n-1)
3432 \end{Piton}
3433
3434
3435 \bigbreak
3436 As you can see, a margin has been added on both sides of the code by the key
3437 |background-color|. If you wish those margins without general background, you
3438 should use |background-color| with the special value~|none|.
3439
3440 \medskip
3441 \begin{BVerbatim}[boxwidth=87mm,baseline=c]
3442 \begin{Piton}[width=min,~emphase#background-color=none@]
3443 def fact(n):
3444 if n==0:
3445 return 1 ~emphase#\rowcolor{yellow!50}@
3446 else:
3447 return n*fact(n-1)
3448 \end{Piton}
3449 \end{BVerbatim}
3450 \hspace{1cm}
3451 \begin{Piton}[width=min,box,background-color=none]
3452 def fact(n):
3453 if n==0:
3454 return 1 \rowcolor{yellow!50}
3455 else:
3456 return n*fact(n-1)
3457 \end{Piton}
3458
3459
3460
3461
3462
3463 \subsection{Use with tcolorbox}
3464
3465 \label{examples-tcolorbox}
3466
3467 The key |tcolorbox| of \pkg{piton} has been presented at the page
3468 \pageref{tcolorbox}.
3469
3470 If, when that key is used, we wish to customize the graphical box created by
3471 \pkg{tcolorbox} (with the keys provided by \pkg{tcolorbox}), we should use the
3472 command |\tcbset| provided by \pkg{tcolorbox}. In order to limit the scope of
3473 the settings done by that command, the best way is to create a new environment
3474 with the dedicated command |\NewPitonEnvironment|
3475 (cf.~p.~\pageref{NewPitonEnvironment}). That environment with contain the
3476 settings done by \pkg{piton} (with |\PitonOptions|) and those done by
3477 \pkg{tcolorbox} (with |\tcbset|).
3478
3479
3480 \bigskip Here is an example of such environment |{Python}| with a colored
3481 column on the left for the numbers of lines.
3482
3483 \begin{footnotesize}
3484 \begin{Verbatim}
3485 \usepackage{tcolorbox} % in the preamble
3486 \tcbuselibrary{breakable,skins} % in the preamble
3487 \end{Verbatim}
3488 \end{footnotesize}
3489
3490 \smallskip
3491
3492 \begin{Verbatim}
3493 \NewPitonEnvironment{Python}{m}
3494 {%
3495 \PitonOptions
3496 {
3497 ~emphase#tcolorbox@,
3498 splittable=3,
3499 width=min,
3500 line-numbers, % activate the numbers of lines
3501 line-numbers = % tuning for the numbers of lines
3502 {
3503 format = \footnotesize\color{white}\sffamily ,
3504 sep = 2.5mm
3505 }
3506 }%
3507 \tcbset
3508 {
3509 enhanced,
3510 title=~#1,
3511 fonttitle=\sffamily,
3512 left = 6mm,
3513 top = 0mm,
3514 bottom = 0mm,
3515 overlay=
3516 {%
3517 \begin{tcbclipinterior}%
3518 \fill[gray!80]
3519 (frame.south west) rectangle
3520 ([xshift=6mm]frame.north west);
3521 \end{tcbclipinterior}%
3522 }
3523 }
3524 }
3525 { }
3526 \end{Verbatim}
3527
3528 \bigskip
3529 In the following example of use, we have illustrated the fact that it is possible
3530 to impose a break of page in such environment with |\newpage{}| if we have required the
3531 detection of the LaTeX command |\newpage| with the key |vertical-detected-commands|
3532 (cf.~p.~\pageref{vertical-detected-commands}) in the preamble of the LaTeX document.
3533
3534 Remark that we must use |\newpage{}| and not |\newpage| because the LaTeX
3535 commands detected by \pkg{piton} are meant to be commands with one argument
3536 (between explicit curly braces).
3537
3538 \begin{footnotesize}
3539 \begin{Verbatim}
3540 \PitonOptions{vertical-detected-commands = newpage} % in the preamble
3541 \end{Verbatim}
3542 \end{footnotesize}
3543
3544 \medskip
3545 \begin{Verbatim}
3546 ~emphase#\begin{Python}@{My example}
3547 def square(x):
3548 """Computes the square of x"""
3549 return x*x
3550 def square(x):
3551 """Computes the square of x"""
3552 return x*x
3553 def square(x):
3554 """Computes the square of x"""
3555 return x*x
3556 def square(x):
3557 """Computes the square of x"""
3558 return x*x ~emphase#\newpage{}@
3559 def square(x):
3560 """Computes the square of x"""
3561 return x*x
3562 ...
3563 def square(x):
3564 """Computes the square of x"""
3565 return x*x
3566 ~emphase#\end{Python}@
3567 \end{Verbatim}
3568
3569 \bigskip
3570
3571 \RenewPitonEnvironment{Python}{m}
3572 {%
3573 \PitonOptions
3574 {
3575 tcolorbox,
3576 splittable=3,
3577 width=min,
3578 line-numbers,
3579 line-numbers =
3580 {
3581 format = \footnotesize\color{white}\sffamily ,
3582 sep = 2.5mm
3583 }
3584 }%
3585 \tcbset
3586 {
3587 enhanced,
3588 title=#1,
3589 fonttitle=\sffamily,
3590 left = 6mm,
3591 top = 0mm,
3592 bottom = 0mm,
3593 overlay=
3594 {%
3595 \begin{tcbclipinterior}%
3596 \fill[gray!80]
3597 (frame.south west) rectangle
3598 ([xshift=6mm]frame.north west);
3599 \end{tcbclipinterior}%
3600 }
3601 }
3602 }
3603 { }
3604
3605
3606 \begin{Python}{My example}
3607 def square(x):
3608 """Computes the square of x"""
3609 return x*x
3610 def square(x):
3611 """Computes the square of x"""
3612 return x*x
3613 def square(x):
3614 """Computes the square of x"""
3615 return x*x
3616 def square(x):
3617 """Computes the square of x"""
3618 return x*x \newpage{}
3619 def square(x):
3620 """Computes the square of x"""
3621 return x*x
3622 def square(x):
3623 """Computes the square of x"""
3624 return x*x
3625 def square(x):
3626 """Computes the square of x"""
3627 return x*x
3628 def square(x):
3629 """Computes the square of x"""
3630 return x*x
3631 def square(x):
3632 """Computes the square of x"""
3633 return x*x
3634 def square(x):
3635 """Computes the square of x"""
3636 return x*x
3637 def square(x):
3638 """Computes the square of x"""
3639 return x*x
3640 def square(x):
3641 """Computes the square of x"""
3642 return x*x
3643 def square(x):
3644 """Computes the square of x"""
3645 return x*x
3646 def square(x):
3647 """Computes the square of x"""
3648 return x*x
3649 def square(x):
3650 """Computes the square of x"""
3651 return x*x
3652 def square(x):
3653 """Computes the square of x"""
3654 return x*x
3655 def square(x):
3656 """Computes the square of x"""
3657 return x*x
3658 def square(x):
3659 """Computes the square of x"""
3660 return x*x
3661 def square(x):
3662 """Computes the square of x"""
3663 return x*x
3664 def square(x):
3665 """Computes the square of x"""
3666 return x*x
3667 def square(x):
3668 """Computes the square of x"""
3669 return x*x
3670 def square(x):
3671 """Computes the square of x"""
3672 return x*x
3673 def square(x):
3674 """Computes the square of x"""
3675 return x*x
3676 def square(x):
3677 """Computes the square of x"""
3678 return x*x
3679 def square(x):
3680 """Computes the square of x"""
3681 return x*x
3682 def square(x):
3683 """Computes the square of x"""
3684 return x*x
3685 def square(x):
3686 """Computes the square of x"""
3687 return x*x
3688 def square(x):
3689 """Computes the square of x"""
3690 return x*x
3691 \end{Python}
3692
3693
3694
3695 \bigskip
3696 \subsection{Use with pyluatex}
3697
3698 \subsubsection{Standard use of pyluatex}
3699
3700 \index{pyluatex@{\pkg{pyluatex}} (extension)}
3701 \label{pyluatex}
3702
3703
3704 \textcolor{red}{Caution: The following examples require the version 0.7.0 of
3705 \pkg{pyluatex}.}
3706
3707 \bigskip
3708
3709 The package \pkg{pyluatex} is an extension which allows the execution of some
3710 Python code from |lualatex| (as long as Python is installed on the machine
3711 and that the compilation is done with |lualatex| and |--shell-escape|).
3712
3713 Here is, for example, an environment |{PitonExecute}| which formats a Python
3714 listing (with \pkg{piton}) but also displays the output of the execution of the
3715 code with Python.
3716
3717 \medskip
3718 \begin{Code}
3719 \NewPitonEnvironment{\emph{PitonExecute}}{O{}}
3720 {\PitonOptions{#1}}
3721 {\begin{center}
3722 \directlua
3723 {
3724 pyluatex.execute(piton.get_last_code(),false,cctab_latex,
3725 false,false,true,"default",false,false)
3726 tex.print(pyluatex.get_last_output())
3727 }
3728 \end{center}}
3729 \end{Code}
3730
3731 \medskip
3732 We have used the Lua function |piton.get_last_code| provided in the API of
3733 \pkg{piton} : cf.~part~\ref{API}, p.~\pageref{API}.
3734
3735 \medskip
3736 This environment |{PitonExecute}| takes in as optional argument (between
3737 square brackets) the options of the command |\PitonOptions|.
3738
3739
3740 \NewPitonEnvironment{PitonExecute}{O{}}
3741 {\PitonOptions{#1}}
3742 {\begin{center}
3743 \directlua
3744 {
3745 pyluatex.execute(piton.get_last_code(),false,cctab_latex,
3746 false,false,true,"default",false,false)
3747 tex.print(pyluatex.get_last_output())
3748 }
3749 \end{center}}
3750
3751
3752 \medskip
3753 \begin{Verbatim}
3754 ~emphase#\begin{PitonExecute}@[background-color=gray!15]
3755 def square(x):
3756 """Computes the square of x"""
3757 return x*x
3758 print(f'The square of 12 is {square(12)}.')
3759 ~emphase#\end{PitonExecute}@
3760 \end{Verbatim}
3761
3762
3763 \medskip
3764 \begin{PitonExecute}[background-color=gray!15]
3765 def square(x):
3766 """Computes the square of x"""
3767 return x*x
3768 print(f'The square of 12 is {square(12)}.')
3769 \end{PitonExecute}
3770
3771
3772 \bigskip
3773 It's also possible to use, in that environment, the mechanims for escape to LaTeX
3774 as previously (cf. p.~\pageref{LaTeX-escapes}).
3775
3776 \begin{footnotesize}
3777 \begin{Verbatim}
3778 \usepackage{luacolor,lua-ul} % in the preamble
3779 \PitonOptions{detected-commands = highLight} % in the preamble
3780 \end{Verbatim}
3781 \end{footnotesize}
3782
3783 \medskip
3784 \begin{Verbatim}
3785 \begin{PitonExecute}[background-color=gray!15]
3786 def square(x):
3787 """Computes the square of x"""
3788 ~emphase#\highLight{return x*x}@
3789 print(f'The square of 12 is {square(12)}.')
3790 \end{PitonExecute}
3791 \end{Verbatim}
3792
3793 \medskip
3794 \begin{PitonExecute}[background-color=gray!15]
3795 def square(x):
3796 """Computes the square of x"""
3797 \highLight{return x*x}
3798 print(f'The square of 12 is {square(12)}.')
3799 \end{PitonExecute}
3800
3801 \bigskip
3802 \subsubsection{Use of the environment \{python\} of pyluatex with the key repl}
3803
3804 \label{python}
3805 \index{python@\texttt{\{python\}} (environment of \pkg{pyluatex})}
3806
3807 With the key |repl| the environment |{python}| of \pkg{pyluatex} submit its
3808 content to Python and return what we obtain when we submit that code to a
3809 \textsc{repl} (\emph{read-eval-print loop}) of Python. We obtain a succession of
3810 instructions preceded by the prompt |>>>| of Python and values returned by
3811 Python (and the outputs of potential commands |print| of Python).
3812
3813 \medskip
3814 It's possible to give that to an environment |{Piton}| which will do the usual formatting
3815 and put on a colored background the lignes corresponding to the instructions provided to
3816 the Python interpreter (the color of that background may be changed with the key
3817 |prompt-background-color| whose inital value is |gray!15|).
3818
3819 \medskip
3820 Here a programmation of environment |{PitonREPL}| which does that job (for technical
3821 reasons, the |!| is here mandatory in the signature of the environment). It's not
3822 possible to process as previously (in the ``standard'' use of \pkg{pyluatex}) because,
3823 of course, the output of |{python}| must be treated by \pkg{piton}. Therefore, it's not
3824 possible to use the escaping tools (|detected-commands|, |begin-escape|, etc.) in the code.
3825
3826 \begin{Verbatim}
3827 \NewDocumentEnvironment { PitonREPL } { ! O { } } % the ! is mandatory
3828 {
3829 \PitonOptions
3830 {
3831 ~emphase#prompt-background-color=blue!15@ ,
3832 ~emphase#background-color=none@, % for small margins
3833 ~#1
3834 }
3835 \PyLTVerbatimEnv
3836 \begin{python}[repl,quiet]
3837 }
3838 {
3839 \end{python}
3840 \directlua
3841 {
3842 tex.print("\\begin{Piton}")
3843 tex.print(pyluatex.get_last_output())
3844 tex.print("\\end{Piton}")
3845 tex.print("")
3846 }
3847 \ignorespacesafterend
3848 }
3849 \end{Verbatim}
3850
3851 \medskip
3852 Here is an example of use of that new environment |{PitonREPL}|.
3853
3854 \medskip
3855 \begin{Code}
3856 \emph{\begin{PitonREPL}}
3857 def absolute_value(x):
3858 """Computes the absolute value of x"""
3859 if x > 0:
3860 return x
3861 else:
3862 return -x
3863
3864 absolute_value(-3)
3865 absolute_value(0)
3866 absolute_value(5)
3867 \emph{\end{PitonREPL}}
3868 \end{Code}
3869
3870 \bigskip
3871
3872
3873 \NewDocumentEnvironment { PitonREPL } { ! O { } }
3874 {
3875 \PitonOptions
3876 {
3877 background-color=none ,
3878 prompt-background-color=blue!15 ,
3879 #1
3880 }
3881 \PyLTVerbatimEnv
3882 \begin{python}[repl,quiet]
3883 }
3884 {
3885 \end{python}
3886 \directlua
3887 {
3888 tex.print("\\begin{Piton}")
3889 tex.print(pyluatex.get_last_output())
3890 tex.print("\\end{Piton}")
3891 tex.print("")
3892 }
3893 \ignorespacesafterend
3894 }
3895
3896
3897 \begin{PitonREPL}
3898 def absolute_value(x):
3899 """Computes the absolute value of x"""
3900 if x > 0:
3901 return x
3902 else:
3903 return -x
3904
3905 absolute_value(-3)
3906 absolute_value(0)
3907 absolute_value(5)
3908 \end{PitonREPL}
3909
3910 \bigskip
3911 In fact, it's possible to avoid the display of the prompts themselves (that is to say
3912 the strings |>>>| and |...|). Indeed, \pkg{piton} provides a style for those elements,
3913 called |Prompt|. The initial value of that style is empty, and that's why no action is done
3914 for those elements and they are displayed as they are. By using a value which
3915 is a function which gobbles its argument, it's possible to require that these prompts are not
3916 displayed.
3917
3918
3919 \bigskip
3920 \begin{savenotes}
3921 \begin{Verbatim}
3922 \NewDocumentCommand{\Gobe}{m}{}#~color#black@~footnote#Here we have defined a function ~texttt#~string~Gobe@ but, in fact, it already exists in L3 with the name ~texttt#~string~use~_none:n@.@@
3923 \SetPitonStyle{ ~emphase#Prompt = \Gobe@ }
3924 \end{Verbatim}
3925 \end{savenotes}
3926
3927 \NewDocumentCommand{\Gobe}{m}{}
3928 \ExplSyntaxOn
3929 \SetPitonStyle{ Prompt = \use_none:n }
3930 \ExplSyntaxOff
3931
3932 \bigskip
3933 L'exemple précédent donne alors :
3934
3935 \medskip
3936 \begin{Verbatim}
3937 ~emphase#\begin{PitonREPL}@
3938 def absolute_value(x):
3939 """Computes the absolute value of x"""
3940 if x > 0:
3941 return x
3942 else:
3943 return -x
3944
3945 absolute_value(-3)
3946 absolute_value(0)
3947 absolute_value(5)
3948 ~emphase#\end{PitonREPL}@
3949 \end{Verbatim}
3950
3951
3952 \bigskip
3953
3954 \begin{PitonREPL}
3955 def absolute_value(x):
3956 """Computes the absolute value of x"""
3957 if x > 0:
3958 return x
3959 else:
3960 return -x
3961
3962 absolute_value(-3)
3963 absolute_value(0)
3964 absolute_value(5)
3965 \end{PitonREPL}
3966
3967
3968
3969
3970 \clearpage
3971 \section{The styles for the different computer languages}
3972
3973 \label{Semantic}
3974
3975
3976 \subsection{The language Python}
3977
3978 In \pkg{piton}, the default language is Python. If necessary, it's possible to
3979 come back to the language Python with |\PitonOptions{language=Python}|.
3980
3981 \bigskip
3982
3983 The initial settings
3984 done by \pkg{piton} in |piton.sty| are inspired by the style \pkg{manni} of
3985 Pygments, as applied by Pygments to the language Python.\footnote{See:
3986 \url{https://pygments.org/styles/}. Remark that, by default, Pygments provides
3987 for its style \pkg{manni} a colored background whose color is the HTML color
3988 |#F0F3F3|. It's possible to have the same color in |{Piton}|
3989 with the instruction |\PitonOptions{background-color = [HTML]{F0F3F3}}|.}
3990
3991 \vspace{1cm}
3992
3993 \begin{center}
3994 \begin{tabularx}{\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
3995 \toprule
3996 \normalfont Style & Use \\
3997 \midrule
3998 Number & the numbers \\
3999 String.Short & the short strings (entre \texttt{'} ou \texttt{"}) \\
4000 String.Long & the long strings (entre \texttt{'''} ou \texttt{"""}) excepted
4001 the doc-strings (governed by |String.Doc|)\\
4002 String & that key fixes both |String.Short| et |String.Long| \\
4003 String.Doc & the doc-strings (only with |"""| following PEP~257) \\
4004 String.Interpol & the syntactic elements of the fields of the f-strings
4005 (that is to say the characters \texttt{\{} et \texttt{\}}); that style
4006 inherits for the styles |String.Short| and |String.Long| (according the kind
4007 of string where the interpolation appears) \\
4008 Interpol.Inside & the content of the interpolations in the f-strings (that
4009 is to say the elements between \texttt{\{} and~\texttt{\}}); if the final
4010 user has not set that key, those elements will be formatted by \pkg{piton}
4011 as done for any Python code. \\
4012 Operator & the following operators: \texttt{!= == << >> - \~{} + / * \% = < >
4013 \& .} \verb+|+ \verb|@| \\
4014 Operator.Word & the following operators: |in|, |is|, |and|, |or| et |not| \\
4015 Name.Builtin & almost all the functions predefined by Python \\
4016 Name.Decorator & the decorators (instructions beginning by \verb|@|) \\
4017 Name.Namespace & the name of the modules \\
4018 Name.Class & the name of the Python classes defined by the user \emph{at their
4019 point of definition} (with the keyword |class|) \\
4020 Name.Function & the name of the Python functions defined by the user \emph{at their
4021 point of definition} (with the keyword |def|) \\
4022 UserFunction & the name of the Python functions previously defined by the user
4023 (the initial value of that parameter is
4024 {\ttfamily \textbackslash PitonStyle\{Identifier\}} and,
4025 therefore, the names of that functions are formatted like the
4026 identifiers). \\
4027 Exception & les exceptions prédéfinies (ex.: \texttt{SyntaxError}) \\
4028 InitialValues & the initial values (and the preceding symbol |=|) of the
4029 optional arguments in the definitions of functions; if the final
4030 user has not set that key, those elements will be formatted by \pkg{piton}
4031 as done for any Python code. \\
4032 Comment & the comments beginning with \texttt{\#} \\
4033 Comment.LaTeX & the comments beginning with \texttt{\#>}, which are composed by
4034 \pkg{piton} as LaTeX code (merely named ``LaTeX comments'' in this document) \\
4035 Keyword.Constant & |True|, |False| et |None| \\
4036 Keyword & the following keywords:
4037 \ttfamily assert, break, case, continue, del,
4038 elif, else, except, exec, finally, for, from,
4039 global, if, import, in, lambda, non local,
4040 pass, raise, return, try, while,
4041 with, yield et yield from.\\
4042 Identifier & the identifiers. \\
4043 \bottomrule
4044 \end{tabularx}
4045 \end{center}
4046
4047
4048 \newpage
4049
4050 \subsection{The language OCaml}
4051
4052 It's possible to switch to the language |OCaml| with the key |language|:
4053 |language = OCaml|.
4054
4055
4056 \bigskip
4057
4058
4059 \begin{center}
4060 \begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
4061 \toprule
4062 \normalfont Style & Use \\
4063 \midrule
4064 Number & the numbers \\
4065 String.Short & the characters (between \texttt{'}) \\
4066 String.Long & the strings, between |"| but also the \emph{quoted-strings} \\
4067 String & that key fixes both |String.Short| and |String.Long| \\
4068 Operator & the oporators, in particular: |+|, |-|, |/|, |*|, |@|, |!=|, |==|, |&&| \\
4069 Operator.Word & the following operators: |asr|, |land|, |lor|, |lsl|, |lxor|, |mod| et |or| \\
4070 Name.Builtin & the functions |not|, |incr|, |decr|, |fst| et |snd| \\
4071 Name.Type & the name of a type of OCaml \\
4072 Name.Field & the name of a field of a module \\
4073 Name.Constructor & the name of the constructors of types (which begins by a capital) \\
4074 Name.Module & the name of the modules \\
4075 Name.Function & the name of the Python functions defined by the user \emph{at their
4076 point of definition} (with the keyword |let|) \\
4077 UserFunction & the name of the Python functions previously defined by the user
4078 (the initial value of that parameter is
4079 {\ttfamily \textbackslash PitonStyle\{Identifier\}} and,
4080 therefore, the names of that functions are formatted like the identifiers). \\
4081 Exception & the predefined exceptions (eg : |End_of_File|) \\
4082 TypeParameter & the parameters of the types \\
4083 Comment & the comments, between |(*| et |*)|; these comments may be nested \\
4084 Keyword.Constant & |true| et |false| \\
4085 Keyword & the following keywords: |assert|, |as|, |done|, |downto|, |do|,
4086 |else|, |exception|, |for|, |function| , |fun|, |if|, |lazy|, |match|,
4087 |mutable|, |new|, |of|, |private|, |raise|, |then|, |to|, |try| , |virtual|,
4088 |when|, |while| and |with| \\
4089 Keyword.Governing & the following keywords: |and|, |begin|, |class|, |constraint|,
4090 |end|, |external|, |functor|, |include|, |inherit|, |initializer|,
4091 |in|, |let|, |method|, |module|, |object|, |open|, |rec|, |sig|,
4092 |struct|, |type| and |val|. \\
4093 Identifier & the identifiers \\
4094 Delim & the delimiters |(|, |[|, \verb+[|+, |)|, |]| and \verb+|]+ \\
4095 Punct & the symbols of ponctuation |,| |:|, |;| and |!|. \\
4096 \bottomrule
4097 \end{tabularx}
4098 \end{center}
4099
4100 \vspace{1cm}
4101
4102 Here is an example:
4103
4104 \medskip
4105 \begin{Piton}[language = OCaml]
4106 let rec quick_sort lst = (* Quick sort *)
4107 match lst with
4108 | [] -> []
4109 | pivot :: rest ->
4110 let left = List.filter (fun x -> x < pivot) rest in
4111 let right = List.filter (fun x -> x >= pivot) rest in
4112 quick_sort left @ [pivot] @ quick_sort right
4113 \end{Piton}
4114
4115
4116 \newpage
4117
4118 \subsection[The language C (and C++)]{The language C (and \CC)}
4119
4120
4121 It's possible to switch to the language |C| with the key |language|: |language = C|.
4122
4123 \bigskip
4124
4125 \begin{center}
4126 \begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
4127 \toprule
4128 \normalfont Style & Use \\
4129 \midrule
4130 Number & the numbers \\
4131 String.Short & the characters (between \texttt{'}) \\
4132 String.Long & the strings (between \texttt{"}) \\
4133 String.Interpol & the elements \texttt{\%d}, \texttt{\%i}, \texttt{\%f},
4134 \texttt{\%c}, etc. in the strings; that style inherits from the style |String.Long| \\
4135 Operator & the following operators :
4136 \texttt{!= == << >> - \~{} + / * \% = < > \& .} \verb+|+ \verb|@| \\
4137 Name.Type & the following predefined types:
4138 |bool|, |char|, |char16_t|, |char32_t|, |double|, |float|, |int|, |int8_t|,
4139 |int16_t|, |int32_t|, |int64_t|, |uint8_t|, |uint16_t|, |uint32_t|, |uint64_t|,
4140 |long|, |short|, |signed|, |unsigned|, |void| et |wchar_t| \\
4141 Name.Builtin & the following predefined functions: |printf|, |scanf|,
4142 |malloc|, |sizeof| and |alignof| \\
4143 Name.Class & the names of the classes when they are defined, that is to say after
4144 the keyword \verb|class| \\
4145 Name.Function & the name of the Python functions defined by the user \emph{at their
4146 point of definition} (with the keyword |let|) \\
4147 UserFunction & the name of the Python functions previously defined by the user
4148 (the initial value of that parameter is
4149 {\ttfamily \textbackslash PitonStyle\{Identifier\}} and,
4150 therefore, the names of that functions are formatted like the
4151 identifiers). \\
4152 Preproc & the instructions of the preprocessor (beginning par |#|) \\
4153 Comment & the comments (beginning by \texttt{//} or between |/*| and |*/|) \\
4154 Comment.LaTeX & the comments beginning by \texttt{//>} which are composed by
4155 \pkg{piton} as LaTeX code (merely named ``LaTeX comments'' in this document) \\
4156 Keyword.Constant & |default|, |false|, |NULL|, |nullptr| and |true| \\
4157 Keyword & the following keywords:
4158 |alignas|, |asm|, |auto|, |break|, |case|, |catch|, |class|,
4159 |constexpr|, |const|, |continue|, |decltype|, |do|, |else|, |enum|,
4160 |extern|, |for|, |goto|, |if|, |nexcept|, |private|, |public|, |register|,
4161 |restricted|, |try|, |return|, |static|, |static_assert|, |struct|, |switch|,
4162 |thread_local|, |throw|, |typedef|, |union|, |using|, |virtual|, |volatile|
4163 and |while| \\
4164 Identifier & the identifiers. \\
4165 \bottomrule
4166 \end{tabularx}
4167 \end{center}
4168
4169 \newpage
4170
4171 \subsection{The language SQL}
4172
4173
4174 It's possible to switch to the language |SQL| with the key |language|: |language = SQL|.
4175
4176 \bigskip
4177
4178 \begin{center}
4179 \begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
4180 \toprule
4181 \normalfont Style & Use \\
4182 \midrule
4183 Number & the numbers \\
4184 String.Long & the strings (between \texttt{'} and not \texttt{"} because the
4185 elements between \texttt{"} are names of fields and formatted with |Name.Field|) \\
4186 Operator & the following operators : \texttt{= != <> >= > < <= * + / } \\
4187 Name.Table & the names of the tables \\
4188 Name.Field & the names of the fields of the tables \\
4189 Name.Builtin & the following built-in functions (their names are \emph{not} case-sensitive):
4190 |avg|, |count|, |char_length|, |concat|, |curdate|, |current_date|,
4191 |date_format|, |day|, |lower|, |ltrim|, |max|, |min|, |month|, |now|,
4192 |rank|, |round|, |rtrim|, |substring|, |sum|, |upper| and |year|. \\
4193 Comment & the comments (beginning by \texttt{--} or between |/*| and |*/|) \\
4194 Comment.LaTeX & the comments beginning by \texttt{-->} which are composed by
4195 \pkg{piton} as LaTeX code (merely named ``LaTeX comments'' in this document) \\
4196 Keyword & the following keywords (their names are \emph{not} case-sensitive):
4197 |abort|, |action|, |add|, |after|, |all|, |alter|, |always|, |analyze|,
4198 |and|, |as|, |asc|, |attach|, |autoincrement|, |before|, |begin|, |between|,
4199 |by|, |cascade|, |case|, |cast|, |check|, |collate|, |column|, |commit|,
4200 |conflict|, |constraint|, |create|, |cross|, |current|, |current_date|,
4201 |current_time|, |current_timestamp|, |database|, |default|, |deferrable|,
4202 |deferred|, |delete|, |desc|, |detach|, |distinct|, |do|, |drop|, |each|,
4203 |else|, |end|, |escape|, |except|, |exclude|, |exclusive|, |exists|,
4204 |explain|, |fail|, |filter|, |first|, |following|, |for|, |foreign|, |from|,
4205 |full|, |generated|, |glob|, |group|, |groups|, |having|, |if|, |ignore|,
4206 |immediate|, |in|, |index|, |indexed|, |initially|, |inner|, |insert|,
4207 |instead|, |intersect|, |into|, |is|, |isnull|, |join|, |key|, |last|,
4208 |left|, |like|, |limit|, |match|, |materialized|, |natural|, |no|, |not|,
4209 |nothing|, |notnull|, |null|, |nulls|, |of|, |offset|, |on|, |or|, |order|,
4210 |others|, |outer|, |over|, |partition|, |plan|, |pragma|, |preceding|,
4211 |primary|, |query|, |raise|, |range|, |recursive|, |references|, |regexp|,
4212 |reindex|, |release|, |rename|, |replace|, |restrict|, |returning|, |right|,
4213 |rollback|, |row|, |rows|, |savepoint|, |select|, |set|, |table|, |temp|,
4214 |temporary|, |then|, |ties|, |to|, |transaction|, |trigger|, |unbounded|,
4215 |union|, |unique|, |update|, |using|, |vacuum|, |values|, |view|, |virtual|,
4216 |when|, |where|, |window|, |with|, |without| \\
4217 \bottomrule
4218 \end{tabularx}
4219 \end{center}
4220
4221
4222 \bigskip
4223 It's possible to automatically capitalize the keywords by modifying locally
4224 for the language SQL the style |Keywords|.
4225 \begin{Verbatim}
4226 \SetPitonStyle~emphase#[SQL]@{Keywords = \bfseries \MakeUppercase}
4227 \end{Verbatim}
4228
4229 \newpage
4230 \subsection{The languages defined by \texttt{\textbackslash NewPitonLanguage}}
4231
4232 \vspace{1cm}
4233 The command |\NewPitonLanguage|, which defines new computer languages with the
4234 syntax of the extension \pkg{listings}, has been described p.~\pageref{NewPitonLanguage}.
4235
4236 All the languages defined by the command |\NewPitonLanguage| use the same styles.
4237 \vspace{1cm}
4238
4239 \begin{center}
4240 \begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
4241 \toprule
4242 \normalfont Style & Use \\
4243 \midrule
4244 Number & the numbers \\
4245 String.Long & the strings defined in |\NewPitonLanguage| by the key |morestring| \\
4246 Comment & the comments defined in |\NewPitonLanguage| by the key |morecomment| \\
4247 Comment.LaTeX & the comments which are composed by \pkg{piton} as LaTeX code (merely named ``LaTeX comments'' in this document) \\
4248 Keyword & the keywords defined in |\NewPitonLanguage| by the keys |morekeywords|
4249 and |moretexcs| (and also the key |sensitive| which specifies whether
4250 the keywords are case-sensitive or not) \\
4251 Directive & the directives defined in |\NewPitonLanguage| by the key
4252 |moredirectives| \\
4253 Tag & the ``tags'' defined by the key |tag| (the lexical units detected within
4254 the tag will also be formatted with their own style) \\
4255 Identifier & the identifiers. \\
4256 \bottomrule
4257 \end{tabularx}
4258 \end{center}
4259
4260
4261 \vspace{1cm}
4262 Here is for example a definition for the language HTML, obtained with a slight
4263 adaptation of the definition done by \pkg{listings} (file |lstlang1.sty|).
4264
4265 \medskip
4266 \begin{small}
4267 \begin{Verbatim}
4268 \NewPitonLanguage{HTML}%
4269 {morekeywords={A,ABBR,ACRONYM,ADDRESS,APPLET,AREA,B,BASE,BASEFONT,%
4270 BDO,BIG,BLOCKQUOTE,BODY,BR,BUTTON,CAPTION,CENTER,CITE,CODE,COL,%
4271 COLGROUP,DD,DEL,DFN,DIR,DIV,DL,DOCTYPE,DT,EM,FIELDSET,FONT,FORM,%
4272 FRAME,FRAMESET,HEAD,HR,H1,H2,H3,H4,H5,H6,HTML,I,IFRAME,IMG,INPUT,%
4273 INS,ISINDEX,KBD,LABEL,LEGEND,LH,LI,LINK,LISTING,MAP,META,MENU,%
4274 NOFRAMES,NOSCRIPT,OBJECT,OPTGROUP,OPTION,P,PARAM,PLAINTEXT,PRE,%
4275 OL,Q,S,SAMP,SCRIPT,SELECT,SMALL,SPAN,STRIKE,STRING,STRONG,STYLE,%
4276 SUB,SUP,TABLE,TBODY,TD,TEXTAREA,TFOOT,TH,THEAD,TITLE,TR,TT,U,UL,%
4277 VAR,XMP,%
4278 accesskey,action,align,alink,alt,archive,axis,background,bgcolor,%
4279 border,cellpadding,cellspacing,charset,checked,cite,class,classid,%
4280 code,codebase,codetype,color,cols,colspan,content,coords,data,%
4281 datetime,defer,disabled,dir,event,error,for,frameborder,headers,%
4282 height,href,hreflang,hspace,http-equiv,id,ismap,label,lang,link,%
4283 longdesc,marginwidth,marginheight,maxlength,media,method,multiple,%
4284 name,nohref,noresize,noshade,nowrap,onblur,onchange,onclick,%
4285 ondblclick,onfocus,onkeydown,onkeypress,onkeyup,onload,onmousedown,%
4286 profile,readonly,onmousemove,onmouseout,onmouseover,onmouseup,%
4287 onselect,onunload,rel,rev,rows,rowspan,scheme,scope,scrolling,%
4288 selected,shape,size,src,standby,style,tabindex,text,title,type,%
4289 units,usemap,valign,value,valuetype,vlink,vspace,width,xmlns},%
4290 tag=<>,%
4291 alsoletter = - ,%
4292 sensitive=f,%
4293 morestring=[d]",
4294 }
4295 \end{Verbatim}
4296 \end{small}
4297
4298
4299
4300 \subsection{The language ``minimal''}
4301
4302 \label{minimal}
4303
4304 It's possible to switch to the language ``|minimal|'' with the key |language|:
4305 |language = minimal|.
4306
4307 \bigskip
4308
4309 \begin{center}
4310 \begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
4311 \toprule
4312 \normalfont Style & Usage \\
4313 \midrule
4314 Number & the numbers \\
4315 String & the strings (between \texttt{"}) \\
4316 Comment & the comments (which begin with |#|) \\
4317 Comment.LaTeX & the comments beginning with \texttt{\#>}, which are composed by
4318 \pkg{piton} as LaTeX code (merely named ``LaTeX comments'' in this document)
4319 \\
4320 Identifier & the identifiers. \\
4321 \bottomrule
4322 \end{tabularx}
4323 \end{center}
4324
4325 \bigskip
4326 That language is provided for the end user who might wish to add keywords in
4327 that language (with the command |\SetPitonIdentifier|: cf. \ref{SetPitonIdentifier},
4328 p.~\pageref{SetPitonIdentifier}) in order to create, for example, a language
4329 for pseudo-code.
4330
4331 \vspace{1cm}
4332
4333 \subsection{The language ``verbatim''}
4334
4335 \label{verbatim}
4336
4337 It's possible to switch to the language ``|verbatim|'' with the key |language|:
4338 |language = verbatim|.
4339
4340 \bigskip
4341
4342 \begin{center}
4343 \begin{tabularx}{0.9\textwidth}{@{}>{\ttfamily}l>{\raggedright\arraybackslash}X@{}}
4344 \toprule
4345 \normalfont Style & Usage \\
4346 \midrule
4347 None... & \\
4348 \bottomrule
4349 \end{tabularx}
4350 \end{center}
4351
4352 The language |verbatim| doesn't provide any style and, thus, does not do any
4353 syntactic formating. However, it's possible to use the mechanism
4354 |detected-commands| (cf. part~\ref{detected-commands},
4355 p.~\pageref{detected-commands}) and the detection of the commands and
4356 environments of Beamer.
4357
4358
4359
4360 \vspace{1cm}
4361 \section{History}
4362
4363
4364 The development of the extension \pkg{piton} is done on the following GitHub
4365 repository:
4366
4367 \verb|https://github.com/fpantigny/piton|
4368
4369 \medskip
4370 The successive versions of the file |piton.sty| provided by TeX Live are also available
4371 on the \textsc{svn} server of TeX Live:
4372
4373 \nobreak
4374 \smallskip
4375 {
4376 \small
4377 \nolinkurl{https://tug.org/svn/texlive/trunk/Master/texmf-dist/tex/lualatex/piton/piton.sty}
4378 }
4379
4380 \subsection*{Changes between versions 4.12 and 4.13}
4381
4382 New key |line-numbers/lmmono10-drawn|.
4383
4384 \subsection*{Changes between versions 4.11 and 4.12}
4385
4386 The documentation has been changed in order to be compatible with the version
4387 0.7.0 of \pkg{pyluatex}.
4388
4389 New key ``|font-command +|''.
4390
4391 \subsection*{Changes between versions 4.10 and 4.11}
4392
4393 New keys |right-margin| and |line-numbers/position|.
4394
4395
4396 \subsection*{Changes between versions 4.9 and 4.10}
4397
4398 New key |line-numbers/step|.
4399
4400 \subsection*{Changes between versions 4.8 and 4.9}
4401
4402 New keys |paperclip| and |annotations|.
4403
4404 The package \pkg{piton} is now provided with three TeX files: |piton-code.dtx| (for the
4405 code), |piton.tex| (the documentation in English) and |piton-french.tex| (the
4406 documentation in French).
4407
4408 \subsection*{Changes between versions 4.7 and 4.8}
4409
4410 New key |\rowcolor|
4411
4412 The command |\label| redefined by \pkg{piton} is now compatible with \pkg{hyperref}
4413 (thanks to P. Le Scornet).
4414
4415 New key |label-as-zlabel|.
4416
4417 \subsection*{Changes between versions 4.6 and 4.7}
4418
4419 New key |rounded-corners|
4420
4421 \subsection*{Changes between versions 4.5 and 4.6}
4422
4423 New keys |tcolorbox|, |box|, |max-width| and |vertical-detected-commands|
4424
4425 New special color: |none|
4426
4427 \subsection*{Changes between versions 4.4 and 4.5}
4428
4429 New key |print|
4430
4431 |\RenewPitonEnvironment|,
4432 |\DeclarePitonEnvironment| and |\ProvidePitonEnvironment| have been added.
4433
4434 \subsection*{Changes between versions 4.3 and 4.4}
4435
4436 New key |join| which generates files embedded in the \textsc{pdf} as \emph{joined files}.
4437
4438 \subsection*{Changes between versions 4.2 and 4.3}
4439
4440 New key |raw-detected-commands|
4441
4442 The key |old-PitonInputFile| has been deleted.
4443
4444 \subsection*{Changes between versions 4.1 and 4.2}
4445
4446 New key |break-numbers-anywhere|.
4447
4448 \subsection*{Changes between versions 4.0 and 4.1}
4449
4450 New language |verbatim|.
4451
4452 New key |break-strings-anywhere|.
4453
4454 \subsection*{Changes between versions 3.1 and 4.0}
4455
4456 The syntax for the relative and absolute paths in |\PitonInputFile| and the key
4457 |path| has been changed to be conform to usual conventions.
4458
4459
4460 New keys |font-command|, |splittable-on-empty-lines| and |env-used-by-split|.
4461
4462
4463 \subsection*{Changes between versions 3.0 and 3.1}
4464
4465 Keys |line-numbers/format|, |detected-beamer-commands| and
4466 |detected-beamer-environments|.
4467
4468
4469 \subsection*{Changes between versions 2.8 and 3.0}
4470
4471 New command |\NewPitonLanguage|. Thanks to that command, it's now possible to
4472 define new computer languages with the syntax used by \pkg{listings}.
4473 Therefore, it's possible to say that virtually all the computer languages
4474 are now supported by \pkg{piton}.
4475
4476 \subsection*{Changes between versions 2.7 and 2.8}
4477
4478 The key |path| now accepts a \emph{list} of paths where the files to include
4479 will be searched.
4480
4481 New commands |\PitonInputFileT|, |\PitonInputFileF| and |\PitonInputFileTF|.
4482
4483 \subsection*{Changes between versions 2.6 and 2.7}
4484
4485 New keys |split-on-empty-lines| and |split-separation|
4486
4487 \subsection*{Changes between versions 2.5 and 2.6}
4488
4489 API: |piton.last_code| and |\g_piton_last_code_tl| are provided.
4490
4491 \subsection*{Changes between versions 2.4 and 2.5}
4492
4493 New key |path-write|
4494
4495 \subsection*{Changes between versions 2.3 and 2.4}
4496
4497 The key |identifiers| of the command |\PitonOptions| is now deprecated and
4498 replaced by the new command |\SetPitonIdentifier|.
4499
4500 A new special language called ``minimal'' has been added.
4501
4502 New key |detected-commands|.
4503
4504 \subsection*{Changes between versions 2.2 and 2.3}
4505
4506 New key |detected-commands|
4507
4508 The variable |\l_piton_language_str| is now public.
4509
4510
4511 New key |write|.
4512
4513 \subsection*{Changes between versions 2.1 and 2.2}
4514
4515 New key |path| for |\PitonOptions|.
4516
4517 New language SQL.
4518
4519 It's now possible to define styles locally to a given language.
4520
4521 \subsection*{Changes between versions 2.0 and 2.1}
4522
4523 The key |line-numbers| has now subkeys |line-numbers/skip-empty-lines|,
4524 |line-numbers/label-empty-lines|, etc.
4525
4526 The key |all-line-numbers| is deprecated: use
4527 |line-numbers/skip-empty-lines=false|.
4528
4529 New system to import, with |\PitonInputFile|, only a part (of the file)
4530 delimited by textual markers.
4531
4532 New keys |begin-escape|, |end-escape|, |begin-escape-math| and |end-escape-math|.
4533
4534 The key |escape-inside| is deprecated: use |begin-escape| and |end-escape|.
4535
4536
4537
4538
4539
4540 \section*{Other documentation}
4541
4542 The document |piton-french.pdf| (provided by the extension \pkg{piton}) contains a French
4543 translation of the current documentation. The file |piton-code.pdf| describes the
4544 implementation of the package \pkg{piton} (both L3 and Lua parts).
4545
4546
4547 \section*{Acknowledgments}
4548
4549 Acknowledgments to Yann Salmon and Pierre Le Scornet for their numerous suggestions
4550 of improvments.
4551
4552
4553
4554
4555 \cleardoublepage
4556
4557 \phantomsection
4558 \addcontentsline{toc}{section}{Index}
4559
4560 \printindex
4561
4562
4563 \tableofcontents
4564
4565 \end{document}
4566
4567 % Local Variables:
4568 % fill-column: 80
4569 % End:
4570
4571
4572