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

% \iffalse
%% File: bpchem.dtx Copyright (C) 2001-2017 
%%                 Bjoern Pedersen <Bjoern.Pedersen@ch.tum.de>
%% This file may be distributed and used freely under 
%% the LaTeX Project Public License
%%
%% 
%
%<*dtx>
          \ProvidesFile{bpchem.dtx}[2017/08/23 v1.1 Chemical input helper]
%</dtx>
%<bpchem>\NeedsTeXFormat{LaTeX2e}
%<bpchem>\ProvidesPackage{bpchem}[2004/08/21 v1.1 Chemical input helper]
%<bpchem>\RequirePackage{xspace}
%<driver>\ProvidesFile{bpchem.drv}
% \fi
%\iffalse
%<*driver>
\documentclass{ltxdoc}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{bpchem}
\RecordChanges
\begin{document}
\DocInput{bpchem.dtx}
\end{document}
%</driver>
%\fi
% \changes{v1.1}{2017/08/23}{
%  Resolved conflict with recent \LaTeX{} releases (thanks to Ulrike Fischer 
%  and Martin Sievers)
% }
%
% \changes{v1.05}{2004/11/06}{
%  changed email
% }
% \changes{v1.03}{2002/11/01}{
%  re-added lost email-address
% }
% \GetFileInfo{bpchem.dtx}
% \title{The \textsf{bpchem} package\thanks{This file
%        has version number \fileversion, last
%        revised \filedate.}}
% \author{Bj{\o}rn Pedersen\\ \texttt{Bjoern.Pedersen@frm2.tum.de}}
% \date{\filedate}
% \maketitle
% \section{Introduction}
% This package has been written to alleviate the task of writing
% publications containing lots of chemistry. It provides methods for
% typesetting chemical names, sum formulae and isotopes. It provides the
% possibility to break very long names even over several lines.
%
% This package also provides a way to automatically enumerate your
% chemical compounds, allowing for one-level subgrouping.
%
% What this package does not provide: Methods to draw chemical
% compounds. Although there exist some packages,which where designed for
% this purpose (e.g. xymtex, PPChTex) they are quite limited once you
% get to complex organic, or metal organic compounds. I recommend using
% an external drawing program, possibly in conjunction with psfrag, in
% these cases.
%
%\section{Package options}
% Currently this package supports only one option:
%
% \verb|cbgreek|
%
% this option causes the definitions of some macros to be changed to
% use the cbgreek fonts. As they are not available on all  systems,
% and only in mf format, the default is to use the math fonts for
% greek symbols.  
%
%\section{User commands in this package}
%\subsection{Setting chemical sum formulae: BPChem{<chemical formula>}}
%\DescribeMacro{\BPChem}
%Within this macro you can use \verb|\_| and \verb|\^| for correct
%chemical sub- and superscripts.
%Example:
%\begin{verbatim}
%\BPChem{C\_2H\_5OH} or \BPChem{SO\_4\^{2-}}
%\end{verbatim}
%\begin{minipage}{10cm}
%\BPChem{C\_2H\_5OH} or \BPChem{SO\_4\^{2-}}
%\end{minipage}
%\subsection{Setting long chemical names: IUPAC{<formula or name>}}
%\DescribeMacro{\IUPAC}
%in addition to sub/superscripts as above, \verb|\-| is a hyphen which 
%allows further breakpoints,\verb!\|! is an (invisible) Multibreakpoint.
%
%This environment is especially useful for your long IUPAC-compound names.
%
%Example:
%\begin{verbatim}
 %\IUPAC{Tetra\|cyclo[2.2.2.1\^{1,4}]\-
%un\|decane-2\-dodecyl\-5\-(hepta\|decyl\|iso\|dodecyl\|thio\|ester)}
%\end{verbatim}
%\begin{minipage}{15em}
%\IUPAC{Tetra\|cyclo[2.2.2.1\^{1,4}]\-^^A
%un\|decane-2\-dodecyl\-5\-(hepta\|decyl\|iso\|dodecyl\|thio\|ester)}
%\end{minipage}
%
%\subsection{Enumerating and referencing chemical compounds: CNlabel\{<label>\}, CNlabelnoref\{<label>\}, CNref\{<label>\}}
%\DescribeMacro{\CNlabel}\DescribeMacro{\CNlabelnoref}\DescribeMacro{\CNref}
%\verb|CNlabel| defines  and use \verb|#1| (via \verb|ref|) as label for
%numbering of chemical compounds. If the label has not yet been
%defined, it is created, otherwise it is just referenced. if you just
%want to define the label, use \verb|\CNlabelnoref| instead.
%
%If you want to get just the reference, use \verb|\CNref|. This comes
%handy for figure captions or section titles, as you would get
%dissorder in the numbering due to the moving argument otherwise.
%
%The default style is: \verb|\textbf{\arabic{\counter}}|
%
%To change, use something like \begin{verbatim}
%\renewcommand{\theBPCno}{\textbf{\arabic{BPCno}}}
%\end{verbatim}

