summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/chemnum/chemnum_doc_en.tex
blob: 1357f246d0a70fc7ced91d85fc4090fd46bc7a16 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% - chemnum - chemnum_doc_en.tex                                                      - %
% - a comprehensive numbering method for chemical compounds                           - %
% ------------------------------------------------------------------------------------- %
% - Clemens NIEDERBERGER                                                              - %
% - 2011/11/01                                                                        - %
% ------------------------------------------------------------------------------------- %
% - 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 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_doc_de.tex,                  - %
% - chemnum_doc_en.tex, bsp.tex, scheme-tmp.eps, scheme-bla.eps README and the        - %
% - derived files chemnum_doc_de.pdf and chemnum_doc_en.pdf                           - %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentclass[DIV11]{scrartcl}
\usepackage[english]{babel}
\usepackage[utf8]{inputenx}
\usepackage{chemnum,textcomp,lmodern,microtype,url,xspace,booktabs,array,chemscheme}
\usepackage[version=3]{mhchem}
\usepackage[normalem]{ulem}
\usepackage[dvipsnames]{xcolor}
  \colorlet{code}{RawSienna}
\usepackage[runs=2]{auto-pst-pdf}
\usepackage{chemfig,chemmacros}
\input{bsp}
\lstset{
      language=[LaTeX]TeX,
      basicstyle={\ttfamily},                       % Grundstil
      extendedchars=true,
      numbers=left,                                 % Zeilennummern
      numberstyle=\tiny,                            % Größe des Zeilennummern
      numberblanklines=true,                        % Leerzeilen nummerieren
      gobble=0,                                     % das erste Leerzeichen abschneiden
      xleftmargin=20pt,                             % Einrückung links
      breaklines=true,                              % Zeilenumbruch
      literate={ä}{{\"a}}1 {ö}{{\"o}}1 {ü}{{\"u}}1 {Ä}{{\"A}}1 {Ö}{{\"O}}1 {Ü}{{\"U}}1 {ß}{{\ss}}1,
      moredelim=[is][\color{red!25!purple}]{!!}{!!},% Hervorhebung
      moredelim=[is][\color{black}]{++}{++},        % Hervorhebung der Keywords rückgängig
      commentstyle={\color[named]{Gray}},
      keywordstyle=\color{code},
      texcsstyle=[30]\color{code},
      moretexcs=[30]
        {
          @m,
          bf,
          cmpd,
          cmpdinit,
          cmpdref,
          cmpdreset,
          cmpdsetup,
          CNlabel,
          CNlabelnoref,
          CNref,
          CNlabelsub,
          CNlabelsubnoref,
          CNrefsub,
          declarecompound,
          compound,
          compoundprefix,
          compoundsuffix,
          fcite,
          lstinline,
          penalty,
          psfrag,
          schemeref,
          sf,
          tableofcontents,
          textcolor,
          textnumero,
          theffbibliography,
          uline
        }
    }%

\usepackage{hyperref}
  \hypersetup{colorlinks=true,
              plainpages=false,
              bookmarksopen=true,
              bookmarksopenlevel=2,
              bookmarksnumbered=true,
              pdfauthor={Clemens Niederberger},
              pdftitle={chemnum - Manual},
              pdfsubject={Numbering chemical compounds},
              pdfkeywords={chemmnum},
              pdfcreator={LaTeX}
  }

\newcommand*\changefont[3]{\fontfamily{#1}\fontseries{#2}\fontshape{#3}\selectfont}

\ExplSyntaxOn
\DeclareDocumentEnvironment { myquote } { m }
  {
    \quote
    \small \changefont { cmss } { m } { sl }
  }
  {
    \par\noindent
    \parbox { \linewidth } { \raggedleft \normalfont \itshape #1 }
    \endquote
  }
\ExplSyntaxOff

\newcommand*\chemnum{\textsf{chemnum}\xspace}
\newcommand*\CNversion{v0.3b\xspace}
\newcommand*\CNdate{2011/11/03\xspace}

\newcommand*\paket[1]{\textsf{#1}\footnote{\url{http://www.ctan.org/pkg/#1}}}
\newcommand*\eg{\mbox{e.\,g.}\xspace}
\newcommand*\ie{\mbox{i.\,e.}\xspace}
\newcommand*\etc{\mbox{etc.}\xspace}

\cmpdinit*{a,aa,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,benzol}
\begin{document}

\begin{titlepage}
 \centering
 \Huge chemnum \CNversion
 \vskip.5cm
 \Large \CNdate
 \vskip.5cm
 \large Clemens \textsc{Niederberger}
 \vskip.25cm
 \normalsize\url{http://www.mychemistry.eu/}\\
 \href{mailto:contact@mychemistry.eu}{contact@mychemistry.eu}
 \vskip2cm
 \begin{abstract}
  \chemnum is a new and hopefully comprehensive approach for the numbering of chemical compounds.
 \end{abstract}
 \vskip3cm \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 \textalpha- and the \textbeta-anomer of \Dfi-glucose \cmpd[list-delim]{glucose.alpha,glucose.beta} are in equilibrium via the open-chain form \cmpd[cmpd-delim]{glucose.chain}.}
 \end{scheme}
\end{titlepage}
\cmpdreset
\tableofcontents

\section{Licence, Requirements}
\chemnum \CNversion underlies the \LaTeX\ Project Public License Version 1.3 or later.\newline(\url{http://www.latex-project.org/lppl.txt})

\chemnum internally loads the packages \textsf{expl3} and \paket{xparse}. \textsf{xparse} is part of the \paket{l3packages} bundle, \textsf{expl3} is part of the \paket{l3kernel} bundle. This means, \chemnum needs \LaTeX3 Support.

\chemnum also needs the packages \paket{etoolbox}, \paket{psfrag} and (sometimes) \paket{textgreek}, see section \ref{sec:package_options}.

\section{New in \chemnum \CNversion}
Since \CNversion the following is new:\cmpd*{a.one,a.two,a.three,a.four,a.five}
\begin{itemize}
 \item the key \lstinline=sub-cmpd-sep= now is \lstinline=sub-marker=, see page \pageref{ssec:sub_label_marker}
 \item the key \lstinline=cmpd-sub-counter= now is \lstinline=sub-counter=, see page \pageref{key:sub-counter}
\end{itemize}
The renaming follows the wish, to distinguish different classes of keys indicating the scope they're used for, see page \pageref{key_classes}.
\begin{itemize}
 \item several keys to create labels like \cmpd[sub-list={one..three,five}]{a}, see section \ref{ssec:lists_ranges} on page \pageref{ssec:lists_ranges}.
 \item the command \lstinline=\cmpdref=, which replaces strings in \lstinline=eps= files, see section \ref{ssec:cmpdref}.
 \item the key \lstinline=ref-tag=, see page \pageref{key:key-tag}.
\end{itemize}

\section{Package Options}\label{sec:package_options}
\chemnum has one package option.
\begin{framed}
 \centering\lstinline+\usepackage[textgreek = <value>]{chemnum}+
\end{framed}
With this you can both choose between the three different styles of the \textsf{textgreek} package\footnote{See the \textsf{textgreek} documentation for details.} or load \chemnum without the \textsf{textgreek} package. Available values are \lstinline=artemisia=, \lstinline=cbgreek=, \lstinline=euler= and \lstinline=false=. If you use \chemnum without option, then \textsf{textgreek} is loaded with the \lstinline=cbgreek= style. Using \lstinline+\usepackage[textgreek]{chemnum}+ is the same as \lstinline+\usepackage[textgreek = cbgreek]{chemnum}+ and \lstinline+\usepackage{chemnum}+.

If you don't have the \textsf{textgreek} package installed and don't need to use greek labels, you can use \lstinline+\usepackage[textgreek = false]{chemnum}+. Then choosing the counter options \lstinline=greek= or \lstinline=Greek= will the result in using \lstinline=alph= or \lstinline=Alph=, respectively (see section \ref{ssec:counter}).

\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 \lstinline=\theffbibliography=. Then one can reference them with \lstinline=\fcite=. However, it produces a list of compounds in the text. So the package author suggests:
\begin{myquote}{Stefan Schulz}
 After compilation and printout, discard the last page.
\end{myquote}
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 \textsf{chemcono} any more. When he wrote the package he basically used the same mechanism to create the labels as \textsf{chemcono} did.
\begin{myquote}{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 \lstinline=\bibitem= and \lstinline=\cite= in pretty much the same way as \textsf{chemcono} does by extracting the corresponding code from \lstinline=article.cls= and \lstinline=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{myquote}
Some points still left me unsatisfied, though:
\begin{enumerate}
 \item Compounds usually need to be declared with \lstinline=\declarecompound=. They need to be declared in any case if you need a label like \textbf{1a}. 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 \lstinline=\compound{a,b,c}= can only be customized with more effort than what would be convenient.
\end{enumerate}

Then there is \paket{bpchem}, which provides commands similar to \lstinline=\label= \lstinline=\ref=: \lstinline=\CNlabel{}=, \lstinline=\CNlabelnoref{}= and \lstinline=\CNref{}=. It provides commands for sublabels, too: \lstinline=\CNlabelsub{}{}=, \lstinline=\CNlabelsubnoref{}{}= and \lstinline=\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.

\chemnum is intended to fill these gaps. For this all commands have been written from scratch. Some of the ideas of \textsf{chemcompounds} \eg regarding delimiters and layout have been picked up, though.

If you notice any feature missing, please let me know by sending me an email.

\section{Numbering compounds}\label{sec:nummerieren}
\subsection{Basic command}
The main command of this package is
\begin{framed}
\centering\lstinline=\cmpd{<label name>}=
\end{framed}
\noindent When \lstinline=<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 possible with
\begin{framed}\label{cmd:unsichtbares_label}
\centering\lstinline=\cmpd*{<label name>}=
\end{framed}
\noindent This declares the label but doesn't print anything. \textbf{This command is not needed when} \lstinline=\cmpdinit{}= \textbf{is used, see section \ref{sec:cmpdinit} (pages \pageref{sec:cmpdinit}ff).}

\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}

You can pretty much use what you like for a label name\footnote{There are restrictions, see section \ref{ssec:unterlabel} on page \pageref{ssec:unterlabel} and section \ref{ssec:sub_label_marker} on page \pageref{ssec:sub_label_marker}.}. 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.

\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}

\subsection{Sublabels}\label{ssec:unterlabel}
If you want a label like \cmpd{a.one}, you need to use the following syntax:
\begin{framed}
\centering\lstinline=\cmpd{<label name>.<subname>}=
\end{framed}
\noindent \lstinline=<label name>= is the main name which stays the same, \lstinline=<subname>= varies. This syntax means that the point \lstinline=.= \emph{cannot} be a part of \lstinline=<label name>= or \lstinline=<subname>=.

\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}

The same way the main name of combined labels can be used solely.

\begin{beispiel}
 \cmpd{f} and \cmpd{g}
\end{beispiel}

How you can create a label like \cmpd[sub-list={one,two}]{f} is explained in section \ref{ssec:lists_ranges}.

\subsection{Lists}
There is actually more to the \lstinline=\cmpd= command. It also prints lists of labels.

The right description would be something like:
\begin{framed}
\centering\lstinline=\cmpd{<(possibly comma separated list of) label name(s)>}=
\end{framed}

\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 -- in the eyes of non-US Americans odd looking -- \verb=, and= between \cmpd{e} and \cmpd{g.two} suggests that there are options to customize the list, see section \ref{ssec:trenner} (page \pageref{ssec:trenner}).

\section{Initialize labels at once}\label{sec:cmpdinit}
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 \textsf{chemcompounds}' command \lstinline=\declarecompound= already. For one thing one has a summary of all used label names. And one may be warned if one uses an uninitialized label name\footnote{for instance due to a typing error}. This behaviour can be realized with these commands:
\begin{framed}
\centering\lstinline=\cmpdinit{<comma separated list of label names>}=
\centering\lstinline=\cmpdinit*{<comma separated list of label names>}=
\end{framed}
All compounds set inside \lstinline=\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{framed}
 \small\ttfamily\noindent
 {}*************************************************\\
 {}* chemnum warning: "cmpd-init"\\
 {}* \\
 {}* You used \verb=\cmpdinit= but didn't initiate compound "D"{} on line 1.\\
 {}*************************************************
\end{framed}

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.

\lstinline=\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{framed}
 \small\ttfamily\noindent
 {}*************************************************\\
 {}* chemnum warning: "cmpd-init"\\
 {}* \\
 {}* You used \verb=\cmpdinit= but didn't initiate compound "W"{} on line 1.\\
 {}*************************************************
\end{framed}

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 \lstinline=\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{framed}
\centering\lstinline+\cmpdinit[!!sub-init = true!!]{<comma separated list of label names>}+
\end{framed}
\noindent This will give you a warning in these cases, too.

\cmpdreset
\begin{beispiel}
 \cmpdinit[sub-init = true]{E.e} \cmpd{E.e, E.f}
\end{beispiel}

\begin{framed}
 \small\ttfamily\noindent
 {}*************************************************\\
 {}* chemnum warning: "cmpd-sub-init"\\
 {}* \\
 {}* You used \verb=\cmpdinit= and "{}sub-init = true"{} but didn't initiate sub-compound\\
 {}* "{}E.f"{} on line 1.\\
 {}*************************************************
\end{framed}

\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 \lstinline=\cmpdinit= like this:
\begin{framed}
\centering\lstinline+\cmpdinit[!!strict=true!!]{<comma separated list of label names>}+
\end{framed}
A usage of \lstinline+strict=false+ would be the usage without optional argument. Of course the *-version has the same option.

With \lstinline+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 \lstinline=\cmpdinit= with both keys:
\begin{framed}
\centering\lstinline+\cmpdinit[strict = true, sub-init = true]{<comma separated list of label names>}+
\end{framed}

If you have chosen a different sublabel marker (see page \pageref{ssec:sub_label_marker}) you need to use it with \lstinline+\cmpdinit[sub-init = true]+ as well.

\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 \lstinline=\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 \lstinline=\cmpdinit= does the same thing as \lstinline=\cmpdinit*= \emph{and} declares all the labels in the given order. So if you use it, you won't have to use \lstinline=\cmpd*= (section \ref{cmd:unsichtbares_label}) and \lstinline=\cmpd+= (section \ref{cmd:cmpd_plus}). This gives you direct control, which number is given to which compound. 
\end{enumerate}

\newpage
\section{Resetting the counter}\label{sec:cmpdreset}
With the command
\begin{framed}
\centering\lstinline=\cmpdreset[<number>]=
\end{framed}
\noindent it is possible to reset the counter. Without argument it is reset to \verb=1=. So \lstinline=\cmpdreset= and \lstinline=\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}

\textbf{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{beispiel}
 Same label: \cmpd{a}, \cmpd{h}
\end{beispiel}

\section{Special usage}
\subsection{Moving arguments -- section titles}
Using \lstinline=\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 \lstinline=\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:
\begin{enumerate}
 \item You declare your labels in the order you want with \lstinline=\cmpdinit{}= (see page \pageref{sec:cmpdinit}) in the preamble or the beginning of the document.
 \item You use \lstinline=\cmpd+= to set the label. It will read the label from the file \lstinline=<jobname>.cmpd= (supposing your main file is called \lstinline=<jobname>.tex=). This means \emph{at least two}, maybe more \LaTeX\ runs are necessary until all labels are set.
\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{framed}
\centering\lstinline=\cmpd+{<label name>}=
\end{framed}
reads the label name that is to be printed from \lstinline=<jobname>.cmpd=. In a way this is the opposite of \lstinline=\cmpd*= since it doesn't declare a label but only references and prints it. So in order to use \lstinline=\cmpd+{<label>}=, \lstinline=<label>= must have been declared, either with \lstinline=\cmpd{<label>}= or with \lstinline=\cmpd*{<label>}=. It doesn't matter, if this declaration is done before or after the usage of \lstinline=\cmpd+=. This command is useful, if the label is used inside a moving argument like in \lstinline=\section{}=. \textbf{It is not needed when} \lstinline=\cmpdinit{}= \textbf{is used, see section \ref{sec:cmpdinit} (pages \pageref{sec:cmpdinit}ff).}

\begin{beispiel}
 \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 \lstinline=\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 \lstinline=\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 \lstinline=[t]=.

\cmpdinit*{Alc,EtherBr,cpd}
\subsection{Schemes created by external programs}\label{ssec:cmpdref}
If you create your schemes by external programs like for \eg \textsc{ChemDraw} or \textsc{Marvin\-Sketch}, and want to use \chemnum with them as well, you can use this command:
\begin{framed}
\centering\lstinline=\cmpdref[<keyval>][<tag>]{<label name>}=
\end{framed}
This command is inspired by the \lstinline=\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 \lstinline=eps= file.
\begin{beispiel}[code and float]
 \begin{scheme}[ht]
  \centering
  \includegraphics{scheme-tmp}
  \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}
  \caption{Scheme with automatted labels.}
 \end{scheme}
\end{beispiel}
So you nummerate the compounds with \textsf{TMP1}, \textsf{TMP2} \etc These markers will then be replaced with the corresponding labels. Like \textsf{chemscheme} \chemnum uses the \lstinline=\psfrag= command to do that. This means you have to either compile via \textsc{latex}, \textsc{dvips}, \textsc{ps2pdf}, or for instance use the package \paket{auto-pst-pdf} to be able to use \textsc{pdflatex}.

In each case it is important that the marker is saved as \emph{text} in the \lstinline=eps= file.

You can customize the labels with the keys presented in section \ref{sec:cmpdsetup}.
\begin{beispiel}[code and float]
 \begin{scheme}[ht]
  \centering
  \cmpdref[cmpd-style=\bf\sf\textcolor{green}]{Alc} % replaces TMP1
  \cmpdref[cmpd-style=\bf\sf\textcolor{green}]{EtherBr} % replaces TMP2
  \includegraphics{scheme-tmp}
  \caption{Scheme with automatted 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}
  \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}
  \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]
  \centering
  \cmpdref{cpd.red}
  \cmpdref{cpd.ox}
  \includegraphics{scheme-tmp}
  \caption{Scheme with automatted labels and sublabels.}
 \end{scheme}
\end{beispiel}

\newpage\cmpdreset[9]
\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{framed}
\centering\lstinline+\cmpdsetup{key1 = value1, key2 = value2}+
\end{framed}
\noindent or only for a single command directly with
\begin{framed}
\centering\lstinline+\cmpd[key1 = value1, key2 = value2]{<label name>}+
\end{framed}

There are different kinds of keys. Depending on it they can have different kinds of values.
\begin{description}
 \item[\ttfamily macro] This kind of keys expects one or more macros as value. The last of them may have a mandatory argument, \eg \lstinline=\bfseries= or \lstinline=\textbf=. \chemnum has only one such key, see section \ref{ssec:schriftstil}.
 \item[\ttfamily literal] These keys use the given value "as it is", \ie literally. Most of \chemnum's keys are \lstinline=literal= keys.
 \item[\ttfamily choice] For these keys there is a list of options from which one must be chosen as a value.
 \item[\ttfamily boolean] These keys can either have the value \lstinline=true= or \lstinline=false=.
\end{description}

If you use keys without values like \lstinline+\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. \emph{All} of \chemnum's keys have default values. They are listed in section \ref{tab:keys} on page \pageref{tab:keys}.

The keys are divided in to different classes\label{key_classes}, which indicate the scope they're used for. They all follow the form \lstinline+<class>-key = <value>+:
\begin{description}
 \item[\ttfamily cmpd] These keys change the whole label or the main label.
 \item[\ttfamily sub] These keys have an impact on sublabels.
 \item[\ttfamily list] Keys which change the output of lists.
 \item[\ttfamily ref] Keys which have an impact on \lstinline=\cmpdref=.
\end{description}

\subsection{Font style}\label{ssec:schriftstil}
With the key
\begin{framed}
\noindent\lstinline+cmpd-style = <style>+ \hfill type: \lstinline=macro=
\end{framed}
\noindent 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
\end{beispiel}

\subsection{Own labels}\label{ssec:own_labels}
With the key
\begin{framed}
\noindent\lstinline+cmpd-label = <label>+ \hfill type: \lstinline=literal=
\end{framed}
\noindent one can choose the label associated with the label name.

\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}

\subsection{Own markers in images}
If you don't want to use \lstinline=TMP= as temporary markers for \lstinline=\cmpdref= (see page \pageref{ssec:cmpdref}), you can change this. For example into \lstinline=tmp=: \label{key:key-tag}
\begin{beispiel}[code only]
 \cmpdsetup{ref-marker = tmp}
\end{beispiel}

\subsection{Counter}\label{ssec:counter}
You can change the format of the counters, too, if you like.
\begin{framed}
\noindent\lstinline+cmpd-counter = <counter>+ \hfill type: \lstinline=choice=\\
\lstinline+sub-counter = <counter>+ \hfill type: \lstinline=choice=\label{key:sub-counter}
\end{framed}
You can choose between \lstinline=arabic=, \lstinline=alph=, \lstinline=Alph=, \lstinline=greek=, \lstinline=Greek=, \lstinline=roman=, \lstinline=Roman= and \lstinline=Symbol=.

Please note: a change of format only affects labels \emph{which are not yet declared}!
\begin{beispiel}
 \cmpdsetup{cmpd-counter = Alph, sub-counter = arabic}
 \cmpd{a, b, f.two, k}\\ % no affect with existing labels
 \cmpd{n.one,n.two,o.one}\\
 \cmpd{f.three,f.four}\\ % be careful: the main label already exists and isn't changed!
 \cmpd[cmpd-counter,sub-counter = greek]{p.one,p.two}
\end{beispiel}

\subsection{Delimiters}
Both single labels and whole lists can get delimiters. This is done with the keys
\begin{framed}
\noindent\lstinline+cmpd-delim = <odelim><cdelim>+ \hfill type: \lstinline=literal=\\
\lstinline+list-delim = <odelim><cdelim>+ \hfill type: \lstinline=literal=\\
values need \emph{two} tokens!
\end{framed}
\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:uebersicht}) of \lstinline=cmpd-delim= and \lstinline=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 \lstinline=\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{framed}\label{cmd:ohne_begrenzer}
\centering\lstinline=\cmpd-{<label name>}=\\
\lstinline=\cmpdref-{<label name>}=
\end{framed}
\noindent 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 \lstinline+\cmpdsetup{cmpd-delim = }+ and \lstinline+\cmpdsetup{list-delim = }+ will restore the default behaviour.

\subsection{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{framed}
\noindent\lstinline+cmpd-prefix = <prefix>+ \hfill type: \lstinline=literal=\\
\lstinline+cmpd-suffix = <prefix>+ \hfill type: \lstinline=literal=\\
\lstinline+list-prefix = <prefix>+ \hfill type: \lstinline=literal=\\
\lstinline+list-suffix = <prefix>+ \hfill type: \lstinline=literal=
\end{framed}
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 = \textnumero}
 \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}

