diff options
author | Karl Berry <karl@freefriends.org> | 2017-08-08 20:40:20 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2017-08-08 20:40:20 +0000 |
commit | c2d6f5036f52ba820291bce134396a26215d95dc (patch) | |
tree | e1b8812ab049ba41f825d1c69767749d1b44b1f2 /Master/texmf-dist/doc/generic/simplekv/simplekv-fr.tex | |
parent | 75f529a8c99a457b98e31992cb965bbc447813c8 (diff) |
simplekv (8aug17)
git-svn-id: svn://tug.org/texlive/trunk@44986 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/simplekv/simplekv-fr.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/simplekv/simplekv-fr.tex | 271 |
1 files changed, 271 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/simplekv/simplekv-fr.tex b/Master/texmf-dist/doc/generic/simplekv/simplekv-fr.tex new file mode 100644 index 00000000000..c899feeb738 --- /dev/null +++ b/Master/texmf-dist/doc/generic/simplekv/simplekv-fr.tex @@ -0,0 +1,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}
\ No newline at end of file |