%Example: 
%\begin{verbatim}
%Alkohol \CNlabel{al} is converted to aldehyd \CNlabel{ad}. \CNref{al}
%can also be used otherwise, while \CNref{ad} cannot.
%\end{verbatim}
%\begin{minipage}{20em}
%Alkohol \CNlabel{al} is converted to aldehyd \CNlabel{ad}. \CNref{al}
%can also be used otherwise, while \CNref{ad} cannot.
%\end{minipage}
% 
%
%\subsection{Using sub-labels for classes of compounds: CNlabelsub\{<label>\}\{<sublabel>\},
%\\CNlabelsubnoref\{<label>\}\{<sublabel>\},\\CNrefsub\{<label>\}\{<sublabel>\}}
%\DescribeMacro{\CNlabelsub}\DescribeMacro{\CNlabelsubnoref}\DescribeMacro{\CNrefsub}
%These commands are the same as above, with additional sub identifier
%\verb|#2| added. If the primary identifier is not yet used, it will be
%created and can also be referenced via the normal commands.
%
%The default style is:\verb|\textbf{\arabic{BPCno}\alph{BPCnoa}}}|
%
%To change, use something like \begin{verbatim}
%\renewcommand{\theBPCnoa}{\textbf{\arabic{BPCno}\alph{BPCnoa}}}
%\end{verbatim}
%
%\begin{verbatim}
%To demonstrate the use of sublabels, methanol \CNlabelsub{alk}{a} and
%ethanol \CNlabelsub{alk}{b} are both natural products. The acohols \CNref{alk}
%can synthezied bio-chemically. \CNrebsub{alk}{a} is toxic, while
%\CNrefsub{alk}{b} is only mildly toxic.
%\end{verbatim}
%\begin{minipage}{20em}
%To demonstrate the use of sublabels, methanol \CNlabelsub{alk}{a} and
%ethanol \CNlabelsub{alk}{b} are both natural products. The alcohols \CNref{alk}
%can synthezied bio-chemically. \CNrefsub{alk}{a} is toxic, while
%\CNrefsub{alk}{b} is only mildly toxic.
%\end{minipage}
%
%\subsection{Shortcuts for common idioms in chemical literature}
%
%
%\begin{description}
%\item[\HNMR] \verb|\HNMR|
%\item[\CNMR] \verb|\CNMR|
%\item[\cis] \verb|\cis|
%\item[\trans] \verb|\trans|
%\item[\bpalpha] \verb|\bpalpha|
%\item[\bpbeta] \verb|\bpbeta|
%\item[\bpDelta] \verb|\bpdelta|
%\item[\IUPAC{\hapto{<nummer>}}] \verb|\hapto{<number>}|
%\end{description}
%\textbf{Note:} Some of these macros are influenced by the
%\verb|cbgreek| option! Use is only recommended with the
%\verb|\BPChem| and \verb|\IUPAC| commands. Some will not even work
%outside  those commands.
% 
%\section{Example}
%\begin{verbatim}
%\begin{minipage}[b]{15em}
%some normal text and math: $A*2=B$
%
%Test \BPChem{ C\_{2}H\_{4}\^{+}} 
%or using math in superscript  \BPChem{ C\_{2}H\_{4}\^{$+$}}
%
%\BPChem{Example\_{longer subscript}\^{superscript}}
%
%Isotope: \BPChem{\_{A}\^{B}X\^{C}\_{D}}
%
%\IUPAC{Tetra\|cyclo[2.2.2.1\^{1,4}]\-^^A
%un\|decane-2\-dodecyl-5-(heptadecyl\|iso\|dodecyl\|thio\|ester)}
%\end{minipage}
%\end{verbatim}
% and the resulting output:
%
%\begin{minipage}[b]{15em}
%some normal text and math: $A*2=B$, just to show it.
%
%Test \BPChem{ C\_{2}H\_{4}\^{+}} 
%or using math in superscript  \BPChem{ C\_{2}H\_{4}\^{$+$}}
%
%\BPChem{Example\_{longer subscript}\^{superscript}} And normal Text again
%
%Isotope: \BPChem{\_{A}\^{B}X\^{C}\_{D}}
%
%
%\IUPAC{Tetra\|cyclo[2.2.2.1\^{1,4}]\-^^A
%un\|decane-2\-dodecyl\-5\-(hepta\|decyl\|iso\|dodecyl\|thio\|ester)}
%\end{minipage}
%
%\StopEventually
%
%\section{The code}
%<*bpchem>^^J
% first comes some option setup
%    \begin{macrocode}
\newif\ifusecbgreek%
\usecbgreekfalse%
\DeclareOption{cbgreek}{\PackageInfo{bpchem}{cbgreek selected}\usecbgreektrue}
\ProcessOptions\relax
%    \end{macrocode}
%\begin{macro}{\textsubscript}
%% Define a  textsubscript corresponing to textsuperscript.
%% This is now also available as the package textsubscript by
%% D.Arsenau or as part of KOMA-Script2 by M. Kohm.
%% 
%% 
%    \begin{macrocode}
\providecommand*\textsubscript[1]{%
  \@textsubscript{\selectfont#1}}
\def\@textsubscript#1{%
  {\m@th\ensuremath{_{\mbox{\fontsize\sf@size\z@#1}}}}}
%    \end{macrocode}
%\end{macro}
%% a register to save the length to backspace
%% two registers needed to get back to correct
%% working position if one is longer than the other.
%    \begin{macrocode}
\newlength{\BPClensub}
\newlength{\BPClensuper}
\newlength{\BPCdelta}
%    \end{macrocode}
%% we are in subscript and maybe  the superscript was longer
%    \begin{macrocode}
\DeclareRobustCommand{\BPCadjustsub}{%
  \setlength\BPCdelta{\BPClensuper}\addtolength\BPCdelta{-\BPClensub}%
  \ifdim\BPCdelta>0pt{\kern\BPCdelta}\else\relax\fi%
  \setlength{\BPClensub}{0pt}% reset 
  \setlength{\BPClensuper}{0pt}% reset 
}%
%    \end{macrocode}
%% we are in superscript and maybe  the subscript was longer
%    \begin{macrocode}
\DeclareRobustCommand{\BPCadjustsuper}{%
  \setlength\BPCdelta{\BPClensub}\addtolength\BPCdelta{-\BPClensuper}%
  \ifdim\BPCdelta>0pt{\kern\BPCdelta}\else\relax\fi%
  \setlength{\BPClensub}{0pt}% reset 
  \setlength{\BPClensuper}{0pt}% reset 
}%
%    \end{macrocode}
%% make a subscript and remember length in BPClen
%    \begin{macrocode}
\DeclareRobustCommand{\BPCsub}[1]{%
  \ifmmode_{#1}\settowidth\BPClensub{_{#1}}%
  \else\textsubscript{#1}\settowidth\BPClensub{\textsubscript{#1}}\fi%
  \futurelet\next\lookforsuper%
}%
%    \end{macrocode}
%% make a superscript and remember length in BPClen
%% raise by 0.15 em, else e.g. + collides with subscript
%    \begin{macrocode}
\DeclareRobustCommand{\BPCsuper}[1]{%
  \ifmmode^{#1}\settowidth\BPClensuper{^{#1}}%
  \else\raisebox{0.15em}{\textsuperscript{#1}}%
  \settowidth\BPClensuper{\textsuperscript{#1}}\fi%
  \futurelet\next\lookforsub%
}%
%    \end{macrocode}
%% see if next token is BPCsuper,
%    \begin{macrocode}
\DeclareRobustCommand\lookforsuper{%
  \ifx\next\BPCsuper\let\next=\BPCsuperbs%
  \else\let\next=\BPCadjustsub\fi\next%
}%
%    \end{macrocode}
%% see if next token is BPCsub
%    \begin{macrocode}
\DeclareRobustCommand\lookforsub{%
  \ifx\next\BPCsub\let\next=\BPCsubbs%
  \else\let\next=\BPCadjustsuper\fi\next%
}%
%    \end{macrocode}
%%  backspace BPClen and make superscript
%%  eats the old \verb|\^|
%    \begin{macrocode}
\DeclareRobustCommand{\BPCsuperbs}[1]{\kern-\BPClensub\BPCsuper}%
%    \end{macrocode}
%% backspace and make subscript
%% eats the old \_
%    \begin{macrocode}
\DeclareRobustCommand{\BPCsubbs}[1]{\kern-\BPClensuper\BPCsub}%
%    \end{macrocode}
%% needed to get catcodes right
%    \begin{macrocode}
\DeclareRobustCommand{\DoBPChem}{}%
\def\DoBPChem#1{%
  #1\endgroup%
}%
\DeclareRobustCommand{\BPCSetupCat}{}
\def\BPCSetupCat{%
  %\catcode`^=\active%
  %\catcode`\_=\active%
  \BPCSetup%
}%
\DeclareRobustCommand{\BPCSetup}{}
\def\BPCSetup{%
 \let\_=\BPCsub%
 \let\^=\BPCsuper%
}%end BPCSetup
%    \end{macrocode}
%% setup for chemical formula
%    \begin{macrocode}
\DeclareRobustCommand\BPChem{%
  \begingroup% endgroup in DoBPChem
  \BPCSetupCat%
  \DoBPChem%
}
%    \end{macrocode}
%% these are taken from german.sty and allow more than one break
%% or breaks and hyphens in a word. Very useful for chemical names, 
%% as they tend to grow rather long. Two short versions are also defined
% \changes{v1.05}{2004/11/06}{
%  fixed whitespace bug in \cs{DoIUPAC}
% }
%    \begin{macrocode}
\DeclareRobustCommand{\allowhyphens}{\penalty\@M \hskip\z@skip}
\DeclareRobustCommand{\BreakHyph}{\penalty\@M -\allowhyphens}
\DeclareRobustCommand{\MultiBreak}%
  {\penalty\@M\discretionary{-}{}{\kern.03em}%
   \allowhyphens}
\let\MB=\MultiBreak \let\BH=\BreakHyph
\DeclareRobustCommand{\DoIUPAC}[1]{%
  #1\endgroup}
\def\Prep{%
  \let\-=\BreakHyph%
  \let\|=\MultiBreak%
  \DoIUPAC%
}
\DeclareRobustCommand*{\IUPAC}{%
  \begingroup\BPCSetup\ignorespaces%
  \Prep}%
%    \end{macrocode}
% \changes{v1.03}{2002/11/01}{%
%  fixed bug in \cs{IUPAC}, \texttt{\textbackslash$\vert$} is not getting 
%  translated to \cs{delimiter} during \cs{write} anymore
% }
%    \begin{macrocode}
\expandafter\DeclareRobustCommand\expandafter\|\expandafter{\|}
%    \end{macrocode}
% \changes{v1.04}{2002/12/14}{also \cs{-} was affected, fixed}
%% Trick by David Kastrup <David.Kastrup@t-online.de> to make
%% non-fragile. Otherwise \verb+\|+ would become \verb+\delimiter"026B30D+ in
%% e.g. the toc
% \changes{v1.1}{2017/08/23}{%
%   Recent \LaTeX{} releases make \cs{-} robust as 
%   well. This results in an infinite loop.
% }
%% Recent \LaTeX{} releases (starting with <2017-04-15>) define \cs{-} robust. 
%% This resulted in a infinite loop with older version of bpchem. We could use 
%% \cs{IncludeInRelease}, but it might be easier to just use the definition 
%% from the latest \LaTeX{} releases.
%    \begin{macrocode}
\DeclareRobustCommand{\-}{%
  \discretionary{%
    \char \ifnum\hyphenchar\font<\z@%
            \defaulthyphenchar%
          \else%
            \hyphenchar\font%
          \fi%
  }{}{}%
}%    \end{macrocode}
%% counters for numbering of chemical substances
%    \begin{macrocode}
\newcounter{BPCno}
\renewcommand{\theBPCno}{\textbf{\arabic{BPCno}}}
%
\newcounter{BPCnoa}[BPCno]
\renewcommand{\theBPCnoa}{\textbf{\arabic{BPCno}\alph{BPCnoa}}}
%    \end{macrocode}
%% helper functions to mark first definition
%    \begin{macrocode}
\newcommand{\newchems@b}[2]{
\expandafter\gdef\csname cna@#1#2\endcsname{#2}%
}
%    \end{macrocode}
%% reference a CNlabel (useful for section titles, captions etc.)
%    \begin{macrocode}
\DeclareRobustCommand*{\CNref}[1]{%
  \ref{cn:#1}%
}
%    \end{macrocode}
%% reference a CNlabel/sublabel
%    \begin{macrocode}
\DeclareRobustCommand*{\CNrefsub}[2]{%
  \ref{cn:#1#2}
%%\textbf{\csname cna@#1#2\endcsname}%
}
%    \end{macrocode}
%% label a substance and insert the number
% \changes{v1.06}{2004/11/25}{
%  fixed whitespace bug in CNlabel
% }
%    \begin{macrocode}
\DeclareRobustCommand*{\CNlabel}[1]{%
  \CNlabelnoref{#1}%
  \CNref{#1}%
}
%    \end{macrocode}
%    \begin{macrocode}
\DeclareRobustCommand*{\CNlabelnoref}[1]{%
  \expandafter\ifx\csname cnd@#1\endcsname\relax%
  {\refstepcounter{BPCno}\label{cn:#1}}%
  \expandafter\gdef\csname cnd@#1\endcsname{x}%
  \fi%
}
%    \end{macrocode}
%    \begin{macrocode}
\DeclareRobustCommand*{\CNlabelsub}[2]{%
  \CNlabelsubnoref{#1}{#2}%
  \CNrefsub{#1}{#2}%
}
\DeclareRobustCommand*{\CNlabelsubnoref}[2]{%
  \CNlabelnoref{#1}%
  \expandafter\ifx\csname cna@#1#2\endcsname\relax%
  {\refstepcounter{BPCnoa}\label{cn:#1#2}}%
  \expandafter\gdef\csname cna@#1#2\endcsname{x}%
%% \newchems@b{#1}{#2}%
%%   \write\@auxout{\string\newchems@b{#1}{#2}}%
  \fi%
}
%    \end{macrocode}
%% more helper mcors
% special symbols and macros for math-symbols without math-mode
% \changes{v1.03}{2002/11/01}{added cbgreek option for using upright
% greek and fixed namespace, old names will still work}
%    \begin{macrocode}
\DeclareRobustCommand{\HNMR}{\IUPAC{\^{1}H-NMR}: $\delta$\xspace}
\DeclareRobustCommand{\CNMR}{\IUPAC{\^{13}C-NMR}: $\delta$\xspace}
\DeclareRobustCommand{\cis}{\textit{cis}\xspace}
\DeclareRobustCommand{\trans}{\textit{trans}\xspace}
%\DeclareRobustCommand{\R}{\textit{R}}
%\DeclareRobustCommand{\S}{\textit{S}}
%%%%%%%%%%%%%%%%%%%%%
\ifusecbgreek% code with roman greek
  \PackageInfo{bpchem}{using upright greek fonts from cbgreek}
  \input{lgrenc.def}
  \DeclareRobustCommand{\rm@greekletter}[1]{{\fontencoding{LGR}\selectfont%
    \def\encodingdefault{LGR}#1}}%
% some examples
  \DeclareRobustCommand{\bpalpha}{\rm@greekletter{a}}
  \DeclareRobustCommand{\bpbeta}{\rm@greekletter{b}}
  \DeclareRobustCommand{\bpDelta}{\rm@greekletter{D}}
  \DeclareRobustCommand{\hapto}[1]{\rm@greekletter{h}\^{#1}}
\else
% code with standard math greek
  \PackageInfo{bpchem}{using default math greek fonts}
  \DeclareRobustCommand{\bpalpha}{\ensuremath{\alpha}\xspace}
  \DeclareRobustCommand{\bpbeta}{\ensuremath{\beta}\xspace} 
  \DeclareRobustCommand{\bpDelta}{\ensuremath{\Delta}\xspace}
  \DeclareRobustCommand{\hapto}[1]{\ensuremath{\eta^{#1}}}
\fi%
\let\talpha\bpalpha
\let\tbeta\bpbeta
%%%%%%
\DeclareRobustCommand*{\dreh}[1]%
  {$\lbrack \alpha \rbrack _{\mathrm D}^{#1}$}
%    \end{macrocode}
%</bpchem>
% \PrintChanges
% \CheckSum{372}
% \Finale