\subsection{Separators}\label{ssec:trenner}
\subsubsection{In case of labels}
If you have labels with sublabels, you can use a separator symbol:
\begin{framed}
\noindent\lstinline+cmpd-sep = <separator>+ \hfill type: \lstinline=literal=
\end{framed}
\begin{beispiel}
 \cmpd{a, b, f.two, f.three, k}\\ % default
 \cmpd[cmpd-sep = -]{a, b, f.two, f.three, k}\\
 \cmpdsetup{cmpd-sep = $\cdot$}
 \cmpd{a, b, f.two, f.three, k}\\
 \cmpd[cmpd-sep = :]{a, b, f.two, f.three, k}
\end{beispiel}

\subsubsection{In case of lists -- generally}
In case of lists you also can set a separator symbol, which determines how the labels are separated from each other. This is the comma as default.
\begin{framed}
\noindent\lstinline+list-sep = <separator>+ \hfill type: \lstinline=literal=
\end{framed}
\begin{beispiel}
 \cmpd{a, b, f.two, k}\\ % default
 \cmpd[list-sep = ]{a, b, f.two, k}\\
 \cmpd{a, b, f.two, k}\\
 \cmpdsetup{list-sep = ;}
 \cmpd{a, b, f.two, k}
\end{beispiel}

