%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % - chemnum - chemnum_doc_en.tex - % % - a comprehensive approach for the numbering of chemical compounds - % % ------------------------------------------------------------------------------------- % % - Clemens NIEDERBERGER - % % - 2012/02/26 - % % ------------------------------------------------------------------------------------- % % - http://www.mychemistry.eu/ - % % - contact@mychemistry.eu - % % ------------------------------------------------------------------------------------- % % - If you have any ideas, questions, suggestions or bugs to report, please feel free - % % - to contact me. - % % ------------------------------------------------------------------------------------- % % - Copyright 2011-2012 Clemens Niederberger - % % - - % % - This work may be distributed and/or modified under the - % % - conditions of the LaTeX Project Public License, either version 1.3 - % % - of this license or (at your option) any later version. - % % - The latest version of this license is in - % % - http://www.latex-project.org/lppl.txt - % % - and version 1.3 or later is part of all distributions of LaTeX - % % - version 2005/12/01 or later. - % % - - % % - This work has the LPPL maintenance status `maintained'. - % % - - % % - The Current Maintainer of this work is Clemens Niederberger. - % % - - % % - This work consists of the files chemnum.sty, chemnum_doc_de.tex, - % % - chemnum_doc_en.tex, chemnum-codehelper.tex, scheme-tmp.eps, scheme-bla.eps, - % % - README and the derived files chemnum_doc_de.pdf and chemnum_doc_en.pdf - % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \documentclass[DIV11,toc=index]{scrartcl} \usepackage[ngerman,german,naustrian,austrian,english,british,american,canadian,frenchb,canadien,spanish,italian]{babel} \usepackage[T1]{fontenc} \usepackage[utf8]{inputenx} \usepackage[textgreek]{chemnum} \usepackage{textcomp,microtype,libertine,url,xspace,longtable,tabu,booktabs,chemscheme,makeidx,multicol} \usepackage[scaled=.95]{inconsolata} \usepackage[iupac=strict]{chemmacros} \DeclareChemIUPAC\a{\textalpha} \DeclareChemIUPAC\b{\textbeta} \usepackage{chemfig} \usepackage[normalem]{ulem} \usepackage[runs=2]{auto-pst-pdf} \input{chemnum-codehelper} \begin{filecontents}{index_en.ist} preamble "\\begin{theindex}\n Section headings are typeset \\textbf{bold}, packages \\textsf{sans serif}, commands \\textcolor{code}{brown}, and keys \\textcolor{key}{green}.\\newline\n\n" heading_prefix "{\\bfseries " heading_suffix "\\hfil}\\nopagebreak\n" headings_flag 1 delim_0 "\\dotfill " delim_1 "\\dotfill " delim_2 "\\dotfill " delim_r "--" suffix_2p "\\nohyperpage{\\,f.}" suffix_3p "\\nohyperpage{\\,ff.}" \end{filecontents} \usepackage{hyperref} \hypersetup{colorlinks = true, allcolors = myblue, plainpages = false, bookmarksopen = true, bookmarksopenlevel = 2, bookmarksnumbered = true, pdfauthor = {Clemens Niederberger}, pdftitle = {chemnum - English documentation}, pdfsubject = {Numbering chemical compounds}, pdfkeywords = {chemmnum}, pdfcreator = {LaTeX} pdfstartview = FitH } \ExplSyntaxOn \NewDocumentCommand \keyentry { mmm } { \noindent \textcolor { key } { \texttt { #1 } } \texttt { ~=~#2 } \hfill type:~ \texttt { #3 } \index { #1 @ \textcolor { key } { \texttt { #1 } } } } \ExplSyntaxOff \GetFileInfo{chemnum} \newcommand*\chemnum{{\scshape\textcolor{myblue}{\filename}}\xspace} \newcommand*\CNversion{\fileversion\xspace} \newcommand*\CNdate{\filedate\xspace} \newcommand*\CNinfo{\fileinfo\ with \LaTeXe.} \newcommand*\eg{\mbox{e.\,g.}\xspace} \newcommand*\ie{\mbox{i.\,e.}\xspace} \newcommand*\etc{\mbox{etc.}\xspace} \cmpdinit*{a,aa,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,benzene,r,s,t,{1,3-dichlorocyclohexanole}} \makeindex \begin{document} \selectlanguage{english} \begin{titlepage} \centering \Huge\textcolor{myblue}{\biolinumshadow[\fontsize{1.5cm}{1.6cm}\fontshape{sc}]{chemnum}} \vskip.5cm \Large \CNversion \qquad \CNdate \vskip.5cm \large Clemens \textsc{Niederberger} \vskip.25cm \normalsize\url{https://bitbucket.org/cgnieder/chemnum/}\\ \href{mailto:contact@mychemistry.eu}{contact@mychemistry.eu} \begin{center} \Large\color{myblue} \CNinfo \\[16pt] \normalcolor English documentation \end{center} \vskip3cm \cmpdinit*{glucose.alpha, glucose.beta, glucose.chain} \cmpd*[sub-counter = greek]{glucose.alpha, glucose.beta}\cmpd*{glucose.chain} \setatomsep{2em} \definesubmol{x}{(-[4]H)(-[0]OH)} \definesubmol{y}{(-[0]H)(-[4]HO)} \begin{scheme}[h] \centering\small \schemestart \chemfig{?(-[:-170]HO)-[:-50](-[:170]HO)-[:10](-[:-55,0.7]OH)-[:-10](-[6,0.8]OH)-[:130]O-[:-170]?(-[:150,0.7]-[2,0.7]OH)} \arrow(alpha--chain){<=>} \chemfig{[2]OH-[3]-!x-!x-!y-!x-=[1]O} \arrow(--beta){<=>} \chemfig{?(-[:-170]HO)-[:-50](-[:170]HO)-[:10](-[:-55,0.7]OH)-[:-10](-[:10]OH)(-[6,,,,draw=none]\vphantom{OH})-[:130]O-[:-170]?(-[:150,0.7]-[2,0.7]OH)} \arrow(@chain--chainlabel){0}[-90,.2] \normalsize\cmpd[cmpd-delim]{glucose.chain} \arrow(@chainlabel--){0}[,2.5] \normalsize\cmpd[cmpd-delim]{glucose.beta} \arrow(@chainlabel--){0}[180,2.3] \normalsize\cmpd[cmpd-delim]{glucose.alpha} \schemestop \caption{In a solution the \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} \end{titlepage} \cmpdreset \begin{multicols}{2} \tableofcontents \end{multicols} \section{A very short readme} \chemnum \CNversion underlies the \LaTeX\ Project Public License Version 1.3 or later.\newline(\url{http://www.latex-project.org/lppl.txt}) \chemnum internally loads the packages \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}. In this command you can easily distinguish between a \textcolor{code}{\ttfamily\textbackslash command}, a \textcolor{key}{\ttfamily key} belonging to a key/value pair and \texttt{other code}. \section{News and a word of apology} In the update to v0.4 there have been some changes made with the keys. 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 keys 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{f.{one,two}}, see page \pageref{sssec:list-output-sep}. \\ \key{sublist-input-sep} & list separation in the input of labels like \cmpd{f.{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 key \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}. With v0.4 this documentation got an index. \section{Package options}\label{sec:package_options}\secidx{Package options} \chemnum has one package option. \begin{framed} \centering\lstinline+\usepackage[textgreek = ]{chemnum}+ \end{framed} With this you can both choose between the three different styles of the \paket{textgreek} package\footnote{See the \paket*{textgreek} documentation for details.} or load \chemnum without the \paket{textgreek} package. Available values are \lstinline=artemisia=, \lstinline=cbgreek=, \lstinline=euler= and \lstinline=false=. Using \lstinline+\usepackage[textgreek]{chemnum}+ is the same as \lstinline+\usepackage[textgreek = cbgreek]{chemnum}+. If you use \chemnum without option \textsf{textgreek} is not used. This corresponds to \lstinline+\usepackage[textgreek = false]{chemnum}+, the default setting. This document was set with \lstinline+\usepackage[textgreek]{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 \lstinline=\theffbibliography=. Then one can reference them with \lstinline=\fcite=. However, it produces a list of compounds in the text. So the package author suggests: \begin{myquote}[Stefan Schulz] After compilation and printout, discard the last page. \end{myquote} Obviously that's not a perfect solution. The second one -- \paket{chemcompounds} -- was written, because the author didn't want to work with the weaknesses of \paket{chemcono} any more. When he wrote the package he basically used the same mechanism to create the labels as \paket{chemcono} did. \begin{myquote}[Stephan Schenk] When taking a closer look at the chemcono package, I realised that the only thing one has to do is to get rid of everything which produces text. Thus, as a basis I used the mechanism of \lstinline=\bibitem= and \lstinline=\cite= in pretty much the same way as \paket{chemcono} does by extracting the corresponding code from \lstinline=article.cls= and \lstinline=latex.ltx= but deleting any unnecessary commands producing output. I also introduced several lines of code to make the printing of the compound names more customisable. \end{myquote} Some points still left me unsatisfied, though: \begin{enumerate} \item Compounds usually need to be declared with \lstinline=\declarecompound=. They need to be declared in any case if you need a label like \textbf{1a}. Then, one even needs to choose the label by hand, what somehow undermines the automatic numbering principle. \item The layout can't be changed for a single label but only for all. \item The numbers can't be reset. \emph{Although in most cases this is neither necessary nor can it be recommended}, there can be individual cases where this would be useful. \item A list of several compounds \lstinline=\compound{a,b,c}= can only be customized with more effort than what would be convenient. \end{enumerate} Then there is \paket{bpchem}, which provides commands similar to \lstinline=\label= \lstinline=\ref=: \lstinline=\CNlabel{}=, \lstinline=\CNlabelnoref{}= and \lstinline=\CNref{}=. It provides commands for sublabels, too: \lstinline=\CNlabelsub{}{}=, \lstinline=\CNlabelsubnoref{}{}= and \lstinline=\CNrefsub{}{}=. This makes it more flexible than the others regarding sublabels. However, it barely provides possibilities to customize the labels, lists are not possible and the fact that there are different commands for labels and sublabels isn't the best solution, either. \chemnum is intended to fill these gaps. For this all commands have been written from scratch. Some of the ideas of \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} The main command of this package is this one: \begin{framed} \centering\cmd{cmpd}{