\documentclass[a4paper,11pt]{article}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage[english]{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[version=1]{chemidentifier}
% this manual is written in English, the package's default (see §7)

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

% --- compounds used in this manual's examples --------------------------
\chemid*{benz}
\chemid*{benz.cl}
\chemid*{benz.br}
\chemid*{benz.i}
\chemid*{amine}
\chemid*{amine.a}
\chemid*{amine.b}
\chemid*{target}{target\textsubscript{final}}[final target]
\chemid*{seriesa}
\chemid*{seriesb}
\chemid*{seriesc}

\title{The \texttt{chemidentifier} package, version 1}
\author{Aliocha SKRZYPCZAK \\ \small Version 1.0.0 --- frozen}
\date{2026-08-17}

\begin{document}
\maketitle

\begin{center}
\fbox{\begin{minipage}{0.9\textwidth}
\small This manual describes \textbf{version 1}, which is frozen: it is
kept unchanged for the documents already written against it, and is
loaded with \cmd{usepackage[version=1]\{chemidentifier\}}. Version 2,
the one \cmd{usepackage\{chemidentifier\}} now loads, has its own
manual (\texttt{chemidentifier-doc.pdf}): it renames \cmd{herechemid}
to \cmd{chemidhere}, leaves a compound with no anchor unlinked rather
than pointing at nothing, and adds templated families.
\end{minipage}}
\end{center}
\bigskip

\begin{abstract}
\noindent
\texttt{chemidentifier} numbers the compounds of a synthesis-chemistry
paper in \emph{the logical order of the synthesis} — the order in which
you declare them — rather than the order in which they appear in the
text. Every printed number is clickable and jumps to the scheme showing
the compound. The package is written in \LaTeX3 (expl3); like
\cmd{ref}/\cmd{label}, everything settles over \textbf{two
compilations}.
\end{abstract}

\tableofcontents

\section{Installation and loading}

Copy \texttt{chemidentifier.sty} next to your document, or run
\texttt{make install} to install it into \texttt{\textasciitilde/texmf}.

\begin{Verbatim}[frame=single,fontsize=\small]
\usepackage{hyperref}          % preferably before chemidentifier
\usepackage[version=1]{chemidentifier}
\end{Verbatim}

\noindent
\texttt{hyperref} is not loaded by the package: it is \emph{detected},
leaving you full control over its options and the loading order. If it
is missing, everything is still numbered normally, nothing is
clickable, and a warning reports it once.

\section{The three commands}

\begin{center}
\begin{tabular}{@{}lll@{}}
\toprule
Command & Role & Output \\
\midrule
\cmd{chemid*\{key\}}  & declaration & none \\
\cmd{chemid\{key\}}   & use & the number, clickable \\
\cmd{herechemid\{key\}} & anchor     & none \\
\bottomrule
\end{tabular}
\end{center}

\subsection{\cmd{chemid*} — declaring}

\begin{Verbatim}[frame=single,fontsize=\small]
\chemid*{key}
\chemid*{key}{rich name}
\chemid*{key}{rich name}[raw name]
\chemid*{key}[rich name][raw name]     % equivalent variant
\end{Verbatim}

The declaration prints nothing. \textbf{The order of declarations sets
the numbering}: place them in the preamble, in the order of your
synthesis scheme.

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

\noindent
The main counter advances on every new \emph{parent}. Each parent has
its own letter counter, so you can declare children later without
breaking the numbering: \chemid{benz} and \chemid{benz.cl,benz.br},
then \chemid{amine}.

A \emph{rich name} entirely replaces the automatic number:

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

\noindent
gives \chemid{target}. The second argument, in brackets, is the
plain-text version used in PDF bookmarks and metadata, where no
formatting is allowed. If you omit it, it is derived automatically
from the rich name (see §\ref{sec:purify}).

\subsubsection*{Declaring several keys at once}

A comma-separated list of keys declares each of them, auto-numbered in
turn — the same convention as \cmd{chemid}:

\begin{Verbatim}[frame=single,fontsize=\small]
\chemid*{mol1,mol2,mol3}     % three parents: 1, 2, 3
\chemid*{mol1.a,mol1.b}      % two children of mol1: 1a, 1b
\end{Verbatim}

\noindent
A custom name cannot accompany a multiple declaration —
\verb|\chemid*{a,b}{name}| would be ambiguous: which key would it
belong to? This is an error; declare that key on its own instead. A
comma \emph{inside} a single key (the result of a malformed key, e.g.\
one built by a macro) is also rejected.

\subsubsection*{A child without its parent}

Declaring children in bulk without ever declaring their parent on its
own also works: the parent is created implicitly (§\ref{sec:parsing}),
with its own number, and \cmd{chemid} of its name alone prints it
normally, without error:

\begin{Verbatim}[frame=single,fontsize=\small]
\chemid*{molz.a,molz.b}      % molz was never declared on its own
...
\chemid{molz}                 % -> its number
\end{Verbatim}

\subsection{\cmd{chemid} — using}

\cmd{chemid} accepts a comma-separated list of keys and works
everywhere: body text, \cmd{caption}, section titles.

\begin{center}
\begin{tabular}{@{}ll l@{}}
\toprule
Call & Result & Rule \\
\midrule
\verb|\chemid{benz}|                  & \chemid{benz}                  & plain key \\
\verb|\chemid{benz.cl}|               & \chemid{benz.cl}               & child key \\
\verb|\chemid{benz.cl,benz.br,benz.i}|& \chemid{benz.cl,benz.br,benz.i}& 3 contiguous: range \\
\verb|\chemid{benz.cl,benz.br}|       & \chemid{benz.cl,benz.br}       & 2 contiguous \\
\verb|\chemid{benz.cl,benz.i}|        & \chemid{benz.cl,benz.i}        & non-contiguous \\
\verb|\chemid{benz,amine.a}|          & \chemid{benz,amine.a}          & different families \\
\verb|\chemid{target}|                & \chemid{target}                & custom name \\
\verb|\chemid{seriesa,seriesb,seriesc}| & \chemid{seriesa,seriesb,seriesc} & 3 consecutive parents: range \\
\bottomrule
\end{tabular}
\end{center}

\noindent
The order you give is respected as-is: nothing is sorted. An
undeclared key produces a compilation error and prints \texttt{??},
like an unresolved \cmd{ref}.

\noindent
Several plain parents cited in a row contract into a range exactly like
several children of the same parent do: \verb|\chemid{seriesa,seriesb}|
(only two, below \opt{range-threshold}) still gives
\chemid{seriesa,seriesb}, but a gap breaks the range rather than being
papered over, e.g.\ \chemid{seriesa,seriesc} for
\verb|\chemid{seriesa,seriesc}| (\texttt{seriesb} not cited in between).
A custom name, an undeclared key, or a child key never joins such a
run — it simply ends it, exactly as a different family would.

\subsection{\cmd{herechemid} — anchoring}

\cmd{herechemid\{key\}} places the target of the link. Put it in the
figure that shows the compound, typically near the \cmd{caption}:

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

% Real anchors for this manual: the numbers printed above are clickable
% and land here.
\herechemid{benz}\herechemid{benz.cl}\herechemid{benz.br}\herechemid{benz.i}%
\herechemid{amine}\herechemid{amine.a}\herechemid{amine.b}\herechemid{target}

\noindent
It prints nothing and \emph{never} affects the layout, in horizontal
mode as well as in vertical mode (this is checked by the test suite).
A click brings the reader to the figure; the PDF format does not allow
targeting a sub-part of an image, an anchor there being a point, not
an area.

Placing the anchor of the same key twice triggers a warning: the PDF
target would be ambiguous. Using a key that was never declared is an
error. Finally, a key that is used but never anchored is reported at
the end of compilation, like an unresolved \cmd{ref}.

\section{What happens in the table of contents and bookmarks}

A compound number in a section title must behave differently depending
on where that title gets reused.

\begin{center}
\begin{tabular}{@{}ll@{}}
\toprule
Context & Behaviour \\
\midrule
Body text, caption, displayed title & clickable number \\
Table of contents, list of figures  & number shown, \emph{not} clickable \\
PDF bookmarks, metadata             & plain text, no formatting \\
\bottomrule
\end{tabular}
\end{center}

\noindent
The link is dropped from the table of contents because the entry is
\emph{already} a link to the section: two nested links cannot be
represented in PDF. The three renderings are produced by the same,
fully expandable internal code, which guarantees they cannot diverge.

\section{Numbering}

\subsection{Keys}
\label{sec:parsing}

A key is written \texttt{parent} or \texttt{parent.child} — a single
level of hierarchy; \texttt{a.b.c} is an error. Keys are case-sensitive
and accept digits, hyphens and underscores (\texttt{2nd},
\texttt{my\_key}, \texttt{compound-3}), but no comma: that is the list
separator of \cmd{chemid} and \cmd{chemid*}.

Declaring \texttt{parent.child} without having declared \texttt{parent}
creates the latter automatically, with its own number, and reports it
in the \texttt{.log}. The option \opt{implicit-parent=false} turns this
into an error instead.

\subsection{Beyond 26 children}

Letters keep going past \texttt{z}: \texttt{aa}, \texttt{ab}, \dots{}
There is no limit at 26.

\subsection{Resetting}

\cmd{chemidreset} resets the main counter to zero: the next declaration
will start again from 1. This is the only reset offered — no resetting
to an arbitrary value, no partial reset. Compounds already declared
keep the number they were given.

\section{Options}

They are given at load time, or at any point with
\cmd{chemidsetup\{\dots\}}; in the latter case they follow the scope of
the current \TeX{} group.

\begin{center}
\begin{tabular}{@{}llp{6.2cm}@{}}
\toprule
Option & Default & Role \\
\midrule
\opt{list-sep}        & \verb|{, }|   & between two families \\
\opt{last-sep}        & \verb|{ and }| & before the last family \\
\opt{sub-sep}         & \verb|{,}|    & between letters of the same family \\
\opt{range-sep}       & \verb|{-}|    & inside a range \texttt{1a-c} \\
\opt{range-threshold} & \opt{3}       & size from which a range is contracted \\
\opt{format}          & (empty)       & formatting applied to each identifier, e.g.\ \verb|\textbf| \\
\opt{main-style}      & \opt{arabic}  & \opt{arabic}, \opt{alph}, \opt{Alph}, \opt{roman}, \opt{Roman} \\
\opt{sub-style}       & \opt{alph}    & same, for the letter \\
\opt{prefix}          & \verb|{chemid.}| & prefix of PDF anchors \\
\opt{unknown-text}    & \verb|{??}|   & shown for an undeclared key \\
\opt{purify}          & \opt{true}    & derive the raw name from the rich name \\
\opt{implicit-parent} & \opt{true}    & create a missing parent automatically \\
\opt{strict-anchors}  & \opt{false}   & see §\ref{sec:strict} \\
\opt{auto-lang}       & \opt{true}    & see §\ref{sec:lang} \\
\bottomrule
\end{tabular}
\end{center}

\noindent
The chemistry-journal typographic convention — bold numbers — is
obtained as follows:

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

\section{Multilingual documents}
\label{sec:lang}

The separator before the last item is, by default, the English
\verb|and| (\opt{last-sep}). To choose a fixed language, without
\texttt{babel}:

\begin{Verbatim}[frame=single,fontsize=\small]
\usepackage[last-sep={~et~}]{chemidentifier}   % at load time
\chemidsetup{last-sep={~et~}}                  % or at any time
\end{Verbatim}

In a thesis mixing several languages with \texttt{babel}, the
separator automatically follows the current language — the one that
\cmd{selectlanguage} just set — without anything further needed:

\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
The mechanism reads \cmd{languagename}, which babel updates on every
\cmd{selectlanguage}, in a fully expandable way: it therefore works
identically in the text, the table of contents and PDF bookmarks.
Without babel loaded, or for an unregistered language, the package
silently falls back to the \opt{last-sep} option.

Five languages are known by default, with their usual babel variants:

\begin{center}
\begin{tabular}{@{}lll@{}}
\toprule
Language & Separator & Recognized babel names \\
\midrule
English  & \texttt{and} & \texttt{english}, \texttt{american}, \texttt{british}, \texttt{australian}, \texttt{UKenglish}, \texttt{USenglish} \\
French   & \texttt{et}  & \texttt{french}, \texttt{francais}, \texttt{acadian}, \texttt{canadien} \\
German   & \texttt{und} & \texttt{german}, \texttt{ngerman}, \texttt{austrian}, \texttt{naustrian} \\
Spanish  & \texttt{y}   & \texttt{spanish}, \texttt{mexican} \\
Italian  & \texttt{e}   & \texttt{italian} \\
\bottomrule
\end{tabular}
\end{center}

\noindent
To add or redefine a language:

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

\noindent
To disable the automatic switch — a fixed separator, whatever the
current language — set \opt{auto-lang=false}; \opt{last-sep} then
becomes the sole source again, as before this feature existed. Like
any option, this can be done locally inside a group:

\begin{Verbatim}[frame=single,fontsize=\small]
\begingroup
  \chemidsetup{auto-lang=false,last-sep={ or else }}
  \chemid{a,b}                          % ... or else ...
\endgroup
\chemid{a,b}                            % the language takes over again
\end{Verbatim}

\section{Two points worth knowing}

\subsection{The raw name derived automatically}
\label{sec:purify}

When you give a rich name without its raw counterpart, the latter is
derived using expl3's \cmd{text\_purify:n}: \verb|H\textsubscript{2}O|
becomes \texttt{H2O}. The result is good for common cases (subscripts,
superscripts, bold, italics) but \textbf{is not guaranteed} for nested
mathematics. For a non-trivial rich name, provide the raw version
yourself:

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

\subsection{Links without a target}
\label{sec:strict}

Links rely on \cmd{hyperlink}/\cmd{hypertarget}, resolved by the PDF
reader, and not on the \texttt{.aux} file. The trade-off is that at the
moment
\cmd{chemid} prints a number, the package cannot know whether the
corresponding anchor will be placed further on: the link is therefore
always written, and the missing anchor is reported at the end of
compilation.

If you would rather a compound that is never anchored have no link at
all, enable \opt{strict-anchors}: anchors are then remembered in the
\texttt{.aux}, which requires \emph{two} compilations, like \cmd{ref}.

\section{Declaring after using}
\label{sec:forward}

\cmd{chemid} and \cmd{herechemid} may appear \emph{before} the
\cmd{chemid*} that declares the key — useful when you don't want to be
forced to declare everything at the top of the document, in particular
when the table of contents precedes the text:

\begin{Verbatim}[frame=single,fontsize=\small]
Compound \chemid{mol1} is mentioned here, before its declaration.
...
\chemid*{mol1}
\end{Verbatim}

\noindent
Every declared key is recorded in the \texttt{.aux} at the end of
compilation (number, letter, rich name, raw name), and read back on
the next \cmd{begin}\texttt{\{document\}} — the same mechanism as
\cmd{label}/\cmd{ref}, with the same trade-off: the first compilation
shows \texttt{??} for any reference ahead of its declaration, the
second resolves it, and the result stays stable afterwards, since the
order of declarations never depends on where they are used. A key
still unknown at the end of the second pass is genuinely undeclared:
the error then keeps showing.

\noindent
If you have no particular constraint, declaring at the top of the
preamble remains the simplest approach: the number is then known as
soon as the key is read, with no forward reference to resolve.

\section{Text substitution in \texttt{.pdf\_tex} figures (LuaLaTeX only)}
\label{sec:pdftex}

A scheme exported by Inkscape (a \texttt{.pdf\_tex} + \texttt{.pdf}
pair) can have its compound labels wired to \cmd{chemid}, the same way
\texttt{psfrag} once patched text into \texttt{.eps} figures — without
the \texttt{.eps}/\texttt{psfrag} baggage: a \texttt{.pdf\_tex} is just
\LaTeX{} text calling \cmd{includegraphics}, so a plain, line-by-line
substitution is enough. This requires compiling with \texttt{lualatex}
(or another engine providing \cmd{directlua}): the substitution is
implemented in Lua, reading the file as plain text and handing the
result back to \TeX{} once the placeholders are replaced. The file on
disk is never modified, so re-exporting from Inkscape loses nothing.

A plain-\TeX{} catcode-trick alternative (à la \texttt{psfrag}) was
considered and rejected: a \texttt{.pdf\_tex} is genuine \TeX/PGF code,
full of \verb|\|, \verb|{|, \verb|}|, \verb|%|, \verb|#|, \verb|_|,
\verb|~|... Reading it verbatim and then re-executing it as code
requires the same character to carry two contradictory catcodes —
inert while captured, active while replayed — for arbitrary content,
which is precisely what made \texttt{psfrag} fragile. Lua sidesteps
this entirely by treating the file as a plain string throughout, and
handing the result to \TeX{} only at the very end, read under \TeX's
own, ordinary catcode regime.

Put a plain-text placeholder in the drawing for each compound label
(\texttt{TMP1}, \texttt{TMP2}\ldots anything, as long as it does not
also occur as a substring elsewhere in the figure text), then:

\begin{Verbatim}[frame=single,fontsize=\small]
\usepackage{graphicx}          % needed by the .pdf_tex itself
\usepackage[version=1]{chemidentifier}
\chemidsetup{ pdftex-font = \sffamily\small }   % optional, once

\chemid*{precursor}
\chemid*{product}

\begin{figure}
  \centering
  \chemidkey{TMP1}{precursor}               % TMP1 -> \chemid{precursor}
  \chemidkey[1.3]{TMP2}{product}            % 1.3x bigger than the rest
  \chemidnote{TMPCOND}{K$_2$CO$_3$, acetone, 70~\textcelsius}
  \chemidscheme[0.8]{figures/scheme.pdf_tex}   % scale is optional
  \herechemid{precursor}\herechemid{product}
  \caption{Synthesis of \chemid{product} from \chemid{precursor}.}
\end{figure}
\end{Verbatim}

\begin{center}
\begin{tabular}{@{}ll@{}}
\toprule
Command & Role \\
\midrule
\cmd{chemidkey[factor]\{motif\}\{key\}} & placeholder $\to$ the compound's current number, e.g. \cmd{chemid}\texttt{\{key\}} \\
\cmd{chemidnote[factor]\{motif\}\{text\}} & placeholder $\to$ any other text, free-form \\
\cmd{chemidscheme[scale]\{path\}} & reads the file, substitutes, typesets; also extends \cmd{graphicspath} \\
\bottomrule
\end{tabular}
\end{center}

\noindent
\cmd{chemidscheme} consumes the pending \cmd{chemidkey}/\cmd{chemidnote}
list as it reads the file, so the next figure automatically starts
from an empty list — there is no separate "clear" step to remember.

The size of a substituted label is the product of three independent
factors, so a figure scaled down still reads fine without retouching
every label by hand:

\begin{enumerate}
  \item \opt{pdftex-font} (\cmd{chemidsetup}) -- the base style, set
        once, independently of the body text (Inkscape otherwise
        reinjects the document's own family, at whatever size the
        drawing used, typically too large), e.g.
        \verb|\chemidsetup{ pdftex-font = \sffamily\fontsize{9}{11}\selectfont }|.
  \item the \texttt{[scale]} of \cmd{chemidscheme} -- the same number
        handed to the figure's own \cmd{svgscale}, so labels
        shrink/grow together with the drawing.
  \item the optional \texttt{[factor]} of \cmd{chemidkey}/\cmd{chemidnote}
        -- one label singled out, relative to the others in the same
        figure; defaults to \texttt{1}.
\end{enumerate}

Under a non-Lua engine, \cmd{chemidscheme} raises a clear error instead
of silently doing nothing or mis-rendering. \cmd{chemidkey} takes the
compound's \emph{current} number: it does not declare or renumber
anything, so keys still need a matching \cmd{chemid*} declared
elsewhere.

\section{Assumed limitations}

\begin{itemize}
  \item A single level of hierarchy (\texttt{parent.child}).
  \item Lists are neither sorted nor deduplicated: what you write is
        what gets printed — \verb|\chemid{a,b,a}| prints
        \texttt{1, 2 and 1}, without error.
  \item \texttt{cleveref} is not handled (out of scope).
  \item A key removed from the document keeps resolving to its last
        known value until the \texttt{.aux} file is cleared — the same
        limitation as \cmd{ref}/\cmd{label}.
  \item The optional arguments of \cmd{chemid*} are only recognized
        when \emph{glued} to the key, with no space or line break at
        all: \verb|\chemid*{k}{rich}[raw]|. Any space before \verb|{|
        or \verb|[| excludes them from being read; the content that
        follows is then treated as ordinary text, never absorbed.
\end{itemize}

\end{document}