summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/chemmacros
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2015-09-12 21:23:52 +0000
committerKarl Berry <karl@freefriends.org>2015-09-12 21:23:52 +0000
commitaf6faae1a8553e2c55f7980152d84d8cf4ac5a96 (patch)
treec0e8e756f5e5118331df38ec867e51d67a8d0f5d /Master/texmf-dist/doc/latex/chemmacros
parentb8a8a5629c2e03bdf95ebe04a220c4568a1dad14 (diff)
chemmacros (12sep15)
git-svn-id: svn://tug.org/texlive/trunk@38359 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/chemmacros')
-rw-r--r--Master/texmf-dist/doc/latex/chemmacros/README9
-rw-r--r--Master/texmf-dist/doc/latex/chemmacros/chemmacros_en.pdfbin842434 -> 954387 bytes
-rw-r--r--Master/texmf-dist/doc/latex/chemmacros/chemmacros_en.tex3600
3 files changed, 2157 insertions, 1452 deletions
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
--- a/Master/texmf-dist/doc/latex/chemmacros/chemmacros_en.pdf
+++ b/Master/texmf-dist/doc/latex/chemmacros/chemmacros_en.pdf
Binary files 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}
-\section{Package Options}\label{sec:options}
-\chemmacros\ has several package options. They all are used as key/value pairs
-like
+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{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 = <value1>, option2 = <value2>]{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}
-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}
+\subsubsection{Latin Phrases}
+
+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}.
+
+\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}
-By the way: \cs*{mmHg} \si{\mmHg} already is defined by \pkg{siunitx} and
-\pkg{chemstyle}.
+\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]
+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.
+
+\subsection{The \chemmodule*{phases} Module}\label{sec:phases-module}
+
+The \chemmodule{phases} module loads the \chemmodule{chemformula} modul.
+
+\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}
+ \ch{C\sld{} + 2 H2O\lqd{} -> CO2\gas{} + 2 H2\gas}\par
+ To make it complete: NaCl\aq.
\end{example}
-\begin{cnltxquote}[{\acs{iupac} Green Book {\cite[][p.\,103]{iupac:greenbook}}}]
- The operator \p{} \textelp{} shall be printed in Roman type.
+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.
+
+\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}
-There is one option which changes the style the \p{} is typeset:
+There are two options to customize the output:
\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.
+ \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}
- \pH, \pKa \par
- \chemsetup[acid-base]{p-style=slanted} \pH, \pKa \par
- \chemsetup[acid-base]{p-style=italics} \pH, \pKa
+ \chemsetup[phases]{pos=sub}
+ \ch{C\sld{} + 2 H2O\lqd{} -> CO2\gas{} + 2 H2\gas}\par
+ To make it complete: NaCl\aq.
\end{example}
-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:
+All those phase commands have an optional argument:
+\begin{example}[side-by-side]
+ \ch{H2O "\lqd[\SI{5}{\celsius}]"}
+\end{example}
+
+There is also a generic phase command:
+\begin{commands}
+ \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}
+
+\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}
- % 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
+ % 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}
-\section{Oxidation Numbers, Real and Formal Charges}\label{sec:ladungen}
+\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.
-\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}.
+See section~\vref{sec:lang-module} for predefined translations and general
+language options of \chemmacros.
-\subsection{Ion Charges}\label{ssec:ionen}
+\subsection{The \chemmodule*{symbols} Module}\label{sec:symbols-module}
-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:}
+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{pch}[\oarg{number}]
- positive charge (\textbf{p}lus + \textbf{ch}arge)
- \command{mch}[\oarg{number}]
- negative charge (\textbf{m}inus + \textbf{ch}arge)
+ \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}[side-by-side]
- \leavevmode
- \pch, Na\pch, Ca\pch[2]\par
- \leavevmode
- \mch, F\mch, S\mch[2]
-\end{example}
+\section{Internal Modules}
+\subsection{The \chemmodule*{base} Module}\label{sec:base-module}
+
+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).
+
+This module requires the packages \pkg{bm}~\cite{pkg:bm} and
+\pkg{amstext}~\cite{pkg:amstext}.
+
+This module also provides \cs{chemsetup} and the option \option{modules}.
-The same for formal charges:
+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}
- \command{fpch}[\oarg{number}]
- positive charge
- \command{fmch}[\oarg{number}]
- negative charge
+ \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}[side-by-side]
- \leavevmode
- \fpch\ \fmch\ \fpch[3] \fmch[3]
-\end{example}
+\subsection{The \chemmodule*{chemformula} Module}\label{sec:chemformula-module}
+
+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.
-\subsection{Oxidation Numbers}\label{ssec:oxidationszahlen}
+\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}
+ \chemsetup[chemformula]{format=\sffamily}
+\end{sourcecode}
+
+\subsubsection{For Module Writers}
-Typesetting oxidation numbers:
+There's only one macro for module writers:
\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*{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}
-\begin{example}
- \ox{+1,Na}, \ox{2,Ca}, \ox{-2,S}, \ox{-1,F}
-\end{example}
+\subsection{The \chemmodule*{greek} Module}\label{sec:greek-module}
+
+The \chemmodule{greek} module loads the \pkg{chemgreek}
+package~\cite{pkg:chemgreek}.
-There are a number of keys, that can be used to modify the \cs{ox} command.
+This module provides one option:
\begin{options}
- \keybool{parse}\Module{ox}\Default{true}
- When \code{false} an arbitrary entry can be used for \code{<number>}.
- \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.
+ \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.
-\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}
+\subsection{The \chemmodule*{lang} Module}\label{sec:lang-module}
-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}
+The \chemmodule{lang} module provides language support for \chemmacros. It
+loads the package \pkg{translations}~\cite{pkg:translations}.
-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}
+\subsubsection{Information For Users}
-\begin{example}
- Compare \ox{-1,\ch{O2^2-}} to \ch{"\ox{-1,O}" {}2^2-}
-\end{example}
+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}
-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 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.
-The fraction uses the \cs*{sfrac} command of the \pkg{xfrac} package. For
-this purpose the instance \code{chemmacros-ox-frac} is defined.
-\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
- }
-\end{sourcecode}
-Of course you can redefine it so that it suits your needs as the output often
-strongly depends on the used font.
+Translation is done with the help of the \pkg{translations} package, available
+translation keys are listed in section~\vref{sec:avail-transl-keys}.
-\subsection{Partial Charges and Similar Stuff}\label{ssec:partialladungen}
+\subsubsection{Available Translation Keys}\label{sec:avail-transl-keys}
-The next ones probably are seldomly needed but nevertheless useful:
+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{delp} \delp\ (\textbf{del}ta + \textbf{p}lus)
- \command{delm} \delm\ (\textbf{del}ta + \textbf{m}inus)
- \command{fdelp} \fdelp
- \command{fdelm} \fdelm
+ \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!
-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
+\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,7 +1840,440 @@ The following macros are useful together with \pkg{chemfig}, too.
\mech[cb]
\end{commands}
-\section{Redox Reactions}\label{sec:redoxreaktionen}% TODO: watch pagebreaks!
+\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{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}
+
+\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}
+ \chemsetup[newman]{angle=45} \newman{}
+ \newman[scale=.75,ring={draw=blue,fill=blue!20}]{}
+\end{example}
+
+\begin{example}
+ \chemsetup[newman]{atoms={draw=red,fill=red!20,inner sep=2pt,rounded corners}}
+ \newman{1,2,3,4,5,6}
+\end{example}
+
+\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}
+\end{example}
+
+\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}
+ \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}
+ \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}
+ \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}
+
+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}
+
+\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}
+ }
+ \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}
+ Reaction without counter:
+ \begin{reaction*}
+ C -> D
+ \end{reaction*}
+\end{example}
+
+\begin{example}
+ 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}
+
+If you want to change the layout of the counter tags, you can use
+
+\begin{commands}
+ \command*{renewtagform}[\marg{tagname}\oarg{format}\marg{right delimiter}\marg{left
+ delimiter}]
+ Provided by the \pkg{mathtools} package.
+\end{commands}
+
+\begin{example}
+ \renewtagform{reaction}[R \textbf]{[}{]}
+ \begin{reaction}
+ H2O + CO2 <<=> H2CO3
+ \end{reaction}
+\end{example}
+
+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}
+
+% \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{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{sourcecode}
+ \NewChemReaction{reaction} {equation}
+ \NewChemReaction{reaction*} {equation*}
+ \NewChemReaction{reactions} {align}
+ \NewChemReaction{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{reactionsat}[1]{alignat}
+\end{sourcecode}
+
+With this the \env{reactionsat} environment is defined.
+\begin{example}
+ \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}
+
+\subsubsection{List of Reactions}
+
+The \chemmodule{reactions} module 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.
+\end{commands}
+\begin{example}
+ \listofreactions
+\end{example}
+
+The output of this list can be modified by two 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~\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}.
+
+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{AddRxnDesc}[\marg{description}]
+ Add a description to a reaction.
+\end{commands}
+
+\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}
+
+\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}
+
+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{<number>}.
+ \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]
+ \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}
+
+The \keyis{pos}{top} variant also can be set with the shortcut \cs{ox}\sarg:
+\begin{example}[side-by-side]
+ \ox{3,Fe} \ox*{3,Fe}
+\end{example}
+
+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}
+
+\begin{example}
+ \chemsetup[redox]{pos=top}
+ Compare \ox{-1,O2^2-} to \ch{"\ox{-1,O}" {}2^2-}
+\end{example}
+
+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.
@@ -1473,7 +2340,7 @@ The default length of the vertical lines can be customized with the option
\OX{a,Na} $\rightarrow$ \OX{b,Na}\pch\redox(a,b)[->,red]{ox}
\end{example}
-Examples:\nopagebreak% TODO: watch pagebreaks!
+\paragraph{Examples}
\begin{example}
\vspace{7mm}
\ch{
@@ -1489,9 +2356,9 @@ Examples:\nopagebreak% TODO: watch pagebreaks!
\begin{example}
\vspace{7mm}
\ch{
- 2 "\OX{o1,\ox{0,Na}}" + "\OX{r1,\ox{0,Cl}}" {}2
+ 2 "\OX{o1,\ox*{0,Na}}" + "\OX{r1,\ox*{0,Cl}}" {}2
->
- 2 "\OX{o2,\ox{+1,Na}}" {}+ + 2 "\OX{r2,\ox{-1,Cl}}" {}-
+ 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$}
@@ -1501,9 +2368,9 @@ Examples:\nopagebreak% TODO: watch pagebreaks!
\begin{example}
\vspace{14mm}
\ch{
- 2 "\OX{o1,\ox{0,Na}}" + "\OX{r1,\ox{0,Cl}}" {}2
+ 2 "\OX{o1,\ox*{0,Na}}" + "\OX{r1,\ox*{0,Cl}}" {}2
->
- 2 "\OX{o2,\ox{+1,Na}}" {}+ + 2 "\OX{r2,\ox{-1,Cl}}" {}-
+ 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$}
@@ -1512,183 +2379,71 @@ Examples:\nopagebreak% TODO: watch pagebreaks!
\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}}" {}-
+ 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}
-\section{(Standard) State, Thermodynamics}\label{sec:stand-state-therm}
-\subsection{Thermodynamic Variables}\label{sec:therm-vari}
-
-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.
-\end{commands}
-
-Their usage is pretty much self-explaining:
-\begin{example}[side-by-side]
- \Enthalpy{123} \par
- \Entropy{123} \par
- \Gibbs{123}
-\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}
-\end{example}
+\subsection{The \chemmodule*{scheme} Module}\label{sec:scheme-module}
-\subsubsection{Create New Variables or Redefine Existing Ones}\label{sec:create-new-variables}
+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{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{listschemename}
+ The name of the list of schemes.
+ \command{schemename}
+ The name used in captions.
\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{example}[side-by-side]
- \RenewChemState\Enthalpy{h}{\joule}
- \Enthalpy(f){12.5}
-\end{example}
-
-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}
-\end{sourcecode}
-
-So -- for following thermodynamic conventions -- one could define a molar and
-an absolute variable:
-\begin{example}
- \NewChemState\enthalpy[exponent=]{h}{\kilo\joule\per\mole}% molar
- \RenewChemState\Enthalpy[exponent=]{H}{\kilo\joule}% absolute
- \enthalpy{-12.3} \Enthalpy{-12.3}
-\end{example}
-
-\subsection{State}\label{ssec:state}
-
-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 list of schemes is printed as expected with
\begin{commands}
- \command{State}[\oarg{options}\marg{symbol}\marg{subscript}]
- Typeset a state variable.
+ \command{listofschemes}
\end{commands}
-It can be used to write the thermodynamic state variables without value and
-unit.
+\subsection{The \chemmodule*{spectroscopy} Module}\label{sec:spectroscopy-module}
-\begin{example}
- \State{A}, \State{G}{f},
- \State[subscript-left=false]{E}{\ch{Na}},
- \State[exponent=\SI{1000}{\celsius}]{H}
-\end{example}
+The \chemmodule{spectroscopy} module loads the \chemmodule{chemformula} module
+and the \pkg{siunitx} package~\cite{pkg:siunitx}.
-Again there are some keys to customize the command:
-\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!
-\end{options}
-
-\section{Spectroscopy and Experimental Data}\label{sec:spektroskopie}
-\subsection{The \cs*{NMR} Command}
+\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}
-\chemmacros\ provides a command which simplifies the input (uses
-\pkg{siunitx}).
+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.
+ 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:
@@ -1721,20 +2476,22 @@ The third argument specifies the solvent:
\NMR[CDCl3]
\end{example}
-\subsection{Short Cuts}
+\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}[<optionen>]{} 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}
+\subsection{The \chemmodule*{thermodynamics} Module}\label{sec:thermodynamics-module}
-\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}
+The \chemmodule{thermodynamics} module loads the \pkg{siunitx}
+package~\cite{pkg:siunitx}.
-With them you can create (un)numbered reaction equations similar to
-mathematical equations.
+\subsubsection{The \cs*{state} Macro}
-Theses environments use the \env*{equation}/\env*{equation*} environments or
-the \env*{align}/\env*{align*} environments, respectively, to display the
-reactions.
+\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}
- Reaction with counter:
- \begin{reaction}
- A -> B
- \end{reaction}
+ \state{A}, \state[subscript-left=f]{G} ,
+ \state[subscript-right=\ch{Na}]{E},
+ \state[superscript-right=\SI{1000}{\celsius}]{H}
\end{example}
-\begin{example}
- Reaction without counter:
- \begin{reaction*}
- C -> D
- \end{reaction*}
-\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}
-\begin{example}
- Several aligned reactions with counter:
- \begin{reactions}
- A &-> B + C \\
- D + E &-> F
- \end{reactions}
-\end{example}
+\subsubsection{Thermodynamic Variables}
-\begin{example}
- Several aligned reactions without counter:
- \begin{reactions*}
- G &-> H + I \\
- J + K &-> L
- \end{reactions*}
-\end{example}
+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}
-If you want to change the layout of the counter tags, you can use
+Their usage is pretty much self-explaining:
+\begin{example}[side-by-side]
+ \enthalpy{123} \par
+ \entropy{123} \par
+ \gibbs{123}
+\end{example}
+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}
-\cs{renewtagform}\marg{tagname}\oarg{format}\marg{right delimiter}\marg{left
- delimiter}\footnote{Provided by the \pkg{mathtools} package}.
+\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}.
+ \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}
-\begin{example}
- \renewtagform{reaction}[R \textbf]{[}{]}
- \begin{reaction}
- H2O + CO2 <<=> H2CO3
- \end{reaction}
+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}
-
-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 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}
-\emph{You should not use \cs{mch} and its relatives inside the \env{reaction}
- environments.}
+\subsubsection{Create New Variables or Redefine Existing Ones}
-\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.
+ \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}
-
-The command has two options.
+The argument \meta{options} is a comma separated list of key/value 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.
+ \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}
-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{example}
+ \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}
+The existing commands have been defined like this:
\begin{sourcecode}
- \NewChemReaction[star,arg]{reactionsat}{alignat}
+ \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}
-With this the \env{reactionsat} environment is defined.
+So -- for following thermodynamic conventions -- one could define a molar and
+an absolute variable:
\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*}
+ \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}
-\subsection{List of Reactions}
+\subsection{The \chemmodule*{units} Module}\label{sec:units-module}
-\chemmacros\ also provides a command to display a list of the reactions
-created with the \env{reaction} environment.
+The \chemmodule{units} module loads the \pkg{siunitx}
+package~\cite{pkg:siunitx}.
+
+In chemistry some non-SI units are very common. \pkg{siunitx} provides the
+command
\begin{commands}
- \command{listofreactions}
- Print a list of reactions.
+ \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}
-\begin{example}
- \listofreactions
-\end{example}
-
-The output of this list can be modified by two 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}.
-\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}
-\end{example}
-
-If you use the \env{reactions} environment this will not work, though. In
-this case you can use
+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{AddRxnDesc}[\marg{description}]
- Add a description to a reaction.
+ \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}
- \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}
-\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).
+By the way: \cs*{mmHg} \si{\mmHg} already is defined by \pkg{siunitx}.
-\section{Phases}\label{sec:phasen}
-\subsection{Basics}
+\section{Internal Modules}
-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}
+\subsection{The \chemmodule*{tikz} Module}\label{sec:tikz-module}
-\begin{example}
- \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}.
-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.
+\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}
-\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}
+\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.
-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\sinceversion{4.7}:
-\begin{example}[side-by-side]
- \ch{H2O "\lqd[\SI{5}{\celsius}]"}
-\end{example}
-
-\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.}
+% TODO
-\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{The \chemmodule*{xfrac} Module}\label{sec:xfrac-module}
-\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.
-
-See section~\ref{sec:languages} for predefined translations.
-
-\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}
-
-\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}
+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.
-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}