\subsubsection{In case of lists -- last separator}
The last separator in a list is a special case. \chemnum provides two keys with which it can be customized.
\begin{framed}
\noindent\lstinline+list-last-sep = <separator>+ \hfill type: \lstinline=literal=\\
\lstinline+list-lang = <lang>+ \hfill type: \lstinline=choice=
\end{framed}
There is the \lstinline=choice= key \lstinline=list-lang=, which changes language dependent settings. You can choose between \lstinline=US= (default), \lstinline=GB=, \lstinline=DE=, \lstinline=FR=, \lstinline=ES= and \lstinline=IT=\footnote{If you're missing a language or have caught me with an error please send me an e-mail.}.
\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}

With the key \lstinline=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}

\lstinline=empty= is a special value. If it is used, the separator set with \lstinline=list-sep= is used for the whole list.
\begin{beispiel}
 \cmpdsetup{list-last-sep = empty}%
 \cmpd{a, b, f.two, k}\\
 \cmpd[list-sep = ;]{a, b, f.two, k}\\
 \cmpd[list-sep = {\ and}]{a, b, f.two, k}
\end{beispiel}

\subsection{Sublabel marker}\label{ssec:sub_label_marker}
As a default setting \chemnum uses the point \lstinline=.= as a token to divide main label names from sub label names. You can change that as you like. Tokens you \emph{can't use} are \verb=, % #= and \emph{you shouldn't} use \lstinline=@=.
\begin{framed}
\noindent\lstinline+sub-marker = <separator>+ \hfill type: \lstinline=literal=
\end{framed}
\begin{beispiel}
 \cmpdsetup{sub-marker = !}%
 \cmpd{f!one, g!two}\\
 \cmpd[sub-marker= +]{f+one, g+two}\\
 \cmpd[sub-marker= ~]{f~one, g~two}\\
 \cmpd[sub-marker= &]{f&one, g&two}\\
 \cmpd[sub-marker= *]{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 \lstinline=\tableofcontents= or in the preamble, which marker you use. Otherwise, the \lstinline=\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 \lstinline=\cmpd= or \lstinline=\cmpdinit= etc.

\subsection{Lists and ranges of sublabels}\label{ssec:lists_ranges}
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}.

