Debian Codegraph @

texmf-dist/doc/generic/simplekv/simplekv-fr.tex

raw
1 % !TeX TS-program = lualatex
2 % !TeX encoding = UTF-8
3 % Ceci est la documentation du package "simplekv"
4 \documentclass[french,a4paper,10pt]{article}
5 \usepackage[utf8]{inputenc}
6 \usepackage[margin=2cm]{geometry}
7 \usepackage[bottom]{footmisc}
8 \usepackage{libertine,boites,tikz,enumitem,babel,xspace,listings,simplekv,hyperref}
9 \usepackage[scaled=0.8]{GoMono}
10 \frenchbsetup{og=«,fg=»}
11 \def\eTeX{\hbox{$\varepsilon$-\TeX}}
12 \def\SKV{\texttt{\skvname}\xspace}
13 \makeatletter
14 \def\code{\expandafter\code@i\string}
15 \def\code@i#1{%
16 \begingroup
17 \par\nobreak\medskip\parindent0pt
18 \leftskip.1\linewidth
19 \make@car@active\^^I{\leavevmode\space\space\space\space}%
20 \let\do\@makeother \dospecials
21 \ttfamily\small\@noligs
22 \make@car@active\<{\begingroup$\langle$\itshape}%
23 \make@car@active\>{\/$\rangle$\endgroup}%
24 \obeylines\obeyspaces
25 \def\code@ii##1#1{##1\par\medbreak\endgroup}%
26 \code@ii
27 }
28 \long\def\grab@toks#1\relax{\gdef\right@content{#1}}
29
30 \newcommand\disable@lig[1]{%
31 \catcode`#1\active
32 \begingroup
33 \lccode`\~`#1\relax
34 \lowercase{\endgroup\def~{\leavevmode\kern\z@\string#1}}%
35 }
36
37 \newcommand\make@car@active[1]{%
38 \catcode`#1\active
39 \begingroup
40 \lccode`\~`#1\relax
41 \lowercase{\endgroup\def~}%
42 }
43
44 \newcommand\exemple{%
45 \begingroup
46 \parskip\z@
47 \exemple@}
48
49 \newcommand\exemple@{%
50 \medbreak\noindent
51 \begingroup
52 \let\do\@makeother\dospecials
53 \make@car@active\ { {}}%
54 \make@car@active\^^M{\par\leavevmode}%
55 \make@car@active\^^I{\space\space}%
56 \make@car@active\,{\leavevmode\kern\z@\string,}%
57 \make@car@active\-{\leavevmode\kern\z@\string-}%
58 \make@car@active\>{\leavevmode\kern\z@\string>}%
59 \make@car@active\<{\leavevmode\kern\z@\string<}%
60 \@makeother\;\@makeother\!\@makeother\?\@makeother\:% neutralise frenchb
61 \exemple@@
62 }
63
64 \newcommand\exemple@@[1]{%
65 \def\@tempa##1#1{\exemple@@@{##1}}%
66 \@tempa
67 }
68
69 \newcommand\exemple@@@[1]{%
70 \xdef\the@code{#1}%
71 \endgroup
72 \begingroup
73 \fboxrule0.4pt \fboxsep=5pt
74 \let\breakboxparindent\z@
75 \def\bkvz@top{\hrule\@height\fboxrule}%
76 \def\bkvz@bottom{\hrule\@height\fboxrule}%
77 \let\bkvz@before@breakbox\relax
78 \def\bkvz@set@linewidth{\advance\linewidth\dimexpr-2\fboxrule-2\fboxsep\relax}%
79 \def\bkvz@left{\vrule\@width\fboxrule\kern\fboxsep}%
80 \def\bkvz@right{\kern\fboxsep\vrule\@width\fboxrule}%
81 \breakbox
82 \kern.5ex\relax
83 \begingroup
84 \ttfamily\small\the@code\par
85 \endgroup
86 \kern3pt
87 \hrule height0.1pt width\linewidth depth0.1pt
88 \vskip5pt
89 \newlinechar`\^^M\everyeof{\noexpand}\scantokens{#1}\par
90 \endbreakbox
91 \endgroup
92 \medbreak
93 \endgroup
94 }
95 \begingroup
96 \catcode`\<13 \catcode`\>13
97 \gdef\verb{\relax\ifmmode\hbox\else\leavevmode\null\fi
98 \bgroup
99 \verb@eol@error \let\do\@makeother \dospecials
100 \verbatim@font\@noligs
101 \catcode`\<13 \catcode`\>13 \def<{\begingroup$\langle$\itshape}\def>{\/$\rangle$\endgroup}%
102 \@ifstar\@sverb\@verb}
103 \endgroup
104 \def\longfrhlstdate@i#1/#2/#3\@nil{\number#3\relax\space \ifcase#2 \or janvier\or février\or mars\or avril\or mai\or juin\or juillet\or aout\or septembre\or octobre\or novembre\or décembre\fi\space#1}
105 \edef\longfrhlstdate{\expandafter\longfrhlstdate@i\skvdate\@nil}
106 \def\<#1>{$\langle$\textit{#1}$\rangle$}
107 \makeatother
108
109 \begin{document}
110 \parindent=0pt
111 \thispagestyle{empty}
112 \begin{titlepage}
113 \begingroup
114 \centering
115 \null\vskip.25\vsize
116 {\large\bfseries L'extension pour \TeX/\LaTeX\par \Huge \skvname\par}
117 \bigbreak
118 v \skvver
119 \smallbreak
120 \longfrhlstdate
121 \vskip1.5cm
122 Christian \bsc{Tellechea}\par
123 \texttt{[email protected]}\par
124 \endgroup
125 \vskip2cm
126 \leftskip=.2\linewidth \rightskip=.2\linewidth \small
127 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.
128 \end{titlepage}
129
130 Cette petite extension se veut minimaliste. Trop sans doute puisqu'on ne la juge pas au niveau d'autres, jugées plus « \href{https://tex.stackexchange.com/questions/560014/}{sérieuses}.»
131
132 Quoiqu'il en soit, simplekv a le mérite d'exister et se place à l'opposé des usines à gaz que l'on peut trouver dans cet exercice de style. Elle est écrite en \TeX{}, fonctionne donc sous tous les moteurs et ne requiert aucun package.
133
134 \section{Clés, valeurs}
135 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>.
136 \medskip
137 Voici brièvement les définitions et les limitations des structures mises à disposition :
138
139 \begin{itemize}
140 \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;
141 \item la syntaxe pour assigner une \<valeur> à une \<clé> est : \hbox{\<clé>=\<valeur>};
142 \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>;
143 \item une \<valeur> est un \<code> arbitraire;
144 \item si une \<valeur> est entourée d'accolades, ces dernières seront retirées : \verb|<clé>=<valeur>| est donc équivalent à \verb|<clé>={<valeur>}|;
145 \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>}|;
146 \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;
147 \item une virgule ne peut figurer dans une \<valeur> que si la virgule est entre 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|;
148 \item les \<valeurs> sont stockées \emph{telles qu'elles sont lues} ; en particulier, aucun développement n'est effectué;
149 \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;
150 \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>.
151 \end{itemize}
152
153 \section{Commandes mises à disposition}
154 \paragraph{Les macros \texttt{\char`\\setKV} et \texttt{\char`\\setKVdefault}}
155 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|.
156
157 On écrit
158 \code|\setKV[<trousseau>]{<clé 1>=<valeur 1>,<clé 2>=<valeur 2>,...,<clé n>=<valeur n>}|
159
160 Il faut noter que
161 \begin{itemize}
162 \item pour parvenir à leurs fins, ces macros peuvent être utilisées une ou plusieurs fois, avec un nombre de couples \<clé>/\<valeur> quelconque;
163 \item un ensemble \<clé>=\<valeur> réduit à 0 caractère après suppression des espaces est ignoré;
164 \item lors de la lecture des \<clés>/\<valeurs>, la virgule et le signe égal doivent avoir un catcode de 12 sans quoi ils ne seront pas compris comme frontières entre \<clés> et \<valeurs> et ne joueront pas leur rôle;
165 \item le nom du \<trousseau>, bien qu'entre crochets, est \emph{obligatoire} , il peut éventuellement être vide bien que cela ne soit pas conseillé;
166 \item les espaces autour du nom du \<trousseau> ne sont \emph{pas} retirés et donc le trousseau «\verb|foo|» n'est pas le même que le trousseau «\verb*|foo |»
167 \item si une même \<clé> est définie plusieurs fois, la \<valeur> retenue sera celle de la dernière assignation;
168 \item les \<valeurs> peuvent être booléennes auquel cas, elles \emph{doivent} être «\texttt{true}» ou «\texttt{false}» en caractères de catcode 11;
169 \item si une \<valeur> est omise, elle est comprise comme étant «\texttt{true}». Ainsi, écrire
170 \code|\setKV[foo]{mon bool}|
171 est équivalent à
172 \code|\setKV[foo]{mon bool = true}|
173 \end{itemize}
174
175 \paragraph{La macro \texttt{\char`\\useKV}}
176 Cette macro purement développable renvoie la \<valeur> préalablement associée à une \<clé> dans un \<trousseau>:
177 \code|\useKV[<trousseau>]{<clé>}|
178
179 Il faut noter que
180 \begin{itemize}
181 \item si la \<clé> n'a pas été définie, une erreur sera émise;
182 \item si la \<clé> est booléenne, le texte «\texttt{true}» ou «\texttt{false}» sera renvoyé;
183 \item il faut 2 développements à \verb|\useKV[<trousseau>]{<clé>}| pour donner la \<valeur> associée à la \<clé>.
184 \end{itemize}
185
186 \exemple|\setKV[foo]{nombre = 5 , lettres= AB \textit{CD} , mon bool}
187 a) \useKV[foo]{nombre}.\qquad b) \useKV[foo]{lettres}.\qquad c) \useKV[foo]{mon bool}.
188
189 \setKV[foo]{lettres = X Y Z \textbf{123} }
190 a) \useKV[foo]{nombre}.\qquad b) \useKV[foo]{lettres}.\qquad c) \useKV[foo]{mon bool}.|
191
192 \paragraph{La macro \texttt{\char`\\restoreKV}}
193 La macro \verb|\restoreKV[<trousseau>]| réinitialise toutes les \<clés> du \<trousseau> aux \<valeurs> qui ont été définies lors des précédentes exécutions de \verb|\setKVdefault|. La macro \verb|\useKVdefault[<trousseau>]| lui est équivalente.
194
195 \paragraph{La macro \texttt{\char`\\ifboolKV}}
196 Cette macro permet, selon la valeur d'une \<clé booléenne>, d'exécuter un des deux \<codes> donnés. La syntaxe est
197 \code|\ifboolKV[<trousseau>]{<clé>}{<code si "true">}{<code si "false">}|
198
199 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.
200
201 \paragraph{La macro \texttt{\char`\\ifkeyKV}}
202 Cette macro teste si une \<clé> est définie selon la syntaxe
203 \code|\ifkeyKV[<trousseau>]{<clé>}{<code si clé définie>}{<code si clé non définie>}|
204
205 La macro est purement développable et nécessite 2 développements pour donner l'un des deux codes.
206 \paragraph{La macro \texttt{\char`\\ifemptyKV}}
207 Cette macro teste si la \<valeur> d'une \<clé> est vide selon la syntaxe
208 \code|\ifemptyKV[<trousseau>]{<clé>}{<code si valeur vide>}{<code si valeur non vide>}|
209
210 La macro est purement développable et nécessite 2 développements pour donner l'un des deux codes.
211 \paragraph{La macro \texttt{\char`\\showKV}}
212 Cette commande écrit dans le fichier \texttt{log} la \<valeur> et le \<code> assignés à une \<clé> d'un \<trousseau>:
213 \code|\showKV[<trousseau>]{<clé>}|
214
215 Si la \<clé> n'est pas définie, «\texttt{non défini}» est affiché dans le fichier log. Il en est de même pour le \<code>.
216
217 \section{Code}
218 En plus d'une \<valeur>, un \<code> arbitraire peut être assigné à n'importe quelle \<clé>. Pour ce faire, on écrit
219 \begin{center} \verb|\defKV[<trousseau>]{<clé 1>=<code 1>,<clé 2>=<code 2>,...,<clé n>=<code n>}|
220 \end{center}
221 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|.
222 \bigbreak
223
224 Ainsi déclarer
225 \code|\defKV[x]{ mykey = \def\foo{\textbf{#1}}|
226 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
227 \code|\setKV[x]{ mykey = bonjour }|
228 le code qui est exécuté en coulisses est
229 \code|\def\foo{\textbf{bonjour}}|
230
231 \exemple|\defKV[x]{ mykey = \def\foo{\textbf{#1}} }
232 \setKV[x]{ mykey = bonjour }% définition
233 1) \meaning\foo\par
234 2) \useKV[x]{ mykey }
235
236 \setKV[x]{ mykey = hello }% redéfinition
237 3) \meaning\foo\par
238 4) \useKV[x]{ mykey }|
239
240 La macro \verb|\testboolKV| permet de tester, par exemple dans un \<code>, si son argument est «true» ou «false»
241 \code|\testboolKV{<argument>}{<code si true>}{<code si false>}|
242
243 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.
244
245 \exemple|\defKV[x]{ x = \def\test{\testboolKV{#1}{test positif}{test négatif}}}
246 \setKV[x]{ x = true}
247 1) \test
248
249 \setKV[x]{ x= false}
250 2) \test|
251 Toute autre valeur que «\verb|true|» ou «\verb|false|» génèrera un message d'erreur.
252
253 \section{Un exemple d'utilisation}
254 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:
255 \begin{itemize}
256 \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;
257 \item \texttt{sep} qui est une dimension mesurant la distance entre le texte et le cadre (par défaut \texttt{3pt});
258 \item \texttt{width} qui est la largeur des traits du cadre (par défaut \texttt{0.5pt});
259 \item \texttt{style} qui contient le code exécuté avant le texte.
260 \end{itemize}
261
262 Une première façon de faire, sans recours à \verb|\defKV|;
263 \exemple|\setKVdefault[frame]{
264 sep = 3pt,
265 line width = 0.5pt,
266 style = \bfseries,
267 inline
268 }
269 \newcommand\frametxt[2][]{%
270 \restoreKV[frame]% revenir au valeurs par défaut
271 \setKV[frame]{#1}% lit les arguments optionnels
272 \fboxsep = \useKV[frame]{sep}
273 \fboxrule= \useKV[frame]{line width}
274 \ifboolKV[frame]{inline}
275 {}
276 {\begin{center}}%
277 \fbox{\useKV[frame]{style}#2}%
278 \ifboolKV[frame]{inline}
279 {}
280 {\end{center}}%
281 }
282 Un essai en ligne par défaut \frametxt{essai} puis un autre \frametxt[sep=5pt,line width=2pt]{essai}
283 et un dernier \frametxt[sep=1pt,style=\itshape]{essai}.
284
285 Un essai hors ligne : \frametxt[inline = false, style=\bfseries\color{red}]{essai centré}|
286
287 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.
288
289 \exemple|\defKV[frame]{%
290 sep = {\fboxsep = #1 },
291 line width = {\fboxrule= #1 },
292 inline = \testboolKV{#1}
293 {\def\hookpre{}\def\hookpost{}}
294 {\def\hookpre{\begin{center}}\def\hookpost{\end{center}}},
295 style = \def\fstyle{#1}
296 }
297 \setKVdefault[frame]{
298 sep = 3pt,
299 line width = 0.5pt,
300 style = \bfseries,
301 inline
302 }
303 \newcommand\frametxt[2][]{%
304 \restoreKV[frame]% revenir au valeurs par défaut
305 \setKV[frame]{#1}% lit les arguments optionnels
306 \hookpre
307 \fbox{\fstyle #2}%
308 \hookpost
309 }
310 Un essai en ligne par défaut \frametxt{essai} puis un autre \frametxt[sep=5pt,line width=2pt]{essai}
311 et un dernier \frametxt[sep=1pt,style=\itshape]{essai}.
312
313 Un essai hors ligne : \frametxt[inline = false, style=\bfseries\color{red}]{essai centré}|
314 \end{document}