path: root/macros/latex/contrib/chemsec/chemsec.dtx

% \iffalse meta-comment
%
% Copyright (C) 2018 by Justin Finnerty <jfinn24985@gmail.com>
%
% This file 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.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{chemsec.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1994/06/01]
%<package>\ProvidesPackage{chemsec}
%<*package>
    [2018/02/01 v1.12 .dtx chemsec file]
%</package>
%<package>\RequirePackage{ifthen}[1994/06/01]
%<*driver>
\documentclass{ltxdoc}
\usepackage{chemsec}[2018/02/01]
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{chemsec.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{418}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
% \changes{v1.0}{1996/06/05}{Initial version}
%
% \GetFileInfo{chemsec.dtx}
%
% \DoNotIndex{\newcommand,\newenvironment}
% 
%
% \title{The \textsf{chemsec} package\thanks{This document
%   corresponds to \textsf{chemsec}~\fileversion, dated \filedate.}}
% \author{Justin Finnerty \\ \textsf{jfinn24985@gmail.com}}
%
% \maketitle
%
% \section{Abstract}
% 
% A cross-reference system designed for an arbitrary set of items.
% Generates a document-order set of consecutive number labels that can
% be cross-referenced anywhere in the document. The motivating example
% is labeling chemical structures in a scientific document.
%
% \section{Usage}
%
% This package solves the problem of providing a sequence of numeric
% labels to represent entities in a document. The motivating example is
% labels for chemical structures in a scientific document. In such a
% document you want the full chemical name and a label to appear in the
% typeset document for each chemical structure the first time the
% structure is referenced in the document text. Subsequent references to
% the structure should only use the label.  These labels should form a
% numeric sequence, with the first chemical structure being labeled
% \textbf{1}, the second \textbf{2} and so on.
%
% These labels share similar features to numeric bibliographic reference
% styles, both use numbers to represent something, the numbers form a
% single sequence starting from one and incrementing as references or
% structures appear in the document. Furthermore these labels or
% citations can appear in multiple places in the text but must retain a
% single unique numeric label.
%
% However there are a couple of differences to a bibliography. Firstly
% the name of the chemical structure generally appears where it is first
% used in the document along with its label rather than in a
% bibliography or footnote. Secondly it is common to use a single
% numeric label for closely related structures, appending a sub-label to
% denote individual structures, usually lower-case letters.  For example
% we might have ``\textsf{methyl acetate (\textbf{1a})}'' and
% ``\textsf{ethyl acetate (\textbf{1b})}'' being specific examples of an
% ``\textsf{acetic acid ester (\textbf{1})}'' structure. Lastly, you may
% need to separate the logical and actual first occurrence of a label,
% allowing use of labels in abstracts and captions before a defining
% macro call that sets the actual number of the label in the main
% document sequence.
%
% The solution presented here uses keys to identify structures, in a
% similar way to the BibTeX, with a special format that allows
% associating related structures to an exemplar structure. This is
% achieved by using keys that contain an exclamation mark
% (|main-key!sub-key|) to separate the key for an exemplar structure
% from a sub-key for the related structures. Following our example above
% we might have keys |acetate!methyl|, |acetate!ethyl| and |acetate| as
% the keys for ``methyl acetate'', ``ethyl acetate'' and ``acetic acid
% ester'' respectively.  Using such keys with this package would
% automatically give the labels ``\textsf{\textbf{1a}}'',
% ``\textsf{\textbf{1b}}'' and ``\textsf{\textbf{1}}''.  Alternatively
% in chemistry we want the sub-labels to be more meaningful, for example
% denoting isomeric structures or an abbreviation for different
% substituents. This package allows you to manually provide such a more
% meaningful sub-label for each sub-key, for example leading to
% ``\textsf{methyl acetate (\textbf{1-Me})}'' and ``\textsf{ethyl
% acetate (\textbf{1-Et})}'' and ``\textsf{acetic acid ester
% (\textbf{1})}'' in the output document.

% However, using sub-keys is entirely optional and you can write a
% complete document without using the sub-key feature. Keys with
% sub-keys can be freely mixed in a document with keys that do not have
% sub-keys. We suggest you generally want to provide an exemplar key
% without sub-key for each set of keys which have sub-keys. This allows
% you to refer in the document to the group of related chemicals as well
% as the specific structures, ``\textsf{acetic acid ester
% (\textbf{1})}'' in our example above. Hopefully the most difficult
% part of using the \textsf{chemsec} package is choosing keys for your
% structures.
%
% \subsection{Known Issues}
%
% \subsection{Capitalization of  names}
% 
% The package cannot capitalize the name of an entity, for example if an
% entity name appears at the beginning of a sentence. For example the
% capitalization of a chemical name requires parsing and understanding
% the complete chemical nomenclature, something well beyond the scope of
% this package. It is also hard to automatically detect when
% capitalization should occur. Currently, the solutions are to avoid
% using the macros that might produce entity names at the start of a
% sentence or to manually type the entity name and use a macro that only
% outputs a label. A possible future extension of this package may allow
% the specification of two names for a compound, one capitalized and one
% not, as well as macros to select between them.
% 
% \subsubsection{Failure to issue warning}
%
% \emph{Note} that any labeling issue arising from this package is
% always resolved when the document is processed twice in a row. It is
% therefore recommended that, after making an edit, the user always
% processes the document twice to ensure correct labeling.
%
% The user should get a warning if the for some reason the labels
% typeset in the document are incorrect and the document processing
% needs to be repeated.  This can happen when using a macro that
% requests the value of a label but does not set it.  These macros use
% current values or values set in the \textsl{aux} file. If the values
% from the \textsl{aux} file need to be used they may either not be present
% or differ from values set later in the document.  When this happens
% the user should get a warning message, however a number of issues may
% prevent this and it is always recommended to process the document twice
% after editing to ensure the correct labeling.
%
% Known cases of failure to get a warning message are:
% \begin{itemize}
% \item Use of macros before the document begins, for example in the
%   \textsf{abstract} environment, may fail to issue a warning about
%   incorrect labels. (I think this is due to the boolean variable that
%   signals an error being reset at the beginning of the document.)
% \item Automatic sub-labels. Currently we cannot check to see if
%   sub-labels change during document processing. This is because
%   sub-labels are stored as text rather than numbers and text comparison
%   is surprisingly difficult in LaTeX.
% \item User-defined sub-labels. We do not detect if a user-defined
%   sub-label is defined after a request for the sub-label.  This is only
%   an issue the first time a document is processed or when a
%   |\DefineChemical| macro command is added to the document.
% \end{itemize}
%
% \subsection{Defining structure names and sub-labels}
%
% \DescribeMacro{\DefineChemical} You define the names and optional
% sub-label of a compound or entity using the |\DefineChemical|
% \marg{key} \marg{name} \marg{sub-label} macro.  This command does not
% display any output in the document nor does it define the first part
% of the label.  This means you can define all the chemicals used in the
% document in a single place rather than as they appear in the document.
% The list can even be placed in a separate file included in the main
% file, facilitating the reuse of keys and names in other documents. No
% matter where this macro is placed in the document the \textsf{chemsec}
% package will use the information wherever needed.
%
% Leaving the \marg{sub-label} argument empty for a |main!sub| key turns
% on automatic sub-labeling for this key. By default this generates
% sequential alphabetic labels for each |sub| key with the same |main|
% key for which there is no user defined sub-label. This means that you
% can manually supply labels for some |main!sub| keys and also have
% |main!sub| keys without a defined label.  This is advanced usage and
% this package does not check to see if the automatically generated
% labels match any of the user-defined labels.
%
% The \textsl{name} parameter can contain many LaTeX formatting
% commands, including the use of |$$| math-mode.
%
% \subsection{\textsf{ChemCite} Macros}
%
% The package provides a range of macros that tailor what information
% about a structure is output into the typeset document. These are the
% |ChemCite| family of macros. All of these macros can have a ``|*|''
% (star) suffix. This suffix indicates this use of the macro should act
% as a cross-reference for the label and not as a possible defining
% reference. This means that the star form can be used in abstracts,
% captions and anywhere in the document you need to use a label where it
% might appear before it appears in the main document text where you
% want the numeric label to be defined.
%   
% \DescribeMacro{\ChemCite\marg{key}} Output the label for the given
% key.  If this is the first time the key is used and the non-star form
% is used the full name precedes the label, with a star no full name is used. For example
% |\ChemCite{acetate!methyl}| could give ``methyl acetate (\textbf{1a})''
% the first time it appeared and ``\textbf{1a}'' elsewhere.
% The non-star form also sets the value of the numeric label at the
% point it first appears in the document. The star form uses in order;
% the current label if defined or a value stored in the \textsl{aux}
% file from the previous time the document was processed or a
% dummy value. The star form also never outputs the full name. For example
% |\ChemCite*{acetate!methyl}| could give ``\textbf{1a}'' if it can
% determine the labels or output a dummy value ``\textbf{0??}'' (or
% less likely ``\textbf{0a}'' or  ``\textbf{1??}'').
% 
% \DescribeMacro{\ChemFCite\marg{key}} This macro always displays the
% structure name as well as the label for the given key. The |F| is a
% mnemonic for \textsf{full}, indicating the full entry of the name and
% label is always used. For example |\ChemFCite{acetate!methyl}| would
% give ``methyl acetate (\textbf{1a})'' the first time it appeared as well
% as elsewhere. The non-star form also
% sets the value of the numeric label at the point it first appears in
% the document. The star form uses in order; the current label if
% defined or a value stored in the \textsl{aux} file from the previous
% time the document was processed or a dummy value. For example
% |\ChemFCite*{acetate!methyl}| could give ``methyl acetate
% (\textbf{1a})'' if it can determine the labels or output a dummy value
% ``?? (\textbf{0??})'' or similar.
% 
% \DescribeMacro{\ChemSCite\marg{key}} In counterpoint to the
% |\ChemFCite| macro, this always only outputs the label for the given
% key.  The |S| is a mnemonic for \textsf{short}, indicating the short
% entry of just the label is always used. For example
% |\ChemSCite{acetate!methyl}| would give ``\textbf{1a}'' the first time
% it appeared as well as ``\textbf{1a}'' elsewhere. The non-star form
% also sets the value of the numeric label at the point it first appears
% in the document. The star form uses in order; the current label if
% defined or a value stored in the \textsl{aux} file from the previous
% time the document was processed or a dummy value. For example
% |\ChemSCite*{acetate!methyl}| could give ``\textbf{1a}'' if it can
% determine the labels or output a dummy value ``\textbf{0??}'' (or less
% likely ``\textbf{0a}'' or ``\textbf{1??}'').
% 
% \DescribeMacro{\ChemMFCite\marg{key}} This macro always displays the
% structure name of the main part of the key with the label for the
% given key.  The |MF| is a mnemonic for \textsf{main full} or
% \textsf{mixed full}, indicating the full entry of the \textit{main}
% (exemplar) name is used with the label and sub-label for the key.  For
% example |\ChemMFCite{acetate!methyl}| would give ``acetic acid ester
% (\textbf{1a})'' wherever it was used. The non-star form also sets the
% value of the numeric label at the point it first appears in the
% document. The star form uses in order; the current label if defined or
% a value stored in the \textsl{aux} file from the previous time the
% document was processed or a dummy value. For example
% |\ChemMFCite*{acetate!methyl}| could give ``acetic acid ester
% (\textbf{1a})'' if it can determine the labels or output a dummy value
% ``?? (\textbf{0??})'' or similar.
% 
% \DescribeMacro{\ChemMSCite\marg{key}} This macro always displays just
% the label from the main part of the key.  The |MS| is a mnemonic for
% \textsf{main short} or \textsf{mixed short}, indicating the short
% entry of just the \textit{main} (exemplar) label for the key.  For
% example |\ChemMSCite{acetate!methyl}| would give ``\textbf{1}''
% wherever it was used.  While this macro always gives exactly the same
% result as |\ChemSCite| with just the main part of a key
% (e.g. |\ChemSCite{acetate}|), it is included here because it allows
% the document writer to include more context in the document as it is
% being written. The non-star form also sets the value of the numeric
% label at the point it first appears in the document. The star form
% uses in order; the current label if defined or a value stored in the
% \textsl{aux} file from the previous time the document was processed or
% a dummy value. For example |\ChemMSCite*{acetate!methyl}| could give
% ``\textbf{1}'' if it can determine the label or output a dummy value
% ``\textbf{0}''.
% 
% \DescribeMacro{\NoCite\marg{key}} This macro outputs nothing in the
% document but sets the numeric value of the label for the key in the
% document ordered sequence.
%
% \subsection{Possible Future extensions}
% 
% \DescribeMacro{\ChemEntityTable} Output a table of entity names,
% labels and keys.  This is intended to be used for creating a useful
% reference table when creating and editing a document rather than for
% final output.
% 
% \subsection{Internal macros that control style}
%
% Style macros can be overridden by the user to control the style of the
% label and accompanying text.
% 
% \DescribeMacro{\ChemLabelStyle} Internal macro that formats a
% label. It is used by the other two style macros for this purpose.
% Users may redefine this macro to change the label formatting.
%
% \DescribeMacro{\ChemFullLabelStyle} Internal macro used to format a
% label and its full name text.  Users may redefine this macro to change
% the name and label formatting, particularly when you wish to format
% the label and sub-label separately.
% 
% \DescribeMacro{\ChemShortLabelStyle} Internal macro used to formats a
% label without name text. Users may redefine this macro to change the
% name and label formatting, particularly when you wish to format the
% label and sub-label separately.
% 
% \DescribeMacro{\ChemMainCounterStyle} Internal macro that converts the
% counter used for main key label into a number or letter. The default
% implementation uses |\arabic| to generate a number. Users may redefine
% this macro to output letters instead of numbers.
%
% \DescribeMacro{\ChemSubCounterStyle} Converts the counter used for the
% sub-key label into a number or letter. The default implementation uses
% |\alph| to generate a letter. Users may redefine this macro to output
% numbers instead of letters.
% 
% \section{Design brief}
% 
% This section contains a description of what this package sets out to
% achieve.  
% The package should be able to consistently label an entity throughout
% the document based on a user-defined key. The label can be either a
% consecutive number or a user-defined label. These labels can be
% combined with a sub-label, which can also be consecutive or
% user-defined.
% 
% When sub-labels are used a user-supplied key and sub-key are
% required. Any entity associated with the key without a sub-key is
% considered to be a generic entity for any entities defined with the
% same key and a sub-key. 
% 
% \subsection{Limits}
% 
% \begin{itemize}
% \item The package can provide consecutive labels or user-defined
%   labels but not both.
% 
% \item Unless user-defined labels are used, consecutive labels are
%   numeric for labels and alphabetic for sub-labels.
% 
% \item The package can provide only a single set of consecutive labels.
% 
% \item The package can provide consecutive sub-labels or user-defined
%   sub-labels but not both for each label.
% \end{itemize}
% 
% \subsection{Actions}
% 
% \begin{itemize}
% \item The first time the |\ChemCite| macros appear in the latex document
%   with a given key is where the consecutive number label for the key
%   is defined (unless user-defined label are being used).
% 
% \item Using macros |\ChemCite*| provides the label without defining the
%   consecutive number label. This allows the label to appear, for
%   example in a table, abstract or figure, before the desired defining
%   location of the label.
% 
% \item The names of entities can be defined anywhere in the document
%   and appear in a user-controlled manner.
% 
% \item The basic macros typeset the entity name and label at the first
%   defining reference position and only the label in other places.
% 
% \item A range of advanced macros allow greater control over the
%   display of the entity name and label.  For example the user can
%   output a label and sub-label but use the name of the generic entity.
%   A chemistry example of this with ``ethyl acetate (1b)'' and its
%   generic entity ``acetic acid ester (1)'' appearing as ``\dots{}gives
%   the second acetic acid ester (1b)\dots{}''.
% 
% \item The label will be typeset in a particular, user configurable,
%   style. The label should be consistently formatted, even in
%   math-mode.
% 
% \item The label can be used transparently by other packages. For
%   example it can be used with the \textsf{psfrag} package to inject
%   the correct labels into figures at documentation preparation time
%   rather than having to recreate new figures whenever the label
%   numbering changes.
% 
% \end{itemize}
% 
% \section{Package options}
% 
% The package has two options.  Both options are intended to be used
% when debugging the package or its usage.  Control of the style used
% when typesetting names and labels is optionally done manually by
% redefining the style control macros described elsewhere.
%
%   \begin{description}
%   \item[|draft|] Output structure/entity key as a superscript before
%     any name and/or label output. This can be useful during document
%     preparation.
%   \item[|debug|] Output extra information in the processing log to do
%   with the operation of the package and turn on |draft| mode.
%   \end{description}
%
% \section{Implementation}
% 
% The package creates a virtual mapping of keys to a name and a
% label. The key is stored as |Main!Sub| if the key has a sub-key. This
% mapping is stored into the \textsf{aux} file where it is read at the
% start of each document processing.  If the mapping is altered during
% processing the user gets a warning to reprocess the document, similar
% to other automatically created indices.
% 
% The package has several sets of macros. The public macros are used to
% define the key to name mapping and to lookup and output the names and
% labels based on the key during document processing.  One set of
% internal macros defines the style used to display the name and
% labels. These macros can be redefined by the user. A second set of
% internal macros controls the definition and management of the map
% data. A third set controls logging information and extra output that
% might be used during testing.
%
% This uses a simple first cited first numbered algorithm to generate a
% unique sequential label for a set of compounds. It relies on a set of
% chemical definitions that can appear anywhere in the text and are
% stored in the ``aux'' file at program termination and read in at
% program start up.
%
% Note on programming style. All the functions are declared using LaTeX
% commands unless using TeX functions |edef|, |gdef| and |xdef| were
% required. The public functions have been defined using LaTeX2e's
% |DeclareRobustCommand*{}|.
%
% \StopEventually{}
%
% \subsection{Output Style Macros}
%
% \begin{macro}{\ChemLabelStyle} \marg{label} The default implementation
%   formats the label in a sloping bold font.
%    \begin{macrocode}
\DeclareRobustCommand*{\ChemLabelStyle}[1]{%
  \textsl{\bfseries{}#1}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ChemFullLabelStyle}
%   \marg{full name} \marg{main label} \marg{sub-label} Formats the full
%   entity name and label. The default implementation does not format
%   the entity name, simply forwarding the argument as-is. The default
%   implementation appends the sub-key label to the main label and uses
%   the |\ChemLabelStyle| to format them together.
%    \begin{macrocode}
\DeclareRobustCommand*{\ChemFullLabelStyle}[3]{%
  \ifthenelse{\equal{}{#3}}{%
    #1 (\ChemLabelStyle{#2})%
  }{%
    #1 (\ChemLabelStyle{#2#3})%
  }%
}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ChemShortLabelStyle}
%   \marg{main label} \marg{sub-label} Formats the labels when they
%   appear without the entity name. The default implementation appends
%   the sub-key label to the main label and uses the |\ChemLabelStyle|
%   to format them together.
%    \begin{macrocode}
\DeclareRobustCommand*{\ChemShortLabelStyle}[2]{%
  \ifthenelse{\equal{}{#2}}{%
    \ChemLabelStyle{#1}%
  }{%
    \ChemLabelStyle{#1#2}%
  }%
}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ChemMainCounterStyle}\marg{counter}
%   Converts the counter used for the main key label into a number or
%   letter. The default implementation uses |\arabic| to generate a
%   number.
%    \begin{macrocode}
\DeclareRobustCommand*{\ChemMainCounterStyle}[1]{%
  \arabic{#1}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ChemSubCounterStyle}\marg{counter}
%   Converts the counter used for the sub-key label into a number or
%   letter. The default implementation uses |\alph| to generate a
%   letter.
%    \begin{macrocode}
\DeclareRobustCommand*{\ChemSubCounterStyle}[1]{%
  \alph{#1}}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Macros for Debugging and Draft Output}
%
% Several macros are defined to implement the |draft| and |debug|
% package options.  When these options are not used these macros fall
% back on default implementations that mostly do nothing.  These macros
% are redefined when the options are used.
%
%  \begin{macro}{\CN@DEBUG}
%    Internal macro used to suppress debugging messages when not
%    debugging.  This is redefined if the |debug| package option is used
%    to output debugging messages in the processing log.
%    \begin{macrocode}
\makeatletter
\gdef\CN@DEBUG #1#2{}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\CN@WARN}
%   Internal macro used to output errors and warnings as information
%   messages when not debugging. This is redefined if the |debug| option
%   is used to promote these messages to warning messages in the
%   processing log.
%    \begin{macrocode}
\gdef\CN@WARN #1#2{\PackageInfo{#1}{#2}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\CN@DRAFT}
%   Internal macro used to suppress draft only output when not in draft
%   mode. This is redefined if the |debug| or |draft| option is used to
%   add superscript text in the output document.
%    \begin{macrocode}
\gdef\CN@DRAFT #1{}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Options for Debugging and Draft Output}
%
% The package has several options to help with using the package.
%
% \begin{itemize}
% \item The \textsf{debug} option generates more error and warning
%   messages as well as outputting draft data. It does this by redefining
%   the |\CN@DEBUG|, |\CN@WARN| and |\CN@DRAFT| macros.
%    \begin{macrocode}
\DeclareOption{debug}{%
  \gdef\CN@DEBUG #1#2{\PackageInfo{#1}{#2}}%
  \gdef\CN@WARN #1#2{\PackageWarning{#1}{#2}}%
  \gdef\CN@DRAFT #1{$^{[#1]}$}%
}
%    \end{macrocode}
% \item The \textsf{draft} option outputs some draft data. It does this
%   by redefining the |\CN@DRAFT| macro.
%    \begin{macrocode}
\DeclareOption{draft}{%
  \gdef\CN@DRAFT #1{$^{[#1]}$}%
} \ProcessOptions
%    \end{macrocode}
% \end{itemize}
%
% \subsection{Counters}
%
% Several counters are used internally for generating the label
% values. They should not be manually altered by the user.
%  
% \begin{itemize}
% \item |CN@MaxLabelIndex| tracks the maximum label index.
%    \begin{macrocode}
\newcounter{CN@MaxLabelIndex}
\setcounter{CN@MaxLabelIndex}{0}
%    \end{macrocode}
% \item |CN@LabelIndex| is the number of the current label.
%    \begin{macrocode}
\newcounter{CN@LabelIndex}
%    \end{macrocode}
% \item |CN@SubLabelIndex| is the number of the current sub-key label
%    \begin{macrocode}
\newcounter{CN@SubLabelIndex}
%    \end{macrocode}
% \end{itemize}
%
% \subsection{Internal Variables}
%
% \begin{itemize}
% \item |\CN@@label| is a dummy value used when no label is found for a
%   particular key. This is a guard value for erroneous usage.
%    \begin{macrocode}
\expandafter\def\csname CN@@label\endcsname{999}
%    \end{macrocode}
% \item |\CN@@name| is a dummy name used when no name is found for a
%   particular key. This is a guard value for erroneous usage.
%    \begin{macrocode}
\expandafter\def\csname CN@@name\endcsname{X}
%    \end{macrocode}
% \item |\CN@@sublabel| is a dummy sub-label used when no label is found
%   for a particular key/sub-key. This is a guard value for erroneous
%   usage.
%    \begin{macrocode}
\expandafter\def\csname CN@@sublabel\endcsname{X}
%    \end{macrocode}
% \item |CN@KeyFound| is a boolean to signal whether the key was found
%   in the key list. Failure to be found indicates that this is the first
%   time this key was cited.
%    \begin{macrocode}
\newboolean{CN@KeyFound}
%    \end{macrocode}
% \item |CN@ScanList| is a boolean to signal whether the key was found
%   in the last loop of the map scan.
%    \begin{macrocode}
\newboolean{CN@ScanList}
%    \end{macrocode}
% \item |CN@Star| is a boolean that signals that a macro was called
%   using the star form of the command. This alters |CN@getLabel| and
%   |CN@getSubLabel| to use predefined labels (if any) instead of labels
%   defined in the regular document flow.
%    \begin{macrocode}
\newboolean{CN@Star}
\setboolean{CN@Star}{false}
%    \end{macrocode}
% \item |CN@Warning| is a boolean that signals that the document has
%   possible incorrect labels and needs to be reprocessed. This is
%   similar to other places where LaTeX generates warnings
%   for automatically generated labels.
%    \begin{macrocode}
\newboolean{CN@Warning}
\setboolean{CN@Warning}{false}
\AtEndDocument{%
  \ifthenelse{\boolean{CN@Warning}}{%
    \PackageWarningNoLine{chemsec}{Chemsec-label(s) were used before they were
      defined or were never defined.  Rerun to get chemsec-labels right. If 
      this warning message persists check that all names and labels have been
      defined in the text}%
  }{%else
    % do nothing
  }%end if
}%end def
%    \end{macrocode}
% \end{itemize}
%
% \subsection{Internal Macros}
%
% \begin{macro}{\CN@mainpartofkey} 
%   Splits the representation of a key as |Main!Sub|, returning only the
%   |Main| part.
%    \begin{macrocode}
\gdef\CN@mainpartofkey (#1!#2){#1}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CN@MainKey}
%   Acts as a driver macro for |\CN@mainpartofkey| macro.
%    \begin{macrocode}
\gdef\CN@MainKey (#1){\CN@mainpartofkey(#1!)}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CN@definenewchemical}\marg{main!sub
%   key}\marg{name}\marg{sub-label}
%   Associate a key with a chemical name and sub-label. The instances of
%   this macro written in the \textsf{aux} file are what define the
%   current mapping of key to names and sub-labels. There is a check to
%   make sure the key is unique but there is no check that the sub-label
%   is unique.
%
%   This macro is the main macro that creates the table of key name and
%   labels that is used by the other macros to generate output in the
%   document.
%    \begin{macrocode}
\DeclareRobustCommand*{\CN@definenewchemical}[3]{%key, name, label
  % check for previous definition of name
  \ifcsname CN@#1@label\endcsname%ifdef
  % previous definition, do nothing
  \CN@DEBUG{chemsec}{Attempt to redefine key "#1" ignored.}%
  \else%
  % label not defined
  \CN@DEBUG{chemsec}{Defining new compound with key "#1". Name is "#2", sub-label is "#3".}%
  \expandafter\gdef\csname CN@#1@label\endcsname{0}%
  \expandafter\gdef\csname CN@#1@name\endcsname{#2}%
  \ifthenelse{\equal{#3}{-}}{%if no sub-label
  }{%else
    \ifthenelse{\equal{#3}{}}{%if no sub-label
    }{%else
      \expandafter\gdef\csname CN@#1@sublabel\endcsname{#3}%
    }%end if
  }%end if
  \fi%
}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CN@defineLabelUsed} \marg{main!sub key} \marg{label
%   index} Associate a label with a |main| key. The instances of this
%   macro written in the \textsf{aux} file are what define the mapping
%   of key to label used to typeset a label before a macro call that
%   defines the position of the key in document order, and hence its
%   true label.
%    \begin{macrocode}
\DeclareRobustCommand*{\CN@defineLabelUsed}[2]{%key, label
  % check for previous definition of name
  \ifcsname CN@#1@labelUsed\endcsname%ifdef
    \CN@DEBUG{chemsec}{Attempt to redefine label for key "#1" ignored.}%
  \else
    % label not defined
    \expandafter\gdef\csname CN@#1@labelUsed\endcsname{#2}%
    \CN@DEBUG{chemsec}{defineLabelUsed: Presetting label of key "#1" to "#2" -> "\csname CN@#1@labelUsed\endcsname"}%
  \fi%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CN@defineSublabelUsed} \marg{main!sub key}
% \marg{label value}
%   Associate a sublabel with a |main!sub| key. The instances of this macro written in
%   the \textsf{aux} file are what define the mapping of key to sublabel
%   used to typeset a sublabel before a macro call that defines the position
%   of the key in document order, and hence its true sublabel.
%    \begin{macrocode}
\DeclareRobustCommand*{\CN@defineSublabelUsed}[2]{%key, sublabel
  % check for previous definition of name
  \ifcsname CN@#1@sublabelUsed\endcsname%ifdef
    \CN@DEBUG{chemsec}{Attempt to redefine sublabel for key "#1" ignored.}%
  \else
    % label not defined
    \expandafter\gdef\csname CN@#1@sublabelUsed\endcsname{#2}%

    \CN@DEBUG{chemsec}{defineLabelUsed: Presetting sublabel of key "#1" to "#2" -> "\csname CN@#1@sublabelUsed\endcsname"}%
  \fi%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CN@GetFullName}
%   Check that a name is defined for the given key. If no name exists
%   then check using only the |Main| part of a |Main!Sub| key.  If still no
%   name is found then output ``|??|'' and print an error message to the
%   processing log.
%    \begin{macrocode}
\DeclareRobustCommand*{\CN@GetFullName}[1]{%
  \ifcsname CN@#1@name\endcsname%if name
  % use my own name
  \csname CN@#1@name\endcsname%
  \else%
  \ifcsname CN@\CN@MainKey(#1)@name\endcsname%if main key name
  % Use main key name
  \csname CN@\CN@MainKey(#1)@name\endcsname%
  \else%
  \CN@WARN{chemsec}{Attempt to find name for key "#1" failed.}%
  \setboolean{CN@Warning}{true}%
  ??%
  \fi%endif main
  \fi%endif full key
}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CN@GetLabel}
%   Check that a label is defined for the given key. If no label exists
%   then check using only the |Main| part of a |Main!Sub| key.  If still
%   no label is found then if the star form is used output the value of
%   the label from the previous time the document was processed
%   (actually the value from |\CN@defineLabelUsed| calls in the
%   \textsl{aux} file) or |0| (zero). If the not a star form then the
%   label is calculated by incrementing the
%   \textsf{CN\@{}MaxLabelIndex}. This also writes a call to
%   |\CN@defineLabelUsed| in the \textsl{aux} for the next processing
%   run.
%    \begin{macrocode}
\DeclareRobustCommand*{\CN@GetLabel}[3]{% key, foundbool,
  % indexcount
  \setboolean{#2}{true}%
  \CN@DEBUG{chemsec}{GetLabel: looking for '#1'}%
  \setcounter{#3}{\csname CN@#1@label\endcsname}%
  \CN@DEBUG{chemsec}{GetLabel: Label count is \arabic{#3}}%
  \CN@DEBUG{chemsec}{GetLabel: Star form is {\ifCN@Star true\else false\fi}}%
  \ifthenelse{\value{#3} = 0}{%
     %% label has NOT been defined
     \CN@DEBUG{chemsec}{GetLabel: No local label for key '#1' is defined.}%
     \ifthenelse{\boolean{CN@Star}}{%
       %% Star form means can only use predefined value
       \ifcsname CN@#1@labelUsed\endcsname% have predefined value
         \CN@DEBUG{chemsec}{GetLabel: Predefined label for key '#1' is \csname CN@#1@labelUsed\endcsname.}%
         \setcounter{#3}{\csname CN@#1@labelUsed\endcsname}%
       \else% no predefined, set warning
         \setboolean{CN@Warning}{true}%
         \CN@DEBUG{chemsec}{GetLabel: No predefined label for key '#1'.}%
       \fi%
     }{%
       %% Non-star form means calculate value
       \CN@DEBUG{chemsec}{GetLabel: MaxLabelIndex is \arabic{CN@MaxLabelIndex}}%
       \stepcounter{CN@MaxLabelIndex}%
       \CN@DEBUG{chemsec}{GetLabel: Increment MaxLabelIndex to \arabic{CN@MaxLabelIndex}}%
       \expandafter\xdef\csname CN@#1@label\endcsname{\arabic{CN@MaxLabelIndex}}%
       \write\@auxout{\string\CN@defineLabelUsed{#1}{\csname CN@#1@label\endcsname}}%
       \setcounter{#3}{\csname CN@#1@label\endcsname}%
       \setboolean{#2}{false}%
       %% Check that @labelUsed matches @label or set @Warning
       \ifcsname CN@#1@labelUsed\endcsname%
         \ifthenelse{\equal{\csname CN@#1@labelUsed\endcsname}{\csname CN@#1@label\endcsname}}{% predefined label matches label - do nothing
         }{% predefined does not match.
           \CN@DEBUG{chemsec}{GetLabel: Local label does not match predefined label}
           \setboolean{CN@Warning}{true}%
         }%
       \fi
    }%
  }{%else
    % do nothing
  }%end if def to 0
  \CN@DEBUG{chemsec}{GetLabel: Result counter \arabic{#3}}%
}%end def
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CN@GetSubLabel}
%   Check that a sublabel is defined for the given key. If the star form
%   is used output the value of the label from the previous time the
%   document was processed (actually the value from
%   |\CN@defineSubLabelUsed| calls in the \textsl{aux} file) or |??|. If
%   not a star form and no sublabel exists then try and calculate a
%   value based on the number of keys having the same |Main| part of the
%   |Main!Sub| key. This also writes a call to |\CN@defineSubLabelUsed|
%   in the \textsl{aux} for the next processing run.
%    \begin{macrocode}
\DeclareRobustCommand*{\CN@GetSubLabel}[3]{% key, found?, return-element
  \setboolean{#2}{true}%
  \CN@DEBUG{chemsec}{GetSubLabel: looking for sublabel of '#1'}%
  \ifthenelse{\equal{\CN@MainKey(#1)}{#1}}{%if a main key
    \CN@DEBUG{chemsec}{GetSubLabel: '#1' is a main key .: no sublabel}%
    \xdef#3{}%
  }{%else
    \ifcsname CN@#1@sublabel\endcsname%if defined
      \CN@DEBUG{chemsec}{GetSubLabel: Sublabel previously defined as '\csname
      CN@#1@sublabel\endcsname'}%
      \xdef#3{\csname CN@#1@sublabel\endcsname}%
    \else% else need to define sublabel
      \setboolean{#2}{false}%
      \ifthenelse{\boolean{CN@Star}}{%
         % Star form means can only use predefined value
         \ifcsname CN@#1@sublabelUsed\endcsname% have predefined value
           \CN@DEBUG{chemsec}{GetSubLabel: Predefined sublabel for key '#1' is \csname CN@#1@sublabelUsed\endcsname.}%
           \xdef#3{\csname CN@#1@sublabelUsed\endcsname}%
         \else% no predefined, set warning
           \setboolean{CN@Warning}{true}%
           \CN@DEBUG{chemsec}{GetSubLabel: No predefined sublabel for key
             '#1'.}%
           \xdef#3{??}%
         \fi%
       }{%
        \CN@DEBUG{chemsec}{GetSubLabel: Sublabel not previously defined}%
        \ifcsname CN@\CN@MainKey(#1)@sublabel\endcsname%if
          % main key def
          \setcounter{CN@SubLabelIndex}{\csname CN@\CN@MainKey(#1)@sublabel\endcsname}%
        \else%
          \setcounter{CN@SubLabelIndex}{0}%
        \fi%
        \CN@DEBUG{chemsec}{GetSubLabel: Highest label for these keys is
          \arabic{CN@SubLabelIndex}.}%
        \stepcounter{CN@SubLabelIndex}%
        \expandafter\xdef\csname CN@\CN@MainKey(#1)@sublabel\endcsname{\arabic{CN@SubLabelIndex}}%
        \expandafter\xdef\csname CN@#1@sublabel\endcsname{\ChemSubCounterStyle{CN@SubLabelIndex}}%
        \write\@auxout{\string\CN@defineSublabelUsed{#1}{\csname CN@#1@sublabel\endcsname}}%
        \CN@DEBUG{chemsec}{GetSubLabel: Sublabel now defined as '\csname
          CN@#1@sublabel\endcsname'}%
        \xdef#3{\csname CN@#1@sublabel\endcsname}%
      }%
    \fi%end if
  }%end if
}% enddef
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CN@RealCite}
%   Search for the label and sublabel for a given key.
%    \begin{macrocode}
\DeclareRobustCommand*{\CN@RealCite}[4]{%key,
  % found, index-counter,
  % sub
  \CN@DRAFT{#1}%
  \CN@DEBUG{chemsec}{In RealCite}%
  \setcounter{#3}{0}%
  \setcounter{CN@SubLabelIndex}{0}%
  \setboolean{#2}{false}%
  \xdef#4{}%
  \CN@DEBUG{chemsec}{Real: calling GetLabel for '\CN@MainKey(#1)', the main
    part of '#1'}%
  \CN@GetLabel{\CN@MainKey(#1)}{#2}{#3}%
  \CN@DEBUG{chemsec}{Real: calling GetSubLabel for "#1"}%
  \CN@GetSubLabel{#1}{CN@ScanList}{#4}%
}%end def
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NoCite}
%   Search for the label and sublabel for a given key without producing
%   any output. This can be used to define the label associated with a
%   key without anything being typeset in the document.
%    \begin{macrocode}
\DeclareRobustCommand*{\NoCite}[1]{%
  \CN@RealCite{#1}{CN@KeyFound}{CN@LabelIndex}{\CN@SubLabel}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CN@ChemCite}
%   Output name, label and sublabel for a given key. The name is output
%   only if |CN@KeyFound| is \textsf{false} which occurs the first time
%   a key is cited.
%    \begin{macrocode}
\DeclareRobustCommand*{\CN@ChemCite}[1]{%
  % \CN@DEBUG{chemsec}{in Chemcite}%
  \CN@RealCite{#1}{CN@KeyFound}{CN@LabelIndex}{\CN@SubLabel}%
  % \CN@DEBUG{chemsec}{Cite: called Real}%
  \ifthenelse{\boolean{CN@KeyFound}}{%
    % \CN@DEBUG{chemsec}{Cite: key found, use Short}%
    \ChemShortLabelStyle{\ChemMainCounterStyle{CN@LabelIndex}}{\CN@SubLabel}%
  }{%else
    % \CN@DEBUG{chemsec}{Cite: key not found, use Long}%
    \ChemFullLabelStyle{\CN@GetFullName{#1}}{\ChemMainCounterStyle{CN@LabelIndex}}{\CN@SubLabel}%
  }%
}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CN@ChemFCite}
%   Output name, label and sublabel for a given key. The name is always
%   output.
%    \begin{macrocode}
\DeclareRobustCommand*{\CN@ChemFCite}[1]{%
  % \CN@DEBUG{chemsec}{in ChemFullCite}%
  \CN@RealCite{#1}{CN@KeyFound}{CN@LabelIndex}{\CN@SubLabel}%
  % \CN@DEBUG{chemsec}{Cite: called Real}%
  \ChemFullLabelStyle{\CN@GetFullName{#1}}{\ChemMainCounterStyle{CN@LabelIndex}}{\CN@SubLabel}%
}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CN@ChemSCite}
%   Output label and sublabel for a given key. The name is never output.
%    \begin{macrocode}
\DeclareRobustCommand*{\CN@ChemSCite}[1]{%
  % \CN@DEBUG{chemsec}{in ChemShortCite}%
  \CN@RealCite{#1}{CN@KeyFound}{CN@LabelIndex}{\CN@SubLabel}%
  % \CN@DEBUG{chemsec}{SCite: called Real}%
  \ChemShortLabelStyle{\ChemMainCounterStyle{CN@LabelIndex}}{\CN@SubLabel}%
}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CN@ChemMFCite}
%   Output name associated with the |Main| part of the |Main!Sub| key as
%   well as the label \textit{and} sublabel.
%    \begin{macrocode}
\DeclareRobustCommand*{\CN@ChemMFCite}[1]{%
  % \CN@DEBUG{chemsec}{in ChemMainFullCite}%
  \CN@RealCite{\CN@MainKey(#1)}{CN@KeyFound}{CN@LabelIndex}{\CN@SubLabel}%
  % \CN@DEBUG{chemsec}{Cite: called Real}%
  \ChemFullLabelStyle{\CN@GetFullName{\CN@MainKey(#1)}}{\ChemMainCounterStyle{CN@LabelIndex}}{\CN@SubLabel}%
}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CN@ChemMSCite}
%   Output the label for the |Main| part of the |Main!Sub| key.
%    \begin{macrocode}
\DeclareRobustCommand*{\CN@ChemMSCite}[1]{%
  % \CN@DEBUG{chemsec}{in ChemMainShortCite}%
  \CN@RealCite{\CN@MainKey{#1}}{CN@KeyFound}{CN@LabelIndex}{\CN@SubLabel}%
  % \CN@DEBUG{chemsec}{SCite: called Real}%
  \ChemShortLabelStyle{\ChemMainCounterStyle{CN@LabelIndex}}{\CN@SubLabel}%
}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CN@ChemCiteStar}
%   Set |CN@Star| boolean before calling base |\CN@ChemCite|.
%    \begin{macrocode}
\DeclareRobustCommand*{\CN@ChemCiteStar}[1]{%
  % \CN@DEBUG{chemsec}{in Chemcite}%
  \setboolean{CN@Star}{true}%
  \CN@ChemCite{#1}%
  \setboolean{CN@Star}{false}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CN@ChemFCiteStar}
%   Set |CN@Star| boolean before calling base |\CN@ChemFCite|.
%    \begin{macrocode}
\DeclareRobustCommand*{\CN@ChemFCiteStar}[1]{%
  % \CN@DEBUG{chemsec}{in ChemFullCite}%
  \setboolean{CN@Star}{true}%
  \CN@ChemFCite{#1}%
  \setboolean{CN@Star}{false}%
}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CN@ChemSCiteStar}
%   Set |CN@Star| boolean before calling base |\CN@ChemSCite|.
%    \begin{macrocode}
\DeclareRobustCommand*{\CN@ChemSCiteStar}[1]{%
  % \CN@DEBUG{chemsec}{in ChemShortCite}%
  \setboolean{CN@Star}{true}%
  \CN@ChemSCite{#1}%
  \setboolean{CN@Star}{false}%
}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CN@ChemMFCiteStar}
%   Set |CN@Star| boolean before calling base |\CN@ChemMFCite|.
%    \begin{macrocode}
\DeclareRobustCommand*{\CN@ChemMFCiteStar}[1]{%
  % \CN@DEBUG{chemsec}{in ChemMainFullCite}%
  \setboolean{CN@Star}{true}%
  \CN@ChemMFCite{#1}%
  \setboolean{CN@Star}{false}%
}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\CN@ChemMSCiteStar}
%   Set |CN@Star| boolean before calling base |\CN@ChemMSCite|.
%    \begin{macrocode}
\DeclareRobustCommand*{\CN@ChemMSCiteStar}[1]{%
  % \CN@DEBUG{chemsec}{in ChemMainShortCite}%
  \setboolean{CN@Star}{true}%
  \CN@ChemMSCite{#1}%
  \setboolean{CN@Star}{false}%
}%
%    \end{macrocode}
% \end{macro}
%
% \subsection{Public Interface Macros}
%
% \begin{macro}{\ChemCite}
%   Delegate to |\CN@ChemCiteStar| or |\CN@ChemCite| depending on
%   whether ``|*|'' was used.  \changes{1.10}{1999/12/10}{This version
%   provides star forms of the standard commands (except for
%   |NoCite|). The star forms use in order; the current label if defined
%   or a value stored in the \textsl{aux} file from the previous time
%   the document was processed if defined or a dummy value. As these
%   files are read in before the document, but in order they should
%   provide the author with greater flexibility in defining the
%   numbering order. Either the author should define a sublabel for all
%   compounds using the (no-longer) optional sublabel field to disable
%   auto-numbering or use the |NoCite| and |Chem?Cite*| commands to get
%   the desired numbering.}
%    \begin{macrocode}
\DeclareRobustCommand*{\ChemCite}{%
  \@ifstar{\CN@ChemCiteStar}{\CN@ChemCite}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ChemFCite}
%   Delegate to |\CN@ChemFCiteStar| or |\CN@ChemFCite| depending on
%   whether ``|*|'' was used.
%    \begin{macrocode}
\DeclareRobustCommand*{\ChemFCite}{%
  \@ifstar{\CN@ChemFCiteStar}{\CN@ChemFCite}%
}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ChemSCite}
%   Delegate to |\CN@ChemSCiteStar| or |\CN@ChemSCite| depending on
%   whether ``|*|'' was used.
%    \begin{macrocode}
\DeclareRobustCommand*{\ChemSCite}{%
  \@ifstar{\CN@ChemSCiteStar}{\CN@ChemSCite}%
}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ChemMFCite}
%   Delegate to |\CN@ChemMFCiteStar| or |\CN@ChemMFCite| depending on
%   whether ``|*|'' was used.
%    \begin{macrocode}
\DeclareRobustCommand*{\ChemMFCite}{%
  \@ifstar{\CN@ChemMFCiteStar}{\CN@ChemMFCite}%
}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ChemMSCite}
%   Delegate to |\CN@ChemMSCiteStar| or |\CN@ChemMSCite| depending on
%   whether ``|*|'' was used.
%    \begin{macrocode}
\DeclareRobustCommand*{\ChemMSCite}{%
  \@ifstar{\CN@ChemMSCiteStar}{\CN@ChemMSCite}%
}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\DefineChemical}\marg{main!sub key}\marg{name}\marg{label}
%   Associate a key with a chemical name and sub-label by inserting a
%   |\CN@definenewchemical| macro call into the \textsf{aux} file.
%    \begin{macrocode}
\DeclareRobustCommand*{\DefineChemical}[3]{%
  \CN@definenewchemical{#1}{#2}{#3}%
  \write\@auxout{\string\CN@definenewchemical{#1}{#2}{#3}}%
}%end def
%    \end{macrocode}
% \end{macro}
%    \begin{macrocode}
\makeatother
%    \end{macrocode}
%
% \Finale
\endinput