\chemnum provides two keys to create such an output and two keys to customize the range.
\begin{framed}
 \noindent\lstinline+cmpd-all = <bool>+ \hfill type: \lstinline=boolean=\\
 \noindent\lstinline+sub-list = {<list of sublabel names>}+ \hfill type: \lstinline=other=\\
 \noindent\lstinline+sub-range-sep = <separator>+ \hfill type: \lstinline=literal=\\
 \noindent\lstinline+sub-range-marker = <marker>+ \hfill type: \lstinline=literal=
\end{framed}
The type of the key \lstinline=sub-list= differs from other keys. It is similar to \lstinline=literal=. Best you look at the example below.

\begin{beispiel}
 List of labels: \cmpd{q.one, q.two, q.three, q.four, q.five} \\
 All at once: \cmpd[cmpd-all]{q}
\end{beispiel}

If you don't want to address all sublabels but some of them, you can use the key \lstinline=sub-list=\label{key:sub-list}. As input you write a comma separated list of sublabel names associated with the main label you use.
\begin{beispiel}
 \cmpd[sub-list={one,three,four}]{q}
\end{beispiel}

You also can use this key to print a range of sublabels. As a marker between the names of the sublabels two points \lstinline=..= are used.
\begin{beispiel}
 \cmpd[sub-list={two..four}]{q}\\
 \cmpd[sub-list={one,three..five}]{q}\\
 \cmpd[sub-list={one..three,five}]{q}
