\documentclass[a4paper,11pt]{article}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage[french]{babel}
\usepackage{geometry}
\geometry{margin=3cm}
\usepackage{microtype}
\usepackage{booktabs}
\usepackage{fancyvrb}
\usepackage{xcolor}
\usepackage[colorlinks,linkcolor=blue!60!black,urlcolor=blue!60!black]{hyperref}
\usepackage{chemidentifier}
\chemidsetup{last-sep={~et~}} % ce manuel est redige en francais ; le
                               % defaut du paquetage est l'anglais (§7)

\newcommand{\cmd}[1]{\texttt{\textbackslash #1}}
\newcommand{\opt}[1]{\texttt{#1}}

% --- composes utilises dans les exemples de ce manuel -----------------
\chemid*{benz}
\chemid*{benz.cl}
\chemid*{benz.br}
\chemid*{benz.i}
\chemid*{amine}
\chemid*{amine.a}
\chemid*{amine.b}
\chemid*{cible}{cible\textsubscript{finale}}[cible finale]
\chemid*{seriea}
\chemid*{serieb}
\chemid*{seriec}
\chemidfamily{lcoum}{ name = Lcoum-C , placeholder = n }
\chemid*{lcoum.quatre}{4}
\chemid*{lcoum.huit}{8}
\chemid*{lcoum.douze}{12}
\chemidfamily{ser}{ name = Série , sub-style = lower-greek ,
                    child-format = plain }
\chemid*{ser.a}
\chemid*{ser.b}
\chemid*{ser.c}

\title{Le paquetage \texttt{chemidentifier}}
\author{Aliocha SKRZYPCZAK \\ \small Version 2.0.0}
\date{2026-08-19}

\begin{document}
\maketitle

\begin{abstract}
\noindent
\texttt{chemidentifier} numérote les composés d'un article de chimie de
synthèse dans \emph{l'ordre logique de la synthèse} — l'ordre où vous les
déclarez — et non dans l'ordre où ils apparaissent dans le texte. Chaque
numéro imprimé est cliquable et renvoie au schéma qui montre le composé.
Le paquetage est écrit en \LaTeX3 (expl3) ; comme
\cmd{ref}/\cmd{label}, tout se stabilise en \textbf{deux
compilations}.
\end{abstract}

\tableofcontents

\section{Installation et chargement}

Copiez \texttt{chemidentifier.sty} à côté de votre document, ou lancez
\texttt{make install} pour l'installer dans \texttt{\textasciitilde/texmf}.

\begin{Verbatim}[frame=single,fontsize=\small]
\usepackage{hyperref}          % avant chemidentifier, de preference
\usepackage{chemidentifier}
\end{Verbatim}

\noindent
\texttt{hyperref} n'est pas chargé par le paquetage : il est
\emph{détecté}, pour vous laisser maîtriser ses options et l'ordre de
chargement. S'il manque, tout est numéroté normalement, rien n'est
cliquable, et un avertissement le rappelle une fois.

\subsection{Quelle version est chargée}
\label{sec:version}

\texttt{chemidentifier.sty} est un chargeur : il lit l'option
\opt{version}, et rien d'autre, puis passe la main à l'implémentation
demandée. La version~2 est celle par défaut, décrite ici ; la
version~1 est conservée telle quelle, définitivement, pour les
documents écrits avec elle.

\begin{Verbatim}[frame=single,fontsize=\small]
\usepackage{chemidentifier}             % version 2
\usepackage[version=1]{chemidentifier}  % version 1, figee
\end{Verbatim}

\noindent
Trois choses changent en version~2 pour un document écrit en
version~1, les trois délibérément :

\begin{itemize}
  \item \cmd{herechemid} s'appelle désormais \cmd{chemidhere}.
        L'ancien nom fonctionne toujours et continuera de fonctionner ;
        il signale une fois par document qu'il a été renommé.
  \item Un composé sans ancre est imprimé \emph{sans} lien plutôt que
        de renvoyer dans le vide (§\ref{sec:strict}). Les liens se
        stabilisent donc à la deuxième compilation, comme \cmd{ref}.
  \item \cmd{chemidhere\{parent\}} ancre maintenant toute la famille,
        enfants compris (§\ref{sec:anchor}).
\end{itemize}

\noindent
Tout le reste est identique, et le manuel de la version~1 est installé
à côté de celui-ci sous le nom \texttt{chemidentifier-doc-v1.fr.pdf}.
La suite de tests compile chaque document de test de la version~1 avec
l'implémentation figée et le compare à ses références d'origine, octet
pour octet.

\section{Les trois commandes}

\begin{center}
\begin{tabular}{@{}lll@{}}
\toprule
Commande & Rôle & Affichage \\
\midrule
\cmd{chemid*\{clé\}}  & déclaration & aucun \\
\cmd{chemid\{clé\}}   & utilisation & le numéro, cliquable \\
\cmd{chemidhere\{clé\}} & ancre     & aucun \\
\bottomrule
\end{tabular}
\end{center}

\subsection{\cmd{chemid*} — déclarer}

\begin{Verbatim}[frame=single,fontsize=\small]
\chemid*{clé}
\chemid*{clé}{nom riche}
\chemid*{clé}{nom riche}[nom brut]
\chemid*{clé}[nom riche][nom brut]     % variante equivalente
\end{Verbatim}

La déclaration n'imprime rien. \textbf{L'ordre des déclarations fixe la
numérotation} : placez-les dans le préambule, dans l'ordre de votre
schéma de synthèse.

\begin{Verbatim}[frame=single,fontsize=\small]
\chemid*{benz}        % 1
\chemid*{benz.cl}     % 1a
\chemid*{benz.br}     % 1b
\chemid*{amine}       % 2
\end{Verbatim}

\noindent
Le compteur principal avance à chaque nouveau \emph{parent}. Chaque
parent possède son propre compteur de lettres, si bien que vous pouvez
déclarer les enfants plus tard sans casser la numérotation :
\chemid{benz} et \chemid{benz.cl,benz.br}, puis \chemid{amine}.

Un \emph{nom riche} remplace complètement le numéro automatique :

\begin{Verbatim}[frame=single,fontsize=\small]
\chemid*{cible}{cible\textsubscript{finale}}[cible finale]
\end{Verbatim}

\noindent
donne \chemid{cible}. Le second argument, entre crochets, est la version
en texte brut utilisée dans les signets PDF et les métadonnées, où
aucune mise en forme n'est admise. Si vous l'omettez, il est déduit
automatiquement du nom riche (voir §\ref{sec:purify}).

\subsubsection*{Déclarer plusieurs clés d'un coup}

Une liste de clés séparées par des virgules déclare chacune d'elles,
auto-numérotée à son tour — la même convention que \cmd{chemid} :

\begin{Verbatim}[frame=single,fontsize=\small]
\chemid*{mol1,mol2,mol3}     % trois parents : 1, 2, 3
\chemid*{mol1.a,mol1.b}      % deux enfants de mol1 : 1a, 1b
\end{Verbatim}

\noindent
Un nom personnalisé ne peut pas accompagner une déclaration multiple —
\verb|\chemid*{a,b}{nom}| serait ambigu, à quelle clé appartiendrait-il ?
C'est une erreur ; déclarez alors cette clé seule. Une virgule
\emph{à l'intérieur} d'une seule clé (résultat d'une clé mal formée,
p.\,ex. générée par macro) est elle aussi rejetée.

\subsubsection*{Un enfant sans son parent}

Déclarer des enfants en bloc sans jamais déclarer leur parent à part
fonctionne aussi : le parent est créé implicitement (§\ref{sec:parsing}),
avec son propre numéro, et \cmd{chemid} de son nom seul l'affiche
normalement, sans erreur :

\begin{Verbatim}[frame=single,fontsize=\small]
\chemid*{molz.a,molz.b}      % molz n'a jamais ete declare seul
...
\chemid{molz}                 % -> son numero
\end{Verbatim}

\subsection{\cmd{chemid} — utiliser}

\cmd{chemid} accepte une liste de clés séparées par des virgules et
fonctionne partout : corps du texte, \cmd{caption}, titres de section.

\begin{center}
\begin{tabular}{@{}ll l@{}}
\toprule
Appel & Résultat & Règle \\
\midrule
\verb|\chemid{benz}|                  & \chemid{benz}                  & clé simple \\
\verb|\chemid{benz.cl}|               & \chemid{benz.cl}               & clé enfant \\
\verb|\chemid{benz.cl,benz.br,benz.i}|& \chemid{benz.cl,benz.br,benz.i}& 3 contiguës : intervalle \\
\verb|\chemid{benz.cl,benz.br}|       & \chemid{benz.cl,benz.br}       & 2 contiguës \\
\verb|\chemid{benz.cl,benz.i}|        & \chemid{benz.cl,benz.i}        & non contiguës \\
\verb|\chemid{benz,amine.a}|          & \chemid{benz,amine.a}          & familles différentes \\
\verb|\chemid{cible}|                 & \chemid{cible}                 & nom personnalisé \\
\verb|\chemid{seriea,serieb,seriec}|  & \chemid{seriea,serieb,seriec}  & 3 parents consécutifs : intervalle \\
\bottomrule
\end{tabular}
\end{center}

\noindent
L'ordre que vous donnez est respecté tel quel : rien n'est trié. Une
clé non déclarée produit une erreur de compilation et s'imprime
\texttt{??}, comme un \cmd{ref} non résolu.

\noindent
Plusieurs parents simples cités à la suite se contractent en intervalle
exactement comme plusieurs enfants d'un même parent :
\verb|\chemid{seriea,serieb}| (seulement deux, sous le
\opt{range-threshold}) donne encore \chemid{seriea,serieb}, mais un
trou casse l'intervalle plutôt que d'être gommé, par exemple
\chemid{seriea,seriec} pour \verb|\chemid{seriea,seriec}|
(\texttt{serieb} non cité entre les deux). Un nom personnalisé, une clé
non déclarée ou une clé enfant ne rejoignent jamais une telle suite —
ils la terminent simplement, comme le ferait une famille différente.

\subsection{\cmd{chemidhere} — ancrer}
\label{sec:anchor}

\cmd{chemidhere\{clé\}} pose la cible du lien. Placez-la dans la figure
qui montre le composé, typiquement près du \cmd{caption} :

\begin{Verbatim}[frame=single,fontsize=\small]
\begin{figure}
  \centering
  \includegraphics{schema}
  \chemidhere{benz}\chemidhere{benz.cl}\chemidhere{benz.br}
  \caption{Halogenation de \chemid{benz}}
\end{figure}
\end{Verbatim}

% Ancres reelles de ce manuel : les numeros imprimes plus haut sont
% cliquables et amenent ici.
\chemidhere{benz}\chemidhere{benz.cl}\chemidhere{benz.br}\chemidhere{benz.i}%
\chemidhere{amine}\chemidhere{amine.a}\chemidhere{amine.b}\chemidhere{cible}%
\chemidhere{seriea,serieb,seriec}\chemidhere{lcoum,ser}

\noindent
Elle n'imprime rien et ne modifie \emph{jamais} la mise en page, en mode
horizontal comme en mode vertical (c'est vérifié par la suite de tests).
Un clic amène le lecteur sur la figure ; le format PDF ne permet pas de
viser une sous-partie d'une image, une ancre y étant un point et non une
zone.

\subsubsection*{Plusieurs clés, et des familles entières, d'un coup}

\cmd{chemidhere} accepte une liste, avec la même convention de virgule
que \cmd{chemid} et \cmd{chemid*}. Et comme un schéma montre en
général un parent avec tous ses enfants, nommer le \emph{parent} ancre
la famille :

\begin{Verbatim}[frame=single,fontsize=\small]
\chemidhere{cmbr.4,cmbr.6,cmbr.8}   % trois cles, trois ancres
\chemidhere{cmbr}                   % les memes trois, plus cmbr
\chemidhere{cmbr,cmal}              % deux familles en un appel
\end{Verbatim}

\noindent
Un enfant qui porte une ancre à lui est laissé tranquille par l'ancre
de famille — l'explicite l'emporte, sans rien signaler. Les enfants
déclarés \emph{après} le schéma sont ancrés eux aussi, étant relus du
\texttt{.aux}. \opt{anchor-children} à \opt{false} limite
\cmd{chemidhere\{parent\}} au parent seul.

\subsubsection*{Diagnostics}

Poser deux fois l'ancre d'une même clé déclenche un avertissement : la
cible PDF serait ambiguë. Utiliser une clé jamais déclarée est une
erreur. Enfin, une clé utilisée mais jamais ancrée est signalée en fin
de compilation, comme un \cmd{ref} non résolu — et, la version~2
n'ayant nulle part où envoyer ce lien, elle est imprimée sans lien du
tout (§\ref{sec:strict}).

\subsubsection*{\cmd{herechemid}, l'ancien nom}

La version~1 appelait cette commande \cmd{herechemid}. Elle fonctionne
toujours, et continuera de fonctionner, mais c'était la seule à sortir
du rang parmi \cmd{chemid}, \cmd{chemidkey}, \cmd{chemidnote},
\cmd{chemidscheme} et \cmd{chemidsetup} ; l'employer le signale une
fois par document.

\section{Ce qui se passe dans la table des matières et les signets}

Un numéro de composé dans un titre de section doit se comporter
différemment selon l'endroit où ce titre est réutilisé.

\begin{center}
\begin{tabular}{@{}ll@{}}
\toprule
Contexte & Comportement \\
\midrule
Corps du texte, légende, titre affiché & numéro cliquable \\
Table des matières, liste des figures  & numéro affiché, \emph{non} cliquable \\
Signets PDF, métadonnées               & texte brut, sans mise en forme \\
\bottomrule
\end{tabular}
\end{center}

\noindent
Le lien est retiré de la table des matières parce que l'entrée est
\emph{déjà} un lien vers la section : deux liens imbriqués ne sont pas
représentables en PDF. Les trois rendus sont produits par le même code
interne, entièrement expansible, ce qui garantit qu'ils ne peuvent pas
diverger.

\section{Numérotation}

\subsection{Clés}
\label{sec:parsing}

Une clé s'écrit \texttt{parent} ou \texttt{parent.enfant} — un seul
niveau de hiérarchie ; \texttt{a.b.c} est une erreur. Les clés
distinguent la casse et acceptent chiffres, tirets et soulignés
(\texttt{2eme}, \texttt{ma\_cle}, \texttt{compose-3}), mais pas de
virgule : c'est le séparateur de liste de \cmd{chemid} et \cmd{chemid*}.

Déclarer \texttt{parent.enfant} sans avoir déclaré \texttt{parent} crée
ce dernier automatiquement, avec son propre numéro, et le signale dans
le \texttt{.log}. L'option \opt{implicit-parent=false} en fait une
erreur.

\subsection{Au-delà de 26 enfants}

Les lettres continuent au-delà de \texttt{z} : \texttt{aa}, \texttt{ab},
\dots{} Il n'y a pas de limite à 26.

\subsection{Remise à zéro}

\cmd{chemidreset} remet le compteur principal à zéro : la prochaine
déclaration repartira de 1. C'est le seul reset offert — pas de remise à
une valeur arbitraire, pas de reset partiel. Les composés déjà déclarés
conservent le numéro qui leur a été attribué.

\section{Familles à gabarit}
\label{sec:family}

Un parent numérote ses enfants avec des lettres : \texttt{1a},
\texttt{1b}, \texttt{1c}. C'est juste pour une série d'analogues, et
faux pour une série dont les membres se distinguent par quelque chose
que le chimiste nomme déjà --- une longueur de chaîne, un degré
d'oxydation, un substituant. Une \emph{famille} laisse le parent
porter le radical, et chaque enfant ne porter que ce qui varie :

\begin{Verbatim}[frame=single,fontsize=\small]
\chemidfamily{lcoum}{ name = Lcoum-C , placeholder = n }
  \chemid*{lcoum.quatre}{4}
  \chemid*{lcoum.huit}{8}
  \chemid*{lcoum.douze}{12}
\end{Verbatim}

\noindent
\cmd{chemidfamily} déclare le parent, exactement comme le ferait
\cmd{chemid*} --- il prend la même place dans la numérotation --- et
lui donne une forme dont ses enfants héritent. Dans une telle famille,
l'argument qui \emph{nommerait} une clé est lu comme sa \emph{valeur} :
le second argument de \verb|\chemid*{lcoum.quatre}{4}| est le
\texttt{4}, pas un composé appelé « 4 ».

\begin{center}
\begin{tabular}{@{}ll@{}}
\toprule
Écrit & Imprimé \\
\midrule
\verb|\chemid{lcoum.quatre}| & \chemid{lcoum.quatre} \\
\verb|\chemid{lcoum.quatre,lcoum.huit}| & \chemid{lcoum.quatre,lcoum.huit} \\
\verb|\chemid{lcoum.quatre,lcoum.huit,lcoum.douze}| & \chemid{lcoum.quatre,lcoum.huit,lcoum.douze} \\
\verb|\chemid{lcoum}| & \chemid{lcoum} \\
\bottomrule
\end{tabular}
\end{center}

\noindent
Le radical est imprimé \emph{une fois} pour tout un groupe et les
valeurs sont rassemblées dans un seul indice, exactement comme
\texttt{1a,b} factorise le \texttt{1}. Chaque valeur garde son propre
lien, et le radical pointe vers la première.

\subsection{Les options d'une famille}

\begin{center}
\begin{tabular}{@{}llp{5.9cm}@{}}
\toprule
Option & Défaut & Rôle \\
\midrule
\opt{name}            & (vide)           & le radical ; sans lui, le numéro du parent sert de radical \\
\opt{raw}             & déduit           & sa version texte brut, comme pour \cmd{chemid*} \\
\opt{sub-style}       & \opt{sub-style}  & numérotation des enfants sans valeur \\
\opt{child-format}    & \opt{subscript}  & \opt{subscript}, \opt{superscript}, \opt{plain}, ou du code \\
\opt{placeholder}     & (vide)           & ce que \cmd{chemid\{parent\}} montre à la place d'une valeur \\
\opt{placeholder-raw} & déduit           & sa version texte brut \\
\bottomrule
\end{tabular}
\end{center}

\noindent
\opt{child-format} prend l'un des trois mots-clés ou, pour tout ce
qu'ils ne savent pas exprimer, le code lui-même, avec
\cmd{chemidvalue} là où la valeur doit venir :

\begin{Verbatim}[frame=single,fontsize=\small]
\chemidfamily{cu}{ name = Cu , child-format = \textsuperscript{\chemidvalue} }
\end{Verbatim}

\subsection{Les enfants numérotés par la famille}

Un enfant déclaré sans valeur à lui est numéroté par le
\opt{sub-style} de la famille --- \opt{lower-greek} compris, qui est
justement ce dont ces séries sont étiquetées :

\begin{Verbatim}[frame=single,fontsize=\small]
\chemidfamily{ser}{ name = Serie , sub-style = lower-greek ,
                    child-format = plain }
  \chemid*{ser.a}\chemid*{ser.b}\chemid*{ser.c}
\end{Verbatim}

\noindent
\verb|\chemid{ser.a}| donne \chemid{ser.a}, et
\verb|\chemid{ser.a,ser.b,ser.c}| donne \chemid{ser.a,ser.b,ser.c} :
des enfants numérotés automatiquement sont consécutifs, ils se
contractent donc en intervalle comme n'importe quelle autre suite.
Dans les signets PDF, où il n'y a pas de mathématiques à espérer, la
lettre grecque apparaît comme le caractère lui-même.

Les valeurs données à la main, elles, ne se contractent jamais :
\texttt{4}, \texttt{8} et \texttt{12} n'ont aucune notion de
« consécutif », et \texttt{4-12} affirmerait ce que personne n'a
écrit. Elles sont toujours listées une à une.

\subsection{Une famille, une sorte d'enfants}

Dans une famille, soit tous les enfants portent une valeur à eux, soit
aucun. Mélanger les deux est une erreur : ceux du milieu devraient
être numérotés par une règle que les autres ne suivent visiblement
pas, et aucune lecture de la liste ne serait honnête. L'enfant est
tout de même déclaré --- un diagnostic ne doit pas décaler la
numérotation de tout ce qui suit.

\section{Options}

Elles se donnent au chargement, ou à tout moment avec
\cmd{chemidsetup\{\dots\}} ; dans ce dernier cas elles suivent la portée
du groupe \TeX{} courant.

\begin{center}
\begin{tabular}{@{}llp{6.2cm}@{}}
\toprule
Option & Défaut & Rôle \\
\midrule
\opt{list-sep}        & \verb|{, }|   & entre deux familles \\
\opt{last-sep}        & \verb|{ and }| & avant la dernière famille \\
\opt{sub-sep}         & \verb|{,}|    & entre lettres d'une même famille \\
\opt{range-sep}       & \verb|{-}|    & dans un intervalle \texttt{1a-c} \\
\opt{range-threshold} & \opt{3}       & taille à partir de laquelle on contracte en intervalle \\
\opt{format}          & (vide)        & mise en forme appliquée à chaque identifiant, p.\,ex. \verb|\textbf| \\
\opt{main-style}      & \opt{arabic}  & \opt{arabic}, \opt{alph}, \opt{Alph}, \opt{roman}, \opt{Roman} \\
\opt{sub-style}       & \opt{alph}    & idem, plus \opt{lower-greek}, pour la lettre \\
\opt{prefix}          & \verb|{chemid.}| & préfixe des ancres PDF \\
\opt{unknown-text}    & \verb|{??}|   & affichage d'une clé non déclarée \\
\opt{purify}          & \opt{true}    & déduire le nom brut du nom riche \\
\opt{implicit-parent} & \opt{true}    & créer un parent manquant automatiquement \\
\opt{strict-anchors}  & \opt{true}    & pas d'ancre, pas de lien — §\ref{sec:strict} \\
\opt{links}           & \opt{true}    & \opt{false} supprime tout lien et toute ancre \\
\opt{anchor-children} & \opt{true}    & \cmd{chemidhere\{parent\}} ancre la famille \\
\opt{version}         & \opt{2}       & implémentation à charger, §\ref{sec:version} \\
\opt{auto-lang}       & \opt{true}    & voir §\ref{sec:lang} \\
\bottomrule
\end{tabular}
\end{center}

\noindent
La convention typographique des revues de chimie — numéros en gras — se
demande ainsi :

\begin{Verbatim}[frame=single,fontsize=\small]
\usepackage[format=\textbf]{chemidentifier}
\end{Verbatim}

\section{Document multilingue}
\label{sec:lang}

Le séparateur devant le dernier élément est, par défaut, l'anglais
\verb|and| (\opt{last-sep}). Pour choisir une langue fixe, sans
\texttt{babel} :

\begin{Verbatim}[frame=single,fontsize=\small]
\usepackage[last-sep={~et~}]{chemidentifier}   % au chargement
\chemidsetup{last-sep={~et~}}                  % ou a tout moment
\end{Verbatim}

Dans une thèse mêlant plusieurs langues avec \texttt{babel}, le
séparateur suit automatiquement la langue courante — celle que
\cmd{selectlanguage} vient de fixer — sans rien demander de plus :

\begin{Verbatim}[frame=single,fontsize=\small]
\usepackage[french,ngerman,spanish,italian,english]{babel}
...
\selectlanguage{french}   \chemid{a,b}   % ... et ...
\selectlanguage{ngerman}  \chemid{a,b}   % ... und ...
\selectlanguage{spanish}  \chemid{a,b}   % ... y ...
\selectlanguage{italian}  \chemid{a,b}   % ... e ...
\selectlanguage{english}  \chemid{a,b}   % ... and ...
\end{Verbatim}

\noindent
Le mécanisme lit \cmd{languagename}, que babel met à jour à chaque
\cmd{selectlanguage}, de façon entièrement expansible : il fonctionne
donc identiquement dans le texte, la table des matières et les signets
PDF. Sans babel chargé, ou pour une langue non enregistrée, le
paquetage retombe silencieusement sur l'option \opt{last-sep}.

Cinq langues sont connues par défaut, avec leurs variantes babel
usuelles :

\begin{center}
\begin{tabular}{@{}lll@{}}
\toprule
Langue & Séparateur & Noms babel reconnus \\
\midrule
anglais  & \texttt{and} & \texttt{english}, \texttt{american}, \texttt{british}, \texttt{australian}, \texttt{UKenglish}, \texttt{USenglish} \\
français & \texttt{et}  & \texttt{french}, \texttt{francais}, \texttt{acadian}, \texttt{canadien} \\
allemand & \texttt{und} & \texttt{german}, \texttt{ngerman}, \texttt{austrian}, \texttt{naustrian} \\
espagnol & \texttt{y}   & \texttt{spanish}, \texttt{mexican} \\
italien  & \texttt{e}   & \texttt{italian} \\
\bottomrule
\end{tabular}
\end{center}

\noindent
Pour ajouter ou redéfinir une langue :

\begin{Verbatim}[frame=single,fontsize=\small]
\chemidaddlanguage{portuges}{ e }
\end{Verbatim}

\noindent
Pour désactiver la bascule automatique — un séparateur fixe, quelle que
soit la langue courante — mettez \opt{auto-lang=false} ; \opt{last-sep}
redevient alors la seule source, comme avant l'introduction de cette
fonctionnalité. Comme toute option, cela peut se faire localement dans
un groupe :

\begin{Verbatim}[frame=single,fontsize=\small]
\begingroup
  \chemidsetup{auto-lang=false,last-sep={ ou bien }}
  \chemid{a,b}                          % ... ou bien ...
\endgroup
\chemid{a,b}                            % la langue reprend la main
\end{Verbatim}

\section{Deux points à connaître}

\subsection{Le nom brut déduit automatiquement}
\label{sec:purify}

Quand vous donnez un nom riche sans son équivalent brut, celui-ci est
déduit avec \cmd{text\_purify:n} d'expl3 : \verb|H\textsubscript{2}O|
devient \texttt{H2O}. Le résultat est bon sur les cas courants
(indices, exposants, gras, italique) mais \textbf{n'est pas garanti} sur
des mathématiques imbriquées. Pour un nom riche non trivial, donnez la
version brute vous-même :

\begin{Verbatim}[frame=single,fontsize=\small]
\chemid*{k}{$\alpha$-D-glucopyranose}[alpha-D-glucopyranose]
\end{Verbatim}

\subsection{Un numéro n'est un lien que s'il mène quelque part}
\label{sec:strict}

Un composé jamais ancré est imprimé comme un numéro ordinaire : aucun
lien, plutôt qu'un lien atterrissant là où le lecteur PDF voudra bien
le poser. C'est \opt{strict-anchors}, activé par défaut en version~2.

Pour cela, le paquetage doit savoir, au moment où il imprime un
numéro, si une ancre existe \emph{quelque part} dans le document — ce
qu'il ne peut pas savoir en avançant. Les ancres sont donc mémorisées
dans le \texttt{.aux} et relues à la compilation suivante : la
première ne met de lien que sur ce qu'elle a déjà vu ancré, la
deuxième les met tous, et cela ne bouge plus. La même contrepartie que
\cmd{ref}/\cmd{label}, et pour la même raison.

Le cas du parent mérite d'être connu. Un schéma n'ancre souvent que
les enfants — \cmd{chemidhere\{parent.a\}},
\cmd{chemidhere\{parent.b\}} — alors que le texte cite aussi le parent
seul. Plutôt que de supprimer ce lien, le paquetage l'envoie vers le
\emph{premier enfant ancré} : \cmd{chemid\{parent\}} arrive sur la
même figure, c'est-à-dire là où le lecteur voulait aller. Avec
\cmd{chemidhere\{parent\}} (§\ref{sec:anchor}), la question ne se
pose même pas, le parent étant ancré lui aussi.

\opt{strict-anchors} à \opt{false} rétablit le comportement de la
version~1 : le lien est toujours écrit, et seule l'absence d'ancre est
signalée en fin de compilation.

\subsection{Couper tous les liens}

\opt{links=false} retire toute la couche d'hyperliens : pas de
\cmd{hyperlink} autour d'un numéro, et pas de \cmd{hypertarget} non
plus, même là où un \cmd{chemidhere} en demande une. Le bilan de fin
de document sur les composés sans ancre se tait également, n'ayant
plus rien à protéger. La numérotation, les noms et tout le reste du
rendu sont inchangés.

\begin{Verbatim}[frame=single,fontsize=\small]
\usepackage[links=false]{chemidentifier}
\chemidsetup{links=false}     % ou a partir d'ici, ou dans un groupe
\end{Verbatim}

\section{Déclarer après avoir utilisé}
\label{sec:forward}

\cmd{chemid} et \cmd{chemidhere} peuvent apparaître \emph{avant} le
\cmd{chemid*} qui déclare la clé — utile pour ne pas être contraint de
tout déclarer en tête de document, en particulier lorsque la table des
matières précède le texte :

\begin{Verbatim}[frame=single,fontsize=\small]
Le compose \chemid{mol1} est cite ici, avant sa declaration.
...
\chemid*{mol1}
\end{Verbatim}

\noindent
Chaque clé déclarée est enregistrée dans le \texttt{.aux} à la fin de la
compilation (numéro, lettre, nom riche, nom brut), et relue au
\cmd{begin}\texttt{\{document\}} suivant — le même mécanisme que
\cmd{label}/\cmd{ref}, avec la même contrepartie : la première
compilation affiche \texttt{??} pour toute référence en avance sur sa
déclaration, la deuxième la résout, et le résultat reste stable ensuite,
puisque l'ordre des déclarations ne dépend jamais de l'endroit où elles
sont utilisées. Une clé encore inconnue à la fin de la deuxième passe
est réellement non déclarée : l'erreur reste alors affichée.

\noindent
Si vous n'avez pas de contrainte particulière, déclarer en tête de
préambule reste ce qu'il y a de plus simple : le numéro est connu dès
la lecture de la clé, sans référence en avant à résoudre.

\section{Substitution de texte dans les figures \texttt{.pdf\_tex} (LuaLaTeX uniquement)}
\label{sec:pdftex}

Un schéma exporté par Inkscape (une paire \texttt{.pdf\_tex} +
\texttt{.pdf}) peut avoir ses étiquettes de composés reliées à
\cmd{chemid}, comme \texttt{psfrag} rustinait autrefois du texte dans
des figures \texttt{.eps} — sans les scories du \texttt{.eps}/psfrag :
un \texttt{.pdf\_tex} n'est que du texte \LaTeX{} qui appelle
\cmd{includegraphics}, donc une simple substitution ligne par ligne
suffit. Cela demande de compiler avec \texttt{lualatex} (ou tout autre
moteur fournissant \cmd{directlua}) : la substitution est faite en
Lua, qui lit le fichier comme du texte brut et rend la main à \TeX{}
une fois les marqueurs remplacés. Le fichier sur le disque n'est
jamais modifié : réexporter depuis Inkscape ne perd donc rien.

Une alternative en \TeX{} pur, à base de manipulation de catcodes (à
la \texttt{psfrag}), a été envisagée puis écartée : un
\texttt{.pdf\_tex} est du vrai code \TeX/PGF, plein de \verb|\|,
\verb|{|, \verb|}|, \verb|%|, \verb|#|, \verb|_|, \verb|~|... Le lire
tel quel puis le ré-exécuter comme du code demanderait qu'un même
caractère porte deux catcodes contradictoires — inerte pendant la
lecture, actif pendant l'exécution — pour un contenu arbitraire :
exactement ce qui rendait \texttt{psfrag} fragile. Lua contourne le
problème en traitant le fichier comme une simple chaîne de bout en
bout, et ne rend la main à \TeX{} qu'à la toute fin, lu alors sous le
régime de catcodes ordinaire de \TeX{}.

Placez dans le dessin un marqueur texte brut pour chaque étiquette de
composé (\texttt{TMP1}, \texttt{TMP2}\ldots ce que vous voulez, à
condition qu'il n'apparaisse pas aussi comme sous-chaîne ailleurs dans
le texte de la figure), puis :

\begin{Verbatim}[frame=single,fontsize=\small]
\usepackage{graphicx}          % necessaire au .pdf_tex lui-meme
\usepackage{chemidentifier}
\chemidsetup{ pdftex-font = \sffamily\small }   % optionnel, une fois

\chemid*{precurseur}
\chemid*{produit}

\begin{figure}
  \centering
  \chemidkey{TMP1}{precurseur}               % TMP1 -> \chemid{precurseur}
  \chemidkey[1.3]{TMP2}{produit}             % 1,3x plus gros que le reste
  \chemidnote{TMPCOND}{K$_2$CO$_3$, acetone, 70~\textcelsius}
  \chemidscheme[0.8]{figures/schema.pdf_tex}   % echelle optionnelle
  \chemidhere{precurseur}\chemidhere{produit}
  \caption{Synthese de \chemid{produit} a partir de \chemid{precurseur}.}
\end{figure}
\end{Verbatim}

\begin{center}
\begin{tabular}{@{}ll@{}}
\toprule
Commande & Rôle \\
\midrule
\cmd{chemidkey[facteur]\{motif\}\{clé\}} & marqueur $\to$ numéro courant du composé, ex.\ \cmd{chemid}\texttt{\{clé\}} \\
\cmd{chemidnote[facteur]\{motif\}\{texte\}} & marqueur $\to$ tout autre texte, libre \\
\cmd{chemidscheme[échelle]\{chemin\}} & lit le fichier, substitue, compose ; étend aussi \cmd{graphicspath} \\
\bottomrule
\end{tabular}
\end{center}

\noindent
\cmd{chemidscheme} consomme la liste \cmd{chemidkey}/\cmd{chemidnote}
en attente au fur et à mesure qu'il lit le fichier : la figure
suivante repart donc automatiquement d'une liste vide — pas d'étape
« vider » séparée à retenir.

La taille d'une étiquette substituée est le produit de trois facteurs
indépendants, pour qu'une figure réduite reste lisible sans retoucher
chaque étiquette à la main :

\begin{enumerate}
  \item \opt{pdftex-font} (\cmd{chemidsetup}) -- la police de base,
        réglée une fois pour toutes, indépendamment du texte du corps
        (sinon Inkscape réinjecte la famille du document, à la taille
        du dessin, souvent trop grande), ex.
        \verb|\chemidsetup{ pdftex-font = \sffamily\fontsize{9}{11}\selectfont }|.
  \item l'\texttt{[échelle]} de \cmd{chemidscheme} -- le même nombre
        transmis au \cmd{svgscale} de la figure, pour que les
        étiquettes suivent la taille du dessin.
  \item le \texttt{[facteur]} optionnel de \cmd{chemidkey}/\cmd{chemidnote}
        -- une étiquette isolée par rapport aux autres de la même
        figure ; vaut \texttt{1} par défaut.
\end{enumerate}

Sous un moteur non-Lua, \cmd{chemidscheme} déclenche une erreur claire
plutôt que de ne rien faire silencieusement ou de mal rendre le
schéma. \cmd{chemidkey} prend le numéro \emph{courant} du composé :
elle ne déclare ni ne renumérote rien, les clés doivent donc toujours
avoir leur \cmd{chemid*} déclaré par ailleurs.

\section{Limites assumées}

\begin{itemize}
  \item Un seul niveau de hiérarchie (\texttt{parent.enfant}), familles
        comprises.
  \item Les listes ne sont pas triées ni dédoublonnées : ce que vous
        écrivez est ce qui est imprimé — \verb|\chemid{a,b,a}| affiche
        \texttt{1, 2 and 1}, sans erreur.
  \item \texttt{cleveref} n'est pas géré (hors périmètre).
  \item Une clé supprimée du document continue de se résoudre à sa
        dernière valeur connue tant que le \texttt{.aux} n'a pas été
        effacé — la même limite que \cmd{ref}/\cmd{label}.
  \item Les arguments optionnels de \cmd{chemid*} ne sont reconnus que
        \emph{collés} à la clé, sans le moindre espace ni saut de
        ligne : \verb|\chemid*{k}{riche}[brut]|. La moindre espace avant
        \verb|{| ou \verb|[| les exclut de la lecture ; le contenu qui
        suit est alors traité comme du texte ordinaire, jamais absorbé.
\end{itemize}

\end{document}