| 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} |