\end{beispiel}

With the keys \lstinline=sub-range-sep= and \lstinline=sub-range-marker= you can both change the symbol that's used to indicate the range and the marker you use to input a range.
\begin{beispiel}
 \cmpdsetup{sub-range-sep = {--}, sub-range-marker = : }
 \cmpd[sub-list={two:four}]{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 \lstinline=<jobname>.cmpd= file (supposing your source file is called \lstinline=<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 key:
\begin{framed}
 \noindent\lstinline+sub-only = <bool>+\hfill type: \lstinline=boolean=
\end{framed}
\begin{beispiel}
 % use packages `chemfig', `mhchem' and `booktabs'
 \cmpd*{benzene.H,benzene.Me,benzene.OH,benzene.NH2}
 \chemname{\chemfig{*6(=-=-(-R)=-)}}{\cmpd[cmpd-all]{benzene}}
 \begin{tabular}{lll}
                               & \ce{{}-R}   & Name \\\midrule
  \cmpd[sub-only]{benzene.H}   & \ce{{}-H}   & Benzene \\
  \cmpd[sub-only]{benzene.Me}  & \ce{{}-CH3} & Toluene \\
  \cmpd[sub-only]{benzene.OH}  & \ce{{}-OH}  & Phenol \\
  \cmpd[sub-only]{benzene.NH2} & \ce{{}-NH2} & Phenylamine (Aniline)
 \end{tabular}
\end{beispiel}

For the time being the \lstinline=sub-list= key requires a little caution. Unfortunately automatic sorting isn't quite as trivial as one would wish. So you have to use the sublabel names in the right order if you want to avoid labels like these:
\begin{beispiel}
 \cmpd[sub-list={five..three}]{q} or \cmpd[sub-list={three,one,four}]{q}.
\end{beispiel}

\newpage
\subsection{Overview}\label{ssec:uebersicht}
In this section all keys are listed. Please be aware that the default values of \lstinline=cmpd-delim= and \lstinline=list-delim= and the default setting of \chemnum are \emph{not} the same. By default \chemnum doesn't use delimiters.
\begin{center}
 \label{tab:keys}
 \begin{tabular}{>{\ttfamily}l>{\ttfamily}l>{\ttfamily}l}\toprule
  \normalfont\bfseries key & \normalfont\bfseries default & \normalfont\bfseries type \\\midrule
  cmpd-style               & \lstinline=\textbf= & macro \\
  cmpd-label               &                     & literal \\
  cmpd-delim$^\mathrm{a}$  & ()                  & literal \\
  cmpd-odelim              &                     & literal \\
  cmpd-cdelim              &                     & literal \\
  cmpd-prefix              &                     & literal \\
  cmpd-suffix              &                     & literal \\
  cmpd-sep                 &                     & literal \\
  cmpd-counter             & arabic              & choice \\
  cmpd-all                 & true                & boolean \\\midrule
  sub-marker               & .                   & literal \\
  sub-counter              & alph                & choice \\
  sub-list                 &                     & other$^\mathrm{b}$ \\
  sub-range-sep            & -                   & literal \\
  sub-range-marker         & ..                  & literal \\
  sub-only                 &                     & boolean \\\midrule
  list-delim$^\mathrm{a}$  & ()                  & literal \\
  list-odelim              &                     & literal \\
  list-cdelim              &                     & literal \\
  list-prefix              &                     & literal \\
  list-suffix              &                     & literal \\
  list-sep                 & ,                   & literal \\
  list-lang                & US                  & choice \\
  list-last-sep            & and$^\mathrm{c}$    & literal \\\midrule
  ref-tag                  & TMP                 & literal \\\bottomrule
 \end{tabular}
 \hspace*{1em}
 \begin{tabular}{>{\footnotesize}r>{\footnotesize\raggedright}p{.3\linewidth}}
  a & value needs \emph{two} tokens. \tabularnewline
  b & input is a comma separated list, see p.\,\pageref{key:sub-list}. \tabularnewline
  c & depends on the value of \lstinline=list-lang=.
 \end{tabular}
\end{center}

\newpage
\section{List of commands}
In this section all commands provided by \chemnum as well as their variants are listed.
\begin{center}
 \label{tab:commands}
 \begin{tabular}{l|>{\raggedright}p{.5\linewidth}}\toprule
  \bfseries command           & \bfseries description \tabularnewline\midrule
  \lstinline=\cmpd[]{}=       & basic command, declares and prints labels or lists of labels, see pages \pageref{sec:nummerieren}ff. \tabularnewline
  \lstinline=\cmpd*{}=        & invisible, declares label, see page \pageref{cmd:unsichtbares_label} \tabularnewline
  \lstinline=\cmpd-[]{}=      & without delimiters, see page \pageref{cmd:ohne_begrenzer} \tabularnewline
  \lstinline=\cmpd+-[]{}=     & label is read from auxiliary file, see page \pageref{cmd:cmpd_plus} \tabularnewline\midrule
  \lstinline=\cmpdinit{}=     & initialise and declare labels, see pages \pageref{sec:cmpdinit}f. \tabularnewline
  \lstinline=\cmpdinit*{}=    & initialise labels, see pages \pageref{sec:cmpdinit}f. \tabularnewline\midrule
  \lstinline=\cmpdref[][]{}=  & replace temporary markers in \texttt{eps} files by labels, see page \pageref{ssec:cmpdref} \tabularnewline
  \lstinline=\cmpdref-[][]{}= & replace temporary markers in \texttt{eps} files by labels without delimiters, see page \pageref{cmd:ohne_begrenzer} \tabularnewline\midrule
  \lstinline=\cmpdreset[]=    & reset counter, siehe page \pageref{sec:cmpdreset} \tabularnewline\midrule
  \lstinline=\cmpdsetup{}=    & setup \chemnum, siehe pages \pageref{sec:cmpdsetup}ff. \tabularnewline\bottomrule
  \end{tabular}
\end{center}

\section{Credits}
I would like to thank Joseph \textsc{Wright} and Russell \textsc{Hewitt} who provided me with valuable feedback and suggestions to improve \chemnum.

\end{document}