summaryrefslogtreecommitdiff
path: root/macros/generic/simplekv/simplekv-fr.tex
blob: c899feeb7389a97e14d961074bf1b51d578df251 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
% !TeX encoding = ISO-8859-1
% Ceci est la documentation du package "hlist"
%
% Fichier compilé avec pdflatex
\documentclass[french,a4paper,10pt]{article}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[margin=2cm]{geometry}
\usepackage[bottom]{footmisc}
\usepackage{libertine,boites,tikz,enumitem,MnSymbol,babel,xspace,listings,simplekv}
\usepackage[scaled=0.8]{luximono}
\frenchbsetup{og=«,fg=»}
\def\eTeX{\hbox{$\varepsilon$-\TeX}}
\def\SKV{\texttt{\skvname}\xspace}
\makeatletter
\def\code{\expandafter\code@i\string}
\def\code@i#1{%
	\begingroup
		\par\nobreak\medskip\parindent0pt
		\leftskip.1\linewidth
		\make@car@active\^^I{\leavevmode\space\space\space\space}%
		\let\do\@makeother \dospecials
		\ttfamily\small\@noligs
		\make@car@active\<{\begingroup$\langle$\itshape}%
		\make@car@active\>{$\rangle$\endgroup}%
		\obeylines\obeyspaces
		\def\code@ii##1#1{##1\par\medbreak\endgroup}%
		\code@ii
}
\long\def\grab@toks#1\relax{\gdef\right@content{#1}}

\newcommand\disable@lig[1]{%
	\catcode`#1\active
	\begingroup
		\lccode`\~`#1\relax
		\lowercase{\endgroup\def~{\leavevmode\kern\z@\string#1}}%
}

\newcommand\make@car@active[1]{%
	\catcode`#1\active
	\begingroup
		\lccode`\~`#1\relax
		\lowercase{\endgroup\def~}%
}

\newcommand\exemple{%
	\begingroup
	\parskip\z@
	\exemple@}

\newcommand\exemple@{%
	\medbreak\noindent
	\begingroup
		\let\do\@makeother\dospecials
		\make@car@active\ { {}}%
		\make@car@active\^^M{\par\leavevmode}%
		\make@car@active\^^I{\space\space}%
		\make@car@active\,{\leavevmode\kern\z@\string,}%
		\make@car@active\-{\leavevmode\kern\z@\string-}%
		\make@car@active\>{\leavevmode\kern\z@\string>}%
		\make@car@active\<{\leavevmode\kern\z@\string<}%
		\@makeother\;\@makeother\!\@makeother\?\@makeother\:% neutralise frenchb
		\exemple@@
}

\newcommand\exemple@@[1]{%
	\def\@tempa##1#1{\exemple@@@{##1}}%
	\@tempa
}

\newcommand\exemple@@@[1]{%
	\xdef\the@code{#1}%
	\endgroup
		\begingroup
			\fboxrule0.4pt \fboxsep=5pt
			\let\breakboxparindent\z@
			\def\bkvz@top{\hrule\@height\fboxrule}%
			\def\bkvz@bottom{\hrule\@height\fboxrule}%
			\let\bkvz@before@breakbox\relax
			\def\bkvz@set@linewidth{\advance\linewidth\dimexpr-2\fboxrule-2\fboxsep\relax}%
			\def\bkvz@left{\vrule\@width\fboxrule\kern\fboxsep}%
			\def\bkvz@right{\kern\fboxsep\vrule\@width\fboxrule}%
			\breakbox
				\kern.5ex\relax
				\begingroup
					\ttfamily\small\the@code\par
				\endgroup
				\kern3pt
				\hrule height0.1pt width\linewidth depth0.1pt
				\vskip5pt
				\newlinechar`\^^M\everyeof{\noexpand}\scantokens{#1}\par
			\endbreakbox
		\endgroup
	\medbreak
	\endgroup
}
\begingroup
	\catcode`\<13 \catcode`\>13
	\gdef\verb{\relax\ifmmode\hbox\else\leavevmode\null\fi
		\bgroup
			\verb@eol@error \let\do\@makeother \dospecials
			\verbatim@font\@noligs
			\catcode`\<13 \catcode`\>13 \def<{\begingroup$\langle$\itshape}\def>{\/$\rangle$\endgroup}%
			\@ifstar\@sverb\@verb}
\endgroup
\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}
\edef\longfrhlstdate{\expandafter\longfrhlstdate@i\skvdate\@nil}
\def\<#1>{$\langle$\textit{#1}$\rangle$}
\makeatother

\begin{document}
\parindent=0pt
\thispagestyle{empty}
\begin{titlepage}
	\begingroup
		\centering
		\null\vskip.25\vsize
		{\large\bfseries L'extension pour \TeX/\LaTeX\par \Huge \skvname\par}
		\bigbreak
		v \skvver
		\smallbreak
		\longfrhlstdate
		\vskip1.5cm
		Christian \bsc{Tellechea}\par
		\texttt{unbonpetit@netc.fr}\par
	\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.
\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

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 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 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>.
\end{itemize}

\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.

On écrit
\begin{center} \verb|\setKVdefault[<trousseau>]{<clé 1>=<valeur 1>,<clé 2>=<valeur 2>,...,<clé i>=<valeur i>}|
\end{center}

Il faut noter que
\begin{itemize}
	\item l'argument entre accolades contenant les \<clés> et les \<valeurs> ne peut pas être vide;
	\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 \<valeur> est omise, elle est comprise comme étant «\texttt{true}». Ainsi, écrire
	\code|\setKVdefault[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|.
\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é>}|

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é> 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
\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`\\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>}|

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

Si la \<clé> n'est pas définie, «\texttt{not defined}» est affiché dans le fichier log.

\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:
\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}).
\end{itemize}

\exemple|\setKVdefault[frame]{inline , left code = \hfill, right code = \hfill, sep = 3pt, width=0.5pt }
\newcommand\frametxt[2][]{%
	\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}%
}
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}.

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


\section{Le code}
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},
		basicstyle=\small\ttfamily\color{black!25},
		identifierstyle=\bfseries\color{white},%
		backgroundcolor=\color{black!85},
		keywordstyle=\bfseries\color{orange},
		commentstyle=\color{cyan!66},
		columns=fixed,
		alsoletter={\_},
		tabsize=2,
		extendedchars=true,
		showspaces=false,
		showstringspaces=false,
		numbers=left,
		numberstyle=\tiny\ttfamily\color{black},
		breaklines=true,
		prebreak={\hbox{$\rhookswarrow$}},
		breakindent=3em,
		breakautoindent=true,
		xleftmargin=1em,
		xrightmargin=0pt,
		lineskip=0pt,
		numbersep=1em,
		classoffset=1,
		alsoletter={\_},
		morekeywords={setKVdefault,setKV,useKVdefault,useKV,ifboolKV,},
		keywordstyle=\bfseries\color{red!85!black},
		classoffset=0,
		]{simplekv.tex}
\end{document}