summaryrefslogtreecommitdiff
path: root/macros/generic/simplekv/simplekv-fr.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/generic/simplekv/simplekv-fr.tex')
-rw-r--r--macros/generic/simplekv/simplekv-fr.tex161
1 files changed, 113 insertions, 48 deletions
diff --git a/macros/generic/simplekv/simplekv-fr.tex b/macros/generic/simplekv/simplekv-fr.tex
index c899feeb73..e23a0ae078 100644
--- a/macros/generic/simplekv/simplekv-fr.tex
+++ b/macros/generic/simplekv/simplekv-fr.tex
@@ -22,7 +22,7 @@
\let\do\@makeother \dospecials
\ttfamily\small\@noligs
\make@car@active\<{\begingroup$\langle$\itshape}%
- \make@car@active\>{$\rangle$\endgroup}%
+ \make@car@active\>{\/$\rangle$\endgroup}%
\obeylines\obeyspaces
\def\code@ii##1#1{##1\par\medbreak\endgroup}%
\code@ii
@@ -126,25 +126,23 @@
\endgroup
\vskip2cm
\leftskip=.2\linewidth \rightskip=.2\linewidth \small
- Cette petite extension est une implémentation d'un système dit à «clé/valeurs» pour \TeX{} ou \LaTeX. Aucune fioriture inutile n'a été codée, elle comporte juste l'essentiel.
+ Cette petite extension est une implémentation d'un système dit à «\<clés>/\<valeurs>» pour \TeX{} ou \LaTeX. Elle comporte juste l'essentiel, aucune fioriture inutile n'a été codée et aucune extension tierce n'est nécessaire à son fonctionnement.
\end{titlepage}
\section{Clés, valeurs}
-Lorsqu'une macro doit recevoir des paramètres dont le nombre n'est pas fixe ou connu, il est commode de procéder par \<clés> et \<valeurs>. Beaucoup d'extensions allant en ce sens existent déjà.
-
-Le but de celle-ci n'est pas de grossir le nombre déjà trop grand de ces extensions, c'est simplement un morceau de l'extension \texttt{hlist} qui a été converti en extension car ce système \<clé>/\<valeurs> est également utilisé par l'extension \texttt{scratch}.\medskip
-
+Lorsqu'une macro doit recevoir des paramètres dont le nombre n'est pas fixe ou connu, il est commode de procéder par \<clés> et \<valeurs>.
+\medskip
Voici brièvement les définitions et les limitations des structures mises à disposition :
\begin{itemize}
- \item une \<clé> est un mot désignant un paramètre; il est formé de préférence avec des caractères de code de catégorie 11 (lettres), 12 (autres caractères sauf la virgule) et 10 (l'espace). On peut cependant y mettre des caractères ayant d'autres codes de catégorie, dans la limitation de ce qui est admis dans la primitive \verb|\detokenize|;
+ \item une \<clé> est un mot désignant un paramètre; il est formé de préférence avec des caractères de code de catégorie 11 (lettres), 12 (autres caractères sauf la virgule et le signe \verb|=|) et 10 (l'espace). On peut cependant y mettre des caractères ayant d'autres codes de catégorie, dans la limitation de ce qui est admis dans la primitive \verb|\detokenize|; une \<clé>, même si cela revêt peu de signification, peut être vide;
\item la syntaxe pour assigner une \<valeur> à une \<clé> est : \hbox{\<clé>=\<valeur>};
\item les espaces qui précèdent et qui suivent la \<clé> et la \<valeur> sont ignorés, mais \emph{pas ceux} qui se trouvent à l'intérieur de la \<clé> ou de la \<valeur>;
\item une \<valeur> est un \<code> arbitraire;
\item si une \<valeur> est entourée d'accolades, ces dernières seront retirées : \verb|<clé>=<valeur>| est donc équivalent à \verb|<clé>={<valeur>}|;
+ \item lorsqu'une valeur est entourée de \emph{plusieurs} imbrications d'accolades, seul le niveau externe est retiré et donc \verb|<clé>={{<valeur>}}| est compris comme \verb|<clé>={<valeur>}|;
\item lorsque plusieurs couples de \<clés>/\<valeurs> doivent être spécifiés, ils sont séparés les uns des autres par des virgules;
\item une virgule ne peut figurer dans une \<valeur> que si la virgule est dans un niveau d'accolades; par exemple, \verb|foo=1,5| n'est pas valide car la \<valeur> s'étend jusqu'au 1. Il faudrait écrire \verb|foo={1,5}| pour spécifier une valeur de \verb|1,5|;
- \item lorsqu'une valeur est entourée de \emph{plusieurs} d'accolades, seul le niveau externe est retiré;
\item les \<valeurs> sont stockées \emph{telles qu'elles sont lues} ; en particulier, aucun développement n'est effectué;
\item les définitions sont \emph{locales} : par conséquent, toute \<clé> définie ou modifiée dans un groupe est restaurée à son état antérieur à la sortie du groupe;
\item des \<clé>/\<valeurs> destinées à une même macro ou à un même usage doivent être regroupées dans un ensemble dont on choisit le nom. Un tel ensemble est appelé \<trousseau>.
@@ -152,87 +150,154 @@ Voici brièvement les définitions et les limitations des structures mises à dispo
\section{Commandes mises à disposition}
-\paragraph{La macro \texttt{\char`\\setKVdefault}}
-Cette commande est un préalable à toute utilisation de \<clés> puisqu'elle définit un \<trousseau> contenant des \<clés> et leurs \<valeurs> par défaut.
+\paragraph{Les macro \texttt{\char`\\setKV} et \texttt{\char`\\setKVdefault}}
+Ces commandes définissent des \<clés> et leur assignent des \<valeurs> dans un \<trousseau>. La seule différence entre les deux macros est que \verb|\setKVdefault|, en plus d'assigner les \<valeurs> aux \<clés>, les sauvegarde en vue d'une restauration ultérieure avec \verb|\restoreKV|.
On écrit
-\begin{center} \verb|\setKVdefault[<trousseau>]{<clé 1>=<valeur 1>,<clé 2>=<valeur 2>,...,<clé i>=<valeur i>}|
-\end{center}
+\code|\setKV[<trousseau>]{<clé 1>=<valeur 1>,<clé 2>=<valeur 2>,...,<clé n>=<valeur n>}|
Il faut noter que
\begin{itemize}
- \item l'argument entre accolades contenant les \<clés> et les \<valeurs> ne peut pas être vide;
+ \item l'argument entre accolades contenant les \<clés> et les \<valeurs> ne devrait pas être vide, sauf à vouloir définir une \<clé> booléenne vide égale à \texttt{true};
+ \item lors de la lecture des \<clés>/\<valeurs>, la virgule et le signe égal ont leurs catcodes rendus égaux à 12;
\item le nom du \<trousseau>, bien qu'entre crochet, est \emph{obligatoire}, mais il peut être vide bien que cela ne soit pas conseillé;
- \item si plusieurs \<clés> sont identiques, seule la dernière \<valeur> sera prise en compte;
- \item les \<valeurs> peuvent être booléennes, auquel cas, elles \emph{doivent} être «\texttt{true}» ou «\texttt{false}» en caractères de catcode 11;
+ \item si une même \<clé> figure plusieurs fois, la \<valeur> retenue sera celle de la dernière assignation;
+ \item les \<valeurs> peuvent être booléennes auquel cas, elles \emph{doivent} être «\texttt{true}» ou «\texttt{false}» en caractères de catcode 11;
\item si une \<valeur> est omise, elle est comprise comme étant «\texttt{true}». Ainsi, écrire
- \code|\setKVdefault[foo]{mon bool}|
+ \code|\setKV[foo]{mon bool}|
est équivalent à
- \code|\setKVdefault[foo]{mon bool = true}|
- \item il est \emph{déconseillé} d'exécuter plusieurs fois \verb|\setKVdefault| pour le même \<trousseau>. Si cela est indispensable, il convient de redéfinir \emph{toutes} les \<clés> qui figuraient dans les précédents appels de \verb|\setKVdefault|.
+ \code|\setKV[foo]{mon bool = true}|
\end{itemize}
-\paragraph{La macro \texttt{\char`\\setKV}}
-Cette macro fonctionne selon les mêmes principes et limitations que \verb|\setKVdefault|, sauf qu'elle redéfinit une ou plusieurs \<clés> dont les \<valeurs> ont précédemment été définies par \verb|\setKVdefault|.
-
-Si une \<clé> n'a pas été prédéfinie par \verb|\setKVdefault|, une erreur sera émise.
-
\paragraph{La macro \texttt{\char`\\useKV}}
Cette macro purement développable renvoie la \<valeur> préalablement associée à une \<clé> dans un \<trousseau>:
-\code|\useKV[<trousseau>]{<clé>}|
+ \code|\useKV[<trousseau>]{<clé>}|
Il faut noter que
\begin{itemize}
- \item si la \<clé> n'a pas été prédéfinie par \verb|\setKVdefault|, une erreur sera émise;
+ \item si la \<clé> n'a pas été définie, une erreur sera émise;
\item si la \<clé> est booléenne, le texte «\texttt{true}» ou «\texttt{false}» sera renvoyé;
\item il faut 2 développements à \verb|\useKV[<trousseau>]{<clé>}| pour donner la \<valeur> associée à la \<clé>.
\end{itemize}
-\exemple|\setKVdefault[foo]{nombre = 5 , lettres= AB \textit{CD} , mon bool}
-a) \useKV[foo]{nombre}.\qquad b) \useKV[foo]{lettres}.\qquad c) \useKV[foo]{mon bool}.\par
+\exemple|\setKV[foo]{nombre = 5 , lettres= AB \textit{CD} , mon bool}
+a) \useKV[foo]{nombre}.\qquad b) \useKV[foo]{lettres}.\qquad c) \useKV[foo]{mon bool}.
+
\setKV[foo]{lettres = X Y Z \textbf{123} }
a) \useKV[foo]{nombre}.\qquad b) \useKV[foo]{lettres}.\qquad c) \useKV[foo]{mon bool}.|
-\paragraph{La macro \texttt{\char`\\useKVdefault}}
-L'exécution de cette macro par \verb|\useKVdefault[<trousseau>]| réinitialise toutes les \<clés> du \<trousseau> aux \<valeurs> qui ont été définies lors de l'exécution \verb|\setKVdefault|.
+\paragraph{La macro \texttt{\char`\\restoreKV}}
+La macro \verb|\restoreKV[<trousseau>]| réinitialise toutes les \<clés> du \<trousseau> aux \<valeurs> qui ont été définies lors de l'exécution \verb|\setKVdefault|. La macro \verb|\useKVdefault[<trousseau>]| lui est équivalente.
\paragraph{La macro \texttt{\char`\\ifboolKV}}
Cette macro permet, selon la valeur d'une \<clé booléenne>, d'exécuter un des deux \<codes> donnés. La syntaxe est
-\code|\ifboolKV[<trousseau>]{<clé>}{<code si "true">}{<code si "false>}|
+ \code|\ifboolKV[<trousseau>]{<clé>}{<code si "true">}{<code si "false>}|
La macro est purement développable, elle nécessite 2 développements pour donner l'un des deux codes, et exige que la \<clé> soit booléenne sans quoi un message d'erreur est émis.
\paragraph{La macro \texttt{\char`\\showKV}}
Cette commande écrit dans le fichier \texttt{log} la \<valeur> assignée à une \<clé> d'un \<trousseau>:
-\code|\showKV[<trousseau>]{<clé>}|
+ \code|\showKV[<trousseau>]{<clé>}|
Si la \<clé> n'est pas définie, «\texttt{not defined}» est affiché dans le fichier log.
+\section{Code}
+En plus d'une \<valeur>, un \<code> arbitraire peut être assigné à n'importe quelle \<clé>. Pour ce faire, on écrit
+\begin{center} \verb|\defKV[<trousseau>]{<clé 1>=<code 1>,<clé 2>=<code 2>,...,<clé n>=<code n>}|
+\end{center}
+Chaque \<code> peut contenir \verb|#1| qui représente la \<valeur> de la \<clé>. Ce \<code> est exécuté lorsque une \<valeur> est assignée à la \<clé> avec \verb|\setKV|, \verb|\setKVdefault| ou \verb|\restoreKV|.
+\bigbreak
+
+Ainsi déclarer
+ \code|\defKV[x]{ mykey = \def\foo{\textbf{#1}}|
+va définir une macro \verb|\foo| dès que la \<clé> «\texttt{mykey}» va être définie (ou redéfinie) et donc, si l'on écrit
+ \code|\setKV[x]{ mykey = bonjour }|
+le code qui est exécuté en coulisses est
+ \code|\long\def\foo{\textbf{bonjour}}|
+
+\exemple|\defKV[x]{ mykey = \def\foo{\textbf{#1}} }
+\setKV[x]{ mykey = bonjour }% définition
+1) \meaning\foo\par
+2) \useKV[x]{ mykey }
+
+\setKV[x]{ mykey = hello }% redéfinition
+3) \meaning\foo\par
+4) \useKV[x]{ mykey }|
+
+La macro \verb|\testboolKV| permet de tester, par exemple dans un \<code>, si son argument est «true» ou «false»
+ \code|\testboolKV{<argument>}{<code si true>}{<code si false>}|
+
+La macro est purement développable, elle nécessite 2 développements pour donner l'un des deux codes, et exige que l'\<argument> soit booléen sans quoi un message d'erreur est émis.
+
+\exemple|\defKV[x]{ x = \def\test{\testboolKV{#1}{test positif}{test négatif}}}
+\setKV[x]{ x = true}
+1) \test
+
+\setKV[x]{ x= false}
+2) \test|
+Toute autre valeur que «\verb|true|» ou «\verb|false|» génèrera un message d'erreur.
+
\section{Un exemple d'utilisation}
-Voici comment on pourrait programmer une macro qui affiche un cadre sur une ligne. Pour cela les \<clés> suivantes seront utilisées:
+Voici comment on pourrait programmer une macro qui affiche un cadre sur une ligne, grâce à la macro \verb|\fbox| et l'environnement \verb|center| de \LaTeX. Pour cela les \<clés> suivantes seront utilisées:
\begin{itemize}
\item le booléen \texttt{inline} qui affichera le cadre dans le texte s'il est vrai et sur une ligne dédié s'il est faux;
- \item \texttt{left code} et \texttt{right code} qui sont deux codes exécutés avant et après le cadre si le booléen est faux (par défaut : \verb|\hfill| et \verb|\hfill| pour un centrage sur la ligne);
\item \texttt{sep} qui est une dimension mesurant la distance entre le texte et le cadre (par défaut \texttt{3pt});
- \item \texttt{width} qui est la largeur des traits du cadre (par défaut \texttt{0.5pt}).
+ \item \texttt{width} qui est la largeur des traits du cadre (par défaut \texttt{0.5pt});
+ \item \texttt{style} qui contient le code exécuté avant le texte.
\end{itemize}
-\exemple|\setKVdefault[frame]{inline , left code = \hfill, right code = \hfill, sep = 3pt, width=0.5pt }
+Une première façon de faire, sans recours à \verb|\defKV|;
+\exemple|\setKVdefault[frame]{
+ sep = 3pt,
+ line width = 0.5pt,
+ style = \bfseries,
+ inline
+ }
+\newcommand\frametxt[2][]{%
+ \restoreKV[frame]% revenir au valeurs par défaut
+ \setKV[frame]{#1}% lit les arguments optionnels
+ \fboxsep = \useKV[frame]{sep}
+ \fboxrule= \useKV[frame]{line width}
+ \ifboolKV[frame]{inline}
+ {}
+ {\begin{center}}%
+ \fbox{\useKV[frame]{style}#2}%
+ \ifboolKV[frame]{inline}
+ {}
+ {\end{center}}%
+}
+Un essai en ligne par défaut \frametxt{essai} puis un autre \frametxt[sep=5pt,line width=2pt]{essai}
+et un dernier \frametxt[sep=1pt,style=\itshape]{essai}.
+
+Un essai hors ligne : \frametxt[inline = false, style=\bfseries\color{red}]{essai centré}|
+
+Dans l'exemple repris ci-dessous et grâce à \verb|\defKV|, on stocke tous les paramètres lors de leur assignation. Il y a bien moins de verbosité dans le code de \verb|frametxt| ce qui le rend plus léger et plus lisible.
+
+\exemple|\defKV[frame]{%
+ sep = {\fboxsep = #1 },
+ line width = {\fboxrule= #1 },
+ inline = \testboolKV{#1}
+ {\def\hookpre{}\def\hookpost{}}
+ {\def\hookpre{\begin{center}}\def\hookpost{\end{center}}},
+ style = \def\fstyle{#1}
+}
+\setKVdefault[frame]{
+ sep = 3pt,
+ line width = 0.5pt,
+ style = \bfseries,
+ inline
+ }
\newcommand\frametxt[2][]{%
+ \restoreKV[frame]% revenir au valeurs par défaut
\setKV[frame]{#1}% lit les arguments optionnels
- \ifboolKV[frame]{inline}{}{\par\noindent\useKV[frame]{left code}}%
- \fboxsep=\useKV[frame]{sep}\relax
- \fboxrule=\useKV[frame]{width}\relax
- \fbox{#2}%
- \ifboolKV[frame]{inline}{}{\useKV[frame]{right code}\null\par}%
+ \hookpre
+ \fbox{\fstyle #2}%
+ \hookpost
}
-Un essai en ligne par défaut \frametxt{essai} puis un autre \frametxt[sep=5pt,width=2pt]{essai}
-et un dernier \frametxt[sep=0.5pt]{essai}.
+Un essai en ligne par défaut \frametxt{essai} puis un autre \frametxt[sep=5pt,line width=2pt]{essai}
+et un dernier \frametxt[sep=1pt,style=\itshape]{essai}.
-\useKVdefault[frame]% revenir au valeurs par défaut
-Un essai centré \frametxt[inline = false]{essai centré}
-un autre fer à gauche \frametxt[left code={}]{essai à gauche}
-un dernier indenté \frametxt[left code=\hskip 5em, right code={}, sep=1pt, width=2pt]{essai indenté}|
+Un essai hors ligne : \frametxt[inline = false, style=\bfseries\color{red}]{essai centré}|
\section{Le code}
@@ -240,7 +305,7 @@ Le code ci-dessous est l'exact verbatim du fichier \verb|simplekv.tex| :
\lstinputlisting[
language=TeX,
- moretexcs={unless,ifcsname,ifdefined,detokenize,numexpr,dimexpr,glueexpr,unexpanded},
+ moretexcs={unless,ifcsname,ifdefined,detokenize,numexpr,dimexpr,glueexpr,unexpanded,expanded},
basicstyle=\small\ttfamily\color{black!25},
identifierstyle=\bfseries\color{white},%
backgroundcolor=\color{black!85},
@@ -264,7 +329,7 @@ Le code ci-dessous est l'exact verbatim du fichier \verb|simplekv.tex| :
numbersep=1em,
classoffset=1,
alsoletter={\_},
- morekeywords={setKVdefault,setKV,useKVdefault,useKV,ifboolKV,},
+ morekeywords={setKVdefault,setKV,useKVdefault,useKV,ifboolKV,defKV,testboolKV,showKV},
keywordstyle=\bfseries\color{red!85!black},
classoffset=0,
]{simplekv.tex}