summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/chemnum/chemnum_en.tex
blob: 8d9cc7b8b2443e89ac78f7866a907d32cc5b0e18 (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
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
% 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
}

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

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

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

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

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.

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

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

\section{Numbering compounds}\label{sec:nummerieren}
\subsection{Main command}\secidx{Main command}\cmpdreset

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

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{f.{one,two}} is explained in
section~\ref{ssec:sub_ranges}.
\secidx*{Sublabel}

\subsection{Lists}\label{ssec:listen}\secidx{Lists}
There is actually more to the \cmd{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}
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}
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{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:
\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.
\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]
  \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>+:
\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.
\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
translation.

\indexprologue{%
  Section headings are typeset \textbf{bold}, packages \textsf{sans serif},
  commands \textcolor{code}{brown}, and options \textcolor{key}{yellow}.%
}
\printindex

\end{document}