summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/chemnum
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2014-03-12 22:33:13 +0000
committerKarl Berry <karl@freefriends.org>2014-03-12 22:33:13 +0000
commit4c7bf2d42fecbd952b9d701396503f6374d14835 (patch)
tree347b9ec38e8951e3825eeab1d8a53cf9ebaf5dd6 /Master/texmf-dist/doc/latex/chemnum
parent44df6d09616942cb3a83276fba2978bc9cdee561 (diff)
chemnum (12mar14)
git-svn-id: svn://tug.org/texlive/trunk@33161 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/chemnum')
-rw-r--r--Master/texmf-dist/doc/latex/chemnum/README43
-rw-r--r--Master/texmf-dist/doc/latex/chemnum/chemnum_en.pdfbin663319 -> 549076 bytes
-rw-r--r--Master/texmf-dist/doc/latex/chemnum/chemnum_en.tex2465
3 files changed, 1125 insertions, 1383 deletions
diff --git a/Master/texmf-dist/doc/latex/chemnum/README b/Master/texmf-dist/doc/latex/chemnum/README
index 97efbc19db7..07f5e70d815 100644
--- a/Master/texmf-dist/doc/latex/chemnum/README
+++ b/Master/texmf-dist/doc/latex/chemnum/README
@@ -1,24 +1,16 @@
-chemnum v0.6b 2013/06/05
+--------------------------------------------------------------------------
+chemnum v1.0 2014/03/12
a comprehensive approach for the numbering of chemical compounds
-Basically one main command is provided, \cmpd{<label name>}. With
-it compound labels are initialized, declared and printed.
-There are some variants of the commands and possibilities to customize
-it. It also can print compund lists.
-
-chemnum loads the packages expl3 and xparse and therefore needs LaTeX3
-support as provided by the package bundles l3kernel and l3packages.
-chemnum also needs the packages etoolbox, psfrag and textgreek or bm
-to be fully functioning.
-
-http://www.mychemistry.eu/
-contact@mychemistry.eu
-
-If you have any ideas, questions, suggestions or bugs to report,
-please feel free to contact me.
-
-Copyright 2011-2013 Clemens Niederberger
+--------------------------------------------------------------------------
+Clemens Niederberger
+Web:
+ v0.* https://bitbucket.org/cgnieder/chemnum/
+ v1.* https://github.com/cgnieder/chemnum
+E-Mail: contact@mychemistry.eu
+--------------------------------------------------------------------------
+Copyright 2011-2014 Clemens Niederberger
This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either version 1.3
@@ -31,9 +23,14 @@ version 2005/12/01 or later.
This work has the LPPL maintenance status `maintained'.
The Current Maintainer of this work is Clemens Niederberger.
-
+--------------------------------------------------------------------------
+If you have any ideas, questions, suggestions or bugs to report,
+please feel free to contact me.
+--------------------------------------------------------------------------
This work consists of the files
- chemnum.sty, chemnum_de.tex, chemnum_en.tex, chemnum_it.tex
- scheme-tmp.ps, scheme-bla.ps,
- README
- chemnum_de.pdf, chemnum_en.pdf, chemnum_it.pdf
+- chemnum.sty,
+- chemnum_en.tex, chemnum_en.pdf
+- README
+--------------------------------------------------------------------------
+Version 1 is a complete re-write from scratch of the `chemnum' package.
+--------------------------------------------------------------------------
diff --git a/Master/texmf-dist/doc/latex/chemnum/chemnum_en.pdf b/Master/texmf-dist/doc/latex/chemnum/chemnum_en.pdf
index 8333d6d2540..c74fec7b72c 100644
--- a/Master/texmf-dist/doc/latex/chemnum/chemnum_en.pdf
+++ b/Master/texmf-dist/doc/latex/chemnum/chemnum_en.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/chemnum/chemnum_en.tex b/Master/texmf-dist/doc/latex/chemnum/chemnum_en.tex
index 8d9cc7b8b24..dc8410ddc43 100644
--- a/Master/texmf-dist/doc/latex/chemnum/chemnum_en.tex
+++ b/Master/texmf-dist/doc/latex/chemnum/chemnum_en.tex
@@ -1,1404 +1,1149 @@
% arara: pdflatex: { shell: on }
-% arara: pdflatex: { shell: on }
% !arara: pdflatex: { shell: on }
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-% - chemnum - chemnum_en.tex
-% - a comprehensive approach for the numbering of chemical compounds
-% -----------------------------------------------------------------------------
-% - Clemens NIEDERBERGER
-% -
-% - contact@mychemistry.eu
-% -----------------------------------------------------------------------------
-% - If you have any ideas, questions, suggestions or bugs to report, please
-% - feel free to contact me.
-% -----------------------------------------------------------------------------
-% - Copyright 2011-2013 Clemens Niederberger
-% -
-% - This work may be distributed and/or modified under the
-% - conditions of the LaTeX Project Public License, either version 1.3
-% - of this license or (at your option) any later version.
-% - The latest version of this license is in
-% - http://www.latex-project.org/lppl.txt
-% - and version 1.3 or later is part of all distributions of LaTeX
-% - version 2005/12/01 or later.
-% -
-% - This work has the LPPL maintenance status `maintained'.
-% -
-% - The Current Maintainer of this work is Clemens Niederberger.
-% -
-% - This work consists of the files
-% - chemnum.sty, chemnum_de.tex, chemnum_en.tex, chemnum_it.tex
-% - scheme-tmp.ps, scheme-bla.ps,
-% - README
-% - chemnum_de.pdf, chemnum_en.pdf, chemnum_it.pdf
-% -
-% - in order to compile this document you need the class `cnpkgdoc' with is
-% - available under the LPPL here: https://bitbucket.org/cgnieder/cnpkgdoc/
-% -
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\RequirePackage[ngerman,german,naustrian,austrian,british,american,canadian,frenchb,
- canadien,spanish,italian,english]{babel}
-\RequirePackage[textgreek=artemisia]{chemnum}
-\PassOptionsToPackage{supstfm=libertinesups}{superiors}
-\documentclass[DIV11,toc=index]{cnpkgdoc}
-\docsetup{
- pkg = chemnum,
- code-box = {skipabove=1ex,skipbelow=1ex}
-}
-\cnpkgusecolorscheme{friendly}
-\renewcommand*\othersectionlevelsformat[3]{%
- \textcolor{main}{#3\autodot}\enskip}
-\renewcommand*\partformat{%
- \textcolor{main}{\partname~\thepart\autodot}}
-\usepackage{libertinehologopatch}
-\usepackage{fnpct}
-
-\addcmds{
- @m,arrow,bf,
- ch,chemfig,chemname,cmpd,cmpdinit,cmpdref,cmpdreset,cmpdsetup,
- CNlabel,CNlabelnoref,CNref,CNlabelsub,CNlabelsubnoref,CNrefsub,
- color,compound,compoundprefix,compoundsuffix,
- declarecompound,fcite,GetTranslation,
- includegraphics,midrule,penalty,psfrag,renewcommand,
- schemename,schemestart,
- schemestop,selectlanguage,setarrowoffset,setatomsep,setcompoundsep,
- setdoublesep,section,sf,subsection,subsubsection,
- tableofcontents,texorpdfstring,textcolor,theffbibliography,
- uline
+% !arara: biber
+% arara: pdflatex
+% arara: pdflatex
+\documentclass[load-preamble+,babel-options={ngerman,british,american}]{cnltx-doc}
+\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{textcomp,longtable,tabu,booktabs,chemscheme}
-
-\usepackage[iupac=strict]{chemmacros}
-\chemsetup[chemformula]{format=\libertineLF}
-\usepackage{chemfig}
-\usepackage[runs=2]{auto-pst-pdf}
-
-\usepackage{imakeidx}
-\indexsetup{noclearpage,othercode=\footnotesize}
-\makeindex[columns=3,intoc,options={-sl \jobname.ist}]
-\usepackage{filecontents}
-\begin{filecontents*}{\jobname.ist}
- heading_prefix "{\\bfseries "
- heading_suffix "\\hfil}\\nopagebreak\n"
- headings_flag 1
- delim_0 "\\dotfill\\hyperpage{"
- delim_1 "\\dotfill\\hyperpage{"
- delim_2 "\\dotfill\\hyperpage{"
- delim_r "}\\textendash\\hyperpage{"
- delim_t "}"
- suffix_2p "\\nohyperpage{\\,f.}"
- suffix_3p "\\nohyperpage{\\,ff.}"
-\end{filecontents*}
-
-\let\prog\textsc
-\let\name\textsc
-\let\CNversion\cnpkgdocpkgversion
-\let\CNdate\cnpkgdocpkgdate
-
-\cmpdinit*{
- a,aa,
- b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,
- benzene,
- r,s,t,
- {1,3-dichlorocyclohexanole}
-}
+\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}}}}
-\TitlePicture{%
- \selectlanguage{english}
- \cmpdinit*{glucose.alpha, glucose.beta, glucose.chain}
- \cmpd*[sub-counter = greek]{glucose.alpha, glucose.beta}\cmpd*{glucose.chain}
- \setatomsep{2em}
- \definesubmol{x}{(-[4]H)(-[0]OH)}
- \definesubmol{y}{(-[0]H)(-[4]HO)}
- \begin{scheme}[h]
- \centering\small
- \schemestart
- \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){<=>}
- \chemfig{[2]OH-[3]-!x-!x-!y-!x-=[1]O}
- \arrow(--beta){<=>}
- \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] \normalsize\cmpd[cmpd-delim]{glucose.chain}
- \arrow(@chainlabel--){0}[,2.5] \normalsize\cmpd[cmpd-delim]{glucose.beta}
- \arrow(@chainlabel--){0}[180,2.3] \normalsize\cmpd[cmpd-delim]{glucose.alpha}
- \schemestop
- \caption{In a solution the \a{} and the \b{} anomer of \D-glucose
- \cmpd[list-delim]{glucose.alpha,glucose.beta} are in equilibrium via the
- open-chain form \cmpd[cmpd-delim]{glucose.chain}.}
- \end{scheme}}
-
-\newcommand*\Default[1]{%
- \hfill\llap{%
- \ifblank{#1}
- {(initially~empty)}
- {Default:~\code{#1}}%
- }\newline
-}
+\usepackage{array,booktabs}
-\usepackage{marginnote}
-\makeatletter
-\providecommand*\sinceversion[1]{%
- \@bsphack
- \marginnote{%
- \footnotesize\sffamily\RaggedRight
- \textcolor{black!75}{Introduced in version~#1}}%
- \@esphack}
-\providecommand*\changedversion[1]{%
- \@bsphack
- \marginnote{%
- \footnotesize\sffamily\RaggedRight
- \textcolor{black!75}{Changed in version~#1}}%
- \@esphack}
+\usepackage{graphicx}
-\begin{document}
-\selectlanguage{english}\cmpdreset
-
-\section{A very short readme}
-\chemnum \CNversion\ underlies the \LaTeX{} Project Public License Version~1.3
-or later. (\url{http://www.latex-project.org/lppl.txt})
-
-\chemnum internally loads the packages \paket*{expl3} and \paket{xparse}.
-\paket{xparse} is part of the \paket{l3packages} bundle, \paket*{expl3} is
-part of the \paket{l3kernel} bundle. This means, \chemnum needs \LaTeX3
-Support.
-
-\chemnum also needs the packages \paket{etoolbox}, \paket{psfrag} and either
-\paket{textgreek} or \paket{bm}, see section~\ref{sec:package:options}.
-
-\section{News and a word of apology}
-\subsection{Version 0.4}
-In the update to v0.4 there have been some changes made with the options.
-There are a few new ones and some of the old ones got new names. They now
-have consistent names which in my opinion better reflect their function. This
-means that your documents set with an older version of \chemnum might not
-compile any more without errors. I am sorry for that. \chemnum still is
-actively developped. Once it reaches v1.0, such changes won't be made any
-more\footnote{Or only in absolutely necessary cases.}.
-
-These options have new names:
-\begin{center}
- \begin{tabular}{ll}\toprule
- \bfseries old name & \bfseries new name \\\midrule
- \key{cmpd-sep} & \key{sub-output-sep} \\
- \key{sub-marker} & \key{sub-input-sep} \\
- \key{sub-range-sep} & \key{subrange-output-sep} \\
- \key{sub-range-marker} & \key{subrange-input-sep} \\
- \key{strict} & \key{init-strict} \\
- \key{sub-init} & \key{init-sub} \\\bottomrule
- \end{tabular}
-\end{center}
-These ones are new:
-\begin{center}
- \begin{tabular}{ll}\toprule
- \bfseries key & \bfseries short info \\\midrule
- \key{sublist-output-sep} & list separation in the output of labels like
- \cmpd{bsp.{one,two}}, see page \pageref{sssec:list-output-sep}. \\
- \key{sublist-input-sep} & list separation in the input of labels like
- \cmpd{bsp.{one,two}}, see page \pageref{sssec:list-input-sep}. \\
- \key{init-input-sep} & input in \cmd{cmpdinit}, see page \pageref{sssec:init-input-sep}. \\
- \key{hyper-use} & usage of hyperlinks, see page \pageref{sec:hyperref}. \\
- \key{hyper-target} & \\
- \key{hyper-link} & \\
- \key{ref-style} & Output of labels with \cmd{cmpdref}, see
- pages \pageref{ssec:cmpdref} and \pageref{ssec:schriftstil}. \\\bottomrule
- \end{tabular}
-\end{center}
-
-Also new is the way how lists and ranges of sublabels are input. The option
-\key{sub-list} no longer exists. More on this in section~\ref{ssec:sub_ranges}.
-
-Then there is the possibility of creating hyperlinked labels together with the
-package \paket{hyperref}, see section~\ref{sec:hyperref}.
-
-\subsection{Version 0.5}
-With v0.5 there is a new option \key{ref-pos} which allows to change the
-positioning options of the \cmd{psfrag} command that is used by the
-\cmd{cmpdref} command internally, see p.\,\pageref{ssec:marker_in_bildern}.
-
-\achtung{%
- The optional arguments of \cmd{cmpdref} have changed their order, see
- p.\,\pageref{ssec:cmpdref}!%
+\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
}
-\section{Package options}\label{sec:package:options}\secidx{Package options}
-\chemnum has one package option.
-\begin{beschreibung}
- \Option{textgreek}{artemisia|\default{cbgreek}|euler|false}\Default{false}
- Choose if and with which option \paket*{textgreek} is used.
-\end{beschreibung}
-This document was set with \verb+\usepackage[textgreek=artemisia]{chemnum}+.
-\secidx*{Package options}
-
-\section{Motivation}
-As far as I know there are three packages that are meant to help with
-numbering chemical compounds. All of them have their weaknesses.
-
-The first one -- \paket{chemcono} -- redefined bibliography commands for that
-purpose. Compounds have to be declared in what is called
-\verb=\theffbibliography=. Then one can reference them with \verb=\fcite=.
-However, it produces a list of compounds in the text. So the package author
-suggests:
-\begin{zitat}[Stefan Schulz]
- After compilation and printout, discard the last page.
-\end{zitat}
-Obviously that's not a perfect solution.
-
-The second one -- \paket{chemcompounds} -- was written, because the author
-didn't want to work with the weaknesses of \paket{chemcono} any more. When he
-wrote the package he basically used the same mechanism to create the labels as
-\paket{chemcono} did.
-\begin{zitat}[Stephan Schenk]
- When taking a closer look at the chemcono package, I realised that the only
- thing one has to do is to get rid of everything which produces text. Thus,
- as a basis I used the mechanism of \verb=\bibitem= and \verb=\cite= in
- pretty much the same way as \paket{chemcono} does by extracting the
- corresponding code from \verb=article.cls= and \verb=latex.ltx= but deleting
- any unnecessary commands producing output. I also introduced several lines
- of code to make the printing of the compound names more customisable.
-\end{zitat}
-Some points still left me unsatisfied, though:
-\begin{enumerate}
- \item Compounds usually need to be declared with \verb=\declarecompound=.
- They need to be declared in any case if you need a label like
- \cmpd{bsp.one}. Then, one even needs to choose the label by hand, what
- somehow undermines the automatic numbering principle.
- \item The layout can't be changed for a single label but only for all.
- \item The numbers can't be reset. \emph{Although in most cases this is
- neither necessary nor can it be recommended}, there can be individual
- cases where this would be useful.
- \item A list of several compounds \verb=\compound{a,b,c}= can only be
- customized with more effort than what would be convenient.
-\end{enumerate}
+\begin{document}
-Then there is \paket{bpchem}, which provides commands similar to \verb=\label=
-\verb=\ref=: \verb=\CNlabel{}=, \verb=\CNlabelnoref{}= and \verb=\CNref{}=.
-It provides commands for sublabels, too: \verb=\CNlabelsub{}{}=,
-\verb=\CNlabelsubnoref{}{}= and \verb=\CNrefsub{}{}=. This makes it more
-flexible than the others regarding sublabels. However, it barely provides
-possibilities to customize the labels, lists are not possible and the fact
-that there are different commands for labels and sublabels isn't the best
-solution, either.
+\section{License and Requirements}\label{sec:license-requirements}
+\license
-\chemnum is intended to fill these gaps. For this all commands have been
-written from scratch. Some of the ideas of \paket{chemcompounds} \eg regarding
-delimiters and layout have been picked up, though.
+\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} from the
+\bnd{chemmacros} bundle~\cite{bnd:chemmacros} and the
+\pkg{psfrag}~\cite{pkg:psfrag} package.
-If you notice any feature missing, please let me know by sending me an email.
+\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}
-\section{Numbering compounds}\label{sec:nummerieren}
-\subsection{Main command}\secidx{Main command}\cmpdreset
+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{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{beschreibung}
- \Befehl{cmpd}{<label name>}
-\end{beschreibung}
-When \code{<label name>} is used the first time, the label is created, saved
-(= declared) and printed. Each further use just prints the label.
-
-\begin{beispiel}
- 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{beispiel}
-
-If it is necessary to declare a compound without printing the label, this is
+\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{beschreibung}
- \Befehl[cmpda]{cmpd*}\ma{<label name>}\label{cmd:unsichtbares_label}
-\end{beschreibung}
-This declares the label but doesn't print anything.
-
-\achtung{%
- This command is not needed when \cmd{cmpdinit} is used, see
- section~\ref{sec:cmpdinit} (pages~\pageref{sec:cmpdinit}ff).%
-}
+\begin{commands}
+ \command{cmpd}[\sarg\marg{\ac{id}}]
+ Declare the label \meta{\ac{id}} but don't print anything.
+\end{commands}
-\begin{beispiel}
- 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{beispiel}
+\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 sections~\ref{ssec:unterlabel}, \ref{ssec:listen},
-\ref{ssec:sub_ranges} and \ref{ssec:trenner}). You shouldn't leave blanks in
-the name, though. This may not cause an error at all, but \emph{could}
-declare different compounds with the same name.
-
-\lstset{showspaces=true}
-\begin{beispiel}
- \cmpd{aa }, \cmpd{a a }, \cmpd{a a}, \cmpd{ a a}, \cmpd{ aa} and \cmpd{ aa }
- all have the same label. As well as \cmpd{aa }, \cmpd{a a}, \cmpd{ aa} and
- \cmpd{aa}.
-\end{beispiel}
-\lstset{showspaces=false}\secidx*{Main command}
-
-\subsection{Sublabel}\label{ssec:unterlabel}\secidx{Sublabel}
+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{beschreibung}
- \Befehl{cmpd}{<label name>.<subname>}
-\end{beschreibung}
-\code{<label name>} is the main name which stays the same, \code{<subname>}
-varies. This syntax means that the point \code{.} \emph{cannot} be a part of
-\code{<label name>} or \code{<subname>}. Instead of the point you also can
-use another symbol, see section~\ref{sssec:sub-input-sep}.
-\begin{beispiel}
- \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{beispiel}
-
-This also works, if the main name has already been used.
-\begin{beispiel}
- \cmpd{a} and its variants \cmpd{a.one} and \cmpd{a.two}
-\end{beispiel}
+\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{beispiel}
- \cmpd{f} and \cmpd{g}
-\end{beispiel}
+\begin{example}[side-by-side]
+ \cmpd{f} and \cmpd{g}
+\end{example}
-How you can create a label like \cmpd{f.{one,two}} is explained in
-section~\ref{ssec:sub_ranges}.
-\secidx*{Sublabel}
+How you can create a combined label like \cmpd{f.{one,two}} is explained in
+section~\ref{sec:lists-rang-subl}.
-\subsection{Lists}\label{ssec:listen}\secidx{Lists}
-There is actually more to the \cmd{cmpd} command. It also prints lists of
+\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{beschreibung}
- \Befehl{cmpd}{<(possibly comma separated list of) label name(s)>}
-\end{beschreibung}
+\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. You can change that, see
-section~\ref{sssec:list-input-sep} on page~\pageref{sssec:list-input-sep}.
-Section~\ref{sssec:input-sep-bsp} shows an example how a changed input could
-look like.
-
-\begin{beispiel}
- More than one label can be put inside \verb=\cmpd=, separated by commas.
- Then a list like \cmpd{a, b, c, e, g.two} is printed.
-\end{beispiel}
-The Harvard comma (see~\ref{ssec:harvard-comma}) in \code{, and} between
-\cmpd{e} and \cmpd{g.two} suggests that there are options to customize the
-list, see sections~\ref{ssec:trenner} and \ref{sec:language_support}.
-\secidx*{Lists}
-
-\subsection{Lists and ranges of sublabels}\label{ssec:sub_ranges}\index{Sublabel!lists}\index{Sublabel!ranges}
+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:
-\cmpd[cmpd-all]{q}.
The syntax is rather intuitive -- you just input a list of sublabels:
-\begin{beispiel}
- list of labels: \cmpd{q.one, q.two, q.three, q.four, q.five}\\
- label with list of sublabels: \cmpd{q.{one,two,three,four,five}}
-\end{beispiel}
-Since the sublist is input with a comma in the default setting, you have to
-put them into braces.
-
-Using this syntax you also can create ranges of sublabels. As a marker to
-indicate the range \chemnum uses two points \verb=..=.
-\begin{beispiel}
- \cmpd{q.{two..four}}\\
- \cmpd{q.{one,three..five}}\\
- \cmpd{q.{one..three,five}}
-\end{beispiel}
-
-This means you can neither use the comma nor the two points as part of a
-sublabel name. How you can use other markers for the input you can read in
-sections~\ref{sssec:range-input-sep} and \ref{sssec:list-input-sep}.
-
-\chemnum provides an option (see section~\ref{sec:cmpdsetup} for more
-details), with which all sublabels of a main label can be printed as range.
-\begin{beschreibung}
- \Option{cmpd-all}{\default{true}|false}\Default{false}
- Show all sublabels.
-\end{beschreibung}
-\begin{beispiel}
- \cmpd[cmpd-all]{q}
-\end{beispiel}
-
-In order to get the right sublabels the command needs to know which sublabels
-have been declared. This means that they're read from the
-\verb=\jobname.cmpd= file (supposing your source file is called
-\verb=\jobname.tex=). So you may need to compile twice (or more) until the
-labels are printed right.
-
-If one uses label with sublabel ranges, one might want to use \emph{only} the
-sublabels in a different place. This is possible with this option:
-\begin{beschreibung}
- \Option{sub-only}{\default{true}|false}\Default{false}
- Print only the sublabel.
-\end{beschreibung}
-\begin{beispiel}
- % uses packages `chemfig', `chemmacros' and `booktabs'
- \cmpd*{benzene.H,benzene.Me,benzene.OH,benzene.NH2}
- \chemname{\chemfig{*6(=-=-(-R)=-)}}{\cmpd[cmpd-all]{benzene}}
- \begin{tabular}{lll}
- & \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)
- \end{tabular}
-\end{beispiel}
-
-Ranges of sublabels require some care. For one thing one has to know which
-sublabel is the lower one and which is the higher one. Then one has to know
-which labels are in between them and what do they represent. As \chemnum
-can't take care for you, you need to do that for yourself if you want to avoid
-labels like these:
-\begin{beispiel}
- \cmpd{q.{five..three}} or \cmpd{q.{three,one,four}}.
-\end{beispiel}
-
-\section{Initialize labels at once}\label{sec:cmpdinit}\secidx{Initialize labels}
-The commands described in this section are not essential for the usage of
-\chemnum, but provide additional functionality that some users might find
-useful.
-
-\subsection{Usage}
-\subsubsection{Main labels}
-Perhaps you're missing \paket{chemcompounds}' command \verb=\declarecompound=
-already. With it for one thing one had a summary of all used label names.
-And there was a warning if one used an uninitialized label name\footnote{for
- instance due to a typing error}. This behaviour can be realized with these
-commands:
-\begin{beschreibung}
- \Befehl{cmpdinit}{<comma separated list of label names>}
- \Befehl[cmpdinita]{cmpdinit*}{<comma separated list of label names>}
-\end{beschreibung}
-All compounds set inside \cmd{cmpdinit} are initialized and declared \emph{in
- the given order}. If one uses a label name that's not in the list, \chemnum
-produces a warning message.
-
-\cmpdreset
-\begin{beispiel}
- \cmpdinit{A, B, C} \cmpd{B} \cmpd{A.a} \cmpd{C} \cmpd{D}
-\end{beispiel}
-
-\begin{mdframed}
- \small\ttfamily\noindent
- {}*************************************************\\
- {}* chemnum warning: "cmpd-init"\\
- {}* \\
- {}* You used \verb=\cmpdinit= but didn't initiate compound "D"{} on line 1.\\
- {}*************************************************
-\end{mdframed}
-
-Please note that for labels with sublabels only the \emph{main name} can and
-should be initialized. This initializes all compounds with the same main
-name.
-
-\cmd[cmpdinita]{cmpdinit*} also produces a warning but doesn't declare the
-labels. They are declared when you first use them in the order of appearance
-in the text.
-
-\cmpdreset
-\begin{beispiel}
- \cmpdinit*{X, Y, Z} \cmpd{Y} \cmpd{X.x} \cmpd{Z} \cmpd{W}
-\end{beispiel}
-
-\begin{mdframed}
- \small\ttfamily\noindent
- {}*************************************************\\
- {}* chemnum warning: "cmpd-init"\\
- {}* \\
- {}* You used \verb=\cmpdinit= but didn't initiate compound "W"{} on line 1.\\
- {}*************************************************
-\end{mdframed}
-
-If you need to use own labels (see page \pageref{ssec:own_labels}) but still
-want to initialize all labels at once, you should use
-\cmd[cmpdinita]{cmpdinit*}{}, because then no labels are declared when they're
-initialized.
-
-This command can be used several times, with or without \verb=*=. A useful
-way would be a single usage, though, proposedly in the preamble of your
-document after the \chemnum setup (see section~\ref{sec:cmpdsetup}).
-
-\subsubsection{Sublabels}
-If you'd like a warning for label-sublabel combinations as well, or want to
-preset their order, you can use
-\begin{beschreibung}
- \Befehl{cmpdinit}[\key{init-sub}{true}]{<comma separated list of label names>}
-\end{beschreibung}
-This will give you a warning in these cases, too.
-
-\cmpdreset
-\begin{beispiel}
- \cmpdinit[init-sub = true]{E.{e,f,g}}
- \cmpd{E.e, E.h}
-\end{beispiel}
-
-\begin{mdframed}
- \small\ttfamily\noindent
- {}*************************************************\\
- {}* chemnum warning: "cmpd-init-sub"\\
- {}* \\
- {}* You used \verb=\cmpdinit= and "{}init-sub = true"{} but didn't initiate sub-compound\\
- {}* "{}E.h"{} on line 1.\\
- {}*************************************************
-\end{mdframed}
-
-\subsection{Error instead of warning}
-If you want \chemnum to produce an error instead of a warning when you use an
-unititialized label name, you can use \cmd{cmpdinit} like this:
-\begin{beschreibung}
- \Befehl{cmpdinit}[\key{init-strict}{true}]{<comma separated list ...>}
-\end{beschreibung}
-A usage of \key{init-strict}{false} would be the usage without optional
-argument. Of course the *-version has the same option.
-
-With \key{init-strict}{true} the \LaTeX\ run will be aborted with a
-corresponding error message, if a label name is used that hasn't been
-initialized before.
-
-Of course you can use \cmd{cmpdinit} with both options
-\begin{beschreibung}
- \Befehl{cmpdinit}[\key{init-strict}{true}, \key{init-sub}{true}]{<comma separated list ...>}
-\end{beschreibung}
-or use \cmd{cmpdsetup}, see section~\ref{sec:cmpdsetup}.
-
-\subsection{Customized input}
-When you're using other tokens for \key{sub-input-sep}
-(page~\pageref{sssec:sub-input-sep}) or \key{sublist-input-sep}
-(page~\pageref{sssec:list-input-sep}), you have to use them with
-\cmd{cmpdinit} as well.
-
-A change of \key{list-input-sep} (page \pageref{sssec:list-input-sep}) doesn't
-affect \cmd{cmpdinit}. If you want to change the input of \cmd{cmpdinit} you
-need to use \key{init-input-sep}, see section~\ref{sssec:init-input-sep} on
-page~\pageref{sssec:init-input-sep}.
-
-\subsection{Why initiate labels?}
-As mentioned in the beginning of this section the initiation of labels is not
-required. There are two possible reasons, why one would like to use them,
-anyway.
-\begin{enumerate}
- \item The use of \cmd[cmpdinita]{cmpdinit*} is a way to keep track of which
- labels you have used and gives you a warning/error message if you use a
- new one or just have mispelled an existing one. Depending on the number
- of labels you (have to) use, this can be lots of additional work, though.
- \item The use of \cmd{cmpdinit} does the same thing as
- \cmd[cmpdinita]{cmpdinit*} \emph{and} declares all the labels in the given
- order. So if you use it, you won't have to use \cmd[cmpda]{cmpd*}
- (section~\ref{cmd:unsichtbares_label}) and \cmd[cmpdb]{cmpd+}
- (section~\ref{cmd:cmpd_plus}). This gives you direct control, which
- number is given to which compound.
-\end{enumerate}
-\secidx*{Initialize labels}
-
-\section{Resetting the counter}\label{sec:cmpdreset}\secidx{Reset the counter}
-With the command
-\begin{beschreibung}
- \Befehl{cmpdreset}[<number>]
-\end{beschreibung}
-it is possible to reset the counter. Without argument it is reset to
-\verb=1=. So \cmd{cmpdreset} and \cmd{cmpdreset}[1] are the same. Unlike
-most other \chemnum commands its impact is not only inside the local \TeX\
-group but resets the counter globally.
-\begin{beispiel}
- \cmpdreset The numbering starts with 1 again: \cmpd{h, i, j}
-\end{beispiel}
-
-\achtung{%
- You should be careful with how you use this command! Usually it cannot be
- recommended to reset the counter. Different compounds can get the same
- label!%
-}
+\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}
-\begin{beispiel}
- Same label: \cmpd{a}, \cmpd{h}
-\end{beispiel}
-\secidx*{Reset the counter}
-
-\section{Special usage}\secidx{Special usage}
-\subsection{Moving arguments -- section titles}
-Using \cmd{cmpd} inside a section title in the first instant doesn't seem to
-be a problem. This doesn't give any errors and the output looks like
-expected:
-\begin{beispiel}[code only]
- \section{Compound \cmpd[cmpd-delim]{b}}
- \ldots
-\end{beispiel}
-However, if you use \verb=\tableofcontents= -- which is rather probable, I
-guess -- something unwanted happens: because the table of contents is at the
-beginning of the document, the label is declared in the table of contents
-instead of at the first appearance in the text. There are two ways to
-circumvent this:
+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 You declare your labels in the order you want with \cmd{cmpdinit}{}=
- (see page~\pageref{sec:cmpdinit}) in the preamble or the beginning of the
- document.
- \item You use \cmd[cmpdb]{cmpd+} to set the label. It will read the label
- from the file \verb=<jobname>.cmpd= (supposing your main file is called
- \verb=<jobname>.tex=). This means \emph{at least two}, maybe more \LaTeX\
- runs are necessary until all labels are set.
+ \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}
-The same is true for any other list of moving arguments that is created
-\emph{before} the actual appearance of the label in the text.
-
-The command\label{cmd:cmpd_plus}
-\begin{beschreibung}
- \Befehl[cmpdb]{cmpd+}\ma{<label name>}
-\end{beschreibung}
-reads the label name that is to be printed from \verb=\jobname.cmpd=. In a
-way this is the opposite of \cmd[cmpda]{cmpd*} since it doesn't declare a
-label but only references and prints it. So in order to use
-\cmd[cmpdb]{cmpd+}{<label>}, \verb=<label>= must have been declared, either
-with \cmd{cmpd}{<label>} or with \cmd[cmpda]{cmpd*}{<label>}. It doesn't
-matter, if this declaration is done before or after the usage of
-\cmd[cmpdb]{cmpd+}. This command is useful, if the label is used inside a
-moving argument like in \verb=\section{}=.
-
-\achtung{%
- It is not needed when \cmd{cmpdinit} is used, see section~\ref{sec:cmpdinit}
- (pages~\pageref{sec:cmpdinit}\,ff).%
-}
-\begin{beispiel}[code only]
- \subsubsection{Test section title with compound label \cmpd+[cmpd-delim]{f.one}}
- % with hyperref:
- \subsubsection{Test section title with compound label \texorpdfstring{\cmpd+[cmpd-delim]{f.two}}{(7b)}}
-\end{beispiel}
-
-\subsection{Floating environments}\cmpdinit*{float1,float2}
-The usage of \cmd{cmpd} inside a float shouldn't be a problem: labels are
-declared in the order the floating environment appears in the code. However,
-to be on the safe side you can of course use \cmd[cmpdb]{cmpd+} here as well.
-\begin{beispiel}[code and float]
- % preamble:
- % \usepackage{chemscheme}
- % document:
- \cmpdreset\cmpd{float1, float2}. Now inside of a scheme:
- \begin{scheme}[h]
- \centering
- \caption{This label should be a 2: \cmpd{float2}}
- If 2 = \cmpd{float2} is true, everything's fine.
- \end{scheme}
-\end{beispiel}
-
-This also works, of the floating environment is placed before the code, for
-instance by using the option \verb=[t]=.
-
-\cmpdinit*{Alc,EtherBr,cpd}
-\subsection{Schemes created by external programs}\label{ssec:cmpdref}\secidx{Schemes by external programs}
-If you create your schemes by external programs like for \eg \prog{ChemDraw}
-or \prog{Marvin\-Sketch}, and want to use \chemnum with them as well, you can
-use this command:
-\begin{beschreibung}
- \Befehl{cmpdref}[<tag>]\oa{<options>}\ma{<label name>}
- \Befehl[cmpdrefa]{cmpdref+}[<tag>]\oa{<options>}\ma{<label name>}
-\end{beschreibung}
-This command is inspired by the \verb=\schemeref= command from the package
-\paket{chemscheme}. It works in a very similar way. You create the scheme
-and save it with temporary labels as an \verb=eps= file.
-
-Like \cmd{cmpd+} the plussed variant only references a label but does not
-declare it.
-
-\begin{beispiel}[code and float]
- \begin{scheme}[ht]
- \centering
- \includegraphics{scheme-tmp.ps}
- \caption{Scheme with temporary markers.}
- \end{scheme}
- \begin{scheme}[ht]
- \centering
- \cmpdref{Alc} % replaces TMP1
- \cmpdref{EtherBr} % replaces TMP2
- % \cmpdref{third} would replace TMP3
- \includegraphics{scheme-tmp.ps}
- \caption{Scheme with automated labels.}
- \end{scheme}
-\end{beispiel}
-So you nummerate the compounds with \textsf{TMP1}, \textsf{TMP2} etc. These
-markerswill then be replaced with the corresponding labels. Like
-\paket{chemscheme} \chemnum uses the \cmd{psfrag} command of the
-\paket{psfrag} package to do that. This means you have to either compile via
-\prog{latex}, \prog{dvips}, \prog{ps2pdf}, or for instance use the package
-\paket{auto-pst-pdf} to be able to use \hologo{pdfLaTeX}. It doesn't work
-with \hologo{XeLaTeX}, neither probably with \hologo{LuaLaTeX}, the author
-didn't test that, though.
-
-In each case it is important that the marker is saved as \emph{text} in the
-\verb=eps= file.
-
-You can customize the labels with the options presented in
-section~\ref{sec:cmpdsetup}.
-\begin{beispiel}[code and float]
- \begin{scheme}[ht]
- \centering
- \cmpdsetup{ref-style=\color{green}}
- \cmpdref{Alc} % replaces TMP1
- \cmpdref{EtherBr} % replaces TMP2
- \includegraphics{scheme-tmp.ps}
- \caption{Scheme with automated labels.}
- \end{scheme}
-\end{beispiel}
-
-You also can replace arbitrary text by using the second optional argument.
-\begin{beispiel}[code and float]
- \begin{scheme}[ht]
- \centering
- \includegraphics{scheme-bla.ps}
- \caption{Scheme with arbitrary markers.}
- \end{scheme}
- \begin{scheme}[ht]
- \centering
- \cmpdref[blah]{Alc}
- \cmpdref[blub]{EtherBr}
- % \cmpdref{third} would replace TMP1
- \includegraphics{scheme-bla.ps}
- \caption{Scheme with explicitly placed labels.}
- \end{scheme}
-\end{beispiel}
-
-Of course sublabels work in the known way:
-\begin{beispiel}[code and float]
- \begin{scheme}[ht]
+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{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 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}).
+\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
- \cmpdref{cpd.red}
- \cmpdref{cpd.ox}
- \includegraphics{scheme-tmp.ps}
- \caption{Scheme with automated labels and sublabels.}
- \end{scheme}
-\end{beispiel}
-\cmpdreset[10]\secidx*{Schemes by external programs}
-\secidx*{Special usage}
-
-\section{Usage with \paket{hyperref}}\label{sec:hyperref}\secidx[Usage with hyperref]{Usage with \textsf{hyperref}}
-\subsection{Basics}
-If you are using the package \paket{hyperref} you can make hyperlinked labels
-in your \prog{pdf}.
-\begin{beschreibung}
- \Option{hyper-use}{\default{true}|false}\Default{false}
- Link labels with \paket{hyperref}'s hyperlink commands.
-\end{beschreibung}
-Setting this option (see section~\ref{sec:cmpdsetup} for more information) to
-\code{true}, the next usage of a label will create a link target and the ones
-after that will create links to this target. This only works if the label
-does \emph{not} contain a list or range of sublabels. Also a label set with
-\cmd[cmpda]{cmpd*} can't be marked as target.
-
-\begin{beispiel}
- \cmpdsetup{hyper-use}
- The first time targets are created: \cmpd{a.two,b,c,d,e,f}. Then links are
- created: \cmpd{a.two,d,e}.
-
- This doesn't work with labels containing a list of sublabels:
- \cmpd{a,f.{one,two},c}. Since \cmpd{a.two} and \cmpd{a} are different labels
- they have different link targets.
-\end{beispiel}
-
-\subsection{Selected usage}
-Maybe the automated use isn't what you want or need. Maybe is is enough to
-create a hyperlink in one or two places. This can be achieved with two
-options:
-\begin{beschreibung}
- \Option{hyper-target}{<link name>}\Default{}
- Set a hyperlink target.
- \Option{hyper-link}{<link name>}\Default{}
- Set a hyperlink.
-\end{beschreibung}
-With \key{hyper-target} you can set the target. \textbf{Caution}: if you use
-this option with a list \emph{every} label of the list will get the same link
-name and \paket{hyperref} will warn you:
-\begin{mdframed}\ttfamily\small
- destination with the same identifier (name\{<link name>\}) has been already
- used, duplicate ignored
-\end{mdframed}
-
-\key{hyper-link} creates a link for the denominated target. \textbf{Caution}:
-if you use this option with a list \emph{every} label of the list will refer
-to the same target.
-\begin{beispiel}
- Create a link \cmpd[hyper-link=mylink,cmpd-all]{f} but don't forget the
- corresponding target: \cmpd[hyper-target=mylink,cmpd-all]{f}.
-\end{beispiel}
-
-If you use \key{hyper-link} without the corresponding \key{hyper-target}
-\paket{hyperref} will issue a warning:
-\begin{mdframed}\ttfamily\small
- name\{<link name>\} has been referenced but does not exist, replaced by a
- fixed one
-\end{mdframed}
-\secidx*[Usage with hyperref]{Usage with \textsf{hyperref}}
-
-\section{Customization}\label{sec:cmpdsetup}
-\subsection{The principle}
-\chemnum is customized with a key-value system. They can either be used for
-all following commands with
-\begin{beschreibung}
- \Befehl{cmpdsetup}{key1 = value1, key2 = value2}
-\end{beschreibung}
-or only for a single command directly with
-\begin{beschreibung}
- \Befehl{cmpd}[key1 = value1, key2 = value2]{<label name>}
-\end{beschreibung}
-
-If you use keys without values like \cmd{cmpdsetup}{key1,key2}, default
-values\label{opt:default} are used. These are \emph{not} necessarily empty
-are \emph{not} necessarily the default setting of \chemnum.
-
-The options are divided in to different classes\label{key_classes}, which
-indicate the scope they're used for. They all follow the form
-\verb+<class>-option = <value>+:
+ \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}
+
+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 \code{cmpd}: These options change the whole label or the main label.
- \item \code{sub}, \code{sublist}, \code{subref}: These options have an
- impact on sublabels.
- \item \code{list}: Options which change the output of lists.
- \item \code{ref}: Options which have an impact on \cmd{cmpdref}.
- \item \code{hyper}: Options which have an impact on the usage with
- \paket{hyperref}.
- \item \code{init}: Options which have an impact in the initialization of the
- labels.
+ \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}
-\subsection{Font style}\label{ssec:schriftstil}\secidx{Font style}
-With the keys
-\begin{beschreibung}
- \Option{cmpd-style}{<style>}\Default{}
- formatting commands for the labels. The last command can demand an
- argument.
- \Option{cmpd-weight}{bold|normal}\Default{bold}
- setting labels in bold series. The setting for this is extra since greek
- labels internally have to be treated a little differently.
-\end{beschreibung}
-you can change the style with which the labels are printed.
-
-\begin{beispiel}
- % preamble:
- % \usepackage[normalem]{ulem}
- % document:
- \cmpd{a, b, f.two, k}\\ % default
- \cmpd[cmpd-style = \uline]{a, b, f.two, k}\\ % underlined
- \cmpd{a, b, f.two, k}\\ % default again
- \cmpdsetup{cmpd-style = \itshape\uline}
- \cmpd{a, b, f.two, k}\\ % underlined and in italics
- \cmpd[cmpd-weight=normal]{a, b, f.two, k}
-\end{beispiel}
-The separate handling of the bold face is because of the greek labels (see
-section~\ref{ssec:counter}). Depending on the package option
-\code{textgreek}, the bold face must realized differently.
-\secidx*{Font style}
-
-\subsection{Own labels}\label{ssec:own_labels}\secidx{Own labels}
-\begin{beschreibung}
- \Option{cmpd-label}{<label>}\Default{}
- This key let's you choose the label associated with the label name.
-\end{beschreibung}
-
-\begin{beispiel}
- Own label: \cmpd[cmpd-label = XYZ]{l}; in a list \emph{all new compounds} get
- this label! \cmpd[cmpd-label = XYZ]{l, a, m}
-\end{beispiel}
-\secidx*{Own labels}
-
-\subsection{Markers in images}\secidx{Markers in images}\label{ssec:marker_in_bildern}
-There are several options that affect labels in external images placed with
-\cmd{cmpdref}.
-\begin{beschreibung}
- \Option{ref-marker}{<marker>}\Default{TMP}
- This changes the default marker that is to be replaced.
- \Option{ref-pos}{\{<tex-pos>\}\{<ps-pos>\}}\Default{bb}
- explained below
- \Option{ref-style}{<style>}\Default{\cmd*{sffamily}}
- change the format of the labels in external schemes.
-\end{beschreibung}
-With \key{ref-pos} you can change the default way how \cmd{cmpdref} places the
-label. The command \cmd{psfrag} that is used internally has two options for
-that. The first one determines the position of the \TeX-replacement, the
-second one how it is placed in the box from the marker that is replaced. For
-details please refer to the documentation of \paket{psfrag}.
-\secidx*{Markers in images}
-
-\subsection{Counter}\label{ssec:counter}\secidx{Counter}
-You can change the format of the counters, too, if you like.
-\begin{beschreibung}
- \Option{cmpd-counter}{arabic|alph|Alph|greek|Greek|roman|Roman|Symbol}\Default{arabic}
- The counter format for the main labels.
- \Option{sub-counter}{arabic|alph|Alph|greek|Greek|roman|Roman|Symbol}\Default{alph}
- The counter format for sublabels.
-\end{beschreibung}
-
-Please note: a change of format only affects labels \emph{which are not yet
- declared}!
-\begin{beispiel}
- \cmpdsetup{cmpd-counter = Alph, sub-counter = arabic}
- % no affect with existing labels
- \cmpd{a, b, f.two, k}\\
- \cmpd{n.one,n.two,o.one}\\
- % be careful: the main label already exists and isn't changed!
- \cmpd{f.three,f.four}\\
- \cmpd[cmpd-counter,sub-counter = greek]{p.one,p.two}
-\end{beispiel}
-\secidx*{Counter}
-
-\subsection{Delimiters}\secidx{Delimiters}
-Both single labels and whole lists can get delimiters. This is done with the
-options
-\begin{beschreibung}
- \Option{cmpd-delim}{<odelim><cdelim>}\Default{}
- Delimiters to the single labels, need to be \emph{two} tokens!
- \Option{list-delim}{<odelim><cdelim>}\Default{}
- Delimiters to a list of labels, need to be \emph{two} tokens!
-\end{beschreibung}
-\begin{beispiel}
- \cmpd{a, b, f.two, k}\\ % default
- \cmpd[cmpd-delim = ()]{a, b, f.two, k}\\ % in braces
- \cmpd{a, b, f.two, k}\\ % default again
- \cmpdsetup{cmpd-delim = ()}
- \cmpd{a, b, f.two, k} % in braces
-\end{beispiel}
-Please be aware that the default values (see pages~\pageref{opt:default} and
-\pageref{ssec:keys_uebersicht}) of \key{cmpd-delim} and \key{list-delim} and
-the default setting of \chemnum are \emph{not} the same. By default \chemnum
-doesn't use delimiters. Also please note that the list delimiters only are
-used if \cmd{cmpd} contains at least two label names.
-\begin{beispiel}
- \cmpd{a, b, f.two, k}\\ % default
- \cmpd[list-delim = {[}{]}]{a, b, f.two, k}\\ % in braces
- \cmpd{a, b, f.two, k}\\ % default again
- \cmpdsetup{list-delim = []}
- \cmpd{a, b, f.two, k}\\ % in braces
- \cmpd{a} % NOT a list!
-\end{beispiel}
-If you generally use labels in braces but want to use a single one without
-braces, you have several possibilities:
-\begin{beispiel}
- \cmpdsetup{cmpd-delim = ()}
- normally: \cmpd{b}, \cmpd{c}, \cmpd{d.one}, but sometimes so
- \cmpd[cmpd-delim = ]{e} or so \cmpd-{e}.
-\end{beispiel}
-With
-\begin{beschreibung}\label{cmd:ohne_begrenzer}
- \Befehl[cmpdc]{cmpd-}\ma{<label name>}
- \Befehl[cmpdrefc]{cmpdref-}\ma{<label name>}
-\end{beschreibung}
-the braces of single labels can easily be removed (but not the ones of a
-list).
-\begin{beispiel}
- \cmpd{a, b, f.two, k}\\ % default
- \cmpdsetup{cmpd-delim = (), list-delim = []}
- \cmpd{a, b, f.two, k}\\ % braced twice
- \cmpd-{a, b, f.two, k} % braced once
-\end{beispiel}
-
-Using \cmd{cmpdsetup}{\key{cmpd-delim}{ }} and
-\cmd{cmpdsetup}{\key{list-delim}{ }} will restore the default behaviour.
-\secidx*{Delimiters}
-
-\subsection{Suffix and prefix}\secidx{Suffix and prefix}
-If you want to, you can also add a prefix and/or a suffix to a compound and/or a
-list.
-\begin{beschreibung}
- \Option{cmpd-prefix}{<prefix>}\Default{}
- Set a prefix for a label.
- \Option{cmpd-suffix}{<prefix>}\Default{}
- Set a suffix for a label.
- \Option{list-prefix}{<prefix>}\Default{}
- Set a prefix for a list.
- \Option{list-suffix}{<prefix>}\Default{}
- Set a suffix for a list.
-\end{beschreibung}
-The same rule as for the delimiters applies: list attributes are only used
-with lists, \ie at least with two items.
-
-An example for the label attributes:
-\begin{beispiel}
- \cmpd{a, b, f.two, k}\\ % default
- \cmpd[cmpd-prefix = Nr.]{a, b, f.two, k}\\
- \cmpdsetup{cmpd-prefix = \(\rightarrow\)}
- \cmpd{a, b, f.two, k}\\
- \cmpd{a} % NOT a list!
-\end{beispiel}
-An example for the list attributes:
-\begin{beispiel}
- \cmpd{a, b, f.two, k}\\ % default
- \cmpd[list-prefix = list:]{a, b, f.two, k}\\
- \cmpdsetup{list-prefix = collection:}
- \cmpd{a, b, f.two, k}\\
- \cmpd{a} % NOT a list!
-\end{beispiel}
-
-Between prefix, label and suffix there is a space inserted as default
-behaviour:
-\begin{beispiel}
- \cmpd[cmpd-suffix=sx,cmpd-prefix=px]{k}
-\end{beispiel}
-It can be changed with
-\begin{beschreibung}
- \Option{cmpd-space}{<space>}
-\end{beschreibung}
-\begin{beispiel}
- \cmpd[cmpd-suffix=sx,cmpd-prefix=px,cmpd-space={}]{k}
-\end{beispiel}
-\secidx*{Suffix and prefix}
-
-\subsection{Separators}\label{ssec:trenner}\secidx{Separators}
-\subsubsection{Labels -- input}\label{sssec:sub-input-sep}\index{Separators!labels!input}
-As a default setting \chemnum use the point \code{.} as a marker to separate
-main labels from sublabels. You can change that as you like. Tokens you
-\emph{can't use} are \verb=%=, \verb=,= and \verb=#= and \emph{you shouldn't}
-use \verb=@=. Furthermore you should be careful to use different symbols for
-the other separators (see the next sections).
-\begin{beschreibung}
- \Option{sub-input-sep}{<separator>}\Default{.}
- The token that separates sublabels from main labels.
-\end{beschreibung}
-\begin{beispiel}
- \cmpdsetup{sub-input-sep = !}
- \cmpd{f!one, g!two}\\
- \cmpd[sub-input-sep= +]{f+one, g+two}\\
- \cmpd[sub-input-sep= ~]{f~one, g~two}\\
- \cmpd[sub-input-sep= &]{f&one, g&two}\\
- \cmpd[sub-input-sep= *]{f*one, g*two}
-\end{beispiel}
-You should -- not only for the sake of consistency -- decide only \emph{once}
-in the beginning of your document \emph{before} the \verb=\tableofcontents= or
-in the preamble, which marker you use. Otherwise, the \verb=\tableofcontents=
-won't know the marker anymore and your labels might be at least displayed
-wrong in the table of contents. Also you need to setup the marker
-\emph{before} you use it with \cmd{cmpd} or \cmd{cmpdinit} etc.
-
-\subsubsection{Labels -- output}\index{Separators!labels!output}
-You can separate the labels from the sublabels if you like to.
-\begin{beschreibung}
- \Option{sub-output-sep}{<separator>}\Default{}
- the separator between main and sublabels in the output.
-\end{beschreibung}
-\begin{beispiel}
- \cmpd{a, b, f.two, f.three, k}\\ % default
- \cmpd[sub-output-sep = -]{a, b, f.two, f.three, k}\\
- \cmpdsetup{sub-output-sep = $\cdot$}
- \cmpd{a, b, f.two, f.three, k}\\
- \cmpd[sub-output-sep = :]{a, b, f.two, f.three, k}
-\end{beispiel}
-
-\subsubsection{Sublabels -- input}\label{sssec:range-input-sep}\index{Separators!subabels!input}
-As a default setting \chemnum use two points \code{..} as a marker to detect
-two sublabels as end and beginning of a range. But you can choose any tokens
-you like to do that. Tokens you \emph{can't use} are \verb=%=, \verb=,= and
-\verb=#= and \emph{you shouldn't} use \verb=@=. Furthermore you should be
-careful to use different symbols for the other separators.
-\begin{beschreibung}
- \Option{subrange-input-sep}{<separator>}\Default{..}
- The tokens that indicate a range of sublabels
-\end{beschreibung}
-\begin{beispiel}
- \cmpd[subrange-input-sep=:]{q.{one:four}}\\
- \cmpdsetup{subrange-input-sep=--}
- \cmpd{q.{one--four}}
-\end{beispiel}
-
-\subsubsection{Sublabels -- output}\index{Separators!subabels!output}
-Maybe you don't like the output of \cmpd[cmpd-all]{q} and you want it displayed
-differently? Then you need this key:
-\begin{beschreibung}
- \Option{subrange-output-sep}{<separator>}\Default{--}
- The tokens that are placed between the sublabels of a range in the
- output.
-\end{beschreibung}
-\begin{beispiel}
- \cmpd[subrange-output-sep={ {\normalfont to} }]{q.{one..four}}\\
- \cmpdsetup{subrange-output-sep=-}
- \cmpd{q.{one..four}}
-\end{beispiel}
-
-\subsubsection{Lists -- input}\label{sssec:list-input-sep}\index{Separators!lists!input}
-If you like you can change the list input separator for both main label lists
-and lists of sublabels. In both cases \chemnum uses the comma \code{,} as
-default. You can change that as you like. Tokens you \emph{can't use} are
-\verb=%=, \verb=,= and \verb=#= and \emph{you shouldn't} use \verb=@=.
-Furthermore you should be careful to use different symbols for the other
-separators.
-\begin{beschreibung}
- \Option{list-input-sep}{<separator>}\Default{,}
- Separator between main labels in the input.
- \Option{sub-input-sep}{<separator>}\Default{,}
- Separator between sublabels in the input.
-\end{beschreibung}
-\begin{beispiel}
- \cmpd{a, b, f.two, k}\\ % default
- \cmpd[list-input-sep = +]{a + b + f.two + k}\\
- \cmpd{a, b, f.two, k}\\
- \cmpdsetup{list-input-sep = ;}
- \cmpd{a; b; f.two; k}
-\end{beispiel}
-With this you can for example use IUPAC names as label names\footnote{Thanks
- to Christina L\"udigk who in a way suggested this feature.}.
-\begin{beispiel}
- \cmpdsetup{list-input-sep=;}
- \cmpd{1,3-dichlorocyclohexanole}
-\end{beispiel}
-
-\subsubsection{Lists -- output}\label{sssec:list-output-sep}\index{Separators!lists!output}
-You can change the separator symbol with which lists are printed as
-well. \chemnum uses the comma for both cases in the default setting.
-\begin{beschreibung}
- \Option{list-output-sep}{<separator>}\Default{,}
- Separator between main labels in the output of a list.
- \Option{sub-output-sep}{<separator>}\Default{,}
- Separator between sublabels in the output of a sublist.
-\end{beschreibung}
-\begin{beispiel}
- \cmpd{a, b, f.two, k}\\ % default
- \cmpd[list-output-sep = ]{a, b, f.two, k}\\
- \cmpd{a, b, f.two, k}\\
- \cmpdsetup{list-output-sep = ;}
- \cmpd{a, b, f.two, k}
-\end{beispiel}
-
-\subsubsection{Lists -- last separator}\label{sssec:last-sep}\index{Separators!list!last seperator}
-The last separator in the main label list is a special case. \chemnum
-provides two options with which it can be customized.
-\begin{beschreibung}
- \Option{list-last-sep}{<separator>}\Default{}
- The separator between the last two labels in the output of a list.
- \Option{list-lang}{US|GB|DE|FR|ES|IT}\Default{US}
- The language setting for a list.
-\end{beschreibung}
-
-\begin{beispiel}
- \cmpd[list-lang = US]{a, b, f.two, k} \cmpd[list-lang = US]{a, b}\\
- \cmpd[list-lang = GB]{a, b, f.two, k} \cmpd[list-lang = GB]{a, b}\\
- \cmpd[list-lang = DE]{a, b, f.two, k} \cmpd[list-lang = DE]{a, b}\\
- \cmpd[list-lang = FR]{a, b, f.two, k} \cmpd[list-lang = FR]{a, b}\\
- \cmpd[list-lang = ES]{a, b, f.two, k} \cmpd[list-lang = ES]{a, b}\\
- \cmpd[list-lang = IT]{a, b, f.two, k} \cmpd[list-lang = IT]{a, b}
-\end{beispiel}
-As you can see the language \key{list-lang}{US} uses the Harvard comma, all
-other languages don't. You'll find more on language support and the Harvard
-comma in section~\ref{sec:language_support}.
-
-With the key \key{list-last-sep} you also can set the last separator
-individually.
-\begin{beispiel}
- \cmpdsetup{list-lang = GB}%
- \cmpd[list-last-sep = {and also}]{a, b, f.two, k}\\
- \cmpd[list-last-sep = ]{a, b, f.two, k}\\
- \cmpd[list-last-sep = {as well as}]{a, b, f.two, k}\\
- \cmpd[list-last-sep = empty]{a, b, f.two, k}
-\end{beispiel}
-
-\key{list-last-sep}{empty} is a special value. If it is used, the separator
-set with \key{list-output-sep} is used for the whole list.
-\begin{beispiel}
- \cmpdsetup{list-last-sep = empty}%
- \cmpd{a, b, f.two, k}\\
- \cmpd[list-output-sep = ;]{a, b, f.two, k}\\
- \cmpd[list-output-sep = {\ und}]{a, b, f.two, k}
-\end{beispiel}
-
-\subsubsection{\cmd*{cmpdinit} -- input}\label{sssec:init-input-sep}
-\index{Separators!cmpdinit@\textcolor{code}{\code{\textbackslash cmpdinit}}}
-
-When you've changed the separator for \cmd{cmpd} you might want to change it
-for \cmd{cmpdinit} as well. \chemnum uses the comma in the default setting.
-You can change that as you like. Tokens you \emph{can't use} are
-\verb=%=, \verb=,= and \verb=#= and \emph{you shouldn't} use \verb=@=.
-\begin{beschreibung}
- \Option{init-input-sep}{<separator>}\Default{,}
- The separator for the input of labels in \cmd{cmpdinit}.
-\end{beschreibung}
-
-\subsubsection{An example}\label{sssec:input-sep-bsp}
-A small example how a customized input could look like:
-\begin{beispiel}
- \cmpdsetup{
- sub-input-sep = ! ,
- subrange-input-sep = : ,
- sublist-input-sep = / ,
- list-input-sep = +
- }
- \cmpd{a + f ! one + q ! one / three : five}
-\end{beispiel}
-\secidx*{Separators}
-
-\section{Language support}\label{sec:language_support}\secidx{Language support}
-\subsection{Cooperation with \textsf{babel}}
-\chemnum supports the language choice made with the \paket{babel} package for
-a number of languages. This is done with the \verb=\GetTranslation= command
-of the \paket*{translations}\footnote{\paket*{translations} is part of the
- \paket*{exsheets} bundle.} package.
-
-\begin{beispiel}
- \selectlanguage{ngerman}DE: \cmpd{r,s,t}\\
- \selectlanguage{english}EN: \cmpd{r,s,t}\\
- \selectlanguage{british}GB: \cmpd{r,s,t}\\
- \selectlanguage{american}US: \cmpd{r,s,t}\\
- \selectlanguage{french}FR: \cmpd{r,s,t}\\
- \selectlanguage{spanish}ES: \cmpd{r,s,t}\\
- \selectlanguage{italian}IT: \cmpd{r,s,t}
-\end{beispiel}
-If you find a language missing, please send me an
-email\footnote{\href{mailto:contact@mychemistry.eu}{contatc@mychemistry.eu}}
-with the corresponding \textsf{babel} option and the right translation, and I
-will gladly add it.
-
-\subsection{Harvard comma}\label{ssec:harvard-comma}\secidx{Harvard comma}
-In American English the so-called Harvard comma is quite commonly used. In
-British English and other European languages it is rather uncommon.
-\begin{zitat}[\href{http://en.wikipedia.org/wiki/Serial_comma}{Wikipedia}, 2011/11/07]
- The serial comma (also known as the Oxford comma or Harvard comma, and
- sometimes referred to as the series comma) is the comma used immediately
- before a coordinating conjunction (usually and or or, and sometimes nor)
- preceding the final item in a list of three or more items. For example, a
- list of three countries can be punctuated as either ``Portugal, Spain, and
- France'' (with the serial comma) or as ``Portugal, Spain and France''
- (without the serial comma).
-
- Opinions vary among writers and editors on the usage or avoidance of the
- serial comma. In American English, the serial comma is standard usage in
- non-journalistic writing that follows the \name{Chicago Manual of Style}.
- Journalists, however, usually follow the AP Stylebook, which advises against
- it. It is used less often in British English, where it is standard usage to
- leave it out, with some notable exceptions such as \name{Fowler's Modern
- English Usage}. In many languages (e.g., French, German, Italian, Polish,
- Spanish), the serial comma is not the norm and may even go against
- punctuation rules. It may be recommended in many cases, however, to avoid
- ambiguity or to aid prosody.
-\end{zitat}
-\chemnum uses the Harvard comma when American English is used and doesn't,
-when other languages are used. However, you have the possibility to disable
-or enable the Harvard comma as you wish:
-
-\begin{beschreibung}
- \Option{list-serial-comma}{\default{true}|false}\Default{true}
- (De-) Activate the serial comma.
-\end{beschreibung}
-
-\begin{beispiel}
- \selectlanguage{ngerman}DE: \cmpd[list-serial-comma]{r,s,t} vs. \cmpd{r,s,t}\\
- \selectlanguage{american}US: \cmpd[list-serial-comma=false]{r,s,t} vs. \cmpd{r,s,t}
-\end{beispiel}
-If you choose the language manually, please note that this resets the default
-behaviour for that language. This means you have to use
-\key{list-serial-comma} \emph{after} \key{list-lang}.
-\begin{beispiel}
- wrong: \cmpdsetup{list-serial-comma=false, list-lang=US}\cmpd{r,s,t}\\
- right: \cmpdsetup{list-lang=US, list-serial-comma=false}\cmpd{r,s,t}
-\end{beispiel}
-\secidx*{Harvard comma}\secidx*{Language support}
-
-\section{Overview}
-\subsection{Options}\label{ssec:keys_uebersicht}
-In this section all options are listed.
-\begin{center}
- \label{tab:keys}
- \begin{longtabu*}{>{\ttfamily\color{key}}l>{\ttfamily}l>{\ttfamily}l>{\ttfamily}l}\toprule
- \normalfont\bfseries\normalcolor option &
- \normalfont\bfseries default &
- \normalfont\bfseries predefined &
- \normalfont\bfseries type \\\midrule
- cmpd-style & & & macro \\
- cmpd-weight & bold & bold & choice \\
- cmpd-label & & & literal \\
- cmpd-delim\color{black}$^\mathrm{a}$ & () & & literal \\
- cmpd-odelim & & & literal \\
- cmpd-cdelim & & & literal \\
- cmpd-prefix & & & literal \\
- cmpd-suffix & & & literal \\
- cmpd-space & \verb=\penalty\@m\ = & \verb=\penalty\@m\ = & literal \\
- cmpd-counter & arabic & arabic & choice \\
- cmpd-all & true & false & boolean \\\midrule
- sub-only & true & false & boolean \\
- sub-counter & alph & alph & choice \\
- sub-output-sep & & , & literal \\
- sub-input-sep & . & . & literal \\
- sublist-output-sep & , & , & literal \\
- sublist-input-sep & , & , & literal \\
- subrange-output-sep & -- & -- & literal \\
- subrange-input-sep & .. & .. & literal \\\midrule
- list-delim\color{black}$^\mathrm{a}$ & () & & literal \\
- list-odelim & & & literal \\
- list-cdelim & & & literal \\
- list-prefix & & & literal \\
- list-suffix & & & literal \\
- list-input-sep & , & , & literal \\
- list-output-sep & , & , & literal \\
- list-lang & US & US$^\mathrm{b}$ & choice \\
- list-last-sep & and$^\mathrm{c}$ & & literal \\
- list-serial-comma & true & true$^\mathrm{c}$ & boolean \\\midrule
- ref-tag & TMP & TMP & literal \\
- ref-style & & \verb=\sffamily= & macro \\
- ref-pos\color{black}$^\mathrm{a}$ & bb & bb & literal \\\midrule
- init-strict & true & false & boolean \\
- init-sub & true & false & boolean \\
- init-input-sep & , & , & literal \\\midrule
- hyper-use & true & false & boolean \\
- hyper-target & & & literal \\
- hyper-link & & & literal \\\bottomrule
- \end{longtabu*}
- \setlength\extrarowheight{-1pt}
- \begin{tabular}{>{\footnotesize}r>{\footnotesize\raggedright}p{.7\linewidth}}
- a & value needs \emph{two} tokens. \tabularnewline
- b & depends in the usage of \paket*{babel}. \tabularnewline
- c & depends on the value of \key{list-lang} and the usage of \paket*{babel}.
- \end{tabular}
-\end{center}
-
-\subsection{Commands}
-In this section all commands provided by \chemnum as well as their variants are
-listed.
-\begin{center}
- \label{tab:commands}
- \begin{tabu*} to \linewidth {X[l]X[p]}\toprule
- \bfseries command & \bfseries description \tabularnewline\midrule
- \cmd*{cmpd}[<keyval>]{<labels>} & basic command, declares
- and prints labels or lists of labels, see pages \pageref{sec:nummerieren}ff. \tabularnewline
- \cmd*[cmpda]{cmpd*}{<labels>} & invisible, declares label,
- see page \pageref{cmd:unsichtbares_label} \tabularnewline
- \cmd*[cmpdc]{cmpd-}[<keyval>]{<labels>} & without delimiters, see
- page \pageref{cmd:ohne_begrenzer} \tabularnewline
- \cmd*[cmpdd]{cmpd+-}[<keyval>]{<labels>} & label is read from auxiliary
- file, see page \pageref{cmd:cmpd_plus} \tabularnewline\midrule
- \cmd*{cmpdinit}[<keyval>]{<labels>} & initialise and declare labels,
- see pages \pageref{sec:cmpdinit}f. \tabularnewline
- \cmd*[cmpdinita]{cmpdinit*}[<keyval>]{<labels>} & initialise labels, see
- pages \pageref{sec:cmpdinit}f. \tabularnewline\midrule
- \cmd*{cmpdref}[<keyval>]\oa[<marker>]\ma{<label>} & replace temporary markers
- in \code{eps} files by labels, see page \pageref{ssec:cmpdref} \tabularnewline
- \cmd*[cmpdrefc]{cmpdref-}[<keyval>]\oa[<marker>]\ma{<label>} & replace temporary
- markers in \code{eps} files by labels without delimiters, see page \pageref{cmd:ohne_begrenzer} \tabularnewline\midrule
- \cmd*{cmpdreset}[<num>] & reset counter, see
- page \pageref{sec:cmpdreset} \tabularnewline\midrule
- \cmd*{cmpdsetup}{<keyval>} & setup \chemnum, see
- pages \pageref{sec:cmpdsetup}ff. \tabularnewline\bottomrule
- \end{tabu*}
-\end{center}
-
-\appendix
-\addsec{Credits}
-I would like to thank Joseph \name{Wright} and Russell \name{Hewitt} who
-provided me with valuable feedback and suggestions to improve \chemnum.
-
-Many thanks also to Jonas \name{Rivetti} who provided the Italian
+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.
+
+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{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 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.
-\indexprologue{%
- Section headings are typeset \textbf{bold}, packages \textsf{sans serif},
- commands \textcolor{code}{brown}, and options \textcolor{key}{yellow}.%
-}
-\printindex
+\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}{\chemnumshowdef{#2}}
+\end{sourcecode}
\end{document}
+
+