summaryrefslogtreecommitdiff
path: root/macros/luatex/latex/piton/piton-french.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/latex/piton/piton-french.tex')
-rw-r--r--macros/luatex/latex/piton/piton-french.tex107
1 files changed, 60 insertions, 47 deletions
diff --git a/macros/luatex/latex/piton/piton-french.tex b/macros/luatex/latex/piton/piton-french.tex
index cd1c2745af..940903dc77 100644
--- a/macros/luatex/latex/piton/piton-french.tex
+++ b/macros/luatex/latex/piton/piton-french.tex
@@ -345,21 +345,21 @@ Ces $n$ caractères ne sont pas nécessairement des espaces.
du nombre d'espaces successifs débutant chaque ligne (non vide) de l'environnement |{Piton}| et applique |gobble|
avec cette valeur de~$n$.
-\item \index{env-gobble}\index{gobble!env-gobble}
-Quand la clé \Definition{env-gobble} est activée, \pkg{piton} analyse la dernière ligne de l'environnement,
-c'est-à-dire celle qui contient le |\end{Piton}| et détermine si cette ligne ne comporte que des espaces suivis par
-|\end{Piton}|. Si c'est le cas, \pkg{piton} calcule le nombre $n$ de ces espaces et applique |gobble| avec cette
-valeur de~$n$. Le nom de cette clé vient de \emph{environment gobble}: le nombre d'espaces à retirer ne dépend que
-de la position des délimiteurs |\begin{Piton}| et |\end{Piton}| de l'environnement.
+\item \index{env-gobble}\index{gobble!env-gobble} Quand la clé \Definition{env-gobble} est activée, \pkg{piton}
+analyse la dernière ligne de l'environnement, c'est-à-dire celle qui contient le |\end{Piton}| et détermine si
+cette ligne ne comporte que des espaces suivis par |\end{Piton}|. Si c'est le cas, \pkg{piton} calcule le nombre
+$n$ de ces espaces et applique |gobble| avec cette valeur de~$n$. Le nom de cette clé vient de \emph{environment
+ gobble}: le nombre d'espaces à retirer ne dépend que de la position des délimiteurs |\begin{Piton}| et
+|\end{Piton}| de l'environnement.
\item \index{write} La clé \Definition{write} prend en argument un nom de fichier (avec l'extension) et écrit le
contenu\footnote{En fait, il ne s'agit pas exactement du contenu de l'environnement mais de la valeur renvoyée par
l'instruction Lua
- |piton.get_last_code()| qui en est une version dans les surcharges de formatage LaTeX (voir la partie \ref{API}, p.~\pageref{API}).} de l'environnement courant dans ce fichier. À la première utilisation du fichier par \pkg{piton}, celui-ci
+ |piton.get_last_code()| qui en est une version sans les surcharges de formatage LaTeX (voir la partie \ref{API}, p.~\pageref{API}).} de l'environnement courant dans ce fichier. À la première utilisation du fichier par \pkg{piton}, celui-ci
est effacé.
-\item \index{path-write} \colorbox{yellow!50}{\bfseries Nouveau 2.5}\enskip La clé \Definition{path-write} indique
-un chemin où seront écrits les fichiers écrits par l'emploi de la clé |write| précédente.
+\item \index{path-write} La clé \Definition{path-write} indique un chemin où seront écrits les fichiers écrits par
+l'emploi de la clé |write| précédente.
\item \index{line-numbers} La clé \Definition{line-numbers} active la numérotation des lignes (en débordement à
gauche) dans les environnements |{Piton}| et dans les listings produits par la commande |\PitonInputFile|.
@@ -368,28 +368,31 @@ Cette clé propose en fait plusieurs sous-clés.
\begin{itemize}
\item La clé \Definition{line-numbers/skip-empty-lines} demande que les lignes vides (qui ne contiennent que des
espaces) soient considérées comme non existantes en ce qui concerne la numérotation des lignes (si la clé
-|/absolute| est active, la clé |/skip-empty-lines| n'a pas d'effet dans |\PitonInputFile|). La valeur initiale de
-cette clé est |true| (et non |false|).\footnote{Avec le langage Python, les lignes vides des \emph{docstrings} sont
+|/absolute|, décrite plus bas, est active, la clé |/skip-empty-lines| n'a pas d'effet dans |\PitonInputFile|). La
+valeur initiale de cette clé est |true| (et non |false|).\footnote{Avec le langage Python, les lignes vides des \emph{docstrings} sont
prises en compte.}
-\item La clé \Definition{line/numbers/label-empty-lines} demande que les labels (c'est-à-dire les numéros) des lignes vides
-soient affichés. Si la clé |/skip-empty-lines| est active, la clé |/label-empty-lines| est sans effet. La
-valeur initiale de cette clé est |true|.
+\item La clé \Definition{line-numbers/label-empty-lines} demande que les labels (c'est-à-dire les numéros) des
+lignes vides soient affichés. Si la clé |/skip-empty-lines| est active, la clé |/label-empty-lines| est sans effet.
+La valeur initiale de cette clé est |true|.\footnote{Quand la clé |split-on-empty-lines| est activée, les labels des
+ lignes vides ne sont jamais imprimés.}
-\item La clé \Definition{line-numbers/absolute} demande, pour les listings générés par |\PitonInputFile|, que les numéros de
-lignes affichés soient absolus (c'est-à-dire ceux du fichier d'origine). Elle n'a d'intérêt que si on n'insère qu'une
-partie du fichier (cf. part~\ref{part-of-a-file}, p.~\pageref{part-of-a-file}). La clé |/absolute| est sans effet dans les environnements |{Piton}|.
+\item La clé \Definition{line-numbers/absolute} demande, pour les listings générés par |\PitonInputFile|, que les
+numéros de lignes affichés soient absolus (c'est-à-dire ceux du fichier d'origine). Elle n'a d'intérêt que si on
+n'insère qu'une partie du fichier (cf. partie~\ref{part-of-a-file}, p.~\pageref{part-of-a-file}). La clé
+|/absolute| est sans effet dans les environnements |{Piton}|.
-\item La clé \Definition{line-numbers/resume} reprend la numérotation là où elle avait été laissée au dernier listing. En fait,
-la clé |line-numbers/resume| a un alias, qui est |resume| tout court.
+\item La clé \Definition{line-numbers/resume} reprend la numérotation là où elle avait été laissée au dernier
+listing. En fait, la clé |line-numbers/resume| a un alias, qui est |resume| tout court (car on peut être amené à
+l'utiliser souvent).
\item La clé \Definition{line-numbers/start} impose que la numérotation commence à ce numéro.
-\item La clé \Definition{line-numbers/sep} est la distance horizontale entre les numéros de lignes (insérés par |line-numbers|)
-et les lignes du code informatique. La valeur initiale est 0.7~em.
+\item La clé \Definition{line-numbers/sep} est la distance horizontale entre les numéros de lignes (insérés par
+|line-numbers|) et les lignes du code informatique. La valeur initiale est 0.7~em.
\end{itemize}
-Pour la commmodité, un dispositif de factorisation du préfixe |line-numbers| est disponible, c'est-à-dire que l'on
+Pour la commodité, un dispositif de factorisation du préfixe |line-numbers| est disponible, c'est-à-dire que l'on
peut écrire :
\begin{Verbatim}
@@ -739,45 +742,55 @@ def carré(x):
\subsubsection{Coupure des pages}
\index{splittable}
+\index{split-on-empty-lines}
+\index{split-separation}
Par défaut les listings produits par l'environnement |{Piton}| et par la commande |\PitonInputFile| sont
insécables.
-Néanmoins, la commande |\PitonOptions| propose la clé \Definition{splittable} pour autoriser de telles coupures.
+
+Néanmoins, la commande |\PitonOptions| propose les clés |split-on-empty-lines| et |splittable| pour autoriser de
+telles coupures.
\begin{itemize}
-\item Si la clé |splittable| est utilisée sans valeur, les listings sont sécables n'importe où.
+\item \colorbox{yellow!50}{\textbf{Nouveau 2.7}}\par\nobreak
+
+La clé \Definition{split-on-empty-lines} autorise les coupures sur les lignes vides\footnote{Les lignes considérées
+ comme vides sont celles qui ne comportent que des espaces.} du listing. Dans les listings informatiques, les
+lignes vides séparent le plus souvent les définitions des fonctions informatiques et il est donc souvent judicieux
+de pouvoir couper au niveau de ces lignes.
+
+Quand la clé |split-on-empty-lines| est activée, le travail effectué va en fait un plus loin : les lignes vides
+successives sont supprimées et remplacées par le contenu du paramètre correspondant à la clé
+\Definition{split-separation}.
+
+La valeur initiale de ce paramètre est |\vspace{\baselineskip}\vspace{-1.25pt}|, ce qui, au final, correspond à une
+ligne vide dans le PDF final (cet espace vertical est supprimé s'il tombe au niveau d'un saut de page).
+
+\medskip
+\item La clé |split-on-empty-lines| peut bien sûr être insuffisante et c'est pourquoi \pkg{piton} propose la clé
+\Definition{splittable}.
+
+Quand la clé |splittable| est utilisée avec la valeur numérique $n$ (qui doit être un entier naturel non nul) le
+listing, ou bien chaque partie de ce listing située entre des lignes vides (quand |split-on-empty-lines| est
+utilisée), pourra être coupé n'importe où avec cette exception qu'aucune coupure ne pourra avoir lieu entre les
+$n$~premières lignes, ni entre les $n$~dernières. Par exemple, |splittable = 4| pourrait être un réglage raisonnable.
+
+Employée sans argument, la clé |splittable| est équivalente à |splittable = 1|, et les listings sont alors sécables
+n'importe où (ce n'est pas recommandable).
-\item Si la clé |splittable| est utilisée avec une valeur numérique $n$ (qui doit être un entier naturel non nul),
-alors les listings seront sécables mais aucune coupure ne pourra avoir lieu entre les $n$~premières lignes, ni
-entre les $n$~dernières. De ce fait, |splittable=1| est équivalent à |splittable|.
\end{itemize}
\medskip
\emph{Remarque}\par\nobreak
Même avec une couleur de fond (fixée avec |background-color|), les sauts de page sont possibles, à partir du moment
-où la clé |splittable| est utilisée.\footnote{Avec la clé |splittable|, un environnement |{Piton}| est sécable même dans un environnement de
- \pkg{tcolorbox} (à partir du moment où la clé |breakable| de \pkg{tcolorbox} est utilisée). On précise cela parce
- que, en revanche, un environnement de \pkg{tcolorbox} inclus dans un autre environnement de \pkg{tcolorbox} n'est
- pas sécable, même quand les deux utilisent la clé |breakable|.}
-
-
-\bigskip
-\index{split-on-empty-lines}
-\index{split-separation}
-\colorbox{yellow!50}{\textbf{Nouveau 2.7}}\enskip L'extension \pkg{piton} fournit une option
-\Definition{split-on-empty-lines}. Quand cette clé est active, les listings sont découpés en morceaux au niveau des
-lignes vides\footnote{Les lignes considérées comme vides sont celles qui ne comportent que des espaces.} du code et
-chaque morceau est traité par \pkg{piton} comme un listing autonome avant d'être envoyé à
-LaTeX. \textbf{De ce fait, LaTeX peut faire des sauts de page entre les morceaux}. Si la clé |splittable| est
-utilisée, elle reste active dans chaque morceau. Évidemment, l'utilisation conjointe de |split-on-empty-lines| et
-|splittable| n'a d'intérêt que si |splittable| est utilisée avec une valeur différente de $1$ (par example $4$), de
-manière à privilégier les coupures de pages au niveau des lignes vides du listing d'origine.
+où |split-on-empty-lines| ou |splittable| est utilisée.\footnote{Avec la clé |splittable|, un environnement
+ |{Piton}| est sécable même dans un environnement de \pkg{tcolorbox} (à partir du moment où la clé |breakable| de
+ \pkg{tcolorbox} est utilisée). On précise cela parce que, en revanche, un environnement de \pkg{tcolorbox} inclus
+ dans un autre environnement de \pkg{tcolorbox} n'est pas sécable, même quand les deux utilisent la clé
+ |breakable|.}
-\smallskip
-La clé \Definition{split-separation} permet de spécifier une liste de tokens LaTeX qui sera insérée entre les
-morceaux. Exemple : |\PitonOptions{split-speration = \hrule\goodbreak}|
\subsubsection{Coupure des lignes}