path: root/macros/latex/contrib/clefval/clefval.dtx

% \iffalse meta-comment
% 
%%%% Copyright (C) 2004, 2020 by Josselin Noirel 
%%%% and Yvon Henel aka Le TeXnicien de surface
%%%% --------------------------------------------------------
% 
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in:
%
%    http://www.latex-project.org/lppl.txt
%
% \fi
%
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\def\fileversion{v0.1}  
%<package>\def\filedate{2020/07/27}  
%<packfra>\def\fileinfo{d\'efinir et utiliser des paires cle/valeurs} 
%<packeng>\def\fileinfo{define and use pair of key/values} 
%<package>\ProvidesPackage{clefval}
%<package>         [\filedate\space\fileversion\space\fileinfo] 
%<*driver>
\documentclass[a4paper]{ltxdoc}
\usepackage[T1]{fontenc}  
\usepackage{clefval}
\usepackage{xspace,url,multicol,ifthen}
\IfFileExists{lmodern.sty}{\usepackage{lmodern}}{}
\usepackage[english, main=french]{babel}
% commentez la ligne suivante pour avoir un document avec le code 
% \OnlyDescription
% comment out the preceding line to obtain the full code 
% with explanations in French only, sorry.
\EnableCrossrefs         
\CodelineIndex
\RecordChanges
\makeatletter
%%% quelques redéfinition de commande de la classe ltxdoc.cls ou de 
%%% l'extension doc.sty pour une documentation en français.
\GlossaryPrologue{\section*{{Changements --
      Changes}}\markboth{{Changements -- Changes}}{{Changements -- Changes}}} 
\IndexPrologue{\section*{Index}\markboth{Index}{Index}%
  \begin{Morciau}\selectlanguage{french}
    Les nombres en italique renvoient à la page où l'entrée est décrite ; les
    nombres soulignés renvoient à la ligne de code de la définition ; les
    nombres en caractères romains renvoient à la ligne de code où l'entrée est
    utilisée.\EnAnglais Numbers written in italic refer to the page where the
    corresponding entry is described; numbers underlined refer to the code
    line of the definition; numbers in roman refer to the code line where the
    entry is used.\end{Morciau}} 
\renewcommand{\SpecialMainEnvIndex}[1]{%
  \@bsphack\special@index{%
    #1\actualchar {\string\ttfamily\space#1}(environnement)% 
    \encapchar main}%
  \special@index{environnements:\levelchar{%
      \string\ttfamily\space#1}\encapchar main}\@esphack}
\makeatother
\def\generalname{Général}
%%% fin de la francisation
\setlength{\columnseprule}{0.5pt}
\setlength{\multicolsep}{6pt plus 2.0pt minus 1.5pt}
\def\FraTitre{\relax}
\def\EngTitre{\relax}
\newcommand{\TraiteTitre}[1]{\TraiteTitreAux#1/Z}
\def\TraiteTitreAux#1/#2/Z{\def\FraTitre{\TitreMorciau{#1}}%
  \ifthenelse{\equal{#2}{}}{\def\LarGuMent{#1}}{\def\LarGuMent{#2}}  
  \def\EngTitre{\TitreMorciau{\LarGuMent}}} 
\newcommand{\TitreMorciau}[1]{%
  \noindent\textbf{#1}\par\noindent\ignorespaces} 
\newenvironment{Morciau}[1][ZXZXZ]{\raggedcolumns\begin{multicols}{2}%
    \selectlanguage{french}%
    \ifthenelse{\equal{#1}{ZXZXZ}}{\relax}{\TraiteTitre{#1}\FraTitre}}% 
  {\end{multicols}}   
\newcommand{\EnAnglais}{\columnbreak\mbox{}
  \par\selectlanguage{english}\EngTitre} 
\newcommand{\NomDeModule}[1]{\texttt{#1.sty}\xspace}
\newcommand{\fctt}{\texttt{fr.comp.text.tex}\xspace}
\newcommand{\Sourire}{\texttt{;-)}\xspace}
\newcommand{\LB}{\linebreak[2]}
%%% fin de la personalisation
\begin{document}
  \DocInput{clefval.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{76}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \GetFileInfo{clefval.sty}
%
% \changes{v0}{2004/05/20}{1\iere version
% publique. \textit{\foreignlanguage{english}{1st public version.}}}
% \changes{v0.1}{2020/07/27}{Amélioration du message d'erreur dans le
% document. \textit{\foreignlanguage{english}{Improved error message
% in document.}}}
% \changes{v0.1}{2020/07/27}{Version permettant l'utilisation du
% codage utf-8 avec \texttt{pdflatex},  \texttt{lualatex} et
% \texttt{xelatex}. \textit{\foreignlanguage{english}{This version can
% be used in utf-8 encoded source with \texttt{pdflatex},
% \texttt{lualatex} and \texttt{xelatex}.}}}

%
% \DoNotIndex{\newcommand, \renewcommand, \providecommand,^^A  
%   \def, \let,\csname, \endcsname, \afterassignment,^^A 
%   \long, \global, \gdef, \edef, \xdef, \null, \write,^^A
%   \newenvironment,\renewenvironment, \expandafter, \relax,^^A 
%   \protect, \begingroup, \endgroup, \bgroup, \egroup^^A  
%   \DeclareOption, \ExecuteOptions, \RequirePackage,^^A
%   \ProcessOptions, \newif, \fi, \if, \or, \ifnum, \ifcase,\ifx,^^A
%   \ifvmode, \@ifundefined, \@bsphack, \@esphack,^^A
%   \nobreak, \if@nobreak, \@onlypreamble, \@unexpandable@protect,^^A
%   \space, \string, \AtBeginDocument, \AtEndDocument,^^A
%   \bfseries, \reset@font, \nfss@text, \',^^A
%   \@latex@warning, \@latex@warning@no@line,^^A
%   \@testdef, \@namedef, \reserved@a,^^A
%   \else, \@ctrerr, \text,\textup, \value, \thepage, \@auxout}
% 
% \title{Le module\thanks{Ce document correspond au fichier
% \textsf{clefval}~\fileversion, du \filedate.}\hspace{2cm} 
% The package\thanks{This document corresponds to the file
% \textsf{clefval}~\fileversion, dated \filedate.}\\ 
% \textsf{clefval}}
% 
% \author{Le \TeX nicien de
% surface\thanks{\texttt{le.texnicien.de.surface@yvon-henel.fr}}\and
% Josselin Noirel}
%
% \maketitle
%
% \section{Introduction}
% \label{secIntro}
% \noindent\textbf{Description}\DescribeMacro{\TheKey}\DescribeMacro{\TheValue}
% \begin{Morciau}[Macros~publiques/Public~Macros]
% Deux macros \cs{TheKey} et \cs{TheValue} pour définir puis utiliser
% des paires clef/valeur.   
% \EnAnglais
% Two macros  \cs{TheKey} and \cs{TheValue} to define then use pairs
% of key/value. 
% \end{Morciau}
% \begin{Morciau}[Syntaxe/Syntax]
%  \cs{TheKey}\marg{clé}\marg{valeur} pour définir la \emph{valeur}
%  associée à la \emph{clé}, ne produit pas de texte ; 
% \cs{TheValue}\marg{clé} pour insérer la \emph{valeur} associée à la
% \emph{clé}. 
% \EnAnglais
% \cs{TheKey}\marg{key}\marg{value} to define the \emph{value}
% associated to the \emph{key}, does not produce text ;
% \cs{TheValue}\marg{key} to insert the \emph{value} linked to the
% \emph{key}. 
% \end{Morciau}
% 
%
% \subsection{Version 0.1}
% 
% \begin{Morciau}
%   Edd \textsc{Barrett}, le 27 juillet 2020, a signalé sur
%   \texttt{stackexchange} un problème lié à l'utilisation de
%   \texttt{clefval}. C'est lui, également, qui a fourni un ECM et
%   trouvé la cause dudit problème: la présence d'un espace insécable
%   dans le fichier codé en \texttt{iso-8859-15} entrainait l'arrêt de
%   \LaTeX{} avec le message:
%   \EnAnglais
%   On the 27th July 2020, Edd \textsc{Barrett} wrote on
%   \texttt{stackexchange} about a problem linked to the use of
%   \texttt{clefval}. He also wrote a MCE and found the cause of the
%   said problem: an unbreakable space in the file encoded in
%   \texttt{iso-8859-15} forced \LaTeX{} to stop with the following
%   error message:  
% \end{Morciau}
% 
% \texttt{Package inputenc Error: Invalid UTF-8 byte "A0.}
% 
% \begin{Morciau}
%   Comme tout le travail avait été fait, il m'a été facile de
%   corriger l'erreur dans le code. J'en ai profité pour faire
%   apparaître, \emph{dans le document}, un message d'erreur plus
%   explicite nommant la clé indéfinie et pour moderniser un peu cette
%   extension. 
%   \EnAnglais
%   As all the work was already done I easily wrote the correction in
%   the code. I've taken the opportunity to make appear, \emph{in the
%   document}, a more explicit error message in case of undefined key
%   and to modernise a bit this package.
% \end{Morciau}
% 
% \section{Utilisation -- Usage}
%
% \begin{Morciau}[Procédé/Process]
% Le procédé mis en œuvre par ce module est le même que celui des
% références classiques de \LaTeX{} avec \cs{label} et \cs{ref}. Il
% faut donc deux compilations pour en voir l'effet. 
% \EnAnglais
% \texttt{clefval} uses the process which \LaTeX's \cs{label} and \cs{ref}
% use. You must therefore compile twice to obtain the full effect.
% \end{Morciau}
% \begin{Morciau}
% Lors de la 1\iere compilation, \cs{TheKey}\LB|{clé}|\LB|{valeur}| écrit,
% dans le fichier \texttt{aux}, \cs{newkey}\LB|{clé}|\LB|{valeur}|. |clé| et
% |valeur| sont développés à moins qu'ils ne soient protégés soit pour avoir
% été déclarés robustes (voir \cs{DeclareRobustCommand}) soit pour avoir été
% protégés (voir \cs{protect}) par vous. 
% \EnAnglais 
% During the 1st run of \LaTeX, \cs{TheKey}\LB|{key}|\LB|{value}| writes
% \cs{newkey}\LB|{key}|\LB|{value}| in the \texttt{aux} file. |key| 
% and |value| are expanded unless they are protected since they have been
% declared robust (see \cs{DeclareRobustCommand}) or since they have been
% protected (see \cs{protect}) by you.
% \end{Morciau}
% \begin{Morciau}
% Lors de la 2\ieme compilation, après lecture du fichier \texttt{aux},
% \cs{TheValue}|{clé}| écrit |valeur|. 
% \EnAnglais
% During the 2nd run, the \texttt{aux} file having been read,
% \cs{TheValue}|{key}| writes |value|.
% \end{Morciau}
% \begin{Morciau}[Attention/Caution]
% Les deux arguments de \cs{TheKey} sont  \og mobiles \fg au sens de \LaTeX{}
% et il faudra donc parfois les protéger. 
% \EnAnglais
% Both arguments of \cs{TheKey} are `moving' as \LaTeX{} defines it and we have
% sometimes to protect them. 
% \end{Morciau}
% 
% \begin{Morciau}
% Par ailleurs, les arguments ne doivent pas contenir de saut de
% paragraphe (\cs{par}) ---~ou tout autre truc interdit dans les
% arguments d'une commande qui n'est pas \cs{long}.
% \EnAnglais
% In addition the arguments must not contain end of paragraph
% (\cs{par}) ---~or any other thingummy which is forbidden in the
% arguments of a macro which is not \cs{long}.
% \end{Morciau}
% 
% \begin{Morciau}[Exemples/Examples]
%   On peut écrire 
%   \EnAnglais
%   On can write
% \end{Morciau}
% 
% {\centering \TheKey{clou}{$2+5=7$}|\TheKey{clou}{$2+5=7$}|
% \TheKey{glue}{\(2+6=8\)}|\TheKey{glue}{\(2+6=8\)}|
% \par}
% 
% \begin{Morciau}
%   puis \EnAnglais then
% \end{Morciau}
% 
% {\centering |\TheValue{clou}|, |\TheValue{glue}|\par}
% 
% \begin{Morciau}
%   pour obtenir \EnAnglais to obtain
% \end{Morciau}
% 
% {\centering \TheValue{clou}, \TheValue{glue}.\par}
% 
% \begin{Morciau}
%   On peut utiliser |$2+3$| comme clé --- même si on ne voit pas
%   pourquoi on le ferait --- mais \textbf{pas} |\(2+3\)|. Ce qui
%   tient à la manière dont les commandes |\(| et |\)| ont été
%   robustifiées. \emph{Ce n'est pas un bogue mais une fonctionnalité.}
%   \EnAnglais
%   On can use |$2+3$| as a key ---and I don't say that one should---
%   but \textbf{not} |\(2+3\)|. That is due to the way the macros |\(|
%   and |\)| have been robustified. \emph{It's not a bug but a feature.}
% \end{Morciau}
% 
% 
% \begin{Morciau}[Avertissements/Warnings]
% Le module signale les définitions multiples d'une même clef et
% marque {\selectlanguage{english}\textbf{[?? clou ??]}} là où l'on utilise
% \cs{TheValue}\LB|{clou}| alors que |clou| n'est pas définie comme
% clef. En cas d'erreur, le fichier \texttt{log} contient la ligne :
% \EnAnglais
% The package warns about multiple definitions of the same key and
% writes \textbf{[?? kew ??]} where one used \cs{TheValue}\LB|{kew}| whereas
% |kew| was not defined as a key. In case of error, the \texttt{log}
% file contains the line:
% \end{Morciau}
% \noindent\hspace*{\stretch{1}}\texttt{LaTeX Warning: There were undefined
% references.}\hspace*{\stretch{1}}
% 
% \vspace{\baselineskip}
% 
% \begin{Morciau}[Remarque/Remark]
% Josselin \textsc{Noirel} est intervenu efficacement, tant sur \fctt
% que par courriel, pour corriger les modifications que j'avais fait
% subir au code tiré de \texttt{ltxref} et \texttt{ltfiles}. C'est
% pour sa contribution décisive qu'il est cité comme co-auteur de ce
% module. Qu'il trouve là l'expression de ma profonde gratitude. 
%
% Cependant, j'assume l'entière responsabilité de la rédaction de
% cette documentation et de sa traduction ainsi que la paternité de
% l'idée d'utiliser le mécanisme des \cs{label} pour accéder à un
% \texttt{hashage} rudimentaire. 
% \EnAnglais
% Josselin \textsc{Noirel} has efficiently helped me, on \fctt and by
% email, to correct the hack I have made in the code taken from
% \texttt{ltxref} and \texttt{ltfiles}. For he made that decisive
% contribution, he is mentionned here as a co-author of this
% package. May he find there the expression of my deep gratefulness. 
%
% Howerver I take the entire responsability for the writing of the
% present documentation and its English translation and I do recognise
% having fathered the idea of using the \cs{label} mecanism to obtain
% a rudimentary \texttt{hash}. 
% \end{Morciau}
% 
% \vspace{\baselineskip}
% 
% \begin{Morciau}[Version 0.1/Version 0.1]
%   Cette version est compatible avec un fichier codé en utf-8 compilé
%   avec \texttt{pdflatex}, \texttt{lualatex} ou \texttt{xelatex}
%   d'après mes --- quelques --- essais. Si ce n'était pas le cas,
%   n'hésitez pas à me signaler le problème.
%   \EnAnglais
%   This version is usable with a utf-8 encoded source run through
%   \texttt{pdflatex}, \texttt{lualatex} or \texttt{xelatex} as it
%   appears from my ---not very numerous--- trials. If it was not the
%   case don't hesitate to contact me.
% \end{Morciau}
% 
% \hspace*{\stretch{1}}Le \TeX nicien de
% surface. \hspace*{0.125\linewidth}
% 
% \vspace{2\baselineskip}
% 
% \begingroup
% \small
% \hspace*{\stretch{1}}\textbf{In memoriam Énola Néra}\hspace*{\stretch{1}}
% 
% \begin{Morciau}
%   Gentille chienne aimante et fidèle, compagne de plus de 10 ans que
%   son cœur a laché le 27 juillet 2020.
%   \EnAnglais
%   Kind, loving and faithfull bitch, companion of more than 10 years
%   whose heart stopped on the 27th July 2020.
% \end{Morciau}
% \endgroup
% 
% \StopEventually{}
% \section{Le code}
% \label{secCode}
% 
% Le code comporte des balises utilisable par \texttt{DocStrip} avec
% lesquelles on peut produire une version francisée ou une version
% anglaise de \NomDeModule{clefval}. Voir la documentation de
% \texttt{DocStrip} pour de plus amples renseignements.
%
% On dit boujour, en français ou en anglais suivant la manière dont on
% a créé \NomDeModule{clefval}. Puis on entre dans le vif du
% sujet. 
%
% Le code a d'abord été repris de \texttt{ltxref} mais j'avais
% quelques ennuis avec les avertissements concernant les clefs non
% définies ou définies plusieurs fois. Josselin Noirel a bien voulu
% répondre à mon appel au secours sur \fctt. Le code qui suit est donc
% la correction par Josselin de mes modifications du code de
% \texttt{ltxref}, moyennant quoi, je signe \Sourire
% 
% \iffalse
%<*package>
% \fi
% \begin{macro}{\@setTheValue}
%  Le code est copié sur celui de |\@setref| dans
%  \texttt{ltxref}. Cette macro est appelée par \cs{TheValue}. Elle
%  vérifie que la \meta{clef} appelée existe. Si elle n'existe pas elle
%  imprime {\selectlanguage{english}\textbf{[?? \meta{clef} ??]}} et place un
%  avertissement dans le \texttt{log}. Sinon elle rend son premier 
%  argument.   
%
% On utilise |\G@refundefinedtrue| pour provoquer le message d'erreur
% \og There were undefined references \fg. Un peu sybillin pour ce qui
% nous concerne, il a l'avantage d'être reconnu par au moins
% \texttt{emacs} plus \texttt{Auctex} et d'indiquer qu'il faut
% relancer la compilation.
%    \begin{macrocode}
\newcommand*{\@setTheValue}[2]{%
  \ifx#1\relax
  \protect\G@refundefinedtrue
  \nfss@text{\reset@font\bfseries[?? #2 ??]}%
%    \end{macrocode}
% \end{macro}
% \iffalse
%</package>
%<*packfra>
% \fi
% \textsf{Messages d'avertissement en français}
%    \begin{macrocode}
\@latex@warning{Valeur de #2 en page \thepage\space non d\'efinie}% 
%    \end{macrocode}
% \iffalse
%</packfra>
%<*packeng>
% \fi
% \textsf{Warning messages in English }
%    \begin{macrocode}
\@latex@warning{Value of `#2' on page \thepage\space  undefined}% 
%    \end{macrocode}
% \iffalse
%</packeng>
%<*package>
% \fi
%    \begin{macrocode}
  \else #1\null \fi}
%    \end{macrocode}
% \begin{macro}{\TheValue}
% Le code est copié sur celui de |\ref| dans \texttt{ltxref}. Si
% l'argument de \cs{TheValue} est une clef valide, on obtient la
% valeur référencée par cette clef.  
%    \begin{macrocode}
\newcommand*{\TheValue}[1]{\expandafter\@setTheValue\csname
  V@#1\endcsname{#1}} 
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\@newk@ey}
% Le code est copié sur celui de |\@newl@bel| dans \texttt{ltxref}. 
%    \begin{macrocode}
\newcommand*{\@newk@ey}[3]{{%
    \@ifundefined{#1@#2}%
    {\relax}%
    {\gdef \@multiplekeys {%
%    \end{macrocode}
% \end{macro}
% \iffalse
%</package>
%<*packfra>
% \fi
% \textsf{Messages d'avertissement en français}
%    \begin{macrocode}
\@latex@warning@no@line{Des clefs sont d\'efinies plusieurs fois.}}% 
\@latex@warning@no@line{La clef #2 est d\'efinie plusieurs fois}}%
%    \end{macrocode}
% \iffalse
%</packfra>
%<*packeng>
% \fi
% \textsf{Warning messages in English }
%    \begin{macrocode}
\@latex@warning@no@line{There were multiply-defined keys.}}% 
\@latex@warning@no@line{Key `#2' multiply defined}}%
%    \end{macrocode}
% \iffalse
%</packeng>
%<*package>
% \fi
%    \begin{macrocode}
    \global\@namedef{#1@#2}{#3}}}
%    \end{macrocode}
% \begin{macro}{\newkey}
% On opère ici une puissante magie qui fait que tout marche comme
% attendu \Sourire 
%    \begin{macrocode}
\def\newkey{\@newk@ey V}
\@onlypreamble\@newk@ey
\AtEndDocument{\let\@newk@ey=\@testdef}
%    \end{macrocode}
% \end{macro}
% \iffalse
%</package>
% ^^A fin du code de Josselin Noirel
%<*package>
% \fi
% À partir d'ici votre serviteur s'est débrouillé tout seul pour 
% modifier le code des bases de \LaTeX.
% 
% \begin{macro}{\@protected@write}
% Le code est copié sur celui de |\protected@write| défini dans
% \texttt{ltfiles}. On n'a besoin que d'un seul argument qui est écrit
% dans le fichier |\@auxout| c-à-d. le fichier \texttt{aux}. 
% La macro prend soin de ce qui est protégé soit de manière définitive
% pour avoir été défini par \cs{DeclareRobustCommand} et ses petits
% amis, soit pour être précédé de \cs{protect} comme on doit le faire
% parfois pour les arguments  \og mobiles \fg (\emph{moving
% argument}).  
%    \begin{macrocode}
\long\def \@protected@write#1{%
  \begingroup
  \let\protect\@unexpandable@protect
  \edef\reserved@a{%
    \write\@auxout{#1}}%
  \reserved@a \endgroup \if@nobreak\ifvmode\nobreak\fi\fi }
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\@multiplekeys}
% En mettant |\@multiplekeys| à \cs{relax}, on s'assure qu'il n'y aura
% pas de hurlements alors que rien n'est encore défini et donc encore
% moins défini plusieurs fois \Sourire
%    \begin{macrocode}
\let \@multiplekeys \relax
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\TheKey}
% Le code remprend celui de \cs{label} mais il nous faut deux
% arguments, le 1\ier pour la clef, le 2\textsuperscript{nd} pour la
% valeur associée.   
%    \begin{macrocode}
\def\TheKey#1#2{{\@bsphack
    \@protected@write{\string\newkey{#1}{#2}}%
    \@esphack}}
%    \end{macrocode}
% \end{macro}
% \iffalse
%</package>
% \fi
% \Finale \PrintChanges\PrintIndex
\endinput