From af6faae1a8553e2c55f7980152d84d8cf4ac5a96 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 12 Sep 2015 21:23:52 +0000 Subject: chemmacros (12sep15) git-svn-id: svn://tug.org/texlive/trunk@38359 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/chemmacros/README | 9 +- .../doc/latex/chemmacros/chemmacros_en.pdf | Bin 842434 -> 954387 bytes .../doc/latex/chemmacros/chemmacros_en.tex | 3762 ++++++++++++-------- 3 files changed, 2238 insertions(+), 1533 deletions(-) (limited to 'Master/texmf-dist/doc/latex/chemmacros') diff --git a/Master/texmf-dist/doc/latex/chemmacros/README b/Master/texmf-dist/doc/latex/chemmacros/README index ecd8835def6..d7bbd234cc6 100644 --- a/Master/texmf-dist/doc/latex/chemmacros/README +++ b/Master/texmf-dist/doc/latex/chemmacros/README @@ -1,11 +1,12 @@ -------------------------------------------------------------------------- -the CHEMMACROS package v4.7 2015/02/08 +the CHEMMACROS package v5.0 2015/09/11 - macros and commands for chemists + comprehensive support for typesetting chemistry documents -------------------------------------------------------------------------- Clemens Niederberger Web: https://github.com/cgnieder/chemmacros/ + http://www.mychemistry.eu/forums/forum/2430/ E-Mail: contact@mychemistry.eu -------------------------------------------------------------------------- Copyright 2011-2015 Clemens Niederberger @@ -23,8 +24,10 @@ This work has the LPPL maintenance status `maintained'. The Current Maintainer of this work is Clemens Niederberger. -------------------------------------------------------------------------- The chemmacros package consists of the following files - - chemmacros.sty, + - chemmacros.sty, chemmacros4.sty, chemmacros5.sty, - chemmacros_en.tex, chemmacros_en.pdf, + - quite a number of module files following the naming scheme + chemmacros.module.*.code.tex - README -------------------------------------------------------------------------- If you have any ideas, questions, suggestions or bugs to report, please diff --git a/Master/texmf-dist/doc/latex/chemmacros/chemmacros_en.pdf b/Master/texmf-dist/doc/latex/chemmacros/chemmacros_en.pdf index 603eafab494..9affd83f227 100644 Binary files a/Master/texmf-dist/doc/latex/chemmacros/chemmacros_en.pdf and b/Master/texmf-dist/doc/latex/chemmacros/chemmacros_en.pdf differ diff --git a/Master/texmf-dist/doc/latex/chemmacros/chemmacros_en.tex b/Master/texmf-dist/doc/latex/chemmacros/chemmacros_en.tex index 511935388ea..26d3d45e756 100644 --- a/Master/texmf-dist/doc/latex/chemmacros/chemmacros_en.tex +++ b/Master/texmf-dist/doc/latex/chemmacros/chemmacros_en.tex @@ -1,22 +1,23 @@ -% !arara: pdflatex +% arara: pdflatex % !arara: biber % arara: pdflatex % arara: pdflatex % -------------------------------------------------------------------------- % the CHEMMACROS package % -% macros and commands for chemists +% comprehensive support for typesetting chemistry documents % % -------------------------------------------------------------------------- % Clemens Niederberger % -------------------------------------------------------------------------- % https://github.com/cgnieder/chemmacros/ +% http://www.mychemistry.eu/forums/forum/chemmacros/ % contact@mychemistry.eu % -------------------------------------------------------------------------- % If you have any ideas, questions, suggestions or bugs to report, please % feel free to contact me. % -------------------------------------------------------------------------- -% Copyright 2011-2015 Clemens Niederberger +% Copyright 2015 Clemens Niederberger % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 @@ -32,11 +33,11 @@ % -------------------------------------------------------------------------- \documentclass[load-preamble+]{cnltx-doc} \usepackage[utf8]{inputenc} -\usepackage[greek=newtx]{chemmacros} +\usepackage{chemmacros} \setcnltx{ package = {chemmacros}, - info = {macros and commands for chemists}, - url = https://github.com/cgnieder/chemmacros/ , + info = {comprehensive support for typesetting chemistry documents}, + url = http://www.mychemistry.eu/forums/forum/chemmacros/ , authors = Clemens Niederberger , email = contact@mychemistry.eu , abstract = {% @@ -44,72 +45,95 @@ \includegraphics{chemmacros-logo.pdf} \par } , + quote-format = \small\biolinumLF , add-cmds = { abinitio, activatechemgreekmapping, AddRxnDesc, anti, aq, aqi, ba, bond, bridge, cd, ch, changechemgreeksymbol, charrow, chcpd, chemabove, chemalpha, chembeta, chemgamma, chemdelta, chemDelta, chemformula@bondlength, + ChemModule, chemomega, chemphi, chemPhi, chemsetup, chlewis, chname , cip, cis, ch, CNMR, data, DeclareChemArrow, DeclareChemBond, DeclareChemBondAlias, - declarechemgreekmapping, DeclareChemIUPAC, DeclareChemLatin, - DeclareChemNMR, DeclareChemParticle, DeclareChemPhase, - DeclareChemReaction, DeclareChemState, delm, delp, Delta, Dfi, - el, ElPot, endo, Enthalpy, enthalpy, Entropy, - fmch, fpch, fscrm, fscrp, - gas, ghs, ghslistall, ghspic, Gibbs, gram, + declarechemgreekmapping, DeclareChemCharge, DeclareChemIUPAC, + DeclareChemIUPACShorthand, DeclareChemLatin, DeclareChemNMR, + DeclareChemNucleophile, DeclareChemPartialCharge, DeclareChemParticle, + DeclareChemPhase, DeclareChemReaction, DeclareChemState, + delm, delp, Delta, Dfi, + el, ElPot, endo, Enthalpy, enthalpy, entropy, + fdelm, fdelp, fmch, fminus, fpch, fplus, fscrm, fscrp, + gas, ghs, ghslistall, ghspic, gibbs, gram, hapto, HNMR, Helmholtz, hydrogen, - insitu, invacuo, iupac, + IfChemCompatibilityF, IfChemCompatibilityT, IfChemCompatibilityTF, insitu, + invacuo, isotope, iupac, Ka, Kb, Kw, Lfi, listofreactions, lqd, mch, mega, meta, mhName, NewChemArrow, NewChemBond, NewChemBondAlias, - newchemgreekmapping, NewChemIUPAC, NewChemLatin, - NewChemNMR, NewChemParticle, NewChemPhase, - NewChemReaction, NewChemState, + newchemgreekmapping, NewChemCharge, NewChemIUPAC, NewChemIUPACShorthand, + NewChemLatin, NewChemNMR, NewChemNucleophile, NewChemPartialCharge, + NewChemParticle, NewChemPhase, NewChemReaction, NewChemState, newman, nitrogen, NMR, Nu, Nuc, orbital, ortho, ox, OX, oxygen, para, pch, per, pH, phase, phosphorus, photon, pKa, pKb, pOH, pos, - positron, Pot, prt, - Rad, redox, RenewChemArrow, RenewChemBond, renewchemgreekmapping, - RenewChemIUPAC, RenewChemLatin, RenewChemNMR, RenewChemParticle, + positron, Pot, ProvideChemArrow, ProvideChemBond, ProvideChemCharge, + ProvideChemIUPAC, ProvideChemIUPACShorthand, ProvideChemLatin, + ProvideChemNMR, ProvideChemNucleophile, ProvideChemPartialCharge, + ProvideChemParticle, ProvideChemPhase, ProvideChemReaction, + ProvideChemState, prt, + Rad, redox, RemoveChemIUPACShorthand, RenewChemArrow, RenewChemBond, + renewchemgreekmapping, renewChemCharge, RenewChemIUPAC, + RenewChemIUPACShorthand, RenewChemLatin, RenewChemNMR, + RenewChemNucleophile, RenewChemPartialCharge, RenewChemParticle, RenewChemPhase, RenewChemState, Sf, scrm, scrp, second, selectchemgreekmapping, setchemformula, - ShowChemArrow, ShowChemBond, sld, Sod, State, sulfur, + ShowChemArrow, ShowChemBond, sld, Sod, state, sulfur, trans, + usechemmodule, val } , add-silent-cmds = { addplot, bottomrule, cancel, cdot, ce, cee, celsius, centering, chemfig, chemname, clap, - cnsetup, color, cstack, cstsetup, + cnsetup, code, color, cstack, cstsetup, DeclareInstance, DeclareSIUnit, definecolor, draw, - electronvolt, + electronvolt, endtikzpicture, footnotesize, glqq, grqq, hertz, hspace, includegraphics, intertext, IUPAC, joule, - kilo, - latin, lewis, Lewis, liquid, ltn, + kelvin, kilo, + latin, lc, lewis, Lewis, liquid, ltn, metre, midrule, milli, mmHg, mole, nano, nicefrac, num, numrange, ominus, oplus, percent, pgfarrowsdeclarealias, pgfarrowsrenewalias, renewtagform, rightarrow, - sample, scriptscriptstyle, setatomsep, setbondoffset, sfrac, shorthandoff, - si, SI, sisetup, square, subsection, - textcolor, textendash, textsuperscript, tiny, toprule, + sample, scriptscriptstyle, setatomsep, setbondoffset, sfrac, shade, + shadedraw, shorthandoff, si, SI, sisetup, square, subsection, + textcolor, textendash, textsuperscript, tikz, tikzpicture, tiny, toprule, upbeta, upeta, upgamma, usetikzlibrary, volt, vphantom, vspave, xspace, z@, z@skip - } + } , + index-setup = { othercode = \footnotesize , level = \section } , + makeindex-setup = { columns = 2 , columnsep = 1em } } \usepackage{chemfig,booktabs,cancel,varioref,csquotes} +\usepackage[ + a4paper, + top = .1\paperheight, + bottom = .1\paperheight, + left = .2\paperwidth, + right = .1\paperwidth +]{geometry} + + \expandafter\def\csname libertine@figurestyle\endcsname{LF} \usepackage[libertine]{newtxmath} \expandafter\def\csname libertine@figurestyle\endcsname{OsF} @@ -168,9 +192,13 @@ } \chemsetup{ - option/synchronize , - chemformula/format = \libertineLF + modules = all , + greek = newtx , +% chemformula/format = \libertineLF } +\setchemformula{format = \libertineLF} + +\usepackage{siunitx} \sisetup{ detect-mode=false, @@ -180,7 +208,7 @@ \usepackage{filecontents} -\defbibheading{bibliography}{\addsec{References}} +\defbibheading{bibliography}{\section{References}} \addbibresource{\jobname.bib} \begin{filecontents*}{\jobname.bib} @book{iupac:greenbook, @@ -190,6 +218,7 @@ Michio Takami and Anders J Thor} , title = {``Quantities, Symbols and Units in Physical Chemistry'', \acs{iupac} Green Book} , + shorttitle = {The \acs{iupac} Green Book} , sorttitle = {Quantities, Symbols and Units in Physical Chemistry} , indexsorttitle = {Quantities, Symbols and Units in Physical Chemistry} , edition = {3rd Edition. 2nd Printing} , @@ -200,6 +229,7 @@ author = {Neil G. Connelly and Ture Damhus and Richard M. Hartshorn and Alan T. Hutton} , title = {``Nomenclature of Inorganic Chemistry'', \acs{iupac} Red Book} , + shorttitle = {The \acs{iupac} Red Book} , sorttitle = {Nomenclature of Inorganic Chemistry} , indexsorttitle = {Nomenclature of Inorganic Chemistry} , year = {2005} , @@ -210,6 +240,7 @@ author = {R. Panico and W. H. Powell and J-C. Richer}, title = {``Nomenclature of Organic Chemistry, Sections A, B, C, D, E, F, and H'', \acs{iupac} Blue Book}, + shorttitle = {The \acs{iupac} Blue Book} , sorttitle = {Nomenclature of Organic Chemistry} , indexsorttitle = {Nomenclature of Organic Chemistry} , edition = {\mkbibacro{draft}}, @@ -237,6 +268,27 @@ urldate = {2012-03-20} , date = {2012-03-20} } +@online{mychemistry:chemmacros-dev, + author = {Clemens Niederberger} , + title = {chemmacros development} , + url = {http://www.mychemistry.eu/2015/06/chemmacros-development/} , + urldate = {2015-07-16} , + date = {2015-06-14} +} +@online{mychemistry:modular-chemmacros, + author = {Clemens Niederberger} , + title = {modular chemmacros} , + url = {http://www.mychemistry.eu/2015/06/modular-chemmacros/} , + urldate = {2015-07-16} , + date = {2015-06-08} +} +@online{mychemistry:chemmacros-update-how, + author = {Clemens Niederberger} , + title = {a new chemmacros -- but how?} , + url = {http://www.mychemistry.eu/2015/07/a-new-chemmacros-but-how/} , + urldate = {2015-07-16} , + date = {2015-07-15} +} \end{filecontents*} \DeclareInstance{xfrac}{chemformula-text-frac}{text} @@ -253,6 +305,7 @@ \usetikzlibrary{calc,positioning,decorations.pathmorphing,patterns} % \newpackagename\chemmacros{chemmacros} +\newcommand*\chemmacrosversion{\csname c_chemmacros_version_number_tl\endcsname} \newpackagename\chemformula{chemformula} \newpackagename\ghsystem{ghsystem} \newpackagename\chemgreek{chemgreek} @@ -261,569 +314,689 @@ \newcommand*\TikZ{Ti\textit{k}Z} \newcommand*\tablehead[1]{\textrm{\bfseries#1}} -\NewChemPhase{\aqi}{aq,$\infty$}% aqueous solution at infinite dilution -\NewChemPhase{\cd}{cd}% condensed phase -\NewChemPhase{\lc}{lc}% liquid crystal +% \NewChemPhase{\aqi}{aq,$\infty$}% aqueous solution at infinite dilution +% \NewChemPhase{\cd}{cd}% condensed phase +% \NewChemPhase{\lc}{lc}% liquid crystal \newname\hensel{Martin Hensel} \newname\pedersen{Bj\o rn Pedersen} -\BeforeBeginEnvironment{example}{\vspace{\baselineskip}} -\AfterEndEnvironment{example}{\vspace{\baselineskip}} -\BeforeBeginEnvironment{sourcecode}{\vspace{\baselineskip}} -\AfterEndEnvironment{sourcecode}{\vspace{\baselineskip}} +% \undef\module +% \undef\moduleidx +\newidxcmd\chemmodule{\code{#1}}[ (module)] +\AtEndPreamble{% + \pdfstringdefDisableCommands{% + \def\chemmodule*#1{\textquotedblleft#1\textquotedblright}% + }% +} +\newidxcmd\sym{\code{#1}}[ (symbol)] + +\makeatletter +\def\cnltx@bash@listings@style{ + language = bash, + basicstyle = {\sourceformat\color{black}}, + % numbers = left, + % numberstyle = \tiny, + xleftmargin = 1em, + numbersep = .75em, + gobble = \cnltx@gobble , + columns = fullflexible, + literate = + {ä}{{\"a}}1 + {ö}{{\"o}}1 + {ü}{{\"u}}1 + {Ä}{{\"A}}1 + {Ö}{{\"O}}1 + {Ü}{{\"U}}1 + {ß}{{\ss}}1 , + breaklines = true, + keepspaces = true, + breakindent = 1em, + commentstyle = \color{comment}, + keywordstyle = \color{black}\bfseries , + stringstyle = \color{black} , + showstringspaces = false , + morekeywords = texdoc +} + +\cnltx@expandargs(nx)\lstdefinestyle + {bash} + {\expandonce\cnltx@bash@listings@style} + +\newcommand*\prompt{} +\patchcmd\lst@NewLine + {\hbox{}}% search + {\hbox{}\prompt}% replace + {}% success + {}% failure +\newsourcecodeenv[ + code-only, + sourcecode-options={style=bash}, + pre-code=\def\prompt{\textasciitilde\space\$\space} +]{bash} +\makeatother + +\renewcommand*\dictumauthorformat[1]{#1} +\renewcommand*\raggeddictumtext{} + +\newcommand*\TF{\textcolor{red}{\uline{\code{\textcolor{cs}{\textit{TF}}}}}} + +\makeatletter +\renewenvironment{commands} + {% + \cnltx@set@catcode_{12}% + \let\command\cnltx@command + \cnltxlist + } + {\endcnltxlist} +\newenvironment{tikzcode} + {% + \def\arrowtip{\@cnltx@option@item\code}% + \cnltxlist + } + {\endcnltxlist} + +\newrobustcmd*\showenv[1]{\beginenv*\code{\{}\env{#1}\code{\}}} +\makeatother + +\ExplSyntaxOn +\cs_new_protected:Npn \chemboldchecks #1 + { + \seq_set_map:NNn \l_tmpa_seq \l__chemmacros_if_bf_seq { \code {##1} } + \seq_use:Nnnn \l_tmpa_seq {,~} {,~} {~#1~} + } +\ExplSyntaxOff \begin{document} \part{Preliminaries} -\section{Licence, Requirements and \textsc{README}} +\section{Licence, Requirements and \textsc{README}}\label{sec:licence-requ-readme} \license -The \chemmacros\ package needs the bundles \bnd{l3kernel}~\cite{bnd:l3kernel} -and \bnd{l3packages}~\cite{bnd:l3packages}. It also needs the packages -\needpackage{siunitx}~\cite{pkg:siunitx}, -\needpackage{mathtools}~\cite{pkg:mathtools}, \needpackage{bm}~\cite{pkg:bm}, -\needpackage{nicefrac}~\cite{pkg:nicefrac} and -\needpackage{environ}~\cite{pkg:environ} as well as -\pkg{tikz}\footnote{\CTANurl[graphics]{pgf}}~\cite{pkg:pgf} and the \TikZ\ -libraries \code{calc} and \code{arrows}. Language support is done with the -help of the \needpackage{translations}~\cite{pkg:translations}. The -\chemmacros\ package also loads the packages -\pkg{chemformula}~\cite{pkg:chemformula} and -\pkg{chemgreek}~\cite{pkg:chemgreek}. - -The package option \option{xspace} also loads the package -\pkg{xspace}~\cite{pkg:xspace}. - -The package option \option{ghsystem} also loads the package -\pkg{ghsystem}~\cite{pkg:ghsystem}. - - -\section{Motivation and Background} -\chemmacros\ started some years ago as a growing list of custom macros that I -frequently used. I cannot completely recall when and why I decided to release -them as a package. Well -- here we go and you might find it useful, too, I -hope. - -Both the macros and their functionality have changed over time and quite a lot -have been added. Many things have been unified and what's probably most -important: many possibilities to customize have been added, too. - -Probably every chemist using \LaTeXe\ is aware of the great \pkg{mhchem} -package by \hensel. There have always been some difficulties intertwining it -with \chemmacros, though. Also, some other minor points in \pkg{mhchem} -always bothered me, but they hardly seemed enough for a new package. They -weren't even enough for a feature request to the \pkg{mhchem} author. The -challenge and the fun of creating a new package and the wish for a highly -customizable alternative led to \chemformula\ after all. \chemformula{} used -to part of \chemmacros{} for quite a while but now is an independent package. - -As a chemist you are probably aware of the fact that the \acl{UN} have -developed the \ac{ghs} as a global replacement for the various different -systems in different countries. While it has not been implemented by all -countries yet~\cite{unece:ghsystem_implementation}, it is only a matter of -time. - -The package \ghsystem\ enables you to typeset all the hazard and precautionary -statements and pictograms in a very easy way. The statements are taken from -\acs{eu} regulation 1272/2008~\cite{eu:ghsystem_regulation}. \ghsystem{} used -to be a part of \chemmacros{} for quite a while but now is an independent -package. - -There are four points I hope I have achieved with this package: +\chemmacros\ loads the packages \pkg{expl3}~\cite{bnd:l3kernel} and +\pkg{xparse}~\cite{bnd:l3packages}. Depending on your usage other packages +will be loaded. They are mentioned when the corresponding module using the +package is described. + +\section{Motivation and Background}\label{sec:motiv-backgr} +This package grew from a small collection of personal helper macros back +in~2010 into a rather big package supporting various different chemical +typesetting tasks. I hope I have achieved the following points with this +package: \begin{itemize} - \item intuitive usage as far as the syntax of the commands is concerned - \item the commands shall not only make typesetting easier and faster but also - the document source more readable with respect to semantics + \item Intuitive usage as far as the syntax of the commands is concerned. + \item A comprehensive set of macros! If there are any needs you might have + with respect to typesetting of chemistry which is not supported by this + package\footnote{Not including needs already solved by other packages such + as \pkg{chemnum} or \pkg{chemfig}.} then let me know so \chemmacros\ can + be extended. + \item The commands shall not only make typesetting easier and faster but + also the document source more readable with respect to semantics (\code{\cs{ortho}-dichlorobenzene} is easier to read and understand than - \code{\cs*{textit}\Marg{o}-dichlorobenzene}) - \item as much customizability as I could think of so every user can adapt the - commands to his or her own wishes - \item default settings compliant with the recommendations of the \acf{iupac}. -\end{itemize} -Especially the last point needed some pushing from users to get things right -in many places. If you find anything not compliant with \ac{iupac} -recommendations\footnote{This does not concern the \cs{ox} command. The - \ac{iupac} version is \cs{ox}\sarg.} I would welcome an email very much! - -\section{News} -\subsection{Version~4.0} -With version~4.0 some changes have been made: -\begin{itemize} - \item first of all the packages \chemformula\ and \ghsystem\ do not load - \chemmacros\ any more which means they can be used independently. - \item the option \option{bpchem} has been dropped. - \item the commands \cs{mch} and \cs{pch} now match \chemformula's - charges. - \item the option \option{method} has been dropped. - \item the option \option{append} has deprecated. - \item the option \option{greek} has been extended to support other uppercase - greek letters, for example those provided by \pkg{kpfonts}. This is - handled internally by the new package in the family: \chemgreek. This - package is not really a package for usage at a user-level but could in - principle be used to extend the \option{greek} option. - \item language support is now done with the help of the \pkg{translations}. - This means that with version~4.0 the document language is recognized - automatically. - \item the status of the commands \cs{Lfi} and \cs{Dfi} has been changed - from \emph{deprecated} to \emph{dropped}. - \item various other changes like bug fixes and improvements on the - typographical appearance of \chemformula's inline formulae with \cs{ch}. + \code{\cs*{textit}\Marg{o}-dichlorobenzene}); the first variant in my + opinion also is more in the spirit of \LaTeXe. + \item As much customizability as I could think of so every user can adapt + the commands to his or her own wishes. Every now an then users have + wishes which can't be solved with the available options. Almost always + I'll add options then. If you find something please contact me, see + section~\vref{sec:sugg-bug-reports}. + \item Default settings that are compliant with the recommendations of the + \acf{iupac}. \end{itemize} +Especially the last point in the past needed some pushing from users to get +things right in many places. If you find anything not compliant with +\ac{iupac} recommendations please contact me, see +section~\vref{sec:sugg-bug-reports}. Don't forget to add references for the +corresponding \ac{iupac} recommendation. + +\section{The Structure of \chemmacros}\label{sec:structure-chemmacros} +\subsection{General Structure} +Since version~5.0 the \chemmacros\ package has a strictly modular +structure\sinceversion{5.0}. On the one hand this eases maintenance but it +will also allow for easy and quick extension in the future. In a way it is a +logical consequence from \chemmacros' history: since version~2.0, \ie, since +the fall of~2011 \chemmacros\ already had modular options. + +The different modules of \chemmacros\ are divided into two groups: +\begin{enumerate} + \item Internal modules which provide underlying functionality or basic + functionality which is not of direct interest from a user perspective but + might be if you plan to write a module yourself (see + section~\ref{sec:own-modules} for details). + \item User modules which provide all the stuff for typesetting. +\end{enumerate} +Both groups each are subdivided into two groups: preloaded modules and modules +which have to be loaded by the programmer (internal modules) or by the +document author (user modules). Those modules are described in +parts~\ref{part:preloaded-modules} (preloaded modules) +and~\ref{part:additional-modules} (additional modules) of this manual. + +The above means that not all functionality is available per default. If you +want to load \emph{all} modules no matter what then you can say: +\begin{sourcecode} + \usechemmodule{all} +\end{sourcecode} +or +\begin{sourcecode} + \chemsetup{modules=all} +\end{sourcecode} +which will load all modules which are part of \chemmacros\ (also see +section~\vref{sec:all-module}). Own modules (see +section~\vref{sec:own-modules}) are \emph{not} loaded through this, though, +and still have to be loaded additionally. + +In part~\vref{part:preloaded-modules} the preloaded modules are described, +first the user modules then the internal ones, in +part~\vref{part:additional-modules} the other available modules are described, +again the user modules first. In each section the modules are described in +an alphabetical order. + +\subsection{Using \chemmacros' Options}\label{sec:using-chemm-opti} +Prior to v5.0 \chemmacros\ had quite a number of package options. +\chemmacros\ v5.0 or higher has none! All of \chemmacros's options are set +using the command +\begin{commands} + \command{chemsetup}[\oarg{module}\marg{option list}] + \chemmacros' setup command. +\end{commands} -\subsection{Version~4.2} +When an option is described then in the left margin the module the option +belongs to is denoted. This looks something like this: +\begin{options} + \keyval{option}{value}\Module{module}\Default + Description of \option{option}. The module is printed in the left margin. + The default value to the right is the setting the option has when + \chemmacros\ is loaded. This can be an explicit setting but the option + can also be empty. + \keychoice{choice-option}{list,of,\default{choices}}\Module{module}\Default{list} + Description of \option{choice-option}. A choice option can only be used + with a predefined list of values. If one of the values is underlined it + means that the option can be used without value in which case the + underlined value is chosen. If no value is underlined then a value + \emph{has} to be given by the user. + \keybool{boolean-option}\Module{module}\Default{true} + Description of \option{boolean-option}. A boolean option is a choice + option with exactly the two values \code{true} and \code{false}. If the + option is called without value then the underlined value is chosen (which + is always \code{true} for a boolean option). +\end{options} +An option or list of options belonging to a module \chemmodule{module} can be +set in two ways: +\begin{sourcecode} + % first possibility: + \chemsetup[module]{ + option1 = value , + option2 = value + } + % second possibility: + \chemsetup{ + module/option1 = value , + module/option2 = value + } +\end{sourcecode} +The second way allows to set options belonging to different modules with one +call of \cs{chemsetup}. + +\subsection{Support Package \chemformula} +\chemformula\ provides means of typesetting chemical formulas and reactions. +You will see its macros \cs{ch} and \cs{chcpd} every now and then in this +manual. When using \chemmacros\ you can consider the \chemformula\ +package~\cite{pkg:chemformula} to be loaded as \chemmacros\ makes use of it in +various places. \chemmacros\ and \chemformula\ are tightly intertwined. In +fact: \emph{when using \chemmacros\ you should prefer \chemformula\ over + \pkg{mhchem} (which provides very similar functionality) for having + consistent typesetting}. + +A historical note: \chemformula\ started as a part of \chemmacros\ in +January~2012. Since July~2013 it is a completely independent package -- from +\chemformula's point of view. It is maintained independently and has a manual +of its own. + +\subsection{Upgrading from version $<5.0$} +People upgrading from versions $<5.0$ will find that almost everything they +know from earlier versions is the same in versions $\geq5.0$. But there are +important and \emph{breaking} differences: \begin{itemize} - \item Changed particles with electron pairs such as \cs{ba} to use - \chemformula's new macro \cs{chlewis} for the Lewis electrons. - \item Changed the implicit \cs*{Delta} in the thermodynamic state variables - into \cs*{ChemDelta} to ensure that an upright symbol is used. - \item Change in the syntax of \cs{DeclareChemState} and - \cs{RenewChemState}. The old syntax is still supported but discouraged. + \item \chemmacros\ has no package options any more, all options are set via + \cs{chemsetup}, also see section~\vref{sec:using-chemm-opti}. + \item Not all of the features are available per default any more, for some + the corresponding module has to be loaded explicitly, see + section~\ref{sec:general-options}. If suddenly some commands or + environments seem to be undefined this is the most likely reason. + \item Some option modules have been renamed (\eg, \module*{iupac} is now + \module{nomenclature}). If you experience strange errors when you upgrade + your document this is the most likely source. + \item The command family \cs*{NewChem\ldots}, \cs*{RenewChem\ldots} and + \cs*{DeclareChem\ldots} has a new member \cs*{ProvideChem\ldots}. + \item In \cs{iupac} the macro \cs*{-} no longer gives a dash with breaking + point. Instead \sym*{-} can be used directly\footnote{\cs*{-} will be + provided a bit longer for easing the upgrade step but will be dropped + eventually.}. + \item The macro \cs{ox} has another default behaviour (\keyis{pos}{super}) + and the starred version has another effect (\keyis{pos}{top}) than the + same macro in earlier versions. Now the default behaviour follows + \acs{iupac} recommendations. A second change is that the atom is now + treated as a \chemformula\ formula. + \item The syntax of \cs{NewChemReaction} and friends is now different from + what it used to be. If you have defined your own reaction environments + you need to adapt! + \item \chemmacros\ offers a macro \cs{state} which is similar to but + different from the earlier macro \cs*{State}. \cs*{State} is deprecated. + There are also differences in the syntax of \cs{enthalpy} \vs\ the earlier + \cs*{Enthalpy}, \cs{entropy} \vs\ \cs*{Entropy} and \cs{gibbs} \vs\ + \cs*{Gibbs}. The uppercase versions are deprecated. The macro + \cs{NewChemState} also has a different syntax now. + \item At various places in the code improvements and fixes have been made, + too many to list them here. You should keep an open eye and first of all + read the manual closely. \end{itemize} -\subsection{Version 4.3} -\begin{itemize} - \item All one-letter \acs{iupac} macros have been exchanged in favour of - more meaningful macro names. The one-letter commands still exist for - backward compatibility (and to some users no doubt also for convenience). - They are no longer recommended though. One-letter commands seldomly have - meaningful names and often they've also been defined by other packages. - This means they make collaboration more difficult than it needs to be and - are a source for package conflicts. \chemmacros\ used to solved the - latter problem by only providing them inside the argument of - \cs{iupac}\label{desc:one-letter-commands}. The one exception - \chemmacros\ makes is the command \cs{p} (for things like \pH) which is - and will remain an official command. - \item The environment \env{experimental} has got a number of new options, - see section~\ref{sec:experimental-customization}. - \item The commands \cs*{DeclareChem\meta{...}} now don't give an error any - more if the command already exists. This is more consistent with \LaTeX's - \cs*{DeclareRobustCommand}. For all those commands a version - \cs*{NewChem\meta{...}} is introduced that \emph{does} give an error if - the new command is already defined. - \item The package option \option{strict} has been deprecated. - \item The package option \option{cmversion} has been deprecated. - \item The command \cs{mhName} has been dropped. -\end{itemize} +\subsection{Compatibility Mode} -\subsection{Version 4.4} -\begin{itemize} - \item New \module{nmr} option \option{atom-number-cs}. - \item New \module{nmr} option \option{coupling-pos-cs}. -\end{itemize} +\subsubsection{For Users} +It is actually not true that \chemmacros' has no package options any more. It +has one very important package option: +\begin{options} + \keyval{compatibility}{num}\Default{\chemmacrosversion} + Let's you specify the version number of \chemmacros\ you want to use. Any + version earlier than 5.0 will load v4.7. \ie, the last version before + \chemmacros\ got its modular structure\footnote{Mostly: the loaded v4.7 + has got a few fixes}. Not using the option will always load the newest + version. Please note that you only can specify the \emph{number} of the + version. For a version \enquote{5.2c} you can only set compatibility mode + \enquote{5.2} but not specify the subrelease. +\end{options} -\subsection{Version 4.5} -\begin{itemize} - \item New \module{acid-base} option \option{subscript}. - \item Dutch translations. -\end{itemize} +In your document you can check for the compatibility mode. For the following +functions it is important to understand the rules: \emph{greater} means +\emph{newer}. The version number is \emph{not} a usual decimal number! The +syntax for \meta{num} is \meta{major}\code{.}\meta{minor}. This means that a +version 5.11 is \emph{newer} than a version 5.7! In the same way \emph{less} +means \emph{older}. As last example: 5.10 is \emph{newer} (greater) than 5.1. +\begin{commands} + \command{IfChemCompatibilityTF}[\marg{comp}\marg{num}\marg{true}\marg{false}] + Checks the value given through the option \option{compatibility} against + \meta{num} using \meta{comp} and either leaves \meta{true} or \meta{false} + in the input stream. \meta{comp} can be one of \code{<}, \code{<=}, + \code{=}, \code{>=} or \code{>}. + \command{IfChemCompatibilityT}[\marg{comp}\marg{num}\marg{true}] + Checks the value given through the option \option{compatibility} against + \meta{num} using \meta{comp} and leaves \meta{true} in the input stream if + the check is logically true. \meta{comp} can be one of \code{<}, + \code{<=}, \code{=}, \code{>=} or \code{>}. + \command{IfChemCompatibilityF}[\marg{comp}\marg{num}\marg{false}] + Checks the value given through the option \option{compatibility} against + \meta{num} using \meta{comp} and leaves \meta{false} in the input stream if + the check is logically false. \meta{comp} can be one of \code{<}, + \code{<=}, \code{=}, \code{>=} or \code{>}. +\end{commands} -\subsection{Version 4.6} -\begin{itemize} - \item The packages \chemformula, \chemgreek{} and \ghsystem{} are no longer - distributed as a part of \chemmacros{} but as packages of their own. - \item Inside \cs{iupac} the characters \code{\textbar} and - \code{\textasciicircum} are active. The corresponding commands - \cs{\textbar} and \cs{\textasciicircum} are deprecated now and will be - dropped eventually. -\end{itemize} +A possible usage: +\begin{sourcecode} + \IfChemCompatibilityT{>=}{5.0}{\usechemmodule{all}} +\end{sourcecode} -\subsection{Version 4.7} -\begin{itemize} - \item Fix broken \cs{iupac}. - \item Change the default subscripts of the equilibrium constants to match - the usage in the \acs{iupac} Green Book. - \item Allow \cs{NewChemPhase} and friends after \verbcode+\begin{document}+. - \item New optional argument to phase commands. - \item New \module{nmr} options n\option{method} and \option{connector}. -\end{itemize} +Loading \chemmacros\ with \keyis{compatibility}{4.7} also allows to use the +package options from that version: +\begin{sourcecode} + \usepackage[compatibility=4.7,language=german]{chemmacros} +\end{sourcecode} + +\subsubsection{For Module Writers} +For future versions the aim is not to make such breaking changes again. While +we never know what the future actually will bring \chemmacros\ now has the +tools for tying code to a version number: +\begin{commands} + \expandable\command*{chemmacros_if_compatiblity:nn}[\TF\ \marg{comp} + \marg{num} \marg{true} \marg{false}] + expl3 version of \cs{IfChemCompatibilityTF}. +\end{commands} + +In modules one can try adding code for a certain version or range of versions: +\begin{commands} + \command{ChemCompatibility}[\marg{num} \meta{code} \cs{EndChemCompatibility}] + Leaves \meta{code} in the input stream if the compatibility version $x$ + given by \option{compatibility} matches \meta{num} + ($x=\text{\meta{num}}$). + \command{ChemCompatibilityFrom}[\marg{num} \meta{code} \cs{EndChemCompatibility}] + Leaves \meta{code} in the input stream if the compatibility version $x$ + given by \option{compatibility} matches \meta{num} or newer. This means + \meta{num} is the \emph{oldest} version allowed + ($x\geq\text{\meta{num}}$). + \command{ChemCompatibilityTo}[\marg{num} \meta{code} \cs{EndChemCompatibility}] + Leaves \meta{code} in the input stream if the compatibility version $x$ given + by \option{compatibility} matches \meta{num} or older. This means + \meta{num} is the \emph{newest} version allowed + ($x\leq\text{\meta{num}}$). + \command{ChemCompatibilityBetween}[\marg{num1}\marg{num2} \meta{code} + \cs{EndChemCompatibility}] + Leaves \meta{code} in the input stream if the compatibility version $x$ + given by \option{compatibility} lies between \meta{num2} and \meta{num2} + ($\text{\meta{num1}}\leq x\leq\text{\meta{num2}}$). + \command{EndChemCompatibility} + This macro \emph{must} end each of the \cs*{ChemCompatibility\ldots} + macros. +\end{commands} + +You may refer to the current version of \chemmacros\ with the following +tokenlists: +\begin{commands} + \command*{c_chemmacros_date_tl} + The current release date: \enquote{\csname + c_chemmacros_date_tl\endcsname}. + \command*{c_chemmacros_version_major_number_tl} + The current major version: \enquote{\csname + c_chemmacros_version_major_number_tl\endcsname}. + \command*{c_chemmacros_version_minor_number_tl} + The current minor version: \enquote{\csname + c_chemmacros_version_minor_number_tl\endcsname}. + \command*{c_chemmacros_version_number_tl} + The current version number: \enquote{\csname + c_chemmacros_version_number_tl\endcsname}. + \command*{c_chemmacros_version_subrelease_tl} + The current sub-release: \enquote{\csname + c_chemmacros_version_subrelease_tl\endcsname}. + \command*{c_chemmacros_version_tl} + The current version: \enquote{\csname c_chemmacros_version_tl\endcsname}. + \command*{c_chemmacros_info_tl} + The package information: \enquote{\csname + c_chemmacros_info_tl\endcsname}. +\end{commands} -\section{Package Options}\label{sec:options} -\chemmacros\ has several package options. They all are used as key/value pairs -like +\section{General Options}\label{sec:general-options} + +\chemmacros\ has some core options which don't belong to any of the modules +described in parts~\ref{part:preloaded-modules} +and~\ref{part:additional-modules}. Those options have no module denoted in +the left margin next to their descriptions and are also set without specifying +a module: \begin{sourcecode} - \usepackage[option1 = , option2 = ]{chemmacros} + \chemsetup{ + option1 = value , + option2 = value + } \end{sourcecode} -Some also can be used without value -(\verbcode+\usepackage[option1]{chemmacros}+), which means that the -\default{underlined} value is used. +Two of those options are explained now: \begin{options} - % circled - \keychoice{circled}{formal,\default{all},none}\Module{option}\Default{formal} - \chemmacros\ uses two different kinds of charges which indicate the usage - of real ($+/-$) and formal (\fplus/\fminus) charges. The option - \code{formal} distinguishes between them, option \code{none} displays them - all without circle, option \code{all} circles all. - % circletype - \keychoice{circletype}{\default{chem},math}\Module{option}\Default{chem} - This option switches between two kinds of circled charge symbols: - \cs{fplus} \fplus\ and \verbcode+$\oplus$+ $\oplus$. - % ghsystem - \keybool{ghsystem}\Module{option}\Default{false} - \keyis{ghsystem}{false} disables the automatic loading of the \ghsystem\ - package. - % greek - \keychoice{greek}{\default{auto},upgreek,textgreek,mathdesign,kpfonts,newtx,% - fourier,textalpha}\Module{option}{}% empty group pushes default value to - % next line - \Default{auto} - This option determines how the letters \cs{chemalpha} and friends are - typeset. See pages~\pageref{desc:greek} and~\pageref{par:greek_letters} - for more information. Please note that this option \emph{does not load - either \pkg{upgreek}, \pkg{kpfonts} or any other package!} It only - determines which one to choose if available. The option \code{auto} will - detect if any of the packages needed for one of the options has been - loaded and use it if available. If more than one of the packages has been - loaded the option will choose the one listed first in the above choice - list. If you explicitly choose an option other than \code{auto} or - \code{math} you also have to load the corresponding package. \emph{This - option can only be chosen in the preamble}. - % iupac - \keychoice{iupac}{auto,restricted,strict}\Module{option}\Default{auto} - Take care of how \ac{iupac} naming commands are defined, see - page~\pageref{desc:iupac}. - % language - \keychoice{language}{american,british,english,french,german,italian,ngerman}% - \Module{option}\Default - Load the language used by \chemmacros. \emph{This option can only be - chosen in the preamble}. - % Nu - \keychoice{Nu}{\default{chemmacros},mathspec}\Module{option}\Default{chemmacros} - The package \pkg{mathspec} also defines a macro \cs{Nu}. This option - chooses which definition holds, see page~\pageref{Nu}. \emph{This option - can only be chosen in the preamble}. - % synchronize - \keybool{synchronize}\Module{option}\Default{false} - The setting \code{true} will tell \chemmacros\ to adapt the font settings - of \chemformula. - % xspace - \keybool{xspace}\Module{option}\Default{true} - With this option most commands are defined with a \cs*{xspace}. + \keyval{modules}{comma separated list of module names}\Default + With this option you can specify which modules you want to load. + Alternatively you can use \cs{usechemmodule}\marg{comma separated list of + module names}. + \keyval{greek}{mapping}\Default + Explicitly specify which mapping should be used by the \chemgreek\ + package~\cite{pkg:chemgreek}. For details about what this means please + refer to section~\vref{sec:greek-module}. \end{options} +Some internal modules may also define core options, \eg, the \chemmodule{lang} +module, see section~\vref{sec:lang-module}. -\section{Setup}\label{sec:setup} -Various of \chemmacros' commands have key/value pairs with which they can be -customized. Most times they can be used as (optional) argument of the -commands themselves. They also can most times be used with the \cs{chemsetup} -command. +\part{The Preloaded Modules}\label{part:preloaded-modules} + +\section{User Modules} +\subsection{The \chemmodule*{acid-base} Module}\label{sec:acid-base-module} + +Easy representation of \pH, \pKa \ldots \begin{commands} - \command{chemsetup}[\oarg{module}\Marg{\meta{key} = \meta{value}}] - Set up the options for module \meta{module} only or - \command{chemsetup}[\Marg{\meta{module}/\meta{key} = \meta{value}}] - in combination with options from other modules. + \command{pH} \pH + \command{pOH} \pOH + \command{Ka} \Ka, depends on language settings, see + section~\vref{sec:lang-module}. The translations can be adapted. + \command{Kb} \Kb + \command{Kw} \Kw + \command{pKa}[\oarg{num}] \cs{pKa}: \pKa, \cs{pKa}\Oarg{1}: \pKa[1], depends + on language settings, see section~\vref{sec:lang-module}. The translations + can be adapted. + \command{pKb}[\oarg{num}] \cs{pKb}: \pKb, \cs{pKb}\Oarg{1}: \pKb[1] + \command{p}[\marg{anything}] \eg\ \cs{p}\Marg{\cs{Kw}} \p{\Kw} \end{commands} -The keys each belong to a module, which defines for which commands they are -intended for. If a key is presented, you'll see the module to which it -belongs in the left margin. You have two ways to use keys with the -\cs{chemsetup}, as you can see above. - -The package options can also be seen as keys belonging to the module -\module{option}. This means they can also be used with the \cs{chemsetup} -command (except for the option \choicekey{version}{1,2,3}). + +\begin{example}[side-by-side] + \Ka\ \Kb\ \pKa\ \pKa[1] \pKb\ \pKb[1] +\end{example} + +\begin{cnltxquote}[{\citetitle{iupac:greenbook} \cite[][p.\,103]{iupac:greenbook}}] + The operator \p{} \textelp{} shall be printed in Roman type. +\end{cnltxquote} + +There is one option which changes the style the \p{} is typeset, other options +allow to change the subscript of the constants: +\begin{options} + \keychoice{p-style}{italics,slanted,upright}\Module{acid-base}\Default{upright} + Set the style of the \p{} operator. + \keyval{K-acid}{text}\Module{acid-base}\Default{\cs{ChemTranslate}\Marg{K-acid}} + The subscript to \cs{Ka} and \cs{pKa}. + \keyval{K-base}{text}\Module{acid-base}\Default{\cs{ChemTranslate}\Marg{K-base}} + The subscript to \cs{Kb} and \cs{pKb}. + \keyval{K-water}{text}\Module{acid-base}\Default{\cs{ChemTranslate}\Marg{K-water}} + The subscript to \cs{Kw}. +\end{options} \begin{example} - \chemsetup[option]{circled=none} - \leavevmode\mch\ \pch\ \fmch\ \fpch\ \el\ \prt \par - \chemsetup[option]{circled=formal} - \leavevmode\mch\ \pch\ \fmch\ \fpch\ \el\ \prt \par - \chemsetup[option]{circletype=math} - \leavevmode\mch\ \pch\ \fmch\ \fpch\ \el\ \prt \par - \chemsetup{option/circletype=chem,option/circled=all}% - \leavevmode\mch\ \pch\ \fmch\ \fpch\ \el\ \prt \par - \chemsetup{option/circletype=math} - \leavevmode\mch\ \pch\ \fmch\ \fpch\ \el\ \prt -\end{example} -Keys \emph{not} belonging to a module \emph{cannot} be used with -\cs{chemsetup}! - -All options of \chemformula\ belong to the module \module{chemformula} and all -of \ghsystem's options belong to the module \module{ghsystem} which means that -their options can also be set up using \cs{chemsetup}. - - -\section{Language Settings}\label{sec:languages} -\subsection{How it Works} -\chemmacros\ uses the \pkg{translations} package for a number of language -dependent strings. That means that if a suitable translation to those strings -is given the \pkg{babel}~\cite{pkg:babel} or -\pkg{polyglossia}~\cite{pkg:polyglossia} language will be picked up -automatically. You can, however, overwrite this mechanism by explicitly -chosing the language you want. This is done with the package option -\option{language}. - -Section~\ref{sec:supported-languages} lists all language dependent strings and -the provided translations. - -\subsection{Supported Languages}\label{sec:supported-languages} -By choosing the option -\begin{commands} - \command{chemsetup}[\oarg{option}\Marg{language=\meta{language}}] - Selection of the language \meta{language}. -\end{commands} -you can set the language that is used by \chemmacros\ if you want it to be a -\emph{different language than your main document language}. + \pH, \pKa \par + \chemsetup[acid-base]{p-style=slanted} \pH, \pKa \par + \chemsetup[acid-base]{p-style=italics} \pH, \pKa +\end{example} -There are some language definitions made by \chemmacros. They include -\begin{itemize} - \item the header of the list of reactions, - \item the beginning of the entries in the list of reactions, and - \item the H- and P-statements of the \ac{ghs} statements. -\end{itemize} +As you can see the default subscripts of \cs{Kw}, \cs{Ka} and \cs{Kb} are +lowercase letters. The literature is inconclusive about if this is the right +way or if uppercase letters should be preferred. In textbooks the uppercase +variant usually seems to be used while journals seem to prefer the lowercase +variant. \chemmacros' default follows the usage in +\citetitle{iupac:greenbook}~\cite{iupac:greenbook}. If you want to change +this you have two possibilities: -\chemmacros\ uses the \pkg{translations} to get translated strings sensitive -to \pkg{babel} or \pkg{polyglossia} settings. All pre-defined -\pkg{translations} keys are listed in -table~\ref{tab:language-dependent-strings}. To some of those a few -non-English translations are provided. +\begin{example} + % this works only in the preamble: + % \DeclareTranslation{English}{K-acid}{\mathrm{A}}% use your language here + % alternative: + \chemsetup{acid-base/K-acid=\mathrm{A}}% overwrites language dependent settings + \pKa +\end{example} -\begin{table} - \centering - \caption{Language dependent strings.} - \label{tab:language-dependent-strings} - \begin{tabular}{>{\ttfamily}ll} - \toprule - \normalfont\bfseries \pkg{translations} key & - \bfseries English default \\ - \midrule - K-acid & $\GetTranslation{K-acid}$ \\ - K-base & $\GetTranslation{K-base}$ \\ - K-water & $\GetTranslation{K-water}$ \\ - \midrule - phase-sld & \GetTranslation{phase-lqd} \\ - phase-lqd & \GetTranslation{phase-sld} \\ - phase-gas & \GetTranslation{phase-gas} \\ - phase-aq & \GetTranslation{phase-aq} \\ - \midrule - list-of-reactions & \GetTranslation{list-of-reactions} \\ - reaction & \GetTranslation{lor-reaction} \\ - \bottomrule - \end{tabular} -\end{table} +\subsection{The \chemmodule*{charges} Module}\label{sec:charges-module} -Currently this includes the following translations: -\begin{sourcecode} - % subscript used in \Ka: - \DeclareTranslation{German}{K-acid}{\mathrm{s}} - % the phases \sld and \lqd: - \DeclareTranslation{German}{phase-sld}{f} - \DeclareTranslation{German}{phase-lqd}{f{}l} - % heading of the list of reactions: - \DeclareTranslation{English}{list-of-reactions}{List of reactions} - \DeclareTranslation{German} {list-of-reactions}{Reaktionsverzeichnis} - \DeclareTranslation{Italian}{list-of-reactions}{Elenco delle reazioni} - \DeclareTranslation{French} {list-of-reactions}{Table des r\'eactions} - % name at the beginning of each entry in the list of reactions: - \DeclareTranslation{English}{reaction}{Reaction} - \DeclareTranslation{German} {reaction}{Reaktion} - \DeclareTranslation{Italian}{reaction}{Reazione} - \DeclareTranslation{French} {reaction}{R\'eaction} -\end{sourcecode} -All other languages will fall back to English. However, you can always add -the translation you want. If you send me an email with translations you'd -like to have added to \chemmacros\ I'll gladly add them. - -\subsection{Specialties} -\subsubsection{German} -If you choose \code{german/ngerman} the phase commands \cs{sld} and \cs{lqd} -and the command \cs{pKa} are translated. - -\subsubsection{Italian} -\NewChemIUPAC{\ter}{\textit{ter}}\NewChemIUPAC{\sin}{\textit{sin}}% -Choosing the language \code{italian} defines two additional \ac{iupac} commands: +The \chemmodule{charges} module loads the module \chemmodule{chemformula}. + +\subsubsection{Charge Symbols} \begin{commands} - \command{ter} \iupac{\ter} - \command{sin} \iupac{\sin} + \command{fplus} \fplus\ formal positive charge + \command{fminus} \fminus\ formal negative charge + \command{scrp} \scrp\ scriptstyle positive charge (\eg, for usage in + \pkg{chemfig}'s~\cite{pkg:chemfig} formulas). + \command{scrm} \scrm\ scriptstyle negative charge (\eg, for usage in + \pkg{chemfig}'s formulas). + \command{fscrp} \fscrp\ scriptstyle formal positive charge (\eg, for usage + in \pkg{chemfig}'s formulas). + \command{fscrm} \fscrm\ scriptstyle formal negative charge (\eg, for usage + in \pkg{chemfig}'s formulas). + \command{fsscrp} \fsscrp\ scriptscriptstyle formal positive charge (\eg, for + usage in \pkg{chemfig}'s formulas). + \command{fsscrm} \fsscrm\ scriptscriptstyle formal negative charge (\eg, for + usage in \pkg{chemfig}'s formulas). \end{commands} -\part{The Package's Features}\label{part:chemmacros} -\section{Particles, Ions and Symbols}\label{sec:particles} -\subsection{Predefined} +\subsubsection{Ion Charges}\label{sec:ion-charges} +Simple displaying of (real) charges. It is worth noting that these commands +really are relicts from a time when \chemmacros\ tried hard to be compliant +with \pkg{mhchem} and \chemformula\ didn't exist, yet. They are still +provided for backwards compatibility but \emph{my recommendation is to use} +\cs{ch} (see the documentation of the \chemformula\ +package~\cite{pkg:chemformula}) \emph{and forget about these commands:} +\begin{commands} + \command{pch}[\oarg{number}] + positive charge + \command{mch}[\oarg{number}] + negative charge + \command{fpch}[\oarg{number}] + formal positive charge + \command{fmch}[\oarg{number}] + formal negative charge +\end{commands} +\begin{example}[side-by-side] + A\pch\ B\mch[3] C\fpch[2] D\fmch +\end{example} -\chemmacros\ defines some simple macros for displaying often needed particles -and symbols. Please note, that they're displayed differently depending on the -package options used, see section~\ref{sec:options}. These commands can be -used in text as well as in math mode. Note that they are not meant to be used -in \chemformula's \cs{ch}. +\subsubsection{Partial Charges and Similar Stuff}\label{sec:part-charg-simil} +The next ones probably are seldomly needed but nevertheless useful: \begin{commands} - \command{Hpl} \Hpl\ (proton) - \command{Hyd} \Hyd\ (hydroxide) - \command{HtO} \HtO\ (oxonium ion) (\textbf{H} \textbf{t}hree \textbf{O}) - \command{water} \water - \command{el} \el\ (electron) - \command{prt} \prt\ (proton) - \command{ntr} \ntr\ (neutron) - \command{Nu} \Nu\ (nucleophile)\par - The package \pkg{mathspec} also defines a macro \cs{Nu}. If you chose - package option \keyis{Nu}{mathspec} \chemmacros\ defines \cs{Nuc} - instead\label{Nu}. - \command{El} \El\ (electrophile) - \command{ba} \ba\ (base) - \command{fplus} \fplus - \command{fminus} \fminus - \command{transitionstatesymbol} \transitionstatesymbol - \command{standardstate} \standardstate\par - This symbol is only provided by \chemmacros, if the package - \pkg{chemstyle} is not loaded; the idea is borrowed from - there\footnote{many thanks to the package author - \href{http://www.texdev.net/}{Joseph Wright}.}. - \command{changestate} $\changestate$\par - A math operator symbol for denoting the change in an extensive - thermodynamic quantity for a process such as \State{H}. This symbol is - used in the definitions presented in section~\ref{sec:stand-state-therm}. - \command{chemalpha}[ \chemalpha, \cs{chemAlpha} \chemAlpha] - For each of the 24 greek letters a lowercase and uppercase \cs*{Chem...} - command is defined that maps to the upright greek letter as set with the - option \option{greek}. More details on this can be found in the manual of - the \chemgreek\ package. + \command{delp} \delp\ partial positive charge + \command{delm} \delm\ partial negative charge + \command{fdelp} \fdelp\ partial formal positive charge + \command{fdelm} \fdelm\ partial formal negative charge \end{commands} -The two particles \cs{Nu} and \cs{ba} can be modified. To do that you use -the option +These macros for example can be used with the \cs{ox} command (see +section~\vref{sec:redox-module}) or with the \pkg{chemfig} package: +\begin{example} + \chemsetup{ + charges/circled = all, + redox/parse = false, + redox/pos = top + } + \ch{"\ox{\delp,H}" -{} "\ox{\delm,Cl}"} \hspace*{1cm} + \chemfig{\chemabove[3pt]{\lewis{246,Br}}{\delm}-\chemabove[3pt]{H}{\delp}} +\end{example} + +\subsubsection{Charge Options} + \begin{options} - \keychoice{elpair}{false,\default{dots},dash}\Module{particle}\Default{false} - Set how the electron pair of the particles \cs{Nu} and \cs{ba} are set. + \keychoice{circled}{formal,\default{all},none}\Module{charges}\Default{formal} + \chemmacros\ uses two different kinds of charges which indicate the usage + of real ($+/-$) and formal (\fplus/\fminus) charges. The option + \code{formal} distinguishes between them, option \code{none} displays them + all without circle, option \code{all} circles all. + \keychoice{circletype}{chem,math}\Module{charges}\Default{chem} + This option switches between two kinds of circled charge symbols: + \cs{fplus} \fplus/\cs{fminus} \fminus\ (\code{chem}) and + \verbcode+$\oplus$+ $\oplus$/\verbcode+$\ominus$+ $\ominus$ (\code{math}). + \keyval{partial-format}{\LaTeX\ code}\Module{charges}\Default{\cs*{tiny}} + Code which formats the macros defined with \cs{NewChemPartialCharge} (see + section~\ref{sec:own-charge-macros}). \end{options} -\begin{example}[side-by-side] - \ba[elpair] \Nu[elpair=dash] - - \chemsetup[particle]{elpair} - \ba\ \Nu -\end{example} -\label{desc:greek}The greek letters aren't newly defined symbols but are -defined differently depending on the packages you've loaded. The default -definition is the corresponding math letter. If you have loaded the -\pkg{textgreek} package the letters are taken from there, and if you have -loaded the package \pkg{upgreek} the macros of that package are used. This is -also described in the description of the package option \option{greek}, other -details can be found in the documentation of the \chemgreek\ package. Which -package you have to load for a specific choice for the package option -\option{greek} is listed in table~\ref{tab:option:greek}. This documentation -uses \pkg{newtxmath} and the setting \keyis{greek}{newtx} for instance. +\subsubsection{Own Charge Macros}\label{sec:own-charge-macros} +Just in case the existing macros don't fit you needs there are commands for +defining new ones or modifying the existing ones. These commands define +macros like those described in section~\vref{sec:ion-charges}. -\begin{table} - \centering - \caption{Packages needed for the \option*{greek} package option..} - \label{tab:option:greek} - \begin{tabular}{>{\ttfamily}ll} - \toprule - \tablehead{option} & \tablehead{needed package} \\ - \midrule - auto & --- \\ - math & --- \\ - textgreek & \pkg{textgreek} \cite{pkg:textgreek} \\ - upgreek & \pkg{upgreek} \cite{pkg:upgreek} \\ - newtx & \pkg{newtxmath} \cite{pkg:newtx} \\ - kpfonts & \pkg{kpfonts} \cite{pkg:kpfonts} \\ - mathdesign & \pkg{mathdesign} \cite{pkg:mathdesign} \\ - fourier & \pkg{fourier} \cite{pkg:fourier} \\ - textalpha & \pkg{textalpha} \cite{bnd:greek-fontenc} \\ - \bottomrule - \end{tabular} -\end{table} +\begin{commands} + \command{NewChemCharge}[\marg{cs}\marg{charge symbol}] + Defines a new macro \meta{cs}. Raises an error if \meta{cs} already + exists. + \command{RenewChemCharge}[\marg{cs}\marg{charge symbol}] + Redefines a new macro \meta{cs}. Raises an error if \meta{cs} doesn't + exist. + \command{DeclareChemCharge}[\marg{cs}\marg{charge symbol}] + Defines a macro \meta{cs}. Silently overwrites \meta{cs} if it exists. + \command{ProvideChemCharge}[\marg{cs}\marg{charge symbol}] + Defines a new macro \meta{cs}. Does nothing if \meta{cs} already exists. +\end{commands} +An example of usage is the definition of the existing ion charge macros: +\begin{sourcecode} + \NewChemCharge\fpch{\fplus} + \NewChemCharge\fmch{\fminus} +\end{sourcecode} -The reason why \chemmacros\ uses these macros in the first place is \ac{iupac} -compliance. \ac{iupac} recommends to use upright greek letters in -nomenclature. +These commands define macros like those described in +section~\vref{sec:part-charg-simil}. +\begin{commands} + \command{NewChemPartialCharge}[\marg{cs}\marg{charge symbol}] + Defines a new macro \meta{cs}. Raises an error if \meta{cs} already + exists. + \command{RenewChemPartialCharge}[\marg{cs}\marg{charge symbol}] + Redefines a new macro \meta{cs}. Raises an error if \meta{cs} doesn't + exist. + \command{DeclareChemPartialCharge}[\marg{cs}\marg{charge symbol}] + Defines a macro \meta{cs}. Silently overwrites \meta{cs} if it exists. + \command{ProvideChemPartialCharge}[\marg{cs}\marg{charge symbol}] + Defines a new macro \meta{cs}. Does nothing if \meta{cs} already exists. +\end{commands} +An example of usage is the definition of the existing partial charge macros: +\begin{sourcecode} + \NewChemPartialCharge\fdelp{\fplus} + \NewChemPartialCharge\fdelm{\fminus} +\end{sourcecode} -\begin{cnltxquote}[{\ac{iupac} Green Book {\cite[][p.\,9]{iupac:greenbook}}}] - Greek letters are used in systematic organic, inorganic, macromolecular and - biochemical nomenclature. These should be roman (upright), since they are - not symbols for physical quantities. -\end{cnltxquote} +\subsection{The \chemmodule*{nomenclature} Module}\label{sec:nomenclature-module} -\chemmacros\ uses these commands now to define nomenclature commands, see -page~\pageref{par:greek_letters}. +The \chemmodule{nomenclature} module loads the \chemmodule{tikz} module. It +also loads the package \pkg{scrlfile} which is part of the +\KOMAScript\ bundle~\cite{bnd:koma-script}. -\subsection{Own Particles} +\subsubsection{The \cs*{iupac} Command} -Surely sometimes it can be handy to have other particle macros defined such as -\cs*{positron} or \cs*{photon}. This can easily be done with this command: -\begin{commands} - \command{NewChemParticle}[\marg{cs}\marg{definition}] - \sinceversion{4.3}Define a new particle command. Gives an error if - \meta{cs} already exists. - \command{DeclareChemParticle}[\marg{cs}\marg{definition}] - \changedversion{4.3}Define a new particle command. - \command{RenewChemParticle}[\marg{cs}\marg{definition}] - Renew the definition of a particle command. -\end{commands} -The particle defined this way behaves uses \chemformula's \cs{ch} to typeset -the particle which means that the \meta{definition} should be a vaild -\chemformula\ compound. Please have a look at the \chemformula\ manual for -details. The particle will obey the \option{circled} option. -\begin{example} - \NewChemParticle\positron{\chembeta+} - \NewChemParticle\photon{\chemgamma} - \RenewChemParticle\el{\chembeta-} - \positron\ \photon\ \el -\end{example} - -\section{Nomenclature, Stereo Descriptors, Latin Phrases}\label{sec:stereo} -\subsection{\acs{iupac} Names} - -Similar to the \pkg{bpchem} package \chemmacros\ provides a -command\footnote{The idea and the implementation is shamelessly borrowed from - \pkg{bpchem} by \pedersen.} to typeset \ac{iupac} names. Why is -that useful? \ac{iupac} names can get very long. So long indeed that they -span over more than two lines, especially in two-column documents. This means -they must be allowed to be broken more than one time. This is what the -following command does. +Similar to the \pkg{bpchem} package~\cite{pkg:bpchem} \chemmacros\ provides a +command\footnote{The idea and initial implementation is shamelessly borrowed + from \pkg{bpchem} by \pedersen.} to typeset \ac{iupac} names. Why is that +useful? \ac{iupac} names can get very long. So long indeed that they span +over more than two lines, especially in two-column documents. This means they +must be allowed to be broken more than one time. This is what the following +command does. \begin{commands} \command{iupac}[\marg{IUPAC name}] - Inside this command use \cs{\textbar} and \cs{-} to indicate a breaking - point or a breaking dash. Use \cs{\textasciicircum} as a shortcut for - \cs*{textsuperscript}. In fact, \sinceversion{4.6}since version~4.6 the - characters \code{\textbar} and \code{\textasciicircum} are active inside - \cs{iupac}. Using \code{\textbar} is equivalent to \cs{\textbar} and using - \code{\textasciicircum} is equivalent to \cs{\textasciicircum}. + Inside this command use \sym{\textbar} indicate a breaking point + \sym{\textasciicircum} as a shortcut for \cs*{textsuperscript}. \sym{-}, + \sym{(} and \sym{)} allow words to be broken while still allow the rest of + word to be hyphenated, likewise \sym{[} and \sym{]}. \end{commands} \begin{example} \begin{minipage}{.4\linewidth} \iupac{% - Tetra|cyclo[2.2.2.1^{1,4}]\-un|decane-2\-dodecyl\-% - 5\-(hepta|decyl|iso|dodecyl|thio|ester)% + Tetra|cyclo[2.2.2.1^{1,4}]-un|decane-2-dodecyl-% + 5-(hepta|decyl|iso|dodecyl|thio|ester)% } \end{minipage} \end{example} -The \cs{iupac} command is more of a semantic command. Most times you can -achieve (nearly) the same thing by using \cs{-} instead of \cs{\textbar}, -\code{-} instead of \cs{-} and \cs*{textsuperscript} instead of -\cs{\textasciicircum}. -There are some subtleties: \cs{-} inserts a small space before the hyphen and -removes a small space after it. The command \cs{\textbar} not only prevents -ligatures but also inserts a small space. +The \cs{iupac} command is more of a semantic command. In many cases you can +achieve (nearly) the same thing by using \cs*{-} instead of \sym{\textbar}, +and \cs*{textsuperscript} instead of \sym{\textasciicircum} without +\cs{iupac}. There are some important differences, though: +\begin{itemize} + \item The character \sym{-} inserts a small space before the hyphen and + removes a small space after it. Also usually words with hyphens are only + allowed to break at the hyphen. Inside \cs{iupac} the hyphen will not + prevent further hyphenation. The amount of inserted space can be + customized. + \item The character \sym{\textbar} not only prevents ligatures but also + inserts a small space. The amount of inserted space can be customized. + \item The characters \sym{(} and \sym{)} allow the word to be hyphenated and + don't prevent further hyphenation, likewise \sym{[} and \sym{]}. +\end{itemize} \begin{example}[side-by-side] - \huge\iupac{2,4\-Di|chlor|pentan} \par + \huge\iupac{2,4-Di|chlor|pentan} \par 2,4-Dichlorpentan \end{example} -The spaces inserted by these commands can be customized. +The spaces inserted by \sym{-} and \sym{\textbar} can be customized. \begin{options} - \keyval{hyphen-pre-space}{dim}\Module{iupac}\Default{.01em} - Set the space that is inserted before the hyphen set with \cs{-}. - \keyval{hyphen-post-space}{dim}\Module{iupac}\Default{-.03em} - Set the space that is inserted after the hyphen set with \cs{-}. - \keyval{break-space}{dim}\Module{iupac}\Default{.01em} - Set the space inserted by \cs{\textbar}. + \keyval{hyphen-pre-space}{dim}\Module{nomenclature}\Default{.01em} + Set the space that is inserted before the hyphen set with \sym{-}. + \keyval{hyphen-post-space}{dim}\Module{nomenclature}\Default{-.03em} + Set the space that is inserted after the hyphen set with \sym{-}. + \keyval{break-space}{dim}\Module{nomenclature}\Default{.01em} + Set the space inserted by \sym{\textbar}. \end{options} The command \cs{iupac} serves another purpose, too, however. Regardless of -the setting of the \option{iupac} option all the commands presented in this -section are always defined \emph{inside} \cs{iupac}. Quite a number of the -naming commands have very general names: \cs{meta}, \cs{D}, \cs{E}, \cs{L}, -\cs{R}, \cs{S}, \cs{trans} and so forth\footnote{Please read - page~\pageref{desc:one-letter-commands} before you consider using the +the setting of the \option{iupac} option (see below) all the commands +presented in this section are always defined \emph{inside} \cs{iupac}. Quite +a number of the naming commands have very general names: \cs{meta}, \cs{D}, +\cs{E}, \cs{L}, \cs{R}, \cs{S}, \cs{trans} and so forth\footnote{Please read + section~\vref{sec:one-letter-commands} before you consider using the one-letter commands}. This means they either are predefined already (\cs{L} \L) or are easily defined by another package or class (the \pkg{cool} package defines both \cs{D} and \cs{E}, for example). In order to give you control -which commands are defined in which way, there is the package option -\option{iupac}\label{desc:iupac}. It has three modes: +which commands are defined in which way, there is the option \option{iupac}: +\begin{options} + \keychoice{iupac}{auto,restricted,strict}\Module{nomenclature}\Default{auto} + Take care of how \ac{iupac} naming commands are defined. +\end{options} +It has three modes: \begin{itemize} \item \keyis{iupac}{auto}: if the commands are \emph{not} defined by any package or class you're using they are available generally, otherwise only @@ -836,7 +1009,7 @@ which commands are defined in which way, there is the package option commands can be redefined (but only in the document body). They will still be available inside \cs{iupac} then. \end{itemize} -Table~\ref{tab:iupac_modes} demonstrates the different modes. +Table~\vref{tab:iupac_modes} demonstrates the different modes. \begin{table} \centering @@ -847,24 +1020,30 @@ Table~\ref{tab:iupac_modes} demonstrates the different modes. \midrule \cs{L} & \L & \L & \iupac{\L} \\ \cs{iupac}\Marg{\cs{L}} & \iupac{\L} & \iupac{\L} & \iupac{\L} \\ - \cs{D} & \D & -- & \D \\ + \cs{D} & \D & --- & \D \\ \cs{iupac}\Marg{\cs{D}} & \iupac{\D} & \iupac{\D} & \iupac{\D} \\ \bottomrule \end{tabular} \end{table} -\subsubsection{Predefined Commands} +\subsubsection{Macros Defined (Not Only) For Usage in \cs*{iupac}} -The macros in this section are intended to make the writing of \ac{iupac} -names more convenient. +\paragraph{One-letter Macros}\label{sec:one-letter-commands} +For some of the macros explained in this section one-letter commands are +defined -- with a \latin{caveat} in mind, though: they are not actively +recommended. One-letter commands seldomly have meaningful names and often +they've also been defined by other packages. This means they make +collaboration more difficult than it needs to be and are a source for package +conflicts. \chemmacros\ solves the latter problem by only providing them +inside the argument of \cs{iupac}. The one exception \chemmacros\ makes is +the command \cs{p} (for things like \pH) which is and will remain an official +command (see section~\vref{sec:acid-base-module}). For all other one-letter +macros alternatives with more meaningful names exist. \paragraph{Greek Letters}\label{par:greek_letters} -Greek\changedversion{4.3} letters in compound names are typeset upright. For -this there are for example the packages \pkg{upgreek} and \pkg{textgreek}. If -you have loaded one of them\footnote{There are other options, see the - description of the \option{greek} option.} the following commands typeset -upright Greek letters: +Greek letters in compound names are typeset upright. Here are a few examples +for the existing macros: \begin{commands} \command{chemalpha}[\quad\chemalpha] Upright lowercase alpha @@ -875,15 +1054,15 @@ upright Greek letters: \command{chemdelta}[\quad\chemdelta] Upright lowercase alpha \end{commands} -The exist two commands for each of the twenty-four Greek letters: a lowercase -and an uppercase version (\cs{chemalpha} and \cs{chemAlpha}). Those commands -are actually provided by the \chemgreek\ package. For more details refer to -its documentation. +There exist two commands for each of the twenty-four Greek letters: a +lowercase and an uppercase version (\cs{chemalpha} and \cs{chemAlpha}). Those +commands are actually provided by the \chemgreek\ package. For more details +read section~\vref{sec:greek-module} and also refer to \chemgreek's +documentation. There are a number of one-letter commands that some people may find convenient -to use which use above mentioned commands to pint Greek letters inside -\cs{iupac}. They're listed in table~\ref{tab:iupac-greek-shortcuts}. But -please read page~\pageref{desc:one-letter-commands} first before you use them. +to use which use above mentioned commands to print Greek letters inside +\cs{iupac}. They're listed in table~\vref{tab:iupac-greek-shortcuts}. \begin{table} \centering @@ -902,46 +1081,35 @@ please read page~\pageref{desc:one-letter-commands} first before you use them. \end{tabular} \end{table} - \begin{example} - \iupac{5\chemalpha\-androstan\-3\chembeta\-ol} \par - \iupac{\chemalpha\-(tri|chloro|methyl)\-\chemomega - \-chloro|poly(1,4\-phenylene|methylene)} + \iupac{5\chemalpha-androstan-3\chembeta-ol} \par + \iupac{\chemalpha-(tri|chloro|methyl)-\chemomega + -chloro|poly(1,4-phenylene|methylene)} \end{example} \paragraph{Hetero Atoms and added Hydrogen} -Attachments to hetero atoms\changedversion{4.3} and added hydrogen atoms are -indicated by italic letters~\cite{iupac:greenbook}. \chemmacros\ defines a -few macros for the most common ones. +Attachments to hetero atoms and added hydrogen atoms are indicated by italic +letters~\cite{iupac:greenbook}. \chemmacros\ defines a few macros for the +most common ones. \begin{commands} \command{hydrogen}[\quad\iupac{\hydrogen}] - The italic H for hydrogen. (An alias for this command is \cs{H}. But - please read page~\pageref{desc:one-letter-commands} first before you use - it.) + The italic H for hydrogen. (An alias for this command is \cs{H}.) \command{oxygen}[\quad\iupac{\oxygen}] - The italic O for oxygen. (An alias for this command is \cs{O}. But - please read page~\pageref{desc:one-letter-commands} first before you use - it.) + The italic O for oxygen. (An alias for this command is \cs{O}.) \command{nitrogen}[\quad\iupac{\nitrogen}] - The italic N for nitrogen. (An alias for this command is \cs{N}. But - please read page~\pageref{desc:one-letter-commands} first before you use - it.) + The italic N for nitrogen. (An alias for this command is \cs{N}.) \command{sulfur}[\quad\iupac{\sulfur}] - The italic S for sulfur. (An alias for this command is \cs{Sf}. But - please read page~\pageref{desc:one-letter-commands} first before you use - it.) + The italic S for sulfur. (An alias for this command is \cs{Sf}.) \command{phosphorus}[\quad\iupac{\phosphorus}] - The italic P for phosphorus. (An alias for this command is \cs{P}. But - please read page~\pageref{desc:one-letter-commands} first before you use - it.) + The italic P for phosphorus. (An alias for this command is \cs{P}.) \end{commands} \begin{example}[side-by-side] - \iupac{\nitrogen\-methyl|benz|amide} + \iupac{\nitrogen-methyl|benz|amide} - \iupac{3\hydrogen\-pyrrole} + \iupac{3\hydrogen-pyrrole} - \iupac{\oxygen\-ethyl hexanethioate} + \iupac{\oxygen-ethyl hexanethioate} \end{example} \paragraph{Cahn-Ingold-Prelog}\label{par:cip} @@ -949,63 +1117,50 @@ few macros for the most common ones. \command{cip}[\marg{conf}] Typeset Cahn-Ingol-Prelog descriptors, \eg: \cs{cip}\Marg{R,S} \cip{R,S} \command{rectus}[\quad\iupac{\rectus}] - Typeset rectus descriptor. (An alias for this command is \cs{R}. But - please read page~\pageref{desc:one-letter-commands} first before you use - it.) + Typeset rectus descriptor. (An alias for this command is \cs{R}.) \command{sinister}[\quad\iupac{\sinister}] - Typeset sinister descriptor. (An alias for this command is \cs{S}. But - please read page~\pageref{desc:one-letter-commands} first before you use - it.) + Typeset sinister descriptor. (An alias for this command is \cs{S}.) \end{commands} Both these commands and the entgegen/zusammen descriptors get a small additional amount of kerning after the closing parenthesis. This amount can be changed through the following option: \begin{options} - \keyval{cip-kern}{dim}\Module{iupac}\Default{.075em} + \keyval{cip-kern}{dim}\Module{nomenclature}\Default{.075em} Set the amount of kerning after the closing parenthesis. \end{options} \paragraph{Fischer} \begin{commands} \command{dexter}[\quad\iupac{\dexter}] - Typeset dexter descriptor. (An alias for this command is \cs{D}. But - please read page~\pageref{desc:one-letter-commands} first before you use - it.) + Typeset dexter descriptor. (An alias for this command is \cs{D}.) \command{laevus}[\quad\iupac{\laevus}] - Typeset laevus descriptor. (An alias for this command is \cs{L}. But - please read page~\pageref{desc:one-letter-commands} first before you use - it.) + Typeset laevus descriptor. (An alias for this command is \cs{L}.) \end{commands} \paragraph{cis/trans, zusammen/entgegen, syn/anti \& tert} \begin{itemize} - \item[] - \cs{cis} \iupac{\cis} \quad - \cs{trans} \iupac{\trans} \quad - \cs{fac} \iupac{\fac} \quad - \cs{mer} \iupac{\mer} \quad - \cs{zusammen} \iupac{\zusammen} \quad - \cs{entgegen} \iupac{\entgegen} \quad - \cs{syn} \iupac{\syn} \quad - \cs{anti} \iupac{\anti} \quad - \cs{tert} \iupac{\tert} + \item \cs{cis} \iupac{\cis} \quad \cs{trans} \iupac{\trans} + \item \cs{fac} \iupac{\fac} \quad \cs{mer} \iupac{\mer} + \item \cs{sin} \iupac{\sin} \quad \cs{ter} \iupac{\ter} + \item \cs{zusammen} \iupac{\zusammen} \quad \cs{entgegen} \iupac{\entgegen} + \item \cs{syn} \iupac{\syn} \quad \cs{anti} \iupac{\anti} + \item \cs{tert} \iupac{\tert} \end{itemize} An alias for \cs{entgegen} is \cs{E} and an alias for \cs{zusammen} is -\cs{Z}. But please read page~\pageref{desc:one-letter-commands} first before -you use them. +\cs{Z}. \paragraph{ortho/meta/para} -\begin{itemize} - \item[] +\begin{center} \cs{ortho} \iupac{\ortho} \quad \cs{meta} \iupac{\meta} \quad \cs{para} \iupac{\para} -\end{itemize} +\end{center} -Although these commands are provided I like to cite~\cite{iupac:bluebook}: +Although these commands are provided I like to cite +\citetitle{iupac:bluebook}~\cite{iupac:bluebook}: -\begin{cnltxquote}[{\acs{iupac} Blue Book {\cite[][p.\,90]{iupac:bluebook}}}] +\begin{cnltxquote}[{\cite[][p.\,90]{iupac:bluebook}}] The letters \iupac{\ortho}, \iupac{\meta}, and \iupac{\para} have been used in place of \textit{ortho}, \textit{meta}, and \textit{para}, respectively, to designate the 1,2-, 1,3-, and 1,4- isomers of disubstituted benzene. @@ -1013,7 +1168,7 @@ Although these commands are provided I like to cite~\cite{iupac:bluebook}: names. \end{cnltxquote} -\paragraph{Absolute Configuration} (uses \TikZ) +\paragraph{Absolute Configuration} \begin{commands} \command{Rconf}[\oarg{letter}] \cs{Rconf}: \Rconf \quad \cs{Rconf}\oarg{}: \Rconf[] @@ -1021,59 +1176,66 @@ Although these commands are provided I like to cite~\cite{iupac:bluebook}: \cs{Sconf}: \Sconf \quad \cs{Sconf}\oarg{}: \Sconf[] \end{commands} -Examples:\nopagebreak -\begin{example} - \iupac{\dexter\-Wein|s\"aure} = - \iupac{\cip{2S,3S}\-Wein|s\"aure} \par - \iupac{\dexter\-($-$)\-Threose} = - \iupac{\cip{2S,3R}\-($-$)\-2,3,4\-Tri|hydroxy|butanal} \par - \iupac{\cis\-2\-Butene} = - \iupac{\zusammen\-2\-Butene}, \par - \iupac{\cip{2E,4Z}\-Hexa|diene} \par - \iupac{\meta\-Xylol} = - \iupac{1,3\-Di|methyl|benzene} -\end{example} - \paragraph{Coordination Chemistry} -\chemmacros\ provides a few commands useful with coordination chemistry: +\chemmacros\ provides a few commands useful in coordination chemistry: \begin{commands} \command{bridge}[\marg{num}\quad\bridge{3}] Denote bridging ligand connection. \command{hapto}[\marg{num}\quad\hapto{5}] Denote hapticity. \command{dento}[\marg{num}\quad\dento{2}] - \sinceversion{4.3}Denote denticity. + Denote denticity. \end{commands} \begin{example} Ferrocene = \iupac{bis(\hapto{5}cyclo|penta|dienyl)iron} \par - \iupac{tetra\-\bridge{3}iodido\-tetrakis[tri|methyl|platinum(IV)]} + \iupac{tetra-\bridge{3}iodido-tetrakis[tri|methyl|platinum(IV)]} \end{example} Two options allow customization: \begin{options} - \keychoice{bridge-number}{sub,super}\Module{iupac}\Default{sub} - Appends the number as a subscript or superscript. \ac{iupac} - recommendation is the subscript~\cite{iupac:redbook}. - \keybool{coord-use-hyphen}\Module{iupac}\Default{true} + \keychoice{bridge-number}{sub,super}\Module{nomenclature}\Default{sub} + Appends the number as a subscript or superscript, depending on the choice. + The \ac{iupac} recommendation is the subscript~\cite{iupac:redbook}. + \keybool{coord-use-hyphen}\Module{nomenclature}\Default{true} Append a hyphen to \cs{hapto}, \cs{dent} and \cs{bridge} or don't. \end{options} -\subsubsection{Own Naming Commands} +\pagebreak + +\paragraph{Examples} +\begin{example} + \iupac{\dexter-Wein|s\"aure} = + \iupac{\cip{2S,3S}-Wein|s\"aure} \par + \iupac{\dexter-($-$)-Threose} = + \iupac{\cip{2S,3R}-($-$)-2,3,4-Tri|hydroxy|butanal} \par + \iupac{\cis-2-Butene} = + \iupac{\zusammen-2-Butene}, \par + \iupac{\cip{2E,4Z}-Hexa|diene} \par + \iupac{\meta-Xylol} = + \iupac{1,3-Di|methyl|benzene} +\end{example} + +\subsubsection{Own \cs*{iupac} Macros And Shorthands} If you find any commands missing you can define them using \begin{commands} \command{NewChemIUPAC}[\marg{cs}\marg{declaration}] - \sinceversion{4.3}Define a new \ac{iupac} command that is in any case - defined inside of \cs{iupac} regardless if \meta{cs} is defined elsewhere - already. + Define a new \ac{iupac} command that is in any case defined inside of + \cs{iupac} regardless if \meta{cs} is defined elsewhere already. + \command{ProvideChemIUPAC}[\marg{cs}\marg{declaration}] + Define a new \ac{iupac} command that is in any case defined inside of + \cs{iupac} regardless if \meta{cs} is defined elsewhere already only if + the corresponding \ac{iupac} macro is not defined, yet. \command{RenewChemIUPAC}[\marg{cs}\marg{declaration}] Redefine an existing \ac{iupac} command that is in any case defined inside of \cs{iupac} regardless if \meta{cs} is defined elsewhere already. \command{DeclareChemIUPAC}[\marg{cs}\marg{declaration}] - \changedversion{4.3}Define a new \ac{iupac} command that is in any case - defined inside of \cs{iupac} regardless if \meta{cs} is defined elsewhere - already. This silently overwrites an existing \ac{iupac} definition. + Define a new \ac{iupac} command that is in any case defined inside of + \cs{iupac} regardless if \meta{cs} is defined elsewhere already. This + silently overwrites an existing \ac{iupac} macro definition. + \command{LetChemIUPAC}[\marg{cs1}\marg{cs2}] + Defines \meta{cs1} to be an alias of \meta{cs2}. \end{commands} A command defined in this way will obey the setting of the option \option{iupac}. This means any existing command is only overwritten with @@ -1082,45 +1244,65 @@ definition of an existing \ac{iupac} naming command but issue an error if the \ac{iupac} naming command already exists. \cs{DeclareChemIUPAC} \emph{will} overwrite an existing \ac{iupac} command. \begin{example} - \NewChemIUPAC\endo{\textit{endo}} - \RenewChemIUPAC\anti{\textit{anti}} - \iupac{(2\-\endo,7\-\anti)\-2\-bromo\-7\-fluoro|bicyclo[2.2.1]heptane} + \NewChemIUPAC\endo{\textsc{endo}} + \RenewChemIUPAC\anti{\textsc{anti}} + \iupac{(2-\endo,7-\anti)-2-bromo-7-fluoro|bicyclo[2.2.1]heptane} \end{example} \cs{RenewChemIUPAC} allows you to redefine the existing \ac{iupac} naming commands. \begin{example}[side-by-side] - \iupac{\meta\-Xylol} \par + \iupac{\meta-Xylol} \par \RenewChemIUPAC\meta{\textup{m}} - \iupac{\meta\-Xylol} + \iupac{\meta-Xylol} \end{example} -\subsection{Latin Phrases} +There's also a way for defining new \ac{iupac} shorthands or changing the +existing ones: +\begin{commands} + \command{NewChemIUPACShorthand}[\meta{shorthand token}\meta{control sequence}] + Defines a new \ac{iupac} shorthand. Inside \cs{iupac} it will be equal to + using \meta{control sequence}. This throws an error if \meta{shorthand + token} is already defined. + \command{RenewChemIUPACShorthand}[\meta{shorthand token}\meta{control sequence}] + Redefines an existing \ac{iupac} shorthand. This throws an error if + \meta{shorthand token} is not defined, yet. + \command{DeclareChemIUPACShorthand}[\meta{shorthand token}\meta{control sequence}] + Defines a new \ac{iupac} shorthand or redefines an existing one. + \command{ProvideChemIUPACShorthand}[\meta{shorthand token}\meta{control sequence}] + Provides a new \ac{iupac} shorthand. Does nothing if \meta{shorthand + token} is already defined. + \command{RemoveChemIUPACShorthand}[\meta{shorthand token}] + Deletes an existing \ac{iupac} shorthand. +\end{commands} + +\subsubsection{Latin Phrases} -The package \pkg{chemstyle} provides the command \cs{latin} to typeset common -latin phrases in a consistent way. \chemmacros\ defines a similar \cs{latin} -only if \pkg{chemstyle} has \emph{not} been loaded and additionally provides -these commands: -\begin{itemize} - \item[] - \cs{insitu} \insitu \quad - \cs{abinitio} \abinitio \quad - \cs{invacuo} \invacuo -\end{itemize} +The package \pkg{chemstyle}~\cite{pkg:chemstyle} provides the command +\cs{latin} to typeset common latin phrases in a consistent way. \chemmacros\ +defines a similar \cs{latin} only if \pkg{chemstyle} has \emph{not} been +loaded and additionally provides these commands: +\begin{center} + \cs{insitu} \insitu \quad + \cs{abinitio} \abinitio \quad + \cs{invacuo} \invacuo +\end{center} -If the package \pkg{chemstyle} has been loaded they are defined using +\emph{If the package \pkg{chemstyle} has been loaded they are defined using \pkg{chemstyle}'s \cs{latin} command. This means that then the appearance -depends on \pkg{chemstyle}'s option \code{abbremph}. +depends on \pkg{chemstyle}'s option \code{abbremph}.} The commands are defined through \begin{commands} \command{NewChemLatin}[\marg{cs}\marg{phrase}] - \sinceversion{4.3}Define a new latin phrase. Gives an error if \meta{cs} - already exists. + Define a new latin phrase. Gives an error if \meta{cs} already exists. \command{DeclareChemLatin}[\marg{cs}\marg{phrase}] - \changedversion{4.3}Define a new latin phrase. + Define a new latin phrase. Silently redefined existing macros. \command{RenewChemLatin}[\marg{cs}\marg{phrase}] - Redefine an existing latin phrase. + Redefine an existing latin phrase. Gives an error if \meta{cs} doesn't + exist. + \command{ProvideChemLatin}[\marg{cs}\marg{phrase}] + Define a new latin phrase only if \meta{cs} doesn't exist. \end{commands} \begin{example}[side-by-side] \NewChemLatin\ltn{latin text}\ltn @@ -1128,252 +1310,504 @@ The commands are defined through If you have \emph{not} loaded \pkg{chemstyle} you can change the appearance with this option: \begin{options} - \keyval{format}{definition}\Module{latin}\Default{\cs*{itshape}} + \keyval{format}{definition}\Module{nomenclature}\Default{\cs*{itshape}} Set the format of the latin phrases. \end{options} -\section{Units for the Usage With \pkg*{siunitx}}\label{sec:einheiten} +\subsection{The \chemmodule*{particles} Module}\label{sec:particles-module} -In chemistry some non-SI units are very common. \pkg{siunitx} provides the -command \cs*{DeclareSIUnit}\marg{command}\marg{unit} to add arbitrary units. -\chemmacros\ uses that command to provide some units. Like all \pkg{siunitx} -units they're only valid inside \cs*{SI}\marg{num}\marg{unit} and -\cs*{si}\marg{unit}. -\begin{commands} - \command{atmosphere} \si{\atmosphere} - \command{atm} \si{\atm} - \command{calory} \si{\calory} - \command{cal} \si{\cal} - \command{cmc} \si{\cmc} \par - The units \cs{cmc}, \cs{molar}, and \cs{Molar} are defined by the - package \pkg{chemstyle} as well. \chemmacros\ only defines them, if - \pkg{chemstyle} is not loaded. - \command{molar} \si{\molar} - \command{moLar} \si{\moLar} - \command{Molar} \si{\Molar} - \command{MolMass} \si{\MolMass} - \command{normal} \si{\normal} - \command{torr} \si{\torr} -\end{commands} +The \chemmodule{particles} module loads the modules \chemmodule{charges} and +\chemmodule{chemformula}. -By the way: \cs*{mmHg} \si{\mmHg} already is defined by \pkg{siunitx} and -\pkg{chemstyle}. +\subsubsection{Provided Particle Macros} +The \chemmodule{particles} defines a number of macros which can be used for +typesetting common particles in the running text. Most of them don't make +much sense in \pkg{chemformula}~\cite{pkg:chemformula}'s \cs{ch}, though, +which doesn't mean that they can't be used there, of course: +\begin{center} + \cs{el} \el\ \cs{prt} \prt\ \cs{ntr} \ntr\ \cs{Hyd} \Hyd\ \cs{Oxo} \Oxo\ + \cs{water} \water\ \cs{El} \El\ \cs{Nuc} \Nuc\ \cs{ba} \ba +\end{center} +All of these macros are defined using \pkg{chemformula}'s \cs{chcpd}. The +details are explained in section~\vref{sec:defin-own-part}. + +The macros \cs{Nuc} and \cs{ba} are special: they have an optional argument +for the following option: +\begin{options} + \keychoice{elpair}{dots,dash,false}\Module{particles}\Default{false} + Determine how the electron pair of the nucleophiles is displayed. The + electron pair is drawn using \chemformula's \cs{chlewis} macro. +\end{options} + +\begin{example}[side-by-side] + \ba[elpair=dots] \Nuc[elpair=dash] + + \chemsetup[particles]{elpair=false} + \ba\ \Nuc +\end{example} -\section{Acid/Base}\label{sec:saeure_base} +\subsubsection{Defining Own Particle Macros}\label{sec:defin-own-part} -Easy representation of \pH, \pKa \ldots\ (the command \cs{pKa} depends on the -package option \option{language}). The translations may be adapted, though, -see section~\ref{sec:languages}. +There are two sets of macros, one for defining particles and one for defining +nucleophiles. \begin{commands} - \command{pH} \pH - \command{pOH} \pOH - \command{Ka} \Ka - \command{Kb} \Kb - \command{Kw} \Kw - \command{pKa}[\oarg{num}] \cs{pKa}: \pKa, \cs{pKa}\Oarg{1}: \pKa[1] - \command{pKb}[\oarg{num}] \cs{pKb}: \pKb, \cs{pKb}\Oarg{1}: \pKb[1] - \command{p}[\marg{anything}] \eg\ \cs{p}\Marg{\cs{Kw}} \p{\Kw} + \command{NewChemParticle}[\marg{cs}\marg{formula}] + Defines a new macro \meta{cs}. \meta{formula} is any valid \chemformula\ + compound. Raises an error if \meta{cs} already exists. + \command{RenewChemParticle}[\marg{cs}\marg{formula}] + Redefines a new macro \meta{cs}. \meta{formula} is any valid \chemformula\ + compound. Raises an error if \meta{cs} doesn't exist. + \command{DeclareChemParticle}[\marg{cs}\marg{formula}] + Defines a macro \meta{cs}. \meta{formula} is any valid \chemformula\ + compound. Silently overwrites \meta{cs} if it exists. + \command{ProvideChemParticle}[\marg{cs}\marg{formula}] + Defines a new macro \meta{cs}. \meta{formula} is any valid \chemformula\ + compound. Does nothing if \meta{cs} already exists. \end{commands} +An example of usage is the definition of the existing particle macros: +\begin{sourcecode} + \NewChemParticle\el {e-} + \NewChemParticle\prt{p+} + \NewChemParticle\ntr{n^0} +\end{sourcecode} -\begin{example}[side-by-side] - \Ka \Kb \pKa \pKa[1] \pKb \pKb[1] -\end{example} +The following set defines macros like \cs{Nuc} +\begin{commands} + \command{NewChemNucleophile}[\marg{cs}\marg{formula}] + Defines a new macro \meta{cs}. \meta{formula} is any valid \chemformula\ + compound. Note that \meta{formula} will get a trailing negative charge! + Raises an error if \meta{cs} already exists. + \command{RenewChemNucleophile}[\marg{cs}\marg{formula}] + Redefines a new macro \meta{cs}. \meta{formula} is any valid \chemformula\ + compound. Note that \meta{formula} will get a trailing negative charge! + Raises an error if \meta{cs} doesn't exist. + \command{DeclareChemNucleophile}[\marg{cs}\marg{formula}] + Defines a macro \meta{cs}. \meta{formula} is any valid \chemformula\ + compound. Note that \meta{formula} will get a trailing negative charge! + Silently overwrites \meta{cs} if it exists. + \command{ProvideChemNucleophile}[\marg{cs}\marg{formula}] + Defines a new macro \meta{cs}. \meta{formula} is any valid \chemformula\ + compound. Note that \meta{formula} will get a trailing negative charge! + Does nothing if \meta{cs} already exists. +\end{commands} +An example of usage is the definition of the existing nucleophile macros: +\begin{sourcecode} + \NewChemNucleophile\Nuc{Nu} + \NewChemNucleophile\ba {ba} +\end{sourcecode} +A macro defined this way will have an optional argument for the +\option{elpair} option. -\begin{cnltxquote}[{\acs{iupac} Green Book {\cite[][p.\,103]{iupac:greenbook}}}] - The operator \p{} \textelp{} shall be printed in Roman type. -\end{cnltxquote} +\subsection{The \chemmodule*{phases} Module}\label{sec:phases-module} -There is one option which changes the style the \p{} is typeset: -\begin{options} - \keychoice{p-style}{italics,slanted,upright}\Module{acid-base}\Default{upright} - Set the style of the \p{} operator. - \keyval{K-acid}{text}\Module{acid-base}\Default{\cs*{mathrm}\Marg{a}} - The subscript to \cs{Ka} and \cs{pKa}. - \keyval{K-base}{text}\Module{acid-base}\Default{\cs*{mathrm}\Marg{b}} - The subscript to \cs{Kb} and \cs{pKb}. - \keyval{K-water}{text}\Module{acid-base}\Default{\cs*{mathrm}\Marg{w}} - The subscript to \cs{Kw}. - % \keychoice{subscript}{lowercase,uppercase}\Module{acid-base}\Default{uppercase} - % Choose\sinceversion{4.5} if the default subscript is written in lower- or - % uppercase. -\end{options} -\begin{example} - \pH, \pKa \par - \chemsetup[acid-base]{p-style=slanted} \pH, \pKa \par - \chemsetup[acid-base]{p-style=italics} \pH, \pKa -\end{example} +The \chemmodule{phases} module loads the \chemmodule{chemformula} modul. -As\changedversion{4.7} you can see the default subscripts of \cs{Kw}, \cs{Ka} -and \cs{Kb} are lowercase letters. The literature is inconclusive about if -this is the right way or if uppercase letters should be preferred. In -textbooks the uppercase variant usually seems to be used while journals seem -to prefer the lowercase variant. \chemmacros' default follows the usage -in~\cite{iupac:greenbook}. If you want to change this you have two -possibilities: +\subsubsection{Basics} +These commands are intended to indicate the phase of a compound. +\begin{center} + \cs{sld} \sld \quad \cs{lqd} \lqd \quad \cs{gas} \gas \quad \cs{aq} \aq +\end{center} \begin{example} - % this works only in the preamble: - % \DeclareTranslation{English}{K-acid}{\mathrm{A}}% use your language here - % alternative: - \chemsetup{acid-base/K-acid=\mathrm{A}}% overwrites language dependent settings - \pKa + \ch{C\sld{} + 2 H2O\lqd{} -> CO2\gas{} + 2 H2\gas}\par + To make it complete: NaCl\aq. \end{example} -\section{Oxidation Numbers, Real and Formal Charges}\label{sec:ladungen} - -\chemmacros{} distinguishes between real ($+$/$-$) and formal (\fplus/\fminus) -charge symbols, also see section~\ref{sec:options}. All commands using formal -charge symbols start with a \code{f}. +The \ac{iupac} recommendation to indicate the state of aggregation is to put +it in parentheses after the compound \cite{iupac:greenbook}. However, you +might want to put it as a subscript which is also very common. -\subsection{Ion Charges}\label{ssec:ionen} +\begin{cnltxquote}[{\citetitle{iupac:greenbook}~\cite[][p.\,54]{iupac:greenbook}}] + The \textelp{} symbols are used to represent the states of aggregation of + chemical species. The letters are appended to the formula in parentheses + and should be printed in Roman (upright) type without a full stop (period). +\end{cnltxquote} -Simple displaying of (real) charges. It is worth noting that these commands -really are relicts from a time when \chemmacros\ tried hard to be compliant -with \pkg{mhchem} and \chemformula\ didn't exist, yet. They are still provided -for backwards compatibility but \emph{my recommendation is to use} \cs{ch} -(see the documentation of the \chemformula\ package) \emph{and forget about - these commands:} -\begin{commands} - \command{pch}[\oarg{number}] - positive charge (\textbf{p}lus + \textbf{ch}arge) - \command{mch}[\oarg{number}] - negative charge (\textbf{m}inus + \textbf{ch}arge) -\end{commands} +There are two options to customize the output: +\begin{options} + \keychoice{pos}{side,sub}\Module{phases}\Default{side} + Switch the position of the phase indicator. + \keyval{space}{dim}\Module{phases}\Default{.1333em} + Change the default spacing between compound a phase indicator if + \keyis{pos}{side}. A \TeX\ dimension. +\end{options} +\begin{example} + \chemsetup[phases]{pos=sub} + \ch{C\sld{} + 2 H2O\lqd{} -> CO2\gas{} + 2 H2\gas}\par + To make it complete: NaCl\aq. +\end{example} +All those phase commands have an optional argument: \begin{example}[side-by-side] - \leavevmode - \pch, Na\pch, Ca\pch[2]\par - \leavevmode - \mch, F\mch, S\mch[2] + \ch{H2O "\lqd[\SI{5}{\celsius}]"} \end{example} -The same for formal charges: +There is also a generic phase command: \begin{commands} - \command{fpch}[\oarg{number}] - positive charge - \command{fmch}[\oarg{number}] - negative charge + \command{phase}[\marg{phase}] + If you need a phase indicator just once or twice. You can use it to + denote a phase for which there is no phase command, yet. \end{commands} -\begin{example}[side-by-side] - \leavevmode - \fpch\ \fmch\ \fpch[3] \fmch[3] +\subsubsection{Define Own Phases} +Depending on the subject of your document you might need to indicate other +states of aggregation. You can easily define them. +\begin{commands} + \command{NewChemPhase}[\marg{cs}\marg{symbol}] + Define a new phase command. See section~\vref{sec:lang-depend} for a way + to define language dependent settings. Gives an error if \meta{cs} + already exists. + \command{DeclareChemPhase}[\marg{cs}\marg{symbol}] + Define a new phase command. See section~\vref{sec:lang-depend} for a way to + define language dependent settings. Overwrites previous definitions of + \meta{cs}. + \command{RenewChemPhase}[\marg{cs}\marg{symbol}] + Redefine an existing phase command. See section~\vref{sec:lang-depend} for + a way to define language dependent settings. Gives an error if \meta{cs} + is not defined. + \command{ProvideChemPhase}[\marg{cs}\marg{symbol}] + Define a new phase command. See section~\vref{sec:lang-depend} for a way + to define language dependent settings. Does nothing if \meta{cs} is + already defined. +\end{commands} + +\begin{example} + % preamble: + \NewChemPhase\aqi{aq,$\infty$} % aqueous solution at infinite dilution + \NewChemPhase\cd {cd} % condensed phase + \NewChemPhase\lc {lc} % liquid crystal + \ch{NaOH\aqi} \ch{H2O\cd} \ch{U\phase{cr}} \ch{A\lc}\par + \chemsetup[phases]{pos=sub} + \ch{NaOH\aqi} \ch{H2O\cd} \ch{U\phase{cr}} \ch{A\lc} \end{example} -\subsection{Oxidation Numbers}\label{ssec:oxidationszahlen} +\subsubsection{Language Dependencies}\label{sec:lang-depend} +For each phase command a translation into the custom language can be defined. +If a phase is declared with \cs{NewChemPhase} no translation exists and +for every \pkg{babel} language the literal string is used that was provided +as a definition. Let's say you define the phase +\begin{sourcecode} + \NewChemPhase\liquid{l} +\end{sourcecode} +and want to add the German translation ``f\/l''. Then you could do +\begin{sourcecode} + \DeclareTranslation{German}{phase-liquid}{f\/l} +\end{sourcecode} +This way, when you use it in a German document using the appropriate +\pkg{babel} option using \cs*{liquid} would correctly translate. For this the +package \pkg{translations}~\cite{pkg:translations} is used. The \acs{id} +always is \code{phase-\meta{csname}} where \meta{csname} is the name of the +phase command you defined without leading backslash. + +See section~\vref{sec:lang-module} for predefined translations and general +language options of \chemmacros. -Typesetting oxidation numbers: +\subsection{The \chemmodule*{symbols} Module}\label{sec:symbols-module} + +The \chemmodule{symbols} module defines a few symbols chemists need now and +then. It loads the package \pkg{amstext}~\cite{pkg:amstext}. \begin{commands} - \command{ox}[\oarg{options}\Marg{\meta{number},\meta{atom}}] - Places \meta{number} above \meta{atom}; \meta{number} has to be a - (rational) number! + \command{transitionstatesymbol} + This is self-explaining: \transitionstatesymbol + \command{standardstate} + Again self-explaining: \standardstate + \command{changestate} + The uppercase delta used in \state[superscript=]{H} for example. \end{commands} -\begin{example} - \ox{+1,Na}, \ox{2,Ca}, \ox{-2,S}, \ox{-1,F} -\end{example} +\section{Internal Modules} +\subsection{The \chemmodule*{base} Module}\label{sec:base-module} -There are a number of keys, that can be used to modify the \cs{ox} command. -\begin{options} - \keybool{parse}\Module{ox}\Default{true} - When \code{false} an arbitrary entry can be used for \code{}. - \keybool{roman}\Module{ox}\Default{false} - Switches from roman to arabic numbers. - \keychoice{pos}{top,super,side}\Module{ox}\Default{top} - \code{top} places \meta{number} above \meta{atom}, \code{super} to the - upper right as superscript and \code{side} to the right and inside - brackets. - \keybool{explicit-sign}\Module{ox}\Default{false} - Shows the $+$ for positiv numbers and the $\pm$ for $0$. - \keychoice{decimal-marker}{comma,point}\Module{ox}\Default{point} - Choice for the decimal marker for formal oxidation numbers like \ox{1.2,X}. - \keychoice{align}{center,right}\Module{ox}\Default{center} - Center the oxidation number relative to the atom or right-align it. -\end{options} +The \chemmodule{base} module is the core module of \chemmacros. It defines +some tools which can (and should) be used in other modules. This means this +section is only interesting for you if you plan to write a module yourself +(see section~\vref{sec:own-modules} for details). -\begin{example}[side-by-side] - \ox[roman=false]{2,Ca} \ox{2,Ca} \\ - \ox[pos=super]{3,Fe}-Oxide \\ - \ox[pos=side]{3,Fe}-Oxide \\ - \ox[parse=false]{?,Mn} \\ - \ox[align=right]{2,Ca} -\end{example} +This module requires the packages \pkg{bm}~\cite{pkg:bm} and +\pkg{amstext}~\cite{pkg:amstext}. -The \keyis{pos}{super} variant also can be set with the shortcut \cs{ox}\sarg: -\begin{example}[side-by-side] - \ox{3,Fe} \ox*{3,Fe} -\end{example} +This module also provides \cs{chemsetup} and the option \option{modules}. -Using the \option{explicit-sign} key will always show the sign of the -oxidation number: -\begin{example} - \chemsetup[ox]{explicit-sign = true} - \ox{+1,Na}, \ox{2,Ca}, \ox{-2,S}, \ch{"\ox{0,F}" {}2} -\end{example} +It also provides a number of (expl3) macros which may be used in other +modules. In the macro descriptions below \TF\ denotes that a \code{T}, an +\code{F} and a \code{TF} variant exist. In case of an expandable conditional +(\expandablesymbol) also the predicate variant is available. +\begin{commands} + \expandable\command*{chemmacros_is_int:n}[\TF\ \marg{number} \marg{true} + \marg{false}] + Checks if \meta{number} is an integer or not. + \expandable\command*{chemmacros_if_loaded:nn}[\TF\ + \Marg{\meta{package}|\meta{class}} \marg{name} \marg{true} \marg{false}] + Checks if package (or class) \meta{name} has been loaded. Also works after + begin document. + \expandable\command*{chemmacros_if_package_loaded:n}[\TF\ \marg{name} + \marg{true} \marg{false}] + Checks if package \meta{name} has been loaded. Also works after begin + document. + \expandable\command*{chemmacros_if_class_loaded:n}[\TF\ \marg{name} + \marg{true} \marg{false}] + Checks if class \meta{name} has been loaded. Also works after begin + document. + \command*{chemmacros_leave_vmode:} + Equivalent of \cs*{leavevmode}. + \command*{chemmacros_nobreak:} + Inserts a penalty of \num{10000}. + \command*{chemmacros_allow_break:} + Inserts a penalty of \num{0}. + \command*{chemmacros_skip_nobreak:N}[ \meta{skip/length variable}] + Insert a horizontal skip while linebreak is disallowed. + \command*{chemmacros_if_is_int:n}[\TF\ \marg{input} \marg{true} \marg{false}] + Checks if \meta{input} is an integer or something else. + \command*{chemmacros_if_bold:}[\TF\ \marg{true} \marg{false}] + Checks if the current font weight is one of \chemboldchecks{or}. + \command*{chemmacros_bold:n}[ \marg{text}] + Checks if the current font weight is bold and if yes places \meta{text} in + \cs*{textbf} if in text mode or in \cs*{bm} if in math mode. If false + \meta{text} simply is placed in the input stream as is. + \command*{chemmacros_text:n}[ \marg{text}] + Ensures that \meta{text} is placed in text mode. + \command*{chemmacros_math:n}[ \marg{text}] + Ensures that \meta{text} is placed in math mode. + \command*{chemmacros_new_macroset:nnn}[ \marg{type} \marg{arg spec} + \marg{internal command call}] + A command to define a set of macros \cs*{NewChem\meta{type}}, + \cs*{RenewChem\meta{type}}, \cs*{DeclareChem\meta{type}} and + \cs*{ProvideChem\meta{type}}. \meta{arg spec} is any valid argument + specification for \pkg{xparse}'s \\ + \cs{DeclareDocumentCommand}~\cite{bnd:l3packages}. \meta{internal command + call} should be a macro which makes definitions \emph{without} error + checks, \ie, define new macros or redefine existing ones like \cs*{def} + does. This macro just should get the arguments passed on to. Have a look + at the example below. +\end{commands} +This is how the macros \cs{NewChemParticle}, \cs{RenewChemParticle}, +\cs{DeclareChemParticle} and \cs{ProvideChemParticle} were defined: +\begin{sourcecode} + \chemmacros_new_macroset:nnn {Particle} {mm} + { \chemmacros_define_particle:Nn #1 {#2} } +\end{sourcecode} -\begin{example} - Compare \ox{-1,\ch{O2^2-}} to \ch{"\ox{-1,O}" {}2^2-} -\end{example} +\subsection{The \chemmodule*{chemformula} Module}\label{sec:chemformula-module} -Sometimes one might want to use formal oxidation numbers like \num{.5} or -$\frac{1}{3}$: -\begin{example}[side-by-side] - \ox{.5,\ch{Br2}} \ch{"\ox{1/3,I}" {}3+} -\end{example} +The \chemmodule{chemformula} module loads the \pkg{chemformula} +package~\cite{pkg:chemformula} and the \pkg{amstext} +package~\cite{pkg:amstext}. It also loads the \chemmodule{charges} module. -The fraction uses the \cs*{sfrac} command of the \pkg{xfrac} package. For -this purpose the instance \code{chemmacros-ox-frac} is defined. +\subsubsection{For Users} +The \chemmodule{chemformula} module makes it possible that you can set all +\chemformula\ options via the \cs{chemsetup} command using the module +\module{chemformula}, for example: \begin{sourcecode} - \DeclareInstance{xfrac}{chemmacros-ox-frac}{text}{ - scale-factor = 1.2 , - denominator-bot-sep = -.5ex , - numerator-top-sep = -.3ex , - slash-left-kern = -.2em , - slash-right-kern = -.2em , - slash-symbol-font = lmr - } + \chemsetup[chemformula]{format=\sffamily} \end{sourcecode} -Of course you can redefine it so that it suits your needs as the output often -strongly depends on the used font. -\subsection{Partial Charges and Similar Stuff}\label{ssec:partialladungen} +\subsubsection{For Module Writers} -The next ones probably are seldomly needed but nevertheless useful: +There's only one macro for module writers: \begin{commands} - \command{delp} \delp\ (\textbf{del}ta + \textbf{p}lus) - \command{delm} \delm\ (\textbf{del}ta + \textbf{m}inus) - \command{fdelp} \fdelp - \command{fdelm} \fdelm + \command*{chemmacros_chemformula:n}[ \marg{formula}] + This is only a wrapper for \cs{chcpd}. It is recommended that module + writers use this macro (or a variant thereof) inside of \chemmacros's + macros whenever they want to display a chemical formula. Writers who + prefer traditional \LaTeXe\ programming over expl3 should use \cs{chcpd} + directly. \end{commands} -These macros for example can be used with the \cs{ox} command or with the -\pkg{chemfig} package: -\begin{example} - \chemsetup{ - option/circled = all, - ox/parse = false +\subsection{The \chemmodule*{greek} Module}\label{sec:greek-module} + +The \chemmodule{greek} module loads the \pkg{chemgreek} +package~\cite{pkg:chemgreek}. + +This module provides one option: +\begin{options} + \keyval{greek}{mapping} + A valid value is any valid \chemgreek\ \meta{mapping}. \chemmacros\ will + warn you if no mapping has been chosen or if you are using the + \code{default} or the \code{var-default} mapping because this means that + no upright Greek letters are available. +\end{options} +If you load a \chemgreek\ support package which allows an unambiguous choice +of a mapping \chemgreek\ will make this choice automatically. This means if +you say +\begin{sourcecode} + \usepackage{upgreek} + \usepackage{chemmacros} +\end{sourcecode} +then \chemmacros\ will use \pkg{upgreek}'s upright Greek letters. If you +have +\begin{sourcecode} + \usepackage{upgreek} + \usepackage{chemmacros} + \usepackage{textgreek} +\end{sourcecode} +then no unambiguous choice is possible and you should choose a mapping +yourself, for example: +\begin{sourcecode} + \usepackage{upgreek} + \usepackage{chemmacros} + \usepackage{textgreek} + \chemsetup{greek=textgreek} +\end{sourcecode} +For further details on mappings please refer to \chemgreek's manual. + +\subsection{The \chemmodule*{lang} Module}\label{sec:lang-module} + +The \chemmodule{lang} module provides language support for \chemmacros. It +loads the package \pkg{translations}~\cite{pkg:translations}. + +\subsubsection{Information For Users} + +This module defines the following option: +\begin{options} + \keychoice{language}{auto,\meta{language}}\Default{auto} + If set to \code{auto} \chemmacros\ will detect the language used by + \pkg{babel}~\cite{pkg:babel} or \pkg{ployglossia}~\cite{pkg:polyglossia} + automatically, fallback is English. Any language known to the + \pkg{translations} package is a valid value for \meta{language}. +\end{options} + +The language chosen via \option{language} is used for translation of certain +strings in different places all over \chemmacros. They are mentioned in the +places when the corresponding function of \chemmacros\ is explained. + +Translation is done with the help of the \pkg{translations} package, available +translation keys are listed in section~\vref{sec:avail-transl-keys}. + +\subsubsection{Available Translation Keys}\label{sec:avail-transl-keys} + +Table~\vref{tab:translation-keys} lists (almost) all keys which are predefined +in \chemmacros. A translation key is a key which is understood by the +\pkg{translations} package and its commands like \cs*{GetTranslation}. For +each key at least the English fallback translation is provided, for most also +the German translation is provided. For a few keys also other translations +are provided. If you find that your translation is missing you can provide it +in the preamble: +\begin{commands} + \command*{DeclareTranslation}[\marg{language}\marg{key}\marg{translation}] + Defines a translation of key \meta{key} for the language \meta{language}. + No error will be raised if a translation of \meta{key} already exists. + This command can only be used in the preamble and is defined by the + \pkg{translations} package. +\end{commands} +f you send me an email (see section~\vref{sec:sugg-bug-reports}) with the +translations for your language I'll gladly add them to the next release of +\chemmacros! + +\begin{table} + \centering + \caption{Translation keys predefined by \chemmacros.} + \label{tab:translation-keys} + \NewDocumentCommand\showtranslation{mm}{% + \SaveTranslationFor\tmp{#1}{#2}% + \code{\detokenize\expandafter{\tmp}}% } - \ch{"\ox{\delp,H}" -{} "\ox{\delm,Cl}"} \hspace*{1cm} - \chemfig{\chemabove[3pt]{\lewis{246,Br}}{\delm}-\chemabove[3pt]{H}{\delp}} -\end{example} + \NewDocumentCommand\showtranslations{m}{ + \code{#1} & + \showtranslation{fallback}{#1} & + \showtranslation{german}{#1} + } + \begin{tabular}{lll} + \toprule + \bfseries key & \bfseries fallback translation & \bfseries German \\ + \midrule + \showtranslations{scheme-name} \\ + \showtranslations{scheme-list} \\ + \showtranslations{K-acid} \\ + \showtranslations{K-base} \\ + \showtranslations{K-water} \\ + \showtranslations{phase-sld} \\ + \showtranslations{phase-lqd} \\ + \showtranslations{phase-gas} \\ + \showtranslations{phase-aq} \\ + \showtranslations{list-of-reactions} \\ + \showtranslations{reaction} \\ + \bottomrule + \end{tabular} +\end{table} + +\subsubsection{Information For Module Writers} -The following macros are useful together with \pkg{chemfig}, too. \begin{commands} - \command{scrp} \scrp\ (\textbf{scr}iptstyle + \textbf{p}lus) - \command{scrm} \scrm\ (\textbf{scr}iptstyle + \textbf{m}inus) - \command{fscrp} \fscrp - \command{fscrm} \fscrm - \command{fsscrp} \fsscrp\ (using \cs*{scriptscriptstyle}) - \command{fsscrm} \fsscrm + \expandable\command*{chemmacros_translate:n}[ \marg{translation key}] + Translates the given key to the language which is detected automatically + or given by the user. Should be used in \chemmacros's macros instead of + \pkg{translations}' \cs*{GetTranslation}. + \command*{l_chemmacros_language_tl} + A token list variable that holds the language which is used by + \cs*{chemmacros_translate:n} for translation, \emph{after begin + document}. + \command{ChemTranslate}[\marg{translation key}] + A version of \cs*{chemmacros_translate:n} for those who prefer + traditional \LaTeXe\ programming over expl3. \end{commands} -\begin{example} - \setatomsep{1.8em}\chemfig{CH_3-\chemabove{C}{\scrp}(-[6]C|H_3)-\vphantom{H_3}CH_3} - - \chemfig{\fmch{}|O-\chemabove{N}{\fscrp}(-[1]O|\fmch)-[7]O|\fmch} +\clearpage + +\part{Additional Modules}\label{part:additional-modules} + +\section{User Modules} +\subsection{The \chemmodule*{all} \emph{pseudo}-module}\label{sec:all-module} + +The \chemmodule{all} module is a pseudo module: it doesn't define any +functionality at all. It does however load all other modules. So you can say +\begin{sourcecode} + \chemsetup{ modules = all } +\end{sourcecode} +to ensure that every module is available. This \emph{will not} load personal +modules! + +\subsection{The \chemmodule*{isotopes} Module}\label{sec:isotopes-module} + +The \chemmodule{isotope} module loads the \pkg{elements} +package~\cite{pkg:elements}. This module defines one user command: +\begin{commands} + \command{isotope}[\sarg\marg{input}] + \meta{input} can either be the \emph{symbol} of an element or the + \emph{name} of an element. Be aware that \emph{the name is language + dependent}, refer to the manual of the \pkg{elements} package for + details. To be on the safe side use the element symbol. + + \meta{input} can also be comma separated list: + \cs{isotope}\Marg{\meta{nuc},\meta{symbol}}. If you leave \meta{nuc} out + then \cs{isotope} will display the most common isotope. Otherwise + \meta{nuc} will be used. If \meta{nuc} is an isotope unknown to the + \pkg{elements} package \cs{isotope} will write a warning to the log file. + + The starred variant omits the element number. +\end{commands} + +\begin{example}[side-by-side] + \isotope{C} + \isotope*{C} + \isotope{14,C} + \isotope*{14,C} +\end{example} + +As input for the element symbol you can choose any of the elements known to +the \pkg{elements} package. + +There are options which allow you to determine how the isotope is printed: +\begin{options} + \keychoice{format}{super,side}\Module{isotopes}\Default{super} + Either print the isotope number as superscript or to the right of the + element symbol. + \keyval{side-connect}{input}\Module{isotopes}\Default{-} + Determine what is printed between the element symbol and the isotope + number if \keyis{format}{side}. +\end{options} + +\begin{example}[side-by-side] + \isotope{C} + \chemsetup[isotopes]{format=side} + \isotope{C} + \chemsetup[isotopes]{side-connect=} + \isotope{C} \end{example} -\section{Reaction Mechanisms}\label{sec:mechanismen} +\subsection{The \chemmodule*{mechanisms} Module}\label{sec:mechanisms-module} + +The module \chemmodule{mechanisms} loads the package +\pkg{amstext}~\cite{pkg:amstext}. It provides one macro: \begin{commands} \command{mech}[\oarg{type}] @@ -1406,335 +1840,658 @@ The following macros are useful together with \pkg{chemfig}, too. \mech[cb] \end{commands} -\section{Redox Reactions}\label{sec:redoxreaktionen}% TODO: watch pagebreaks! - -\chemmacros\ provides two commands to visualize the transfer of electrons in -redox reactions. Both commands are using \TikZ. +\subsection{The \chemmodule*{newman} Module}\label{sec:newman-module} +The \chemmodule{newman} module provides a command for drawing Newman +projections. It loads the \chemmodule{tikz} module. \begin{commands} - \command{OX}[\Marg{\meta{name},\meta{atom}}] - Label \meta{atom} with the label \meta{name}. - \command{redox}[\Darg{\meta{name1},\meta{name2}}\oarg{tikz}\oarg{num}\marg{text}] - Connect two \meta{atom}s previously labelled with \cs{OX}. Only the first - argument \Darg{\meta{name1},\meta{name2}} is required, the others are all - optional. + \command{newman}[\oarg{options}\darg{angle}% + \Marg{\meta{1},\meta{2},\meta{3},\meta{4},\meta{5},\meta{6}}] + Create Newman projections. This command uses \TikZ\ internally. + \meta{angle} rotates the back atoms counter clockwise with respect to the + front atoms and is an optional argument. \meta{1} to \meta{6} are the + positions, the first three are the front atoms, the last three the back + atoms. \end{commands} -\cs{OX} places \meta{atom} into a node, which is named with \meta{name}. If -you have set two \cs{OX}, they can be connected with a line using \cs{redox}. -To do so the names of the two nodes that are to be connected are written in -the round braces. Since \cs{redox} draws a \code{tikzpicture} with options -\code{remember picture,overlay}, the document needs to be \emph{compiled at - least two times}. +\begin{example} + \newman{} \newman(170){} + \newman{1,2,3,4,5,6} \newman{1,2,3} \newman{,,,4,5,6} +\end{example} + +Several options allow customization: +\begin{options} + \keyval{angle}{angle}\Module{newman}\Default{0} + Default angle. + \keyval{scale}{factor}\Module{newman}\Default{1} + Scale the whole projection by factor \meta{factor}. + \keyval{ring}{tikz}\Module{newman}\Default + Customize the ring with \TikZ\ keys. + \keyval{atoms}{tikz}\Module{newman}\Default + Customize the nodes within which the atoms are set with \TikZ\ keys. + \keyval{back-atoms}{tikz}\Module{newman}\Default + Explicitly customize the nodes of the back atoms with \TikZ\ keys. +\end{options} \begin{example} - \vspace{7mm} - \OX{a,Na} $\rightarrow$ \OX{b,Na}\pch\redox(a,b){oxidation} + \chemsetup[newman]{angle=45} \newman{} + \newman[scale=.75,ring={draw=blue,fill=blue!20}]{} \end{example} -This line can be customized using \TikZ\ keys in \oarg{tikz}: \begin{example} - \vspace{7mm} - \OX{a,Na} $\rightarrow$ \OX{b,Na}\pch\redox(a,b)[->,red]{ox} + \chemsetup[newman]{atoms={draw=red,fill=red!20,inner sep=2pt,rounded corners}} + \newman{1,2,3,4,5,6} \end{example} -With the argument \oarg{num} the length of the vertical parts of the line can -be adjusted. The default length is \code{.6em}. This length is multiplied -with \meta{num}. If you use a negative value the line is placed \emph{below} -the text. \begin{example} - \vspace{7mm} - \OX{a,Na} $\rightarrow$ \OX{b,Na}\pch - \redox(a,b)[->,red]{ox} - \redox(a,b)[<-,blue][-1]{red} - \vspace{7mm} + \chemsetup[newman]{ + atoms = {draw=red,fill=red!20,inner sep=2pt,rounded corners}, + back-atoms = {draw=blue,fill=blue!20,inner sep=2pt,rounded corners} + } + \newman{1,2,3,4,5,6} \newman(170){1,2,3,4,5,6} \end{example} -The default length of the vertical lines can be customized with the option -\begin{options} - \keyval{dist}{dim}\Module{redox}\Default{.6em} - A \TeX\ dimension. -\end{options} +\subsection{The \chemmodule*{orbital} Module}\label{sec:orbital-module} +The \chemmodule{orbital} module loads the \chemmodule{tikz} module. It +provides the following command to create orbitals: +\begin{commands} + \command{orbital}[\oarg{options}\marg{type}] + Draw an orbital shape of type \meta{type}. This command uses \TikZ\ + internally. +\end{commands} + +There are the following types available for \meta{type}: +\begin{center} + \code{s} \quad + \code{p} \quad + \code{sp} \quad + \code{sp2} \quad + \code{sp3} +\end{center} \begin{example} - \vspace{7mm} - \chemsetup{redox/dist=1em} - \OX{a,Na} $\rightarrow$ \OX{b,Na}\pch\redox(a,b)[->,red]{ox} + \orbital{s} \orbital{p} \orbital{sp} \orbital{sp2} \orbital{sp3} \end{example} +Depending on the type you have different options to modify the orbitals: \begin{options} - \keyval{sep}{dim}\Module{redox}\Default{.2em} - The option can be used to change the distance between the atom and the - beginning of the line. + \keychoice{phase}{+,-}\Module{orbital}\Default{+} + changes the phase of the orbital (all types) + \keyval{scale}{factor}\Module{orbital}\Default{1} + changes the size of the orbital (all types) + \keyval{color}{color}\Module{orbital}\Default{black} + changes the color of the orbital (all types) + \keyval{angle}{angle}\Module{orbital}\Default{0} + rotates the orbitals with a p contribution counter clockwise (all types + except \code{s}) + \keybool{half}\Module{orbital}\Default{false} + displays only half an orbital (only \code{p}) \end{options} \begin{example} - \vspace{7mm} - \chemsetup{redox/sep=.5em} - \OX{a,Na} $\rightarrow$ \OX{b,Na}\pch\redox(a,b)[->,red]{ox} + \orbital{s} \orbital[phase=-]{s} + \orbital{p} \orbital[phase=-]{p} + \orbital{sp3} \orbital[phase=-]{sp3} + + \orbital[angle=0]{p} \orbital[color=red!50]{p} + \orbital[angle=135,scale=1.5]{p} \orbital[half]{p} \end{example} -Examples:\nopagebreak% TODO: watch pagebreaks! -\begin{example} - \vspace{7mm} - \ch{ - 2 "\OX{o1,Na}" + "\OX{r1,Cl}" {}2 - -> - 2 "\OX{o2,Na}" {}+ + 2 "\OX{r2,Cl}" {}- +Additionally there are two options, with which the \TikZ\ behaviour can be +changed. +\begin{options} + \keybool{overlay}\Module{orbital} + The orbital \enquote{doesn't need space}; it is displayed with the \TikZ\ + option \code{overlay}. + \keyval{opacity}{num}\Module{orbital} + The orbital becomes transparent; \meta{value} can have values between + \code{1} (fully opaque) to \code{0} (invisible). +\end{options} +\begin{example} + \vspace{7mm} + \chemsetup[orbital]{ + overlay, + p/color = black!70 + } + \setbondoffset{0pt} + \chemfig{ + ?\orbital{p} + -[,1.3]{\orbital[phase=-]{p}} + -[:30,1.1]\orbital{p} + -[:150,.9]{\orbital[phase=-]{p}} + -[4,1.3]\orbital{p} + -[:-150,1.1]{\orbital[phase=-]{p}}? } - \redox(o1,o2){\small OX: $- 2\el$} - \redox(r1,r2)[][-1]{\small RED: $+ 2\el$} \vspace{7mm} \end{example} \begin{example} \vspace{7mm} - \ch{ - 2 "\OX{o1,\ox{0,Na}}" + "\OX{r1,\ox{0,Cl}}" {}2 - -> - 2 "\OX{o2,\ox{+1,Na}}" {}+ + 2 "\OX{r2,\ox{-1,Cl}}" {}- + \setbondoffset{0pt} + \chemsetup[orbital]{ + overlay , + opacity = .75 , + p/scale = 1.6 , + s/color = blue!50 , + s/scale = 1.6 } - \redox(o1,o2){\small OX: $- 2\el$} - \redox(r1,r2)[][-1]{\small RED: $+ 2\el$} - \vspace{7mm} + \chemfig{ + \orbital{s} + -[:-20]{\orbital[scale=2]{p}} + {\orbital[half,angle=0]{p}} + {\orbital[angle=170,half]{p}} + {\orbital[angle=-150,half]{p}} + (-[:-150]\orbital{s})-\orbital{s} + } + \vspace{1cm} +\end{example} + +\subsection{The \chemmodule*{reactions} Module}\label{sec:reactions-module} +The \chemmodule{reactions} module loads the \chemmodule{chemformula} module +and the \pkg{mathtools} package~\cite{pkg:mathtools}. + +\subsubsection{Predefined Environments} + +You can use these environments for numbered\ldots +\begin{environments} + \environment{reaction} + A single reaction where \chemformula\ code is placed directly in the + environment body. A wrapper around the \env*{equation} environment. + \environment{reactions} + Several aligned reactions. A wrapper around \pkg{amsmath}'s \env*{align} + environment. +\end{environments} + +\ldots and their starred versions for unnumbered reactions. +\begin{environments} + \environment{reaction*} + A wrapper around the \env*{equation*} environment. + \environment{reactions*} + A wrapper around \pkg{amsmath}'s \env*{align*} environment. +\end{environments} + +With them you can create (un)numbered reaction equations similar to +mathematical equations. + +Theses environments use the \env*{equation}/\env*{equation*} environments or +the \env*{align}/\env*{align*} environments, respectively, to display the +reactions. + +\begin{example} + Reaction with counter: + \begin{reaction} + A -> B + \end{reaction} \end{example} \begin{example} - \vspace{14mm} - \ch{ - 2 "\OX{o1,\ox{0,Na}}" + "\OX{r1,\ox{0,Cl}}" {}2 - -> - 2 "\OX{o2,\ox{+1,Na}}" {}+ + 2 "\OX{r2,\ox{-1,Cl}}" {}- - } - \redox(o1,o2)[draw=red,->][3.33]{\small OX: $- 2\el$} - \redox(r1,r2)[draw=blue,->]{\small RED: $+ 2\el$} + Reaction without counter: + \begin{reaction*} + C -> D + \end{reaction*} \end{example} \begin{example} - \vspace{7mm} - \ch{ - 2 "\OX{o1,\ox{0,Na}}" + "\OX{r1,\ox{0,Cl}}" {}2 - -> 2 "\OX{o2,\ox{+1,Na}}" {}+ + 2 "\OX{r2,\ox{-1,Cl}}" {}- - } - \redox(o1,o2)[green,-stealth]{\small OX} - \redox(r1,r2)[purple,-stealth][-1]{\small RED} - \vspace{7mm} + Several aligned reactions with counter: + \begin{reactions} + A &-> B + C \\ + D + E &-> F + \end{reactions} +\end{example} + +\begin{example} + Several aligned reactions without counter: + \begin{reactions*} + G &-> H + I \\ + J + K &-> L + \end{reactions*} \end{example} -\section{(Standard) State, Thermodynamics}\label{sec:stand-state-therm} -\subsection{Thermodynamic Variables}\label{sec:therm-vari} +If you want to change the layout of the counter tags, you can use -The following commands use \pkg{siunitx}: \begin{commands} - \command{Enthalpy}[\oarg{options}\darg{subscript}\marg{value}] - Typeset the amount of enthalpy. - \command{Entropy}[\oarg{options}\darg{subscript}\marg{value}] - Typeset the amount of entropy. - \command{Gibbs}[\oarg{options}\darg{subscript}\marg{value}] - Typeset the amount of Gibbs enthalpy. + \command*{renewtagform}[\marg{tagname}\oarg{format}\marg{right delimiter}\marg{left + delimiter}] + Provided by the \pkg{mathtools} package. \end{commands} -Their usage is pretty much self-explaining: -\begin{example}[side-by-side] - \Enthalpy{123} \par - \Entropy{123} \par - \Gibbs{123} +\begin{example} + \renewtagform{reaction}[R \textbf]{[}{]} + \begin{reaction} + H2O + CO2 <<=> H2CO3 + \end{reaction} \end{example} -The argument \darg{subscript} adds a subscript for specification: -\cs{Enthalpy}\Darg{r}\Marg{123} \Enthalpy(r){123}. - -There are several keys to customize the commands. They do not belong to a -module and can only be used in the optional arguments of the commands. -\begin{options} - \keyval{exponent}{anything} - Choose \meta{anything} as exponent. - \keychoice{delta}{\meta{anything},false} - Disable or choose a symbol in front of the main symbol. \meta{anything} - will be placed in math mode! - \keychoice{subscript}{left,right} - Choose if the subscript is placed to the left or the right of the main - symbol. - \keyval{unit}{unit} - Set the unit of the variable. -\end{options} -The default values depend on the command. -\begin{example}[side-by-side] - \Enthalpy[unit=\kilo\joule]{-285} \par - \Gibbs[delta=false]{0} \par - \Entropy[delta=\Delta,exponent=]{56.7} -\end{example} -The unit is set corresponding to the rules of \pkg{siunitx} and depends on -its settings: -\begin{example}[side-by-side] - \Enthalpy{-1234.56e3} \par - \sisetup{ - per-mode=symbol, - exponent-product=\cdot, - output-decimal-marker={,}, - group-four-digits=true - } - \Enthalpy{-1234.56e3} +The use of \AmS math's \cs{intertext} is possible: +\begin{example} + \begin{reactions} + A + 2 B &-> 3 C + D "\label{rxn:test}" + \intertext{Some text in between aligned reactions} + 3 E + F &<=> G + 1/2 H + \end{reactions} + See reaction~\ref{rxn:test}. \end{example} -\subsubsection{Create New Variables or Redefine Existing Ones}\label{sec:create-new-variables} +% \emph{You should not use \cs{mch} and its relatives inside the \env{reaction} +% environments.} +\subsubsection{Own Reactions} +You can create new types of reactions with the command: \begin{commands} - \command{NewChemState}[\marg{name}\oarg{options}\marg{symbol}\marg{unit}] - \sinceversion{4.3}Define new corresponding commands. \meta{name} may - either be a control sequence token or a control sequence name without - leading backslash. This means that \cs{DeclareChemState}\Marg{name} and - \cs{DeclareChemState}\Marg{\cs*{name}} are equivalent. The reason for - this rather strange definition is a syntax change in \cs{DeclareChemState} - while retaining backwards compaitibility. The latter version is - recommended though and the former version may deprecate in the future. - Gives an error if \meta{name} already exists - \command{RenewChemState}[\marg{name}\oarg{options}\marg{symbol}\marg{unit}] - Redefine existing state commands. \meta{name} may either be a control - sequence token or a control sequence name without leading backslash. - \changedversion{4.2}This means that \cs{RenewChemState}\Marg{name} and - \cs{RenewChemState}\Marg{\cs*{name}} are equivalent. The reason for - this rather strange definition is a syntax change in \cs{RenewChemState} - while retaining backwards compaitibility. The latter version is - recommended though and the former version may deprecate in the future. - \command{DeclareChemState}[\marg{name}\oarg{options}\marg{symbol}\marg{unit}] - \changedversion{4.3}Like \cs{NewChemState} but gives now error if - \meta{name} already exists. + \command{NewChemReaction}[\marg{name}\oarg{number of arguments}\marg{math name}] + \meta{name} will be the name of the new chem environment. \meta{math name} is + the underlying math environment. Gives an error if \meta{name} already + exists. + \command{RenewChemReaction}[\marg{name}\oarg{number of arguments}\marg{math name}] + \meta{name} is the name of the renewed chem environment. \meta{math name} is + the underlying math environment. Gives an error if \meta{name} does not exist. + \command{DeclareChemReaction}[\marg{name}\oarg{number of arguments}\marg{math name}] + \meta{name} will be the name of the chem environment. \meta{math name} is + the underlying math environment. + \command{ProvideChemReaction}[\marg{name}\oarg{number of arguments}\marg{math name}] + \meta{name} will be the name of the new chem environment. \meta{math name} is + the underlying math environment. The new environment is only defined if + it doesn't exist, yet. \end{commands} -\begin{example} - \NewChemState\Helmholtz{A}{\kilo\joule\per\mole} - \NewChemState\ElPot[subscript-left=false,exponent=]{E}{\volt} - \Helmholtz{123.4} \par - \ElPot{-1.1} \par - \ElPot[exponent=0]($\ch{Sn}|\ch{Sn^2+}||\ch{Pb^2+}|\ch{Pb}$){0.01} -\end{example} - -The command has some keys with which the default behaviour of the new command -can be set. -\begin{options} - \keyval{exponent}{anything}\Default{\cs{standardstate}} - Set the default exponent. - \keychoice{delta}{\meta{anything},false}\Default{\cs{changestate}} - Choose the default ``delta'' symbol that is placed in front of the - main symbol. \meta{anything} will be placed in math mode! - \keybool{subscript-left}\Default{true} - Choose the default position of the sybscript. - \keyval{subscript}{anything}\Default - Choose the default subscript symbol. -\end{options} +\begin{sourcecode} + \NewChemReaction{reaction} {equation} + \NewChemReaction{reaction*} {equation*} + \NewChemReaction{reactions} {align} + \NewChemReaction{reactions*}{align*} +\end{sourcecode} -\begin{example}[side-by-side] - \RenewChemState\Enthalpy{h}{\joule} - \Enthalpy(f){12.5} -\end{example} +Let's suppose, you'd like to have the alignment behaviour of the \env{alignat} +environment for \chemformula\ reactions. You could do the following: -The existing commands have been defined like this: \begin{sourcecode} - \NewChemState\Enthalpy{H}{\kilo\joule\per\mole} - \NewChemState\Entropy[delta=false,subscript-left=false]{S} - {\joule\per\kelvin\per\mole} - \NewChemState\Gibbs{G}{\kilo\joule\per\mole} + \NewChemReaction{reactionsat}[1]{alignat} \end{sourcecode} -So -- for following thermodynamic conventions -- one could define a molar and -an absolute variable: +With this the \env{reactionsat} environment is defined. \begin{example} - \NewChemState\enthalpy[exponent=]{h}{\kilo\joule\per\mole}% molar - \RenewChemState\Enthalpy[exponent=]{H}{\kilo\joule}% absolute - \enthalpy{-12.3} \Enthalpy{-12.3} + \NewChemReaction{reactionsat}[1]{alignat} + \NewChemReaction{reactionsat*}[1]{alignat*} + \begin{reactionsat}{3} + A &-> B &&-> C &&-> D \\ + aaaaa &-> bbbbb &&-> ccccc &&-> ddddd + \end{reactionsat} + \begin{reactionsat*}{2} + A &-> B & C &-> D \\ + aaaaa &-> bbbbb &\quad{} ccccc &-> ddddd + \end{reactionsat*} \end{example} -\subsection{State}\label{ssec:state} +\subsubsection{List of Reactions} -The commands presented in section~\ref{sec:therm-vari} internally all use the -command\footnote{Please note that \marg{subscript} is an \emph{optional} - argument.} +The \chemmodule{reactions} module also provides a command to display a list of +the reactions created with the \env{reaction} environment. \begin{commands} - \command{State}[\oarg{options}\marg{symbol}\marg{subscript}] - Typeset a state variable. + \command{listofreactions} + Print a list of reactions. \end{commands} - -It can be used to write the thermodynamic state variables without value and -unit. - \begin{example} - \State{A}, \State{G}{f}, - \State[subscript-left=false]{E}{\ch{Na}}, - \State[exponent=\SI{1000}{\celsius}]{H} + \listofreactions \end{example} -Again there are some keys to customize the command: +The output of this list can be modified by two options: \begin{options} - \keyval{exponent}{anything}\Module{state} - Set the default exponent symbol. - \keybool{subscript-left}\Module{state} - Set the default subscript position. - \keychoice{delta}{\meta{anything},false}\Module{state} - Set the default ``delta'' symbol. \meta{anything} will be placed in math - mode! + \keyval{list-name}{name of the list}\Module{reaction}\Default{List of + reactions} + Let's you set the name of the list manually. The default name is language + dependent, see section~\vref{sec:lang-module}. + \keyval{list-entry}{prefix to each entry}\Module{reaction}\Default{Reaction} + Let's you set a prefix to each list entry. The default name is language + dependent, see section~\vref{sec:lang-module}. \end{options} +Instead of using the option \option{list-name} you also could redefine +\cs{reactionlistname}. -\section{Spectroscopy and Experimental Data}\label{sec:spektroskopie} -\subsection{The \cs*{NMR} Command} - -When you're trying to find out if a compound is the one you think it is often -NMR spectroscopy is used. The experimental data are typeset similar to this: -\begin{center} - \NMR(400)[CDCl3] = \num{1.59} -\end{center} -\chemmacros\ provides a command which simplifies the input (uses -\pkg{siunitx}). +The list lists all reactions with a number and disregards reactions without +number. All reaction environments without star have an optional argument +which let's you add a description (or caption) for the entry in the list. +\begin{example} + \begin{reaction}[Autoprotolyse] + 2 H2O <<=> H3O+ + OH- + \end{reaction} +\end{example} +If you use the \env{reactions} environment this will not work, though. In +this case you can use \begin{commands} - \command{NMR}[\sarg\Marg{\meta{num},\meta{element}}% - \Darg{\meta{num},\meta{unit}}\oarg{solvent}] - Typeset nuclear magnetic resonance data. + \command{AddRxnDesc}[\marg{description}] + Add a description to a reaction. \end{commands} -\emph{All} Argument are optional! Without arguments we get: -\begin{example}[side-by-side] - \NMR \par - \NMR* +\begin{example} + \begin{reactions} + "\chlewis{0.}{Cl}" + CH4 & + -> HCl + "\chlewis{180.}{C}" H3 \AddRxnDesc{first~step~of~chain} \\ + "\chlewis{180.}{C}" H3 + Cl2 & + -> CH3Cl + "\chlewis{0.}{Cl}" \AddRxnDesc{second~step~of~chain} + \end{reactions} \end{example} -The first argument specifies the kind of NMR: -\begin{example}[side-by-side] - \NMR{13,C} +\subsection{The \chemmodule*{redox} Module}\label{sec:redox-module} + +The \chemmodule{redox} module loads the modules \chemmodule{tikz} and +\chemmodule{xfrac}. It also loads the packages +\pkg{mathtools}~\cite{pkg:mathtools} and \pkg{relsize}~\cite{pkg:relsize}. + +\subsubsection{Oxidation Numbers}\label{sec:oxidation-numbers} + +Regarding the typesetting of oxidation numbers +\citetitle{iupac:greenbook}~\cite{iupac:greenbook} says the following: +\begin{cnltxquote}[{\cite[][p.\,50]{iupac:greenbook}}] + Oxidation numbers are denoted by positive or negative Roman numerals or by + zero \textelp{} + + \textit{Examples}\quad \ox{7,Mn}, \ox[pos=side]{7,manganese}, \ox{-2,O}, + \ox{0,Ni} +\end{cnltxquote} + +The following command is provided to set oxidation numbers: +\begin{commands} + \command{ox}[\sarg\oarg{options}\Marg{\meta{number},\meta{atom}}] + Places \meta{number} as right superscript to \meta{atom}; \meta{number} + has to be a (rational) number! \meta{atom} is treated as a \chemformula\ + formula, like it would be in \cs{chcpd}. +\end{commands} + +\begin{example} + \ox{+1,Na}, \ox{2,Ca}, \ox{-2,S}, \ox{-1,F} \end{example} -The second argument sets the frequency (in \si{\mega\hertz}): +There are a number of options that can be used to modify the typeset result: +\begin{options} + \keybool{parse}\Module{redox}\Default{true} + When \code{false} an arbitrary entry can be used for \code{}. + \keybool{roman}\Module{redox}\Default{false} + Switches from roman to arabic numbers. + \keychoice{pos}{top,super,side}\Module{redox}\Default{super} + \code{top} places \meta{number} above \meta{atom}, \code{super} to the + upper right as superscript and \code{side} to the right and inside + brackets. Both \code{super} and \code{side} follow \ac{iupac} + recommendation, \code{top} does not! + \keybool{explicit-sign}\Module{redox}\Default{false} + Shows the $+$ for positiv numbers and the $\pm$ for $0$. + \keychoice{decimal-marker}{comma,point}\Module{redox}\Default{point} + Choice for the decimal marker for formal oxidation numbers like \ox{1.2,X}. + \keychoice{align}{center,right}\Module{redox}\Default{center} + Center the oxidation number relative to the atom or right-align it. + \keyval{side-connect}{code}\Module{redox}\Default{\cs*{,}} + Code that is inserted between atom and oxidation number if + \keyis{pos}{side} is used. + \keyval{text-frac}{cs}\Module{redox}\Default{\cs{chemfrac}\Oarg{text}\Marg{\#1}\Marg{\#2}} + The fraction macro that is used for fractions if \keyis{pos}{side} is + used. \meta{cs} must be a macro that takes two mandatory arguments, the + first for the numerator and the second for the denominator. + \keyval{super-frac}{cs}\Module{redox}\Default{\cs{chemfrac}\Oarg{superscript}% + \Marg{\#1}\Marg{\#2}} + The fraction macro that is used for fractions if \keyis{pos}{top} or + \keyis{pos}{super} is used. \meta{cs} must be a macro that takes two + mandatory arguments, the first for the numerator and the second for the + denominator. +\end{options} + \begin{example}[side-by-side] - \NMR(400) + \ox[roman=false]{2,Ca} \ox{2,Ca} \\ + \ox[pos=top]{3,Fe}-Oxide \\ + \ox[pos=side]{3,Fe}-Oxide \\ + \ox[parse=false]{?,Mn} \\ + \ox[pos=top,align=right]{2,Ca} \end{example} -You can choose another unit: + +The \keyis{pos}{top} variant also can be set with the shortcut \cs{ox}\sarg: \begin{example}[side-by-side] - \NMR(4e8,\hertz) + \ox{3,Fe} \ox*{3,Fe} \end{example} -Please note that the setup of \pkg{siunitx} also affects this command: -\begin{example}[side-by-side] - \sisetup{exponent-product=\cdot} - \NMR(4e8,\hertz) + +Using the \option{explicit-sign} option will always show the sign of the +oxidation number: +\begin{example} + \chemsetup[redox]{explicit-sign = true} + \ox{+1,Na}, \ox{2,Ca}, \ox{-2,S}, \ch{"\ox{0,F}" {}2} \end{example} -The third argument specifies the solvent: -\begin{example}[side-by-side] - \NMR[CDCl3] +\begin{example} + \chemsetup[redox]{pos=top} + Compare \ox{-1,O2^2-} to \ch{"\ox{-1,O}" {}2^2-} \end{example} -\subsection{Short Cuts} +Sometimes one might want to use formal oxidation numbers like \num{.5} or +\chemfrac{1}{3}: +\begin{example}[side-by-side] + \chemsetup[redox]{pos=top} + \ox{.5,Br2} + \ch{"\ox{1/3,I}" {}3+} + + \chemsetup[redox]{pos=side} + \ox{1/3,I3+} +\end{example} + +The fraction is displayed with the help of the \pkg{xfrac} +package~\cite{bnd:l3packages}. For more details on how \chemmacros\ uses it +read section~\vref{sec:xfrac-module}. + +\subsubsection{Redox Reactions}\label{sec:redox-reactions} + +\chemmacros\ provides two commands to visualize the transfer of electrons in +redox reactions. Both commands are using \TikZ. +\begin{commands} + \command{OX}[\Marg{\meta{name},\meta{atom}}] + Label \meta{atom} with the label \meta{name}. + \command{redox}[\Darg{\meta{name1},\meta{name2}}\oarg{tikz}\oarg{num}\marg{text}] + Connect two \meta{atom}s previously labelled with \cs{OX}. Only the first + argument \Darg{\meta{name1},\meta{name2}} is required, the others are all + optional. +\end{commands} + +\cs{OX} places \meta{atom} into a node, which is named with \meta{name}. If +you have set two \cs{OX}, they can be connected with a line using \cs{redox}. +To do so the names of the two nodes that are to be connected are written in +the round braces. Since \cs{redox} draws a \code{tikzpicture} with options +\code{remember picture,overlay}, the document needs to be \emph{compiled at + least two times}. + +\begin{example} + \vspace{7mm} + \OX{a,Na} $\rightarrow$ \OX{b,Na}\pch\redox(a,b){oxidation} +\end{example} + +This line can be customized using \TikZ\ keys in \oarg{tikz}: +\begin{example} + \vspace{7mm} + \OX{a,Na} $\rightarrow$ \OX{b,Na}\pch\redox(a,b)[->,red]{ox} +\end{example} + +With the argument \oarg{num} the length of the vertical parts of the line can +be adjusted. The default length is \code{.6em}. This length is multiplied +with \meta{num}. If you use a negative value the line is placed \emph{below} +the text. +\begin{example} + \vspace{7mm} + \OX{a,Na} $\rightarrow$ \OX{b,Na}\pch + \redox(a,b)[->,red]{ox} + \redox(a,b)[<-,blue][-1]{red} + \vspace{7mm} +\end{example} + +The default length of the vertical lines can be customized with the option +\begin{options} + \keyval{dist}{dim}\Module{redox}\Default{.6em} + A \TeX\ dimension. +\end{options} + +\begin{example} + \vspace{7mm} + \chemsetup{redox/dist=1em} + \OX{a,Na} $\rightarrow$ \OX{b,Na}\pch\redox(a,b)[->,red]{ox} +\end{example} + +\begin{options} + \keyval{sep}{dim}\Module{redox}\Default{.2em} + The option can be used to change the distance between the atom and the + beginning of the line. +\end{options} + +\begin{example} + \vspace{7mm} + \chemsetup{redox/sep=.5em} + \OX{a,Na} $\rightarrow$ \OX{b,Na}\pch\redox(a,b)[->,red]{ox} +\end{example} + +\paragraph{Examples} +\begin{example} + \vspace{7mm} + \ch{ + 2 "\OX{o1,Na}" + "\OX{r1,Cl}" {}2 + -> + 2 "\OX{o2,Na}" {}+ + 2 "\OX{r2,Cl}" {}- + } + \redox(o1,o2){\small OX: $- 2\el$} + \redox(r1,r2)[][-1]{\small RED: $+ 2\el$} + \vspace{7mm} +\end{example} + +\begin{example} + \vspace{7mm} + \ch{ + 2 "\OX{o1,\ox*{0,Na}}" + "\OX{r1,\ox*{0,Cl}}" {}2 + -> + 2 "\OX{o2,\ox*{+1,Na}}" {}+ + 2 "\OX{r2,\ox*{-1,Cl}}" {}- + } + \redox(o1,o2){\small OX: $- 2\el$} + \redox(r1,r2)[][-1]{\small RED: $+ 2\el$} + \vspace{7mm} +\end{example} + +\begin{example} + \vspace{14mm} + \ch{ + 2 "\OX{o1,\ox*{0,Na}}" + "\OX{r1,\ox*{0,Cl}}" {}2 + -> + 2 "\OX{o2,\ox*{+1,Na}}" {}+ + 2 "\OX{r2,\ox*{-1,Cl}}" {}- + } + \redox(o1,o2)[draw=red,->][3.33]{\small OX: $- 2\el$} + \redox(r1,r2)[draw=blue,->]{\small RED: $+ 2\el$} +\end{example} + +\begin{example} + \vspace{7mm} + \ch{ + 2 "\OX{o1,\ox*{0,Na}}" + "\OX{r1,\ox*{0,Cl}}" {}2 + -> 2 "\OX{o2,\ox*{+1,Na}}" {}+ + 2 "\OX{r2,\ox*{-1,Cl}}" {}- + } + \redox(o1,o2)[green,-stealth]{\small OX} + \redox(r1,r2)[purple,-stealth][-1]{\small RED} + \vspace{7mm} +\end{example} + +\subsection{The \chemmodule*{scheme} Module}\label{sec:scheme-module} + +The \chemmodule{scheme} module defines a floating environment +\showenv{scheme}. That is, it \emph{only} defines this float if no +environment \env{scheme} exists at begin document. The module checks for +different available float defining methods, in \emph{this} order: +\begin{itemize} + \item If the current class is a \KOMAScript\ class \cs*{DeclareNewTOC} will + be used. + \item If the current class is \cls{memoir}, \cls{memoir}'s methods are used. + \item If the package \pkg{tocbasic} has been loaded \cs*{DeclareNewTOC} will + be used. + \item If the package \pkg{newfloat} has been loaded + \cs*{DeclareFloatingEnvironment} will be used. + \item If the package \pkg{float} has been loaded its method will be used. + \item If neither of the above the \enquote{manual} method is used. This + means the environment is defined the same way like \env*{figure} is + defined in the \cls*{article} class or the \cls*{book} class, depending if + \cs*{chapter} is defined or not. +\end{itemize} + +The list name and the caption name both are translated to the language +specified according to the \option{lang} option and the provided translations, +see section~\vref{sec:lang-module} for details. If you want to manually change +them then redefine these macros after begin document: +\begin{commands} + \command{listschemename} + The name of the list of schemes. + \command{schemename} + The name used in captions. +\end{commands} +The list of schemes is printed as expected with +\begin{commands} + \command{listofschemes} +\end{commands} + +\subsection{The \chemmodule*{spectroscopy} Module}\label{sec:spectroscopy-module} + +The \chemmodule{spectroscopy} module loads the \chemmodule{chemformula} module +and the \pkg{siunitx} package~\cite{pkg:siunitx}. + +\subsubsection{The \cs*{NMR} Command} + +When you're trying to find out if a compound is the one you think it is often +NMR spectroscopy is used. The experimental data are typeset similar to this: +\begin{center} + \NMR(400)[CDCl3] = \num{1.59} +\end{center} +The \chemmodule{spectroscopy} module provides a command which simplifies the +input. + +\begin{commands} + \command{NMR}[\sarg\Marg{\meta{num},\meta{element}}% + \Darg{\meta{num},\meta{unit}}\oarg{solvent}] + Typeset nuclear magnetic resonance data. \meta{num} is a valid + \pkg{siunitx} number input, \meta{unit} is a valid \pkg{siunitx} unit + input. \meta{solvent} is any valid \chemformula\ input as in \cs{chcpd}. +\end{commands} + +\emph{All} Argument are optional! Without arguments we get: +\begin{example}[side-by-side] + \NMR \par + \NMR* +\end{example} + +The first argument specifies the kind of NMR: +\begin{example}[side-by-side] + \NMR{13,C} +\end{example} + +The second argument sets the frequency (in \si{\mega\hertz}): +\begin{example}[side-by-side] + \NMR(400) +\end{example} +You can choose another unit: +\begin{example}[side-by-side] + \NMR(4e8,\hertz) +\end{example} +Please note that the setup of \pkg{siunitx} also affects this command: +\begin{example}[side-by-side] + \sisetup{exponent-product=\cdot} + \NMR(4e8,\hertz) +\end{example} + +The third argument specifies the solvent: +\begin{example}[side-by-side] + \NMR[CDCl3] +\end{example} + +\subsubsection{Short Cuts} It is possible to define short cut commands for specific nuclei. \begin{commands} \command{NewChemNMR}[\marg{cs}\Marg{\meta{num},\meta{atom}}] - \sinceversion{4.3}Define a new shortcut macro for typesetting a certain - type of magnetic resonence data. Gives an error if \meta{cs} already - exists. + Define a new shortcut macro for typesetting a certain type of magnetic + resonence data. Gives an error if \meta{cs} already exists. \command{DeclareChemNMR}[\marg{cs}\Marg{\meta{num},\meta{atom}}] - \changedversion{4.3}Define a new shortcut macro for typesetting a certain - type of magnetic resonence data. + Define a new shortcut macro for typesetting a certain type of magnetic + resonence data. Overwrites an existing macro. \command{RenewChemNMR}[\marg{cs}\Marg{\meta{num},\meta{atom}}] Redefine an existing shortcut macro for typesetting a certain type of - magnetic resonence data. + magnetic resonence data. Gives an error if \meta{cs} doesn't exist. + \command{ProvideChemNMR}[\marg{cs}\Marg{\meta{num},\meta{atom}}] + Define a new shortcut macro for typesetting a certain type of magnetic + resonence data. \meta{cs} is only defined if it doesn't exist, yet. \end{commands} This defines a command with the same arguments as \cs{NMR} \emph{except} for @@ -1746,9 +2503,10 @@ This defines a command with the same arguments as \cs{NMR} \emph{except} for \HNMR*(400) \end{example} -\subsection{An Environment to Typeset Experimental Data} +\subsubsection{An Environment to Typeset Experimental Data} -\chemmacros\ provides an environment to ease the input of experimental data. +The \chemmodule{spectroscopy} module provides an environment to ease the input +of experimental data. \begin{environments} \environment{experimental} Environment for the output of experimental data. Inside the environment @@ -1767,7 +2525,7 @@ This defines a command with the same arguments as \cs{NMR} \emph{except} for \cs{NMR}\Marg{13,C[\textasciicircum 1H]} \NMR{13,C[^1H]} \command{J}[\Darg{\meta{bonds};\meta{nuclei}}\oarg{unit}\marg{list of nums}] Coupling constant, values are input separated by \code{;} (NMR). The - argument \Darg{\meta{bonds};\meta{nuclei}} and \oarg{unit} are optional + arguments \Darg{\meta{bonds};\meta{nuclei}} and \oarg{unit} are optional and enable further specifications of the coupling. \command{\#}[\marg{num}] Number of nuclei (NMR). @@ -1787,57 +2545,54 @@ This defines a command with the same arguments as \cs{NMR} \emph{except} for \end{experimental} \end{example} -\subsection{Customization}\label{sec:experimental-customization} +\paragraph{Customization}\label{sec:experimental-customization} The output of the environment and of the NMR commands can be customized be a number of options. For historical reasons they all belong to the module \module{nmr}. \begin{options} - \keyval{unit}{unit}\Module{nmr}\Default{\cs*{mega}\cs*{hertz}} + \keyval{unit}{unit}\Module{spectroscopy}\Default{\cs*{mega}\cs*{hertz}} The used default unit. - \keychoice{nucleus}{\Marg{\meta{num},\meta{atom}}}\Module{nmr}\Default{\Marg{1,H}} + \keychoice{nucleus}{\Marg{\meta{num},\meta{atom}}}\Module{spectroscopy}\Default{\Marg{1,H}} The used default nucleus. - \keyval{connector}{code}\Default{-} - \sinceversion{4.7}Places \meta{code} between the nucleus and the method. - \keyval{method}{code}\Default{NMR} - \sinceversion{4.7}The measuring method. - \keyval{format}{commands}\Module{nmr}\Default + \keyval{connector}{code}\Module{spectroscopy}\Default{-} + Places \meta{code} between the nucleus and the method. + \keyval{method}{code}\Module{spectroscopy}\Default{NMR} + The measuring method. + \keyval{format}{commands}\Module{spectroscopy}\Default For example \cs*{bfseries}. - \keychoice{pos-number}{side,sub,super}\Module{nmr}\Default{side} - \changedversion{4.3}Position of the number next to the atom. - \keyval{coupling-symbol}{code}\Module{nmr}\Default{J} - \sinceversion{4.3}The symbol used for the coupling constant. - \keyval{coupling-unit}{unit}\Module{nmr}\Default{\cs*{hertz}} + \keychoice{pos-number}{side,sub,super}\Module{spectroscopy}\Default{side} + Position of the number next to the atom. + \keyval{coupling-symbol}{code}\Module{spectroscopy}\Default{J} + The symbol used for the coupling constant. + \keyval{coupling-unit}{unit}\Module{spectroscopy}\Default{\cs*{hertz}} A \pkg{siunitx} unit. - \keychoice{coupling-pos}{side,sub}\Module{nmr}\Default{side} - \sinceversion{4.3}Placement of the coupling nuclei next to the symbol - $J$ (or rather the symbol specified with option - \option{coupling-symbol}). - \keyval{coupling-nuclei-pre}{code}\Module{nmr}\Default{(} - \sinceversion{4.3}Code inserted before the coupling nuclei when - \keyis{coupling-pos}{side}. - \keyval{coupling-nuclei-post}{code}\Module{nmr}\Default{)} - \sinceversion{4.3}Code inserted after the coupling nuclei when - \keyis{coupling-pos}{side}. - \keyval{coupling-bonds-pre}{code}\Module{nmr}\Default - \sinceversion{4.3}Code inserted before the coupling bonds. - \keyval{coupling-bonds-post}{code}\Module{nmr}\Default{\cs*{!}} - \sinceversion{4.3}Code inserted after the coupling bonds. - \keyval{coupling-pos-cs}{cs}\Module{nmr}\Default{\cs*{@firstofone}} - \sinceversion{4.4}Set the macro that prints the number set with the - \cs{pos} macro. This needs to be a command with one mandatory argument. - \keyval{atom-number-cs}{cs}\Module{nmr}\Default{\cs*{@firstofone}} - \sinceversion{4.4}Set the macro that prints the number set with the - \cs{\#} macro. This needs to be a command with one mandatory argument. - \keybool{parse}\Module{nmr}\Default{true} + \keychoice{coupling-pos}{side,sub}\Module{spectroscopy}\Default{side} + Placement of the coupling nuclei next to the symbol $J$ (or rather the + symbol specified with option \option{coupling-symbol}). + \keyval{coupling-nuclei-pre}{code}\Module{spectroscopy}\Default{(} + Code inserted before the coupling nuclei when \keyis{coupling-pos}{side}. + \keyval{coupling-nuclei-post}{code}\Module{spectroscopy}\Default{)} + Code inserted after the coupling nuclei when \keyis{coupling-pos}{side}. + \keyval{coupling-bonds-pre}{code}\Module{spectroscopy}\Default + Code inserted before the coupling bonds. + \keyval{coupling-bonds-post}{code}\Module{spectroscopy}\Default{\cs*{!}} + Code inserted after the coupling bonds. + \keyval{coupling-pos-cs}{cs}\Module{spectroscopy}\Default{\cs*{@firstofone}} + Set the macro that prints the number set with the \cs{pos} macro. This + needs to be a command with one mandatory argument. + \keyval{atom-number-cs}{cs}\Module{spectroscopy}\Default{\cs*{@firstofone}} + Set the macro that prints the number set with the \cs{\#} macro. This + needs to be a command with one mandatory argument. + \keybool{parse}\Module{spectroscopy}\Default{true} Treat the solvent as \chemformula\ formula or not. - \keyval{delta}{tokens}\Module{nmr}\Default + \keyval{delta}{tokens}\Module{spectroscopy}\Default The \meta{tokens} are added after $\delta$. - \keybool{list}\Module{nmr}\Default{false} + \keybool{list}\Module{spectroscopy}\Default{false} The environment \env{nmr}[]{} is formatted as a list - \keyval{list-setup}{setup}\Module{nmr} + \keyval{list-setup}{setup}\Module{spectroscopy} Setup of the list. See below for the default settings. - \keybool{use-equal}\Module{nmr}\Default{false} + \keybool{use-equal}\Module{spectroscopy}\Default{false} Add egual sign after \cs{NMR} and \cs{data}. \end{options} @@ -1867,8 +2622,7 @@ can be used like \cs{data} for the NMR data. \end{experimental} \end{example} -\subsection{An Example} - +\paragraph{An Example} The code below is shown with different specifications for \meta{options}. Of course options can also be chosen with \cs{chemsetup}. @@ -1914,9 +2668,9 @@ Of course options can also be chosen with \cs{chemsetup}. \end{experimental} \end{sourcecode} -\subsubsection{Nearly Standard} - +\paragraph{Nearly Standard} Output with these options: + \begin{sourcecode} delta=(ppm),pos-number=sub,use-equal \end{sourcecode} @@ -1961,8 +2715,9 @@ Output with these options: \data*{quantum yield} $\Phi = \val{0.74+-0.1}$\,. \end{experimental} -\subsubsection{Formatted List} +\paragraph{Formatted List} Output with these options: + \begin{sourcecode} format=\bfseries,delta=(ppm),list=true,use-equal \end{sourcecode} @@ -2007,9 +2762,9 @@ Output with these options: \data*{quantum yield} $\Phi = \val{0.74+-0.1}$\,. \end{experimental} -\subsubsection{Crazy} - +\paragraph{Crazy} Output for these options: + \begin{sourcecode} format=\color{red}\itshape, list=true, @@ -2066,482 +2821,429 @@ Output for these options: \data*{quantum yield} $\Phi = \val{0.74+-0.1}$\,. \end{experimental} -\section{Reaction Environments}\label{sec:reactions} -\subsection{Defined by \chemmacros} - -You can use these environments for numbered\ldots -\begin{environments} - \environment{reaction} - A single reaction where \chemformula\ code is placed directly in the - environment body. A wrapper around the \env*{equation} environment. - \environment{reactions} - Several aligned reactions. A wrapper around \pkg{amsmath}'s \env*{align} - environment. -\end{environments} - -\ldots and their starred versions for unnumbered reactions. -\begin{environments} - \environment{reaction*} - A wrapper around the \env*{equation*} environment. - \environment{reactions*} - A wrapper around \pkg{amsmath}'s \env*{align*} environment. -\end{environments} - -With them you can create (un)numbered reaction equations similar to -mathematical equations. +\subsection{The \chemmodule*{thermodynamics} Module}\label{sec:thermodynamics-module} -Theses environments use the \env*{equation}/\env*{equation*} environments or -the \env*{align}/\env*{align*} environments, respectively, to display the -reactions. +The \chemmodule{thermodynamics} module loads the \pkg{siunitx} +package~\cite{pkg:siunitx}. -\begin{example} - Reaction with counter: - \begin{reaction} - A -> B - \end{reaction} -\end{example} +\subsubsection{The \cs*{state} Macro} -\begin{example} - Reaction without counter: - \begin{reaction*} - C -> D - \end{reaction*} -\end{example} +\begin{commands} + \command{state}[\oarg{options}\marg{symbol}] + Typeset a state variable. +\end{commands} +This macro can be used to write the thermodynamic state variables. \begin{example} - Several aligned reactions with counter: - \begin{reactions} - A &-> B + C \\ - D + E &-> F - \end{reactions} + \state{A}, \state[subscript-left=f]{G} , + \state[subscript-right=\ch{Na}]{E}, + \state[superscript-right=\SI{1000}{\celsius}]{H} \end{example} -\begin{example} - Several aligned reactions without counter: - \begin{reactions*} - G &-> H + I \\ - J + K &-> L - \end{reactions*} -\end{example} +These options are available: +\begin{options} + \keyval{pre}{text}\Module{thermodynamics}\Default{\cs{changestate}} + Code inserted before the variable. Inserted in text mode. + \keyval{post}{text}\Module{thermodynamics}\Default + Code inserted after the variable. Inserted in text mode. + \keyval{superscript-left}{text}\Module{thermodynamics}\Default + The left superscript. Inserted in text mode. + \keyval{superscript-right}{text}\Module{thermodynamics}\Default{\cs{standardstate}} + The right superscript. Inserted in text mode. + \keyval{superscript}{text}\Module{thermodynamics} + An alias of \option{superscript-right}. + \keyval{subscript-left}{text}\Module{thermodynamics}\Default + The left subscript. Inserted in text mode. + \keyval{subscript-right}{text}\Module{thermodynamics}\Default + The right subscript. Inserted in text mode. + \keyval{subscript}{text}\Module{thermodynamics} + An alias of \option{subscript-left}. +\end{options} -If you want to change the layout of the counter tags, you can use +\subsubsection{Thermodynamic Variables} -\cs{renewtagform}\marg{tagname}\oarg{format}\marg{right delimiter}\marg{left - delimiter}\footnote{Provided by the \pkg{mathtools} package}. +The \chemmodule{thermodynamics} module provides a few commands for specific +thermodynamic variables: +\begin{commands} + \command{enthalpy}[\sarg\oarg{options}\darg{subscript}\marg{value}] + Typeset the amount of enthalpy. + \command{entropy}[\sarg\oarg{options}\darg{subscript}\marg{value}] + Typeset the amount of entropy. + \command{gibbs}[\sarg\oarg{options}\darg{subscript}\marg{value}] + Typeset the amount of Gibbs enthalpy. +\end{commands} -\begin{example} - \renewtagform{reaction}[R \textbf]{[}{]} - \begin{reaction} - H2O + CO2 <<=> H2CO3 - \end{reaction} +Their usage is pretty much self-explaining: +\begin{example}[side-by-side] + \enthalpy{123} \par + \entropy{123} \par + \gibbs{123} \end{example} - -With version~3.3 referencing and the use of \AmS math's \cs{intertext} also -function properly: -\begin{example} - \begin{reactions} - A + 2 B &-> 3 C + D \label{rxn:test} - \intertext{Some text in between aligned reactions} - 3 E + F &<=> G + 1/2 H - \end{reactions} - See reaction~\ref{rxn:test}. +The argument \darg{subscript} adds a subscript for specification, \sarg\ hides +number and unit: +\begin{example}[side-by-side] + \enthalpy(r){123} \par + \enthalpy*{123} \par \end{example} -\emph{You should not use \cs{mch} and its relatives inside the \env{reaction} - environments.} - -\subsection{Own Reactions} -You can create new types of reactions with the command: -\begin{commands} - \command{NewChemReaction}[\oarg{options}\marg{name}\marg{math name}] - \sinceversion{4.3}\meta{name} will be the name of the new environment. - \meta{math name} is the underlying math environment. Gives an error if - \meta{name} already exists. - \command{DeclareChemReaction}[\oarg{options}\marg{name}\marg{math name}] - \changedversion{4.3}\meta{name} will be the name of the new environment. - \meta{math name} is the underlying math environment. - \command{RenewChemReaction}[\oarg{options}\marg{name}\marg{math name}] - \sinceversion{4.3}Renew an existing definition. -\end{commands} - -The command has two options. \begin{options} - \keybool{star} - Also create a starred variant. - \keybool{arg} - Add a mandatory argument to the defined environment. + \keyval{pre}{text}\Module{thermodynamics}\Default{\cs{changestate}} + Code inserted before the variable. Inserted in text mode. + \keyval{post}{text}\Module{thermodynamics}\Default + Code inserted after the variable. Inserted in text mode. + \keyval{superscript-left}{text}\Module{thermodynamics}\Default + The left superscript. Inserted in text mode. + \keyval{superscript-right}{text}\Module{thermodynamics}\Default{\cs{standardstate}} + The right superscript. Inserted in text mode. + \keyval{superscript}{text}\Module{thermodynamics} + An alias of \option{superscript-right}. + \keyval{subscript-left}{text}\Module{thermodynamics}\Default + The left subscript. Inserted in text mode. + \keyval{subscript-right}{text}\Module{thermodynamics}\Default + The right subscript. Inserted in text mode. + \keyval{subscript}{text}\Module{thermodynamics} + An alias of \option{subscript-left}. + \keychoice{subscript-pos}{left,right}\Module{thermodynamics}\Default{left} + Determines wether the subscript given in \darg{subscript} is placed to the + left or the right of the variable. + \keyval{symbol}{symbol}\Module{thermodynamics}\Default + The symbol of the variable. Inserted in math mode. + \keyval{unit}{unit}\Module{thermodynamics}\Default + A valid \pkg{siunitx} unit. \end{options} -There is \option{star}, which will also define a starred version of the new -environment, if the starred math environment exists. If it doesn't exist, -this will cause an error. - -Then there is \option{arg}, which is used to define an environment with a -mandatory argument. Of course this only works, if the used math environment -has a mandatory argument. -The predefined environments are defined via -\begin{sourcecode} - \NewChemReaction[star]{reaction}{equation} - \NewChemReaction[star]{reactions}{align}. -\end{sourcecode} - -Let's suppose, you'd like to have the alignment behaviour of the \env{alignat} -environment for \chemformula\ reactions. You could do the following: - -\begin{sourcecode} - \NewChemReaction[star,arg]{reactionsat}{alignat} -\end{sourcecode} - -With this the \env{reactionsat} environment is defined. -\begin{example} - \NewChemReaction[star,arg]{reactionsat}{alignat} - \begin{reactionsat}{3} - A &-> B &&-> C &&-> D \\ - aaaaa &-> bbbbb &&-> ccccc &&-> ddddd - \end{reactionsat} - \begin{reactionsat*}{2} - A &-> B & C &-> D \\ - aaaaa &-> bbbbb &\quad{} ccccc &-> ddddd - \end{reactionsat*} +The default values depend on the command. +\begin{example}[side-by-side] + \enthalpy[unit=\kilo\joule]{-285} \par + \gibbs[pre=]{0} \par + \entropy[pre=$\Delta$,superscript=]{56.7} +\end{example} +The unit is set corresponding to the rules of \pkg{siunitx} and depends on +its settings: +\begin{example}[side-by-side] + \enthalpy{-1234.56e3} \par + \sisetup{ + per-mode=symbol, + exponent-product=\cdot, + output-decimal-marker={,}, + group-four-digits=true + } + \enthalpy{-1234.56e3} \end{example} -\subsection{List of Reactions} +\subsubsection{Create New Variables or Redefine Existing Ones} -\chemmacros\ also provides a command to display a list of the reactions -created with the \env{reaction} environment. \begin{commands} - \command{listofreactions} - Print a list of reactions. + \command{NewChemState}[\marg{cs}\marg{options}] + Define new state commands like \cs{enthalpy}. Gives an error is \meta{cs} + already exists. + \command{RenewChemState}[\marg{cs}\marg{options}] + Redefine existing state commands. + \command{DeclareChemState}[\marg{cs}\marg{options}] + Like \cs{NewChemState} but gives now error if \meta{cs} already exists. + \command{ProvideChemState}[\marg{cs}\marg{options}] + Define new state commands like \cs{enthalpy}. Defines \meta{cs} only if + it is not defined, yet. \end{commands} -\begin{example} - \listofreactions -\end{example} - -The output of this list can be modified by two options: +The argument \meta{options} is a comma separated list of key/value options: \begin{options} - \keyval{list-name}{name of the list}\Module{reaction}\Default{List of - reactions} - Let's you set the name of the list manually. The default name is language - dependent, see section~\ref{sec:languages}. - \keyval{list-entry}{prefix to each entry}\Module{reaction}\Default{Reaction} - Let's you set a prefix to each list entry. The default name is language - dependent, see section~\ref{sec:languages}. + \keyval{pre}{text}\Module{thermodynamics}\Default{\cs{changestate}} + Code inserted before the variable. Inserted in text mode. + \keyval{post}{text}\Module{thermodynamics}\Default + Code inserted after the variable. Inserted in text mode. + \keyval{superscript-left}{text}\Module{thermodynamics}\Default + The left superscript. Inserted in text mode. + \keyval{superscript-right}{text}\Module{thermodynamics}\Default{\cs{standardstate}} + The right superscript. + \keyval{superscript}{text}\Module{thermodynamics} + An alias of \option{superscript-right}. + \keyval{subscript-left}{text}\Module{thermodynamics}\Default + The left subscript. Inserted in text mode. + \keyval{subscript-right}{text}\Module{thermodynamics}\Default + The right subscript. Inserted in text mode. + \keyval{subscript}{text}\Module{thermodynamics} + An alias of \option{subscript-left}. + \keychoice{subscript-pos}{left,right}\Module{thermodynamics}\Default{left} + Determines wether the subscript given in \darg{subscript} is placed to the + left or the right of the variable. + \keyval{symbol}{symbol}\Module{thermodynamics}\Default + The symbol of the variable. + \keyval{unit}{unit}\Module{thermodynamics}\Default + A valid \pkg{siunitx} unit. \end{options} -Instead of using the option \option{list-name} you also could redefine -\cs{reactionlistname}. -The list lists all reactions with a number and disregards reactions without -number. All reaction environments without star have an optional argument -which let's you add a description (or caption) for the entry in the list. \begin{example} - \begin{reaction}[Autoprotolyse] - 2 H2O <<=> H3O+ + OH- - \end{reaction} + \NewChemState\Helmholtz{ symbol=A , unit=\kilo\joule\per\mole } + \NewChemState\ElPot{ symbol=E , subscript-pos=right , superscript= , unit=\volt } + \Helmholtz{123.4} \par + \ElPot{-1.1} \par + \ElPot[superscript=0]($\ch{Sn}|\ch{Sn^2+}||\ch{Pb^2+}|\ch{Pb}$){0.01} \par + \RenewChemState\enthalpy{ symbol=h , unit=\joule} \par + \enthalpy(f){12.5} \end{example} -If you use the \env{reactions} environment this will not work, though. In -this case you can use -\begin{commands} - \command{AddRxnDesc}[\marg{description}] - Add a description to a reaction. -\end{commands} +The existing commands have been defined like this: +\begin{sourcecode} + \NewChemState \enthalpy{ symbol = H, unit = \kilo\joule\per\mole } + \NewChemState \entropy { symbol = S, unit = \joule\per\kelvin\per\mole, pre = } + \NewChemState \gibbs { symbol = G, unit = \kilo\joule\per\mole } +\end{sourcecode} +So -- for following thermodynamic conventions -- one could define a molar and +an absolute variable: \begin{example} - \begin{reactions} - Cl "\Lewis{0.,\vphantom{Cl}}" + CH4 & - -> HCl + "\Lewis{4.,\vphantom{CH}}" CH3 \AddRxnDesc{first~step~of~chain} \\ - "\Lewis{4.,\vphantom{CH}}" CH3 + Cl2 & - -> CH3Cl + Cl "\Lewis{0.,\vphantom{Cl}}" \AddRxnDesc{second~step~of~chain} - \end{reactions} + \RenewChemState\enthalpy{symbol=h,superscript=,unit=\kilo\joule\per\mole}% molar + \RenewChemState\Enthalpy{symbol=H,superscript=,unit=\kilo\joule}% absolute + \enthalpy{-12.3} \Enthalpy{-12.3} \end{example} -Note: you don't have to use the phantom commands if you haven't changed the -format of the atoms (see the documentation of the \chemformula\ package for -information on how to do this). +\subsection{The \chemmodule*{units} Module}\label{sec:units-module} -\section{Phases}\label{sec:phasen} -\subsection{Basics} +The \chemmodule{units} module loads the \pkg{siunitx} +package~\cite{pkg:siunitx}. -These commands are intended to indicate the phase of a compound. -\begin{itemize} - \item[] - \cs{sld} \sld \quad - \cs{lqd} \lqd \quad - \cs{gas} \gas \quad - \cs{aq} \aq -\end{itemize} +In chemistry some non-SI units are very common. \pkg{siunitx} provides the +command +\begin{commands} + \command*{DeclareSIUnit}[\marg{cs}\marg{unit}] + Define \meta{cs} to be a valid unit command inside \pkg{siunitx}' macros + \cs*{SI} and \cs*{si} which represents \meta{unit}. +\end{commands} +to add arbitrary units. \chemmacros\ uses that command to provide some +units. Like all \pkg{siunitx} units they're only valid inside +\cs*{SI}\marg{num}\marg{unit} and \cs*{si}\marg{unit}. +\begin{commands} + \command{atmosphere} \si{\atmosphere} + \command{atm} \si{\atm} + \command{calory} \si{\calory} + \command{cal} \si{\cal} + \command{cmc} \si{\cmc} \par + The units \cs{cmc}, \cs{molar}, and \cs{Molar} are defined by the + package \pkg{chemstyle} as well. \chemmacros\ only defines them, if + \pkg{chemstyle} is not loaded. + \command{molar} \si{\molar} + \command{moLar} \si{\moLar} + \command{Molar} \si{\Molar} + \command{MolMass} \si{\MolMass} + \command{normal} \si{\normal} + \command{torr} \si{\torr} +\end{commands} -\begin{example} - \ch{C\sld{} + 2 H2O\lqd{} -> CO2\gas{} + 2 H2\gas}\par - To make it complete: NaCl\aq. -\end{example} +By the way: \cs*{mmHg} \si{\mmHg} already is defined by \pkg{siunitx}. -The \ac{iupac} recommendation to indicate the state of aggregation is to put -it in parentheses after the compound \cite{iupac:greenbook}. However, you -might want to put it as a subscript which is also very common. +\section{Internal Modules} -\begin{cnltxquote}[{\acs{iupac} Green Book {\cite[][p.\,54]{iupac:greenbook}}}] - The \textelp{} symbols are used to represent the states of aggregation of - chemical species. The letters are appended to the formula in parentheses - and should be printed in Roman (upright) type without a full stop (period). -\end{cnltxquote} +\subsection{The \chemmodule*{tikz} Module}\label{sec:tikz-module} -There are two options to customize the output: -\begin{options} - \keychoice{pos}{side,sub}\Module{phases}\Default{side} - Switch the position of the phase indicator. - \keyval{space}{dim}\Module{phases}\Default{.1333em} - Change the default spacing between compound a phase indicator if - \keyis{pos}{side}. A \TeX\ dimension. -\end{options} -\begin{example} - \chemsetup[phases]{pos=sub} - \ch{C\sld{} + 2 H2O\lqd{} -> CO2\gas{} + 2 H2\gas}\par - To make it complete: NaCl\aq. -\end{example} +The \chemmodule{tikz} module loads the \pkg{tikz} package~\cite{pkg:pgf} and +the \TikZ\ library \code{calc}. -All those phase commands have an optional argument\sinceversion{4.7}: -\begin{example}[side-by-side] - \ch{H2O "\lqd[\SI{5}{\celsius}]"} -\end{example} +\subsubsection{For Users} +The \chemmodule{tikz} module defines a few arrow tips: +\begin{tikzcode} + \arrowtip{el} + An arrow tip: \verbcode+\tikz\draw[-el](0,0)--(1,0);+ + \tikz\draw[-el](0,0)--(1,0); + \arrowtip{left el} + An arrow tip: \verbcode+\tikz\draw[-left el](0,0)--(1,0);+ + \tikz\draw[-left el](0,0)--(1,0); + \arrowtip{right el} + An arrow tip: \verbcode+\tikz\draw[-right el](0,0)--(1,0);+ + \tikz\draw[-right el](0,0)--(1,0); +\end{tikzcode} + +\subsubsection{For Module Writers} +The \chemmodule{tikz} module provides some macros for common \TikZ\ +functions. This allows to use expl3's powerful function variants for +expansion control. -\subsection{Define Own Phases} -Depending on the subject of your document you might need to indicate other -states of aggregation. You can easily define them. \begin{commands} - \command{NewChemPhase}[\marg{cs}\oarg{german}\marg{english}] - \sinceversion{4.3}Define a new phase command. Actually the optional - argument is an artefact of an earlier implementation of the command. It - has no effect at all. See section~\ref{sec:lang-depend} for a way to - define language dependent settings. Gives an error if \meta{cs} already - exists. - \command{DeclareChemPhase}[\marg{cs}\oarg{german}\marg{english}] - Define a new phase command. Actually the optional argument is an artefact - of an earlier implementation of the command. It has no effect at all. - See section~\ref{sec:lang-depend} for a way to define language dependent - settings. - \command{RenewChemPhase}[\marg{cs}\oarg{german}\marg{english}] - Redefine an existing phase command. Actually the optional argument is an - artefact of an earlier implementation of the command. It has no effect at - all. See section~\ref{sec:lang-depend} for a way to define language - dependent settings. - \command{phase}[\marg{phase}] - If you need a phase indicator just once or twice. + \command*{c_chemmacros_other_colon_tl} + A constant tokenlist which contains a colon with category code~12 (other). + This is useful since \TikZ\ sometimes expects an other colon and in an + expl3 programming environment \code{:} has category code~11 (letter). + \command*{chemmacros_tikz_picture:nn}[ \marg{options} \marg{code}] + Defined as \verbcode+\tikzpicture[{#1}] #2 \endtikzpicture+. + \command*{chemmacros_tikz:nn}[ \marg{options} \marg{code}] + Defined as \verbcode+\tikz[{#1}]{#2}+. + \command*{chemmacros_tikz_draw:n}[ \marg{options}] + Defined as \verbcode+\draw[{#1}]+. + \command*{chemmacros_tikz_node:n}[ \marg{options}] + Defined as \verbcode+\node[{#1}]+. + \command*{chemmacros_tikz_shade:n}[ \marg{options}] + Defined as \verbcode+\shade[{#1}]+. + \command*{chemmacros_tikz_shadedraw:n}[ \marg{options}] + Defined as \verbcode+\shadedraw[{#1}]+. + \command*{chemmacros_tikz_node_in_draw:n}[ \marg{options}] + Defined as \verbcode+node[{#1}]+. \end{commands} -\cs{NewChemPhase} only defines a phase if \meta{cs} is not already used by any -other command. If it \emph{is} already used \chemmacros\ will either give an -error \cs{RenewChemPhase} \emph{only} defines a phase if \meta{cs} \emph{is} -already used and issues an error otherwise. \cs{DeclareChemPhase} does not -check if the phase command already exists but simply defines it with the new -meaning. Unlike the other declaration commands of \chemmacros\ -\cs{NewChemPhase}, \cs{RenewChemPhase} and \cs{DeclareChemPhase} \emph{can - only be used in the preamble.} - -\begin{example} - % preamble: - % \NewChemPhase{\aqi}{aq,$\infty$}% aqueous solution at infinite dilution - % \NewChemPhase{\cd}{cd}% condensed phase - % \NewChemPhase{\lc}{lc}% liquid crystal - NaOH\aqi\ \ch{H2O\cd} U\phase{cr} A\lc \par - \chemsetup[phases]{pos=sub} - NaOH\aqi\ \ch{H2O\cd} U\phase{cr} A\lc -\end{example} - -\subsection{Language Dependencies}\label{sec:lang-depend} -For each pahse command a translation into the custom language can be defined. -If a phase is declared with \cs{NewChemPhase} no translation exists and -for every \pkg{babel} languuage the literal string is used that was provided -as a definition. Let's say you define the phase -\begin{sourcecode} - \NewChemPhase\liquid{l} -\end{sourcecode} -and want to add the German translation ``f{}l''. Then you could do -\begin{sourcecode} - \DeclareTranslation{German}{phase-liquid}{f{}l} -\end{sourcecode} -This way, when you use it in a German document using the appropriate -\pkg{babel} option using \cs*{liquid} would correctly translate. For this the -package \pkg{translations} is used. The \acs{id} always is -\code{phase-\meta{csname}} where \meta{csname} is the name of the phase -command you defined without leading backslash. +% TODO -See section~\ref{sec:languages} for predefined translations. +\subsection{The \chemmodule*{xfrac} Module}\label{sec:xfrac-module} -\section{Newman Projections}\label{sec:newman} -\chemmacros\ provides a command to draw Newman projections. +The \chemmodule{xfrac} module loads the package +\pkg{xfrac}~\cite{bnd:l3packages}. For the following explanations it will be +helpful if you know about said package and how it works first. This module is +a support module that defines the macro \begin{commands} - \command{newman}[\oarg{options}\darg{angle}% - \Marg{\meta{1},\meta{2},\meta{3},\meta{4},\meta{5},\meta{6}}] - Create Newman projections. This command uses \TikZ\ internally. - \meta{angle} rotates the back atoms counter clockwise with respect to the - front atoms and is an optional argument. \meta{1} to \meta{6} are the - positions, the first three are the front atoms, the last three the back - atoms. + \command{chemfrac}[\oarg{type}\marg{numerator}\marg{denominator}] + \meta{type} can either be \code{text} or \code{superscript}. \end{commands} +This macro calls a certain instance of the \pkg{xfrac} \code{text} template, +depending on the option \meta{type} and the current font family. If used +\cs{chemfrac} looks if an instance +\begin{center} + \code{chemmacros-frac-\cs*{f@family}-\meta{type}} +\end{center} +exists. If yes this instance is used, if no the instance +\code{chemmacros-frac-default-\meta{type}} is used. The \code{default} +instances are the same as the ones for \code{cmr}. -\begin{example} - \newman{} \newman(170){} - \newman{1,2,3,4,5,6} \newman{1,2,3} \newman{,,,4,5,6} -\end{example} +\begin{table} + \centering + \newcommand*\showfrac[1]{% + \code{#1} & + \fontfamily{#1}\selectfont + \chemfrac[text]{2}{3} & + \fontfamily{#1}\selectfont + \chemfrac[superscript]{2}{3}% + } + \caption{Predefined \chemmodule{xfrac} \code{text} instances.} + \label{tab:xfrac} + \begin{tabular}{llcc} + \toprule + \bfseries font family & \bfseries text & \bfseries superscript \\ + \midrule + \showfrac{cmr} \\ + \showfrac{lmr} \\ + \showfrac{LinuxLibertineT-TLF} \\ + \showfrac{LinuxLibertineT-TOsF} \\ + \bottomrule + \end{tabular} +\end{table} -Several options allow customization: -\begin{options} - \keyval{angle}{angle}\Module{newman}\Default{0} - Default angle. - \keyval{scale}{factor}\Module{newman}\Default{1} - Scale the whole projection by factor \meta{factor}. - \keyval{ring}{tikz}\Module{newman}\Default - Customize the ring with \TikZ\ keys. - \keyval{atoms}{tikz}\Module{newman}\Default - Customize the nodes within which the atoms are set with \TikZ\ keys. - \keyval{back-atoms}{tikz}\Module{newman}\Default - Explicitly customize the nodes of the back atoms with \TikZ\ keys. -\end{options} +The \chemmodule{xfrac} module defines instances some font families, they are +listed and demonstrated in table~\vref{tab:xfrac}. The \code{superscript} +type fractions \emph{look} larger than the \code{text} types. The reason is +that the \code{superscript} types are typically used with a smaller font size. +Let's take a look at an example where both instances are used: +\begin{example}[side-by-side] + \chemsetup[redox]{pos=top} + \code{superscript}: + \ch{"\ox{1/3,I}" {}3+} -\begin{example} - \chemsetup[newman]{angle=45} \newman{} - \newman[scale=.75,ring={draw=blue,fill=blue!20}]{} -\end{example} + \chemsetup[redox]{pos=side} + \code{text}: \ox{1/3,I3+} -\begin{example} - \chemsetup[newman]{atoms={draw=red,fill=red!20,inner sep=2pt,rounded corners}} - \newman{1,2,3,4,5,6} -\end{example} + \huge + \chemsetup[redox]{pos=top} + \code{superscript}: + \ch{"\ox{1/3,I}" {}3+} -\begin{example} - \chemsetup[newman]{ - atoms = {draw=red,fill=red!20,inner sep=2pt,rounded corners}, - back-atoms = {draw=blue,fill=blue!20,inner sep=2pt,rounded corners} - } - \newman{1,2,3,4,5,6} \newman(170){1,2,3,4,5,6} + \chemsetup[redox]{pos=side} + \code{text}: \ox{1/3,I3+} \end{example} -\section{s, p, and Hybrid Orbitals}\label{sec:orbitale} +If you define instances for other families please feel free to submit them to +me (see section~\vref{sec:submitting-module}) so they can be added to the +\chemmodule{xfrac} module. -\chemmacros\ provides the following command to create orbitals: -\begin{commands} - \command{orbital}[\oarg{options}\marg{type}] - Draw an orbital shape of type \meta{type}. This command uses \TikZ\ - internally. -\end{commands} - -There are the following types available for \meta{type}: -\begin{itemize} - \item[] - \code{s} \quad - \code{p} \quad - \code{sp} \quad - \code{sp2} \quad - \code{sp3} -\end{itemize} +\appendix +\part{Appendix} +\section{Own Modules}\label{sec:own-modules} +\subsection{How To} -\begin{example} - \orbital{s} \orbital{p} \orbital{sp} \orbital{sp2} \orbital{sp3} -\end{example} +If you have additional functionality which you think might be useful as a +\chemmacros\ module then you can easily write one yourself. The module must +be a file in a path where \TeX\ can find it following a certain naming +scheme. The file for a module \chemmodule*{foo} must be named +\code{chemmacros.module.foo.code.tex}. -Depending on the type you have different options to modify the orbitals: -\begin{options} - \keychoice{phase}{\default{+},-}\Module{orbital}\Default{+} - changes the phase of the orbital (all types) - \keyval{scale}{factor}\Module{orbital}\Default{1} - changes the size of the orbital (all types) - \keyval{color}{color}\Module{orbital}\Default{black} - changes the color of the orbital (all types) - \keyval{angle}{angle}\Module{orbital}\Default{0} - rotates the orbitals with a p contribution counter clockwise (all types - except \code{s}) - \keybool{half}\Module{orbital}\Default{false} - displays only half an orbital (only \code{p}) -\end{options} +The first line in the file then should look similar to this: +\begin{sourcecode} + \ChemModule{foo}{2015/07/14 description of foo} +\end{sourcecode} +This registers module \chemmodule*{foo} which means \chemmacros\ will accept +this file as a valid module. -\begin{example} - \orbital{s} \orbital[phase=-]{s} - \orbital{p} \orbital[phase=-]{p} - \orbital{sp3} \orbital[phase=-]{sp3} - - \orbital[angle=0]{p} \orbital[color=red!50]{p} - \orbital[angle=135,scale=1.5]{p} \orbital[half]{p} -\end{example} +Since \chemmacros\ is written using expl3 \cs{ChemModule} starts an expl3 +programming environment. If you don't want that but rather want to write your +module using traditional \LaTeXe\ methods then use the starred variant: +\begin{sourcecode} + \ChemModule*{foo}{2015/07/14 description of foo} +\end{sourcecode} +In both variants \code{@} has category code~11 (letter). -Additionally there are two options, with which the \TikZ\ behaviour can be -changed. -\begin{options} - \keybool{overlay}\Module{orbital} - The orbital \enquote{doesn't need space}; it is displayed with the \TikZ\ - option \code{overlay}. - \keyval{opacity}{num}\Module{orbital} - The orbital becomes transparent; \meta{value} can have values between - \code{1} (fully opaque) to \code{0} (invisible). -\end{options} -\begin{example} - \vspace{7mm} - \chemsetup[orbital]{ - overlay, - p/color = black!70 - } - \setbondoffset{0pt} - \chemfig{ - ?\orbital{p} - -[,1.3]{\orbital[phase=-]{p}} - -[:30,1.1]\orbital{p} - -[:150,.9]{\orbital[phase=-]{p}} - -[4,1.3]\orbital{p} - -[:-150,1.1]{\orbital[phase=-]{p}}? - } - \vspace{7mm} -\end{example} +You should be aware that your module \emph{will not be loaded} with +\verbcode+\usechemmodule{all}+! The pseudo-module \chemmodule{all} contains a +manually maintained list of the modules that are loaded by it. -\begin{example} - \vspace{7mm} - \setbondoffset{0pt} - \chemsetup[orbital]{ - overlay , - opacity = .75 , - p/scale = 1.6 , - s/color = blue!50 , - s/scale = 1.6 - } - \chemfig{ - \orbital{s} - -[:-20]{\orbital[scale=2]{p}} - {\orbital[half,angle=0]{p}} - {\orbital[angle=170,half]{p}} - {\orbital[angle=-150,half]{p}} - (-[:-150]\orbital{s})-\orbital{s} +If you decide to write your module \chemmodule*{foo} using expl3 and add +options you want to be able to set using +\cs{chemsetup}\Oarg{foo}\marg{options} please make sure you define them the +following way: +\begin{sourcecode} + \keys_define:nn {chemmacros/foo} { + ... } - \vspace{1cm} -\end{example} +\end{sourcecode} +Also (especially if you consider submitting the module, see +section~\vref{sec:submitting-module}) please follow the expl3 naming +conventions for variables and functions, \ie, use \code{chemmacros} as expl3 +module name: +\begin{sourcecode} + \tl_new:N \l__chemmacros_my_internal_variable_tl + \tl_new:N \l_chemmacros_my_public_variable_tl + \cs_new:Npn \__chemmacros_my_internal_function:n #1 { ... } + \cs_new_protected:Npn \chemmacros_my_public_function:n #1 { ... } + \NewDocumentCommand \publicfunction {m} + { \chemmacros_my_public_function:n {#1} } +\end{sourcecode} +You will find more details on the naming conventions in \code{interface3.pdf} +which most likely is available on your system: +\begin{bash} + texdoc interface3 +\end{bash} -\appendix -\part{Appendix} -\addsec{Suggestions and Bug Reports} +\subsection{Submitting a Module}\label{sec:submitting-module} -Feedback on \chemmacros{} (and also on \chemformula, \chemgreek, and -\ghsystem) is highly appreciated and welcome! +If you have written a module and feel it might be useful for other users +please feel free to contact me and submit the module. I will surely take at +look at both functionality and code and if I feel that it adds value to +\chemmacros\ I will add it to the package. Requirement for this is that the +module is licensed with the \LPPL\ (v1.3 or later) and that I take over +maintenance (according to the \enquote{maintainer} status of the \lppl). -If you have suggestions for macros, missing features \etc, please don't -hesitate to contact me. If you recognize any errors, be it chemical ones, -wrong documentation and the like, I'd be grateful about a short -email\footnote{\href{mailto:contact@mychemistry.eu}{contact@mychemistry.eu}}. +Please do \emph{not} submit your module via pull request but send me the files +directly. In the best case you also have a short piece of documentation. -If you find any bugs, it would be best, if you'd send me a minimal example, -with which I can reproduce the bug. You can also submit an issue on -\url{https://github.com/cgnieder/chemmacros/} instead. +\section{Suggestions, Bug Reports, Support}\label{sec:sugg-bug-reports} -Many thanks to all the people who already provided me with feedback, -especially (in alphabetical order): +\paragraph{Support} +If you need support or help with anything regarding \chemmacros\ please use +the usual support forums +\begin{itemize} + \item \url{http://www.golatex.de/} or + \item \url{http://texwelt.de/wissen/} if you speak German, + \item \url{http://www.latex-community.org/forum/} or + \item \url{http://tex.stackexchange.com/} if you speak English +\end{itemize} +or go the \emph{dedicated support forum} \begin{itemize} - \item Peter Cao - \item Ignacio Fernández Galván for his translation of the hazard and - precautionary statements of the \ghsystem{} package into Spanish - \item Christina Lüdigk - \item Dr.~Paul King - \item Jonas Rivetti (Special thanks for his translation of the hazard and - precautionary statements of the \ghsystem{} package into Italian!) - \item Christoph Schäfer - \item Timo Stein - \item Herbert Voß + \item \url{http://www.mychemistry.eu/forums/forum/chemmacros/} \end{itemize} +where you can be sure that I will see the question. + +\paragraph{Suggestions} +If you have any suggestions on how \chemmacros\ could be improved, adding +missing features \etc, please feel free to contact me via +\email{contact@mychemistry.eu}. + +\paragraph{Bug reports} +If you find any bugs, \ie, errors (something not working as described, +conflicts with other packages, \ldots) then please go to +\url{https://github.com/cgnieder/chemmacros/issues/} and open a new issue +describing the error including a minimal working example. \end{document} -- cgit v1.2.3