From e87acedb229047d5bb0c777c8805fd02e370aeed Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 27 Apr 2020 21:17:47 +0000 Subject: simplekv (27apr20) git-svn-id: svn://tug.org/texlive/trunk@54915 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/generic/simplekv/README | 4 +- .../doc/generic/simplekv/simplekv-fr.pdf | Bin 329306 -> 326887 bytes .../doc/generic/simplekv/simplekv-fr.tex | 161 +++++++++++++++------ 3 files changed, 115 insertions(+), 50 deletions(-) (limited to 'Master/texmf-dist/doc/generic/simplekv') diff --git a/Master/texmf-dist/doc/generic/simplekv/README b/Master/texmf-dist/doc/generic/simplekv/README index d612d38b6b7..1172bd96a6a 100644 --- a/Master/texmf-dist/doc/generic/simplekv/README +++ b/Master/texmf-dist/doc/generic/simplekv/README @@ -3,9 +3,9 @@ ___________________________________ L'extension simplekv - v0.1 + v0.2 - 8 aout 2017 + 27 avril 2020 ___________________________________ Authors : Christian Tellechea diff --git a/Master/texmf-dist/doc/generic/simplekv/simplekv-fr.pdf b/Master/texmf-dist/doc/generic/simplekv/simplekv-fr.pdf index 797171dd55e..950d64baa11 100644 Binary files a/Master/texmf-dist/doc/generic/simplekv/simplekv-fr.pdf and b/Master/texmf-dist/doc/generic/simplekv/simplekv-fr.pdf differ diff --git a/Master/texmf-dist/doc/generic/simplekv/simplekv-fr.tex b/Master/texmf-dist/doc/generic/simplekv/simplekv-fr.tex index c899feeb738..e23a0ae0782 100644 --- a/Master/texmf-dist/doc/generic/simplekv/simplekv-fr.tex +++ b/Master/texmf-dist/doc/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 à «\/\» 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 \ et \. 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 \/\ 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 \ et \. +\medskip Voici brièvement les définitions et les limitations des structures mises à disposition : \begin{itemize} - \item une \ 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 \ 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 \, même si cela revêt peu de signification, peut être vide; \item la syntaxe pour assigner une \ à une \ est : \hbox{\=\}; \item les espaces qui précèdent et qui suivent la \ et la \ sont ignorés, mais \emph{pas ceux} qui se trouvent à l'intérieur de la \ ou de la \; \item une \ est un \ arbitraire; \item si une \ est entourée d'accolades, ces dernières seront retirées : \verb|=| est donc équivalent à \verb|={}|; + \item lorsqu'une valeur est entourée de \emph{plusieurs} imbrications d'accolades, seul le niveau externe est retiré et donc \verb|={{}}| est compris comme \verb|={}|; \item lorsque plusieurs couples de \/\ 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 \ que si la virgule est dans un niveau d'accolades; par exemple, \verb|foo=1,5| n'est pas valide car la \ 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 \ 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 \ définie ou modifiée dans un groupe est restaurée à son état antérieur à la sortie du groupe; \item des \/\ 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é \. @@ -152,87 +150,154 @@ Voici bri \section{Commandes mises à disposition} -\paragraph{La macro \texttt{\char`\\setKVdefault}} -Cette commande est un préalable à toute utilisation de \ puisqu'elle définit un \ contenant des \ et leurs \ par défaut. +\paragraph{Les macro \texttt{\char`\\setKV} et \texttt{\char`\\setKVdefault}} +Ces commandes définissent des \ et leur assignent des \ dans un \. La seule différence entre les deux macros est que \verb|\setKVdefault|, en plus d'assigner les \ aux \, les sauvegarde en vue d'une restauration ultérieure avec \verb|\restoreKV|. On écrit -\begin{center} \verb|\setKVdefault[]{=,=,...,=}| -\end{center} +\code|\setKV[]{=,=,...,=}| Il faut noter que \begin{itemize} - \item l'argument entre accolades contenant les \ et les \ ne peut pas être vide; + \item l'argument entre accolades contenant les \ et les \ ne devrait pas être vide, sauf à vouloir définir une \ booléenne vide égale à \texttt{true}; + \item lors de la lecture des \/\, la virgule et le signe égal ont leurs catcodes rendus égaux à 12; \item le nom du \, bien qu'entre crochet, est \emph{obligatoire}, mais il peut être vide bien que cela ne soit pas conseillé; - \item si plusieurs \ sont identiques, seule la dernière \ sera prise en compte; - \item les \ 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 \ figure plusieurs fois, la \ retenue sera celle de la dernière assignation; + \item les \ peuvent être booléennes auquel cas, elles \emph{doivent} être «\texttt{true}» ou «\texttt{false}» en caractères de catcode 11; \item si une \ 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 \. Si cela est indispensable, il convient de redéfinir \emph{toutes} les \ 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 \ dont les \ ont précédemment été définies par \verb|\setKVdefault|. - -Si une \ 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 \ préalablement associée à une \ dans un \: -\code|\useKV[]{}| + \code|\useKV[]{}| Il faut noter que \begin{itemize} - \item si la \ n'a pas été prédéfinie par \verb|\setKVdefault|, une erreur sera émise; + \item si la \ n'a pas été définie, une erreur sera émise; \item si la \ est booléenne, le texte «\texttt{true}» ou «\texttt{false}» sera renvoyé; \item il faut 2 développements à \verb|\useKV[]{}| pour donner la \ associée à la \. \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[]| réinitialise toutes les \ du \ aux \ qui ont été définies lors de l'exécution \verb|\setKVdefault|. +\paragraph{La macro \texttt{\char`\\restoreKV}} +La macro \verb|\restoreKV[]| réinitialise toutes les \ du \ aux \ qui ont été définies lors de l'exécution \verb|\setKVdefault|. La macro \verb|\useKVdefault[]| lui est équivalente. \paragraph{La macro \texttt{\char`\\ifboolKV}} Cette macro permet, selon la valeur d'une \, d'exécuter un des deux \ donnés. La syntaxe est -\code|\ifboolKV[]{}{}{}| + \code|\ifboolKV[]{}{}{}| La macro est purement développable, elle nécessite 2 développements pour donner l'un des deux codes, et exige que la \ 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 \ assignée à une \ d'un \: -\code|\showKV[]{}| + \code|\showKV[]{}| Si la \ n'est pas définie, «\texttt{not defined}» est affiché dans le fichier log. +\section{Code} +En plus d'une \, un \ arbitraire peut être assigné à n'importe quelle \. Pour ce faire, on écrit +\begin{center} \verb|\defKV[]{=,=,...,=}| +\end{center} +Chaque \ peut contenir \verb|#1| qui représente la \ de la \. Ce \ est exécuté lorsque une \ est assignée à la \ 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 \ «\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 \, si son argument est «true» ou «false» + \code|\testboolKV{}{}{}| + +La macro est purement développable, elle nécessite 2 développements pour donner l'un des deux codes, et exige que l'\ 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 \ 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 \ 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} -- cgit v1.2.3