summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/chemnum/chemnum_en.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/chemnum/chemnum_en.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/chemnum/chemnum_en.tex')
-rw-r--r--macros/latex/contrib/chemnum/chemnum_en.tex1178
1 files changed, 1178 insertions, 0 deletions
diff --git a/macros/latex/contrib/chemnum/chemnum_en.tex b/macros/latex/contrib/chemnum/chemnum_en.tex
new file mode 100644
index 0000000000..a5abd7365d
--- /dev/null
+++ b/macros/latex/contrib/chemnum/chemnum_en.tex
@@ -0,0 +1,1178 @@
+% arara: pdflatex: { shell: on }
+%! arara: pdflatex: { shell: on }
+% arara: biber
+% arara: pdflatex
+% arara: pdflatex
+\documentclass[load-preamble+,ngerman,british,american]{cnltx-doc}
+\usepackage[utf8]{inputenc}
+\usepackage{chemnum}
+\setcnltx{
+ package = chemnum ,
+ info = numbering of chemical compounds ,
+ authors = Clemens Niederberger ,
+ email = contact@mychemistry.eu ,
+ url = https://github.com/cgnieder/chemnum/ ,
+ add-cmds = {
+ chemnumshowdef,
+ chemnumshowref,
+ cmpd ,
+ initcmpd ,
+ labelcmpd ,
+ cmpdplain ,
+ cmpdproperty ,
+ cmpdref ,
+ replacecmpd ,
+ resetcmpd ,
+ setchemnum ,
+ cmpdshowdef ,
+ cmpdshowref ,
+ newcmpdcounterformat ,
+ subcmpdplain ,
+ submaincmpdplain ,
+ subcmpdproperty ,
+ subcmpdshowdef ,
+ subcmpdshowref ,
+ } ,
+ add-silent-cmds = {
+ arrow,
+ bottomrule,
+ ch,chemfig,chemname,
+ CNlabel,CNlabelnoref,CNlabelsub,CNlabelsubnoref,
+ CNref,CNrefsub,CNsubnoref,
+ compound,cs,
+ declarecompound,definesubmol,detokenize,
+ expandfull,expandtwice,
+ fcite,
+ includegraphics,
+ keyis,
+ marginnote, midrule,
+ NewDocumentCommand,
+ schemestart,schemestop,setatomsep,
+ theffbibliography, toprule
+ } ,
+ index-setup = { othercode=\footnotesize,level=\addsec },
+ makeindex-setup = { columns=3,columnsep=1em } ,
+ add-frame = false
+}
+\usepackage[artemisia]{textgreek}
+\activatechemgreekmapping{textgreek}
+
+\usepackage{chemformula}
+\setchemformula{format=\libertineLF}
+\usepackage{chemfig,relsize}
+\setatomsep{1.78500 em}
+\setbondstyle{line width = 0.06642 em}
+\renewcommand*\printatom[1]{\textsmaller{\ensuremath{\mathsf{#1}}}}
+
+\usepackage{array,booktabs}
+
+\usepackage{graphicx}
+
+\defbibheading{bibliography}[References]{\addsec{#1}}
+
+\usepackage{acro,accsupp}
+\acsetup{
+ short-format = \scshape ,
+ first-style = short
+}
+\DeclareAcronym{pdf}{
+ short = pdf ,
+ long = portable document format ,
+ pdfstring = PDF ,
+ accsupp = PDF
+}
+\DeclareAcronym{eps}{
+ short = eps ,
+ long = encapsulated postscript ,
+ pdfstring = EPS ,
+ accsupp = EPS
+}
+\DeclareAcronym{ps}{
+ short = ps ,
+ long = postscript ,
+ pdfstring = PS ,
+ accsupp = PS
+}
+\DeclareAcronym{id}{
+ short = id ,
+ long = identification key ,
+ pdfstring = ID ,
+ accsupp = ID
+}
+
+\begin{document}
+\selectlanguage{american}
+
+\section{License and Requirements}\label{sec:license-requirements}
+\license
+
+\chemnum\ requires the bundles \bnd{l3kernel}~\cite{bnd:l3kernel} and
+\bnd{l3packages}~\cite{bnd:l3packages}. It also requires the
+\pkg{translations} package~\cite{pkg:translations},
+\pkg{chemgreek}~\cite{pkg:chemgreek} and the \pkg{psfrag}~\cite{pkg:psfrag}
+package.
+
+\section{News}\label{sec:news}
+The \chemnum\ package has been my first attempt to create a comprehensive
+labeling package for chemical compounds. However, it had and has more than
+one weakness and its code was -- to be frank -- a mess. Version~1 is now a
+complete re-write of \chemnum\ where I tried to achieve several points:
+\begin{itemize}
+ \item A cleaner code internally.
+ \item A cleaner user interface, \ie, more user macros for different tasks, a
+ unified naming of the commands and a less redundant naming of the
+ options.
+ \item Extended functionality such as sorting and compressing of sublabel
+ lists and sorting and merging of main label lists.
+\end{itemize}
+
+Although the syntax seems more or less the same at first sight quite a number
+of changes have been made that make version~1 incompatible with version~0.
+While I thought a while about maintaining backwards compatibility version~0
+was known to be in an experimental stage where everything was allowed to be
+changed at any time. So users \emph{could} know there was a risk. I have a
+feeling that many users nevertheless didn't realize this and may be bothered
+by this incompatibility. So I am well aware that the update will
+inconvenience some users. However, since version~0 won't be updated any more
+it made more sense to make a breaking update once.
+
+The same is not true for version~1. The syntax and commands described in this
+manual will not be changed as easily and from this version on I will take care
+of backwards compatibility.
+
+For those people wanting to keep older versions: they are are still available
+from websites such as \website{ctanhg.scharrer-online.de} or
+\securewebsite{bitbucket.org/cgnieder/chemnum}. You can also email me for an
+older version.
+
+Many commands have got a new name! The most important ones are:
+\begin{itemize}
+ \item \cs*{cmpdref}; this is now called \cs{replacecmpd}.
+ \item \cs*{cmpdinit}; this is now called \cs{initcmpd}.
+ \item \cs*{cmpdreset}; this is now called \cs{resetcmpd}.
+ \item \cs*{cmpdsetup}; this is now called \cs{setchemnum}.
+\end{itemize}
+However, there are many more changes. Basically all options have new names
+and often do their thing slightly different from the way things have been
+before.
+
+Please note that this overall change does not mean that version~1 is version~0
+declared stable. It is very likely that version~1 will now have quite a
+number of bugs to be fixed and probably missing features, too. So I'd be very
+glad to receive feedback either on \chemnum's homepage
+\securewebsite{github.com/cgnieder/chemnum} or via email to
+\email{contact@mychemistry.eu}.
+
+\section{Overview over the Available Commands}\label{sec:overv-over-avail}
+
+This section lists all available commands with a brief description. Commands
+marked with \expandablesymbol\ are expandable in an \cs*{edef} like context.
+Most of the commands will be explained in a later section in more detail.
+
+\begin{commands}
+ \command{cmpd}[\sarg\code{+}\oarg{options}\marg{list of \acp{id}}]
+ The main command for creating and refering to compound labels. This
+ command is described in detail in section~\ref{sec:deta-comp-labels}. For
+ many people this will be the only command they need.
+ \command{refcmpd}[\oarg{options}\marg{\ac{id}}]
+ This command only refers to an already defined label but does not define a
+ label itself. This is an alias of \cs{cmpd}\code{+}.
+ \command{labelcmpd}[\oarg{options}\marg{\ac{id}}]
+ This command only defines a new label but does not print it. This is an
+ alias of \cs{cmpd}\sarg.
+ \expandable\command{cmpdplain}[\marg{\ac{id}}]
+ Reads a label and writes it expandably without formatting. It is not able
+ to parse a list. Its sole purpose is usage in \ac{pdf} strings
+ (\cf\ \cs*{texorpdfstring}\marg{\TeX}\marg{\ac{pdf} string}). This
+ command is described in section~\ref{sec:deta-comp-labels}.
+ \expandable\command{subcmpdplain}[\marg{main \ac{id}}\marg{sub \ac{id}}]
+ Reads a sublabel and writes it expandably without formatting. It is not
+ able to parse a list. Its sole purpose is usage in pdfstrings
+ (\cf\ \cs*{texorpdfstring}\marg{\TeX}\marg{\ac{pdf} string}). This
+ command is described in section~\ref{sec:deta-comp-labels}.
+ \expandable\command{submaincmpdplain}[\marg{main \ac{id}}\marg{sub \ac{id}}]
+ Reads a main label and a sublabel and writes them expandably without
+ formatting. It is not able to parse a list. Its sole purpose is usage in
+ \ac{pdf} strings (\cf\ \cs*{texorpdfstring}\marg{\TeX}\marg{\ac{pdf}
+ string}). This command is described in
+ section~\ref{sec:deta-comp-labels}.
+ \command{replacecmpd}[\code{+}\oarg{options}\marg{\ac{id}}]
+ A command for replacing tags in \ac{eps} files, see
+ section~\ref{sec:replacing-tags-aceps} for details.
+ \command{initcmpd}[\oarg{options}\marg{list of \acp{id}}]
+ Initiate compound labels. This command can only be used in the preamble.
+ It is desribed in section~\ref{sec:deta-comp-labels}.
+ \expandable\command{cmpdproperty}[\marg{\ac{id}}\marg{property}]
+ Get the associated property \meta{property} of compound
+ \meta{\ac{id}}. This command is described in
+ section~\ref{sec:deta-comp-labels}.
+ \expandable\command{subcmpdproperty}[\marg{main \ac{id}}\marg{sub
+ \ac{id}}\marg{property}]
+ Get the associated property \meta{property} of subcompound \meta{sub
+ \ac{id}} of compound \meta{main \ac{id}}. This command is described
+ in section~\ref{sec:deta-comp-labels}.
+ \command{newcmpdcounterformat}[\marg{name}\marg{command}]
+ Makes the label format \meta{name} known to \chemnum. \meta{command}
+ needs to be a command that takes an integer number as argument and should
+ return a formatted version of it. In practice you should not need to use
+ this command as the most common formats already are defined. This command
+ is described in section~\ref{sec:change-numbering}.
+ \command{resetcmpd}[\oarg{integer}]\Default{1}
+ Reset the numbering for main compound labels to start with \meta{integer}
+ again. This is the same as
+ \cs*{setcounter}\Marg{cmpdmain}\Marg{$\text{\meta{integer}}-1$}. The
+ command is described in section~\ref{sec:reset-numbering}.
+ \command{cmpdshowdef}[\marg{\ac{id}}]
+ Internal command used to display \meta{\ac{id}} of a newly defined compound
+ label when the option \option{show-keys} is used. The command is
+ described in section~\ref{sec:debugg-inform}.
+ \command{cmpdshowref}[\marg{\ac{id}}]
+ Internal command used to display \meta{\ac{id}} of a referencing compound
+ label when the option \option{show-keys} is used. The command is
+ described in section~\ref{sec:debugg-inform}.
+ \command{subcmpdshowdef}[\marg{main \ac{id}}\marg{sub \ac{id}}]
+ Internal command used to display \meta{main \ac{id}} and \meta{sub
+ \ac{id}} of a newly defined subcompound label when the option
+ \option{show-keys} is used. The command is described in
+ section~\ref{sec:debugg-inform}.
+ \command{subcmpdshowref}[\marg{main \ac{id}}\marg{sub \ac{id}}]
+ Internal command used to display \meta{main \ac{id}} and \meta{sub
+ \ac{id}} of a referencing subcompound label when the option
+ \option{show-keys} is used. The command is described in
+ section~\ref{sec:debugg-inform}.
+\end{commands}
+
+\section{Numbering Compounds}\label{sec:numbering-compounds}
+\subsection{Main Command}\label{sec:main-command}\resetcmpd
+
+The main command of this package is this one:
+\begin{commands}
+ \command{cmpd}[\marg{\ac{id}}]
+ When \meta{\ac{id}} is used the first time, the label is created, saved
+ (= declared) and printed. Each further use just prints the label.
+\end{commands}
+
+\begin{example}
+ Compounds \cmpd{a} and \cmpd{b} are declared and can be used any time:
+ \cmpd{a}. No pre-declaring is necessary. Compounds like \cmpd{c} are
+ numbered in the order they appear in the text.\par
+ Once again: \cmpd{b}, \cmpd{a}, \cmpd{c}.
+\end{example}
+
+If it is necessary to declare a compound without printing the label it is
+possible with
+\begin{commands}
+ \command{cmpd}[\sarg\marg{\ac{id}}]
+ Declare the label \meta{\ac{id}} but don't print anything.
+\end{commands}
+
+\begin{example}
+ The hidden version\cmpd*{d} declares the label but doesn't print anything.
+ The next \cmpd{e} continues to count with the next number. With \cmpd{d}
+ the label can be used, of course.
+\end{example}
+
+You can pretty much use what you like for a label name except for the
+separator symbols (see also section~\ref{sec:chang-input-mark}). Be careful
+with blanks though! Leading and trailing spaces are ignored, spaces at other
+places are not. It's probably best not to use blanks in label names at all.
+
+\begin{example}[add-sourcecode-options={showspaces=true}]
+ \cmpd{aa}, \cmpd{aa }, \cmpd{ aa}, and \cmpd{ aa } all have the same label.
+ Likewise \cmpd{a a}, \cmpd{a a }, \cmpd{ a a}, \cmpd{ a a }, \cmpd{a a},
+ \cmpd{a a }, \cmpd{ a a}, and \cmpd{ a a }.
+\end{example}
+
+\subsection{Sublabels}\label{sec:sublabel}
+If you want a label like \cmpd{a.one}, you need to use the following syntax:
+\begin{commands}
+ \command{cmpd}[\Marg{\meta{main \ac{id}}.\meta{sub \ac{id}}}]
+ \meta{main \ac{id}} is the main name which stays the same, \meta{sub
+ \ac{id}} varies. This syntax means that the point \code{.}
+ \emph{cannot} be a part of \meta{main \ac{id}} or \meta{sub \ac{id}}
+ (except if you enclose the respective \ac{id} in braces). Instead of the
+ point you also can use another symbol, see
+ section~\ref{sec:chang-input-mark} for details.
+\end{commands}
+
+\begin{example}
+ \cmpd{f.one} and \cmpd{f.two} are related, as are \cmpd{g.one} and
+ \cmpd{g.two}. Of course these labels can be used again: \cmpd{g.two} and
+ \cmpd{f.one}.
+\end{example}
+
+This also works if the main name has already been used.
+\begin{example}
+ \cmpd{a} and its variants \cmpd{a.one} and \cmpd{a.two}
+\end{example}
+
+The same way the main name of combined labels can be used solely.
+\begin{example}[side-by-side]
+ \cmpd{f} and \cmpd{g}
+\end{example}
+
+How you can create a combined label like \cmpd{f.{one,two}} is explained in
+section~\ref{sec:lists-rang-subl}.
+
+\subsection{Lists}\label{sec:lists}
+There is actually more to the \cs{cmpd} command. It also prints lists of
+labels. The right description would be something like:
+\begin{commands}
+ \command{cmpd}[\marg{(possibly comma separated list of) label name(s)}]
+ Treats each entry of the list as described before.
+\end{commands}
+This means that with default settings the comma can't be part of the label
+name unless hidden in braces. As separator another symbol can be used, too,
+see section~\ref{sec:chang-input-mark} for details.
+
+\begin{example}
+ More than one label can be put inside \cs{cmpd}, separated by commas. Then
+ a list like \cmpd{a, b, c, e, g.two} is printed.
+\end{example}
+The Harvard comma (see section~\ref{sec:lang-depend-sett}) in \code{, and}
+between \cmpd{e} and \cmpd{g.two} suggests that there are options to customize
+the list, see section~\ref{sec:formatting-labels} for more on this.
+
+The option \option{merge} has an effect on lists: if it is set to \code{true}
+multiple occurences of a main label with a possibly different set of sublabels
+are merged into one label:
+
+\begin{example}
+ With \keyis{merge}{true} a list like \cmpd{c,g.two,a,g.{one,four}} looks
+ like \cmpd[merge=true]{c,g.two,a,g.{one,four}}.
+\end{example}
+
+\subsection{Lists and Ranges of Sublabels}\label{sec:lists-rang-subl}
+Sometimes it can be useful to display a label with a list or a range of
+sublabels. Suppose you have compounds
+\cmpd{q.one,q.two,q.three,q.four,q.five} which for example differ in their
+substituents. It can be useful to refer to them all at once:
+
+The syntax is rather intuitive -- you just input a list of sublabels:
+\begin{example}
+ \setchemnum{compress=false}%
+ list of labels: \cmpd{q.one, q.two, q.three, q.four, q.five}\par
+ label with list of sublabels: \cmpd{q.{one,two,three,four,five}}
+\end{example}
+Since the sublist is input with a comma in the default setting you have to
+put them into braces. If you add a list of sublabels to a main label they
+will always be printed in the order the sublabels have been declared and not
+in the order they're input in the list:
+
+\begin{example}
+ \setchemnum{compress=false}%
+ compare \cmpd{q.{one,two,three,four,five}}
+ with \cmpd{q.{five,four,three,two,one}} and
+ \cmpd{q.{three,four,one,five,two}}
+\end{example}
+
+Using this syntax you also can create ranges of sublabels. For this you
+enable the option \option{compress}. Or rather: this is the default setting.
+If you don't want compressed sublabels you have to disable the option like in
+the previous examples.
+\begin{example}[side-by-side]
+ \cmpd{q.{two,four,three}} \par
+ \cmpd{q.{five,one,three,four}} \par
+ \cmpd{q.{one,three,five,two}}
+\end{example}
+
+Obviously you can't use a comma as part of a sublabel name. You can change
+the input marker, though. See section~\ref{sec:overv-over-avail-1} for
+available options.
+
+Sometimes it can be useful to get only the sublabel without the main label.
+This is achieved with the option \option{sub-only}:
+
+\begin{example}
+ % uses packages `chemfig', `chemformula' and `booktabs'
+ \chemname{\chemfig{*6(=-=-(-R)=-)}}{\cmpd{benzene.{H,Me,OH,NH2}}}
+ \quad
+ \begin{tabular}{lll}
+ \toprule
+ & \ch{-R} & Name \\
+ \midrule
+ \cmpd[sub-only]{benzene.H} & \ch{-H} & Benzene \\
+ \cmpd[sub-only]{benzene.Me} & \ch{-CH3} & Toluene \\
+ \cmpd[sub-only]{benzene.OH} & \ch{-OH} & Phenol \\
+ \cmpd[sub-only]{benzene.NH2} & \ch{-NH2} & Phenylamine (Aniline) \\
+ \bottomrule
+ \end{tabular}
+\end{example}
+
+\subsection{Usage in Section Headings and Captions}\label{sec:usage-sect-head}
+If you use labels in section headings or captions you will want to use either
+\cs{refcmpd} or \cs{cmpd}\code{+} (they are completely equivalent). Otherwise
+the corresponding labels will be declared when the section headings appear in
+the table of contents or maybe the page header. This would mess up the
+desired order of the compound numbers.
+
+\section{Details on Compound Labels}\label{sec:deta-comp-labels}
+\subsection{How Things Work}\label{sec:how-things-work}
+
+When you call \cs{cmpd} with a new label three things happen:
+\begin{itemize}
+ \item The new label gets initiated. This is nothing more than adding it to
+ an internal list. The purpose of this is explained in
+ section~\ref{sec:initiating-labels}.
+ \item The new label gets declared. This means that a number of internal
+ commands are defined. Amongst other things they hold a number of
+ properties associated with the corresponding label. Those properties are
+ explained in more detail in section~\ref{sec:prop-comp-labels}. The
+ necessary information of the label are also written to the \code{aux}
+ file.
+ \item The label gets printed.
+\end{itemize}
+
+Since new labels are declared when \cs{cmpd} is first used using it in section
+titles that are written to the table of contents may to lead to wrong
+numbering. In order to avoid this compound label information is written to
+the \code{aux} file. The command \cs{refcmpd}\oarg{options}\marg{\ac{id}}
+only reads those information but does not declare a label. There is also a
+command which does the opposite: it declares a label if it hasn't been
+declared before but will not print the corresponding label:
+\cs{labelcmpd}\oarg{options}\marg{\ac{id}}. Both commands have shortcut
+versions: \cs{cmpd}\code{+} is the same as \cs{refcmpd}, \cs{cmpd}\sarg\ is
+the same as \cs{labelcmpd}.
+
+Another command available is \cs{cmpdplain}\marg{\ac{id}}. This command is
+similar to \cs{refcmpd}. There are a few important differences, though:
+\cs{cmpdplain} does \emph{not} take a list of labels as argument. It also is
+\emph{not} able to interpret sublabels. \cs{cmpdplain} does not format the
+label with whatever format has been declared. And last but not least: it is
+expandable. This means it can be used to get labels in \ac{pdf} bookmarks.
+It's equivalent \cs{subcmpdplain}\marg{main \ac{id}}\marg{sub \ac{id}} does
+the same for sublabels. A third sibling, \cs{submaincmpdplain}\marg{main
+ \ac{id}}\marg{sub \ac{id}}, writes both the main and the sublabel.
+
+I should also say a few words on lists of labels. A usage like
+\verbcode+\cmpd{a,b,c,e}+ will be printed as a \emph{sorted} list. The order
+will be in the order \emph{in which the labels have been defined}. The above
+usage gives \cmpd{a,b,c,e}. The same thing holds for the order of sublabels
+of a compound: the usage \verbcode+\cmpd{q.{one,three,four,two,five}}+ gives
+\cmpd{q.{one,three,four,two,five}} or
+\cmpd[compress=false]{q.{one,three,four,two,five}} (depending on the
+\option{compress} option). Be careful if you have a list with several
+occurences of the same main label but with different sublabels: the labels
+will not be sorted depending on their sublabels.
+\begin{example}[side-by-side]
+ \cmpd{q.five,q.two} \par
+ \cmpd{q.two,q.five} \par
+ \cmpd[merge]{q.five,q.two} \par
+ \cmpd{q.five,b,r,q.two,a}
+\end{example}
+
+A last thing on lists: duplicate entries (\ie, \emph{exact} duplicates) will
+be removed.
+
+\subsection{Properties of Compound Labels}\label{sec:prop-comp-labels}
+
+Every label has a number of properties. The first property is of course its
+\ac{id} which identifies the label. The other properties are:
+\begin{description}
+ \item[number] An internal unique number.
+ \item[counter-representation] The counter representation associated with the
+ label. This is the actual label that get's printed.
+ \item[pre-label-code] Code to be inserted before the label is printed.
+ \item[post-label-code] Code to be inserted after the complete label is
+ printed.
+ \item[pre-main-label-code] Code to be inserted before the \emph{main} label
+ is printed.
+ \item[post-main-label-code] Code to be inserted after the \emph{main} label
+ is printed.
+ \item[label-format] Formatting commands for the label. This is most likely
+ something like \cs*{bfseries}. This is the \emph{default} format. Unlike
+ the other properties it can be changed locally with the \option{format}
+ option on a case by case basis.
+\end{description}
+
+The properties for a label are set the when a label is declared for the first
+time.
+
+\begin{commands}
+ \expandable\command{cmpdproperty}[\marg{\ac{id}}\marg{property}]
+ Get the associated property \meta{property} of compound \meta{\ac{id}}. This
+ command is expandable.
+\end{commands}
+
+\begin{example}
+ \def\expandfull{\romannumeral-`0}%
+ \def\expandtwice{\detokenize\expandafter\expandafter\expandafter}%
+ \ttfamily
+ number: \cmpdproperty{benzene}{number}\par
+ counter-representation: \cmpdproperty{benzene}{counter-representation}\par
+ pre-label-code: \cmpdproperty{benzene}{pre-label-code}\par % empty
+ post-label-code: \cmpdproperty{benzene}{post-label-code}\par % empty
+ label-format: \expandtwice{\expandfull\cmpdproperty{benzene}{label-format}}
+\end{example}
+
+Similarly a sublabel has associated properties. Additionally to the obvious
+ones -- its \ac{id} and the \ac{id} the main label it belongs to -- these
+are
+\begin{description}
+ \item[number] An internal unique number.
+ \item[counter-representation] The counter representation associated with the
+ label. This is the actual label that get's printed.
+\end{description}
+
+\begin{commands}
+ \expandable\command{subcmpdproperty}[\marg{main \ac{id}}\marg{sub
+ \ac{id}}\marg{property}]
+ Get the associated property \meta{property} of subcompound \meta{sub
+ \ac{id}} of compound \meta{main \ac{id}}. This command is
+ expandable.
+\end{commands}
+
+\begin{example}
+ \ttfamily
+ main-compound: \subcmpdproperty{benzene}{OH}{main-compound}\par
+ number: \subcmpdproperty{benzene}{OH}{number}\par
+ counter-representation: \subcmpdproperty{benzene}{OH}{counter-representation}
+\end{example}
+
+If you compile with the \keyis{log}{verbose} all properties of a label are
+listed in the log when it is declared. This will typically look like this:
+
+\begin{sourcecode}
+ .................................................
+ . chemnum info: defined new compound:
+ . ID = a
+ . internal number = 1
+ . label = A
+ . pre label code =
+ . post label code =
+ . pre main label code =
+ . post main label code =
+ . format = \bfseries
+ .................................................
+\end{sourcecode}
+
+\subsection{Initiating Labels}\label{sec:initiating-labels}
+Initiating labels is not the same as declaring them although it happens
+simultaneously. When a label is \emph{initiated} its \ac{id} is added to an
+internal list. When a label is \emph{declared} all of its properties and
+associated macros are defined. Initiating can serve two purposes:
+\begin{enumerate}
+ \item It can help in keeping track of defined labels; if you set the option
+ \option{init} \chemnum\ will either issue a warning or an error (depending
+ on the actual setting you chose) if a label is used (and hence probably
+ declared) \emph{that hasn't been initiated}. This can also help in
+ detecting typos in label names.
+ \item Since the labels are declared in the preamble you don't need to worry
+ about a label erroneously being declared in the table of contents. This
+ means the variants \cs{cmpd}\sarg\ and \cs{cmpd}\code{+} shouldn't be
+ needed.
+\end{enumerate}
+
+Initiating is done via the command \cs{initcmpd}:
+\begin{sourcecode}
+ \initcmpd{a,b,c,d}
+\end{sourcecode}
+You simply use all \acp{id} you want to use like you would use them in
+\cs{cmpd}. \cs{initcmpd} also has an optional argument that allows you to set
+options for those labels. Legal options are the same as for \cs{cmpd}.
+
+Remember: \cs{initcmpd} will both initiate the labels \emph{and} declare the
+labels!
+
+\section{Overview over the Available Options}\label{sec:overv-over-avail-1}
+% Except for the \option{version} option
+All of the following options are either
+set as options to \cs{cmpd} or \cs{initcmpd} directly or via
+\cs{setchemnum}\marg{options}, each time as a comma separated list of
+key/value pairs. Options that can only be set via \cs{setchemnum} are marked
+with \module{general}, those that only have an effect when used with \cs{cmpd} and
+friends are marked with \module{cmpd}. Those marked with \module{both} can
+be set either way. The options affecting the compounds are further divided in
+two classes: I named them global \module*{(g)} and local \module*{(l)}. Options
+from the global class are set when a label is declared the first time and then
+are a fixed property of the corresponding label. Options from the local class
+can be changed at each instance of a label and will then only be active for
+the one instance.
+
+A few of the options only have an effect when used with the \cs{replacecmpd}
+command. They are marked with \module{replace}.
+
+\begin{options}
+ \keyval{counter-within}{counter}\Module{general}
+ Reset the compound numbers when \meta{counter} is stepped.
+ \keychoice{counter-format}{arabic,alph,Alph,roman,Roman,greek,Greek}%
+ \Module{both (g)}\Default{arabic}
+ The format of the number associated with the main compounds.
+ \keychoice{sub-counter-format}{arabic,alph,Alph,roman,Roman,greek,Greek}%
+ \Module{both (g)}\Default{alph}
+ The format of the number associated with the sub compounds.
+ \keybool{compress}\Module{both (l)}\Default{true}
+ If set to true a list of sublabels is compressed, \ie,
+ \cmpd[compress=false]{q.{one,three,four,five}} becomes
+ \cmpd{q.{one,three,four,five}}.
+ \keybool{merge}\Module{both (l)}\Default{false}
+ If set to true a list of labels is merged, \ie,
+ ``\cmpd{q.five,a,q.two}'' becomes ``\cmpd[merge=true]{q.five,a,q.two}''.
+ \keyval{pre-label-code}{code}\Module{cmpd (g)}\Default
+ Code to be inserted before a label.
+ \keyval{post-label-code}{code}\Module{cmpd (g)}\Default
+ Code to be inserted after a label.
+ \keyval{main-sub-sep}{code}\Module{both (l)}\Default{.}
+ The separator symbol that is used in \cs{cmpd} to separate the \meta{main
+ \ac{id}} from a \meta{sub \ac{id}}.
+ \keyval{format}{formatting commands}\Module{both (l)}\Default{\cs*{bfseries}}
+ The default format of the labels.
+ \keyval{list-label-sep}{code}\Module{both (l)}\Default{,}
+ The separator that is used to separate different \meta{main \acp{id}} in
+ \cs{cmpd}.
+ \keyval{sub-list-label-sep}{code}\Module{both (l)}\Default{,}
+ The marker that is used to split an input list of sublabels.
+ \keyval{list-sep-two}{code}%
+ \Module{both (l)}\Default{\visualizespaces{\GetTranslation{chemnum-sep-two}}}
+ The output separator between labels in a list that contains of two items.
+ \keyval{list-sep-more}{code}\Module{both (l)}\Default{\visualizespaces{, }}
+ The output separator between labels in a list that contains of more than
+ two items.
+ \keyval{list-sep-last-two}{code}%
+ \Module{both (l)}\Default{\visualizespaces{\GetTranslation{chemnum-sep-last-two}}}
+ The output separator between the last two labels in a list that contains
+ of more than two items.
+ \keybool{sub-only}\Module{cmpd (l)}\Default{false}
+ If true the command \cs{cmpd} will only print sublabels but no main
+ labels.
+ \keybool{sub-all}\Module{cmpd (l)}\Default{false}
+ If true the command \cs{cmpd} will print all sublabels belonging to the
+ corresponding main label.
+ \keyval{sub-list-sep-two}{code}\Module{both (l)}\Default{,}
+ The output separator between labels in a sublist that contains of two
+ items.
+ \keyval{sub-list-sep-more}{code}\Module{both (l)}\Default{,}
+ The output separator between labels in a sublist that contains of more
+ than two items.
+ \keyval{sub-list-sep-last-two}{code}\Module{both (l)}\Default{,}
+ The output separator between the last two labels in a sublist that
+ contains of more than two items.
+ \keyval{sub-list-sep-range}{code}\Module{both (l)}\Default{--}
+ The output separator between two labels in a sublist denoting a range.
+ This is only used when the option \option{compress} is active.
+ \keybool{replace-auto}\Module{general}\Default{true}
+ When set to true this adds an incremented integer to the replacement tag.
+ \keyval{replace-tag}{text}\Module{general}\Default{TMP}
+ The default replacement tag.
+ \keyval{replace-tag-nr}{int}\Module{general}\Default{1}
+ The\sinceversion{1.1} next number used by \cs{replacecmpd} when the
+ default tag is used.
+ \keyval{tag}{text}\Module{replace}\Default{TMP\meta{number}}
+ The local replacement tag. \meta{number} is incremented by one at each
+ use and starts with \code{1}. The starting number can be changed with the
+ option \option{replace-tag-nr}. The increment happens locally.
+ \keyval{replace-style}{code}\Module{general}\Default{\cs*{sffamily}}
+ Additional \TeX\ code that it placed before the \cs{cmpd} command in the
+ replacement.
+ \keyval{style}{code}\Module{replace}\Default{\cs*{sffamily}}
+ Local additional \TeX\ code that it placed before the \cs{cmpd} command in
+ the replacement.
+ \keychoice{replace-pos}{\marg{\TeX\ pos}\marg{\ac{ps}
+ pos}}\Module{general}\Default{bb}
+ Options for \pkg{psfrag}'s \cs{psfrag}.
+ \keychoice{pos}{\marg{\TeX\ pos}\marg{\ac{ps}
+ pos}}\Module{replace}\Default{bb}
+ Local options for \pkg{psfrag}'s \cs{psfrag}.
+ \keychoice{init}{\default{true},main,false,strict,main-strict}%
+ \Module{general}\Default{false}
+ Determines how labels have to be initiated. \code{false} means that
+ labels are initiated when they're used the first time in the text.
+ \code{true} means that labels should be initiated in the preamble with
+ \cs{initcmpd}. \code{main} is the same as \code{true} but only for main
+ labels. \code{strict} means that if an un-initiated label is used an
+ error is thrown. \code{main-strict} is the same as \code{strict} but only
+ for main labels.
+ \keychoice{log}{\default{true},false,silent,verbose}\Module{general}\Default{false}
+ Determines how the declaration of the labels will be logged. \code{false}
+ means that no information is written to the \code{.log} file. \code{true}
+ means that basic information is written to the \code{.log} file when a
+ label or a sublabel is declared. \code{silent} is an alias of
+ \code{true}. \code{verbose} means that detailed information is written to
+ the \code{.log} file when a label or a sublabel is declared.
+ \keychoice{show-keys}{\default{true},false,def,ref}\Module{general}\Default{false}
+ This option will write visual hints when a label is defined (choices
+ \code{true} or \code{def}) or when a label is referenced (choices
+ \code{true} or \code{ref}).
+ \keybool{hyperlinks}\Module{general}\Default{false}
+ \sinceversion{1.2}When package \pkg{hyperref} is loaded and this option is
+ set to \code{true} then each main label links back to the first time it
+ has been used (\ie, it has been labelled \emph{and} printed).
+\end{options}
+
+\section{The Counter Settings}\label{sec:counter-settings}
+The default setting for main labels is arabic numbering which is the most
+common use case for compound labels. There are however cases when you might
+want a different numbering. The numbering also is not reset in a document. I
+have heard of cases where this might be desirable, though. This section will
+tell you how you can achieve those things.
+
+\subsection{Change the Numbering}\label{sec:change-numbering}
+
+The counter representation used for the main and the sublabels can be changed
+using the following options:
+\begin{options}
+ \keychoice{counter-format}{arabic,alph,Alph,roman,Roman,greek,Greek}%
+ \Module{general}\Default{arabic}
+ The format of the number associated with the main compounds.
+ \keychoice{sub-counter-format}{arabic,alph,Alph,roman,Roman,greek,Greek}%
+ \Module{general}\Default{alph}
+ The format of the number associated with the sub compounds.
+\end{options}
+
+Those options can be set globally with \cs{setchemnum} or localized for the
+single compounds.
+\begin{example}[side-by-side]
+ \cmpd[counter-format=Alph]{Alpha} and
+ \cmpd[counter-format=greek]{greek}
+\end{example}
+
+While it may not be necessary very often to change the default setting one
+could image cases where it makes sense, \eg, Greek sublabels for the anomers
+of a carbohydrate.
+\begin{example}
+ % this example uses the `chemfig' package
+ \definesubmol{r}{(-[4]H)(-[0]OH)}
+ \definesubmol{l}{(-[0]H)(-[4]HO)}
+ \labelcmpd[sub-counter-format=greek]{glucose.{alpha,beta}}
+ \labelcmpd{glucose.chain}
+ \centering
+ \schemestart
+ \small\chemfig{
+ ?(-[:-170]HO)
+ -[:-50](-[:170]HO)
+ -[:10](-[:-55,0.7]OH)
+ -[:-10](-[6,0.8]OH)
+ -[:130]O-[:-170]?(-[:150,0.7]-[2,0.7]OH)
+ }
+ \arrow(alpha--chain){<=>}
+ \small\chemfig{[6]O=^[5]-!r-!l-!r-!r--[7]OH}
+ \arrow(--beta){<=>}
+ \small\chemfig{
+ ?(-[:-170]HO)
+ -[:-50](-[:170]HO)
+ -[:10](-[:-55,0.7]OH)
+ -[:-10](-[:10]OH)(-[6,,,,draw=none]\vphantom{OH})
+ -[:130]O-[:-170]?(-[:150,0.7]-[2,0.7]OH)
+ }
+ \arrow(@chain--chainlabel){0}[-90,.2] \cmpd{glucose.chain}
+ \arrow(@chainlabel--){0}[,2.5] \cmpd{glucose.beta}
+ \arrow(@chainlabel--){0}[180,2.3] \cmpd{glucose.alpha}
+ \schemestop
+\end{example}
+
+Should it ever be necessary to use another kind of counter representations
+than the ones already provided they can be added with this command:
+\begin{commands}
+ \command{newcmpdcounterformat}[\marg{name}\marg{code}]
+ Makes the label format \meta{name} known to \chemnum. \meta{code}
+ needs to end with a command that takes an integer number as mandatory
+ argument and should return a formatted version of it.
+\end{commands}
+The \code{arabic} and \code{alph} counter settings for example could have been
+defined like this:
+\begin{sourcecode}
+ \newcmpdcounterformat{arabic}{\@arabic}
+ \newcmpdcounterformat{alph} {\@alph}
+\end{sourcecode}
+This is actually not true: since \chemnum\ is written in expl3 the
+corresponding \cs*{int\_to\_\meta{\ldots}} functions have been used.
+
+Although the name of the command suggests otherwise it can be used to
+overwrite the default definitions.
+
+\subsection{Reset the Numbering}\label{sec:reset-numbering}
+
+There are cases when it actually might make sense to reset the counting of the
+compound labels. For this you can use this command:
+\begin{commands}
+ \command{resetcmpd}[\oarg{integer}]\Default{1}
+ Reset the numbering for main compound labels to start with \meta{integer}
+ again. This is the same as
+ \cs*{setcounter}\Marg{cmpdmain}\Marg{$\text{\meta{integer}}-1$} which
+ means the change is global!
+\end{commands}
+
+Be careful, though. You might end up with the same number for different
+compounds:
+\begin{example}
+ \resetcmpd The numbering starts with 1 again: \cmpd{h,i,j}, but:
+ two compounds with the same label: \cmpd{a,h}
+\end{example}
+
+\section{Formatting Labels}\label{sec:formatting-labels}
+
+As you will have noticed by now labels are typeset with a bold face with the
+default setting of \chemnum. This can be changed:
+\begin{options}
+ \keyval{format}{formatting commands}\Module{both (l)}\Default{\cs*{bfseries}}
+ The default format of the labels.
+\end{options}
+
+This options works in two ways: it sets the default format that is picked up
+by a compound label when it is defined. When you change it later already
+defined labels dont change:
+\begin{example}[side-by-side]
+ \setchemnum{format=\itshape}
+ \cmpd{a,b} and \cmpd{new}
+\end{example}
+
+If it is applied directly to the \cs{cmpd} command it changes the formatting
+for this usage of the command only, regardless if the label is new or not:
+\begin{example}[side-by-side]
+ \cmpd[format=\itshape]{a,b} vs
+ \cmpd{a,b}
+\end{example}
+
+There is more that you can do. Maybe you want to enclose labels in
+parentheses?
+\begin{example}
+ \cmpd[pre-label-code=(,post-label-code=)]{x, y, z.one }
+\end{example}
+Please note that these options only have an effect for \emph{newly defined}
+labels since they belong to a label's properties.
+
+Other options are the customization of the list separators:
+\begin{options}
+ \keyval{list-sep-two}{code}%
+ \Module{general}\Default{\visualizespaces{\GetTranslation{chemnum-sep-two}}}
+ The output separator between labels in a list that contains of two items.
+ \keyval{list-sep-more}{code}\Module{general}\Default{\visualizespaces{, }}
+ The output separator between labels in a list that contains of more than
+ two items.
+ \keyval{list-sep-last-two}{code}%
+ \Module{general}\Default{\visualizespaces{\GetTranslation{chemnum-sep-last-two}}}
+ The output separator between the last two labels in a list that contains
+ of more than two items.
+\end{options}
+
+\begin{example}
+ \setchemnum{list-sep-two=;,list-sep-more=;,list-sep-last-two=;}
+ \cmpd{a, b, c, d}
+\end{example}
+
+In the default settings these separators are language dependent. Setting them
+explicitly will overwrite the language sensitivity. If you only want to adapt
+the separators to your language have a look at
+section~\ref{sec:lang-depend-sett}.
+
+\section{Replacing Tags in \ac{eps} or \ac{ps} Files}\label{sec:replacing-tags-aceps}
+
+Although it is quite possible to create rection schemes within \LaTeX\
+directly -- for example with the \pkg{chemfig} package~\cite{pkg:chemfig} --
+many people prefer to use a program such as \textsc{ChemDraw} for it. In
+order to be able to use the labels with such schemes as well the following
+method is usually used:
+\begin{itemize}
+ \item Create the scheme and place temporary tags like \code{TMP1},
+ \code{TMP2} and so on where you want the compound labels to be.
+ \item Export the scheme as \ac{eps} or \ac{ps} figure where you make sure
+ that the tags are embedded as text strings.
+ \item Include the \ac{eps} with \cs*{includegraphics}. Right before that
+ use \cs{replacecmpd} once for every temporary tag.
+\end{itemize}
+
+\begin{commands}
+ \command{replacecmpd}[\code{+}\oarg{options}\marg{\ac{id}}]
+ Replaces a tag in the following \ac{eps} file. This command doesn't have
+ an optional star otherwise the syntax is the same as with \cs{cmpd}.
+\end{commands}
+
+Figure~\ref{fig:scheme-tmp-tags} shows a scheme with temporary tags. It is
+produced with the following code where the class \cls{standalone} has been
+used to get the figure only:
+\begin{example}[compile,exe-with={--shell-escape},runs=1,float=htbp,caption={A scheme with
+ temporary tags.\label{fig:scheme-tmp-tags}}]
+ % code for figure 1
+ \documentclass{standalone}
+ \usepackage{graphicx,auto-pst-pdf}
+ \begin{document}
+ \includegraphics{scheme-tmp.ps}
+ \end{document}
+\end{example}
+
+The tags now can be replaced with labels. The result is shown in
+figure~\ref{fig:scheme-tmp-tags-replaced}.
+\begin{example}[compile,exe-with={--shell-escape},runs=1,float=htbp,caption={A scheme with
+ temporary tags replaced with labels.\label{fig:scheme-tmp-tags-replaced}}]
+ % code for figure 2
+ \documentclass{standalone}
+ \usepackage{graphicx,auto-pst-pdf,chemnum}
+ \begin{document}
+ \replacecmpd{Alc}% replaces TMP1
+ \replacecmpd{EtherBr}% replaces TMP2
+ \includegraphics{scheme-tmp.ps}
+ \end{document}
+\end{example}
+
+The replacement is done with the help of the \pkg{psfrag}
+package~\cite{pkg:psfrag} and its \cs{psfrag} command. For details on this
+package and its command I refer to its documentation.
+
+Although the examples don't do it the usage of \cs{replacecmpd} and the
+corresponding graphic file should be placed inside a group (probably a
+\env*{figure} or a \env*{scheme} environment) in order to keep the stepping of
+the tag number local: this allows to use the same tags \code{TMP1},
+\code{TMP2}, \ldots, in the next figure again.
+
+As you can see the labels are printed sans serif. This setting can of course
+be changed. The complete list of options is this:
+\begin{options}
+ \keybool{replace-auto}\Module{general}\Default{true}
+ When set to true this adds an incremented integer to the replacement tag.
+ \keyval{replace-tag}{text}\Module{general}\Default{TMP}
+ The default replacement tag.
+ \keyval{replace-tag-nr}{int}\Module{general}\Default{1}
+ The\sinceversion{1.1} next number used by \cs{replacecmpd} when the
+ default tag is used.
+ \keyval{tag}{text}\Module{replace}\Default{TMP\meta{number}}
+ The local replacement tag. \meta{number} is incremented by one at each
+ use and starts with \code{1}. The starting number can be changed with the
+ option \option{replace-tag-nr}. The increment happens locally.
+ \keyval{replace-style}{code}\Module{general}\Default{\cs*{sffamily}}
+ Additional \TeX\ code that it placed before the \cs{cmpd} command in the
+ replacement.
+ \keyval{style}{code}\Module{replace}\Default{\cs*{sffamily}}
+ Local additional \TeX\ code that it placed before the \cs{cmpd} command in
+ the replacement.
+ \keychoice{replace-pos}{\marg{\TeX\ pos}\marg{\ac{ps}
+ pos}}\Module{general}\Default{bb}
+ Options for \pkg{psfrag}'s \cs{psfrag}.
+ \keychoice{pos}{\marg{\TeX\ pos}\marg{\ac{ps}
+ pos}}\Module{replace}\Default{bb}
+ Local options for \pkg{psfrag}'s \cs{psfrag}.
+\end{options}
+
+If you have a scheme with arbitrary tabs like in
+figure~\ref{fig:scheme-bla-tags} you can specify the \option{tag} option to
+\cs{replacecmpd}. Figure~\ref{fig:scheme-bla-tags-replaced} demonstrates
+this. It also demonstrates that you can of course use sublabels in the
+\cs{replacecmpd} command.
+
+\begin{example}[compile,exe-with={--shell-escape},runs=1,float=htbp,caption={A scheme with
+ arbitrary tags.\label{fig:scheme-bla-tags}}]
+ % code for figure 3
+ \documentclass{standalone}
+ \usepackage{graphicx,auto-pst-pdf}
+ \begin{document}
+ \includegraphics{scheme-bla.ps}
+ \end{document}
+\end{example}
+
+If you don't want to use \code{TMP\meta{number}} as temporary tags but for
+example \code{temp\meta{number}} you can change this with following option:
+\begin{sourcecode}
+ \setchemnum{replace-tag=temp}
+\end{sourcecode}
+
+The options \option{pos} and \option{replace-pos} refer to \cs{psfrag}'s
+optional arguments which determine the positioning of the \TeX\ box with
+respect to the \ac{ps} box that is replaced. This is described in
+\pkg{psfrag}'s documentation.
+
+\begin{example}[compile,exe-with={--shell-escape},runs=1,float=htbp,caption={A scheme with
+ arbitrary tags replaced with labels.\label{fig:scheme-bla-tags-replaced}}]
+ % code for figure 4
+ \documentclass{standalone}
+ \usepackage{graphicx,auto-pst-pdf,chemnum}
+ \begin{document}
+ \setchemnum{replace-style=\itshape}
+ \replacecmpd[tag=blah]{main}% replaces blah
+ \replacecmpd[tag=blub]{main.sub}% replaces blub
+ \includegraphics{scheme-bla.ps}
+ \end{document}
+\end{example}
+
+\section{Changing the Input Markers}\label{sec:chang-input-mark}
+
+In \chemnum's labels there are two markers (or three, actually) that can't be
+part of a label name: the comma \code{,} and the dot \code{.}. You can change
+them with options:
+
+\begin{options}
+ \keyval{list-label-sep}{token}\Module{general}\Default{,}
+ The marker that is used to split an input list of main labels.
+ \keyval{sub-list-label-sep}{token}\Module{general}\Default{,}
+ The marker that is used to split an input list of sublabels.
+ \keyval{main-sub-sep}{token}\Module{general}\Default{.}
+ The marker that divides sublabels from main labels.
+\end{options}
+
+\begin{example}[side-by-side]
+ \setchemnum{
+ main-sub-sep = ! ,
+ list-label-sep = ;
+ }
+ \cmpd{a; b; c; e; g!two} \par
+ \cmpd{q!one,two,three,four,five}
+\end{example}
+
+\section{Language Dependent Settings}\label{sec:lang-depend-sett}
+
+A few settings of \chemnum\ depend on the language you chose with
+\pkg{babel}~\cite{pkg:babel} or \pkg{polyglossia}~\cite{pkg:polyglossia}.
+Those regard the list separators. The language dependent strings are
+translated with the help of the \pkg{translations}~\cite{pkg:translations}
+package. This package provides the means to define translations for strings
+associated with identification keys. \chemnum\ defines two strings. The
+available languages and the corresponding translations of the two strings are
+listed in table~\ref{tab:languages}. Note that both the comma or a leading
+space as well as a trailing space are part of the translations. To make this
+obvious the relevant parts of the table are typeset in monotype and spaces are
+represented by \code{\textvisiblespace}.
+
+If you find your language missing or the translation to your language to be
+wrong please write me an email and I'll add your language or fix the wrong
+translation.
+
+\begin{table}[htbp]
+ \centering
+ \caption{Available languages}
+ \label{tab:languages}
+ \begin{tabular}{l>{\ttfamily}l>{\ttfamily}l}
+ \toprule
+ \bfseries Language &
+ \bfseries chemnum-sep-two &
+ \bfseries chemnum-sep-last-two \\
+ \midrule
+ English
+ & \visualizespaces{\GetTranslationFor{English}{chemnum-sep-two}}
+ & \visualizespaces{\GetTranslationFor{English}{chemnum-sep-last-two}} \\
+ American
+ & \visualizespaces{\GetTranslationFor{American}{chemnum-sep-two}}
+ & \visualizespaces{\GetTranslationFor{American}{chemnum-sep-last-two}} \\
+ German
+ & \visualizespaces{\GetTranslationFor{German}{chemnum-sep-two}}
+ & \visualizespaces{\GetTranslationFor{German}{chemnum-sep-last-two}} \\
+ French
+ & \visualizespaces{\GetTranslationFor{French}{chemnum-sep-two}}
+ & \visualizespaces{\GetTranslationFor{French}{chemnum-sep-last-two}} \\
+ Spanish
+ & \visualizespaces{\GetTranslationFor{Spanish}{chemnum-sep-two}}
+ & \visualizespaces{\GetTranslationFor{Spanish}{chemnum-sep-last-two}} \\
+ Italian
+ & \visualizespaces{\GetTranslationFor{Italian}{chemnum-sep-two}}
+ & \visualizespaces{\GetTranslationFor{Italian}{chemnum-sep-last-two}} \\
+ Catalan
+ & \visualizespaces{\GetTranslationFor{Catalan}{chemnum-sep-two}}
+ & \visualizespaces{\GetTranslationFor{Catalan}{chemnum-sep-last-two}} \\
+ Portuguese
+ & \visualizespaces{\GetTranslationFor{Portuguese}{chemnum-sep-two}}
+ & \visualizespaces{\GetTranslationFor{Portuguese}{chemnum-sep-last-two}} \\
+ Dutch
+ & \visualizespaces{\GetTranslationFor{Dutch}{chemnum-sep-two}}
+ & \visualizespaces{\GetTranslationFor{Dutch}{chemnum-sep-last-two}} \\
+ Danish
+ & \visualizespaces{\GetTranslationFor{Danish}{chemnum-sep-two}}
+ & \visualizespaces{\GetTranslationFor{Danish}{chemnum-sep-last-two}} \\
+ Swedish
+ & \visualizespaces{\GetTranslationFor{Swedish}{chemnum-sep-two}}
+ & \visualizespaces{\GetTranslationFor{Swedish}{chemnum-sep-last-two}} \\
+ Finnish
+ & \visualizespaces{\GetTranslationFor{Finnish}{chemnum-sep-two}}
+ & \visualizespaces{\GetTranslationFor{Finnish}{chemnum-sep-last-two}} \\
+ Norwegian
+ & \visualizespaces{\GetTranslationFor{Norwegian}{chemnum-sep-two}}
+ & \visualizespaces{\GetTranslationFor{Norwegian}{chemnum-sep-last-two}} \\
+ \bottomrule
+ \end{tabular}
+\end{table}
+
+\section{Debugging Information}\label{sec:debugg-inform}
+
+If you want information on the labels you have defined you can exploit the
+following options:
+\begin{options}
+ \keychoice{log}{\default{true},false,silent,verbose}\Module{general}\Default{false}
+ Determines how the declaration of the labels will be logged. \code{false}
+ means that no information is written to the \code{.log} file. \code{true}
+ means that basic information is written to the \code{.log} file when a
+ label or a sublabel is declared. \code{silent} is an alias of
+ \code{true}. \code{verbose} means that detailed information is written to
+ the \code{.log} file when a label or a sublabel is declared.
+ \keychoice{show-keys}{\default{true},false,def,ref}\Module{general}\Default{false}
+ This option will write visual hints when a label is defined (choices
+ \code{true} or \code{def}) or when a label is referenced (choices
+ \code{true} or \code{ref}).
+\end{options}
+
+The option \option{log} will write information on a label to the \code{log}
+file when a label is defined. Depending on the choice (\code{true}, its alias
+\code{silent}, or \code{verbose}) this will be only the main information or
+detailed information including label properties. The following code shows an
+example when \keyis{log}{verbose}:
+\begin{sourcecode}
+ .................................................
+ . chemnum info: defined new compound:
+ . ID = a
+ . internal number = 1
+ . label = 1
+ . pre label code = (
+ . post label code = )
+ . post main label code =
+ . format = \bfseries
+ .................................................
+\end{sourcecode}
+
+The \option{show-keys} writes some visual information to the document itself:
+\begin{example}
+ \setchemnum{show-keys}
+ \cmpd{a} and a bit later \cmpd{b}.
+\end{example}
+The last example shows the information when a label is referenced. If a label
+is newly declared information is written to the margin like for this label
+with the \ac{id} \code{showkey}: \setchemnum{show-keys}\cmpd{showkey} that
+again is referencend here: \cmpd{showkey}.
+
+The option activates four commands:
+\begin{commands}
+ \command{cmpdshowdef}[\marg{\ac{id}}]
+ Internal command used to display \meta{\ac{id}} of a newly defined compound
+ label when the option \option{show-keys} is used. The command is
+ described in section~\ref{sec:debugg-inform}.
+ \command{cmpdshowref}[\marg{\ac{id}}]
+ Internal command used to display \meta{\ac{id}} of a referencing compound
+ label when the option \option{show-keys} is used. The command is
+ described in section~\ref{sec:debugg-inform}.
+ \command{subcmpdshowdef}[\marg{main \ac{id}}\marg{sub \ac{id}}]
+ Internal command used to display \meta{main \ac{id}} and \meta{sub
+ \ac{id}} of a newly defined subcompound label when the option
+ \option{show-keys} is used. The command is described in
+ section~\ref{sec:debugg-inform}.
+ \command{subcmpdshowref}[\marg{main \ac{id}}\marg{sub \ac{id}}]
+ Internal command used to display \meta{main \ac{id}} and \meta{sub
+ \ac{id}} of a referencing subcompound label when the option
+ \option{show-keys} is used. The command is described in
+ section~\ref{sec:debugg-inform}.
+\end{commands}
+This means you can customize the appearance of the information by redefining
+those commands. The ones that show the definition use a \cs*{marginpar} in
+their default definition. This may cause them to disappear if issued
+somewhere \cs*{marginpar} cannot be used. The following shows an equivalent
+definition with \cs*{marginnote} from the \pkg{marginnote}
+package~\cite{pkg:marginnote}. (This definition has another drawback: it
+several \cs*{marginnote}s can print over one another if issued in the same
+line.)
+
+\begin{example}
+ \renewcommand*\cmpdshowdef[1]{% /needs/ one mandatory argument
+ \marginnote{\fbox{\normalfont\ttfamily#1}}}
+ \renewcommand*\subcmpdshowdef[2]{% /needs/ two mandatory arguments
+ \marginnote{\fbox{\normalfont\ttfamily#2 (#1)}}}
+ a\cmpdshowdef{foo}\par
+ b\cmpdshowref{foo}\par
+ c\subcmpdshowdef{foo}{bar}\par
+ d\subcmpdshowref{foo}{bar}
+\end{example}
+
+Actually there are two other commands you could redefine -- all four of the
+above commands are defined in terms of them:
+\begin{sourcecode}
+ \NewDocumentCommand\cmpdshowdef{m}{\chemnumshowdef{#1}}
+ \NewDocumentCommand\cmpdshowref{m}{\chemnumshowref{#1}}
+ \NewDocumentCommand\subcmpdshowdef{mm}{\chemnumshowdef{#2 (#1)}}
+ \NewDocumentCommand\subcmpdshowref{mm}{\chemnumshowref{#2}}
+\end{sourcecode}
+
+\end{document}
+
+