diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/chemmacros/chemformula_en.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/chemmacros/chemformula_en.tex | 1377 |
1 files changed, 1377 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/chemmacros/chemformula_en.tex b/Master/texmf-dist/doc/latex/chemmacros/chemformula_en.tex new file mode 100644 index 00000000000..fe4a075664b --- /dev/null +++ b/Master/texmf-dist/doc/latex/chemmacros/chemformula_en.tex @@ -0,0 +1,1377 @@ +% arara: xelatex +% !arara: biber +% !arara: xelatex +% !arara: xelatex +\documentclass[DIV11,toc=index,toc=bib]{cnpkgdoc} +\docsetup{ + pkg = {[greek=newtx]chemmacros}, + language = en, + title = the \Chemmacros\ bundle, + subtitle = { + packages \Chemmacros\ (v\csname chemmacros@version\endcsname), + \Chemformula\ (v\csname chemformula@version\endcsname), + \Ghsystem\ (v\csname ghsystem@version\endcsname) and + \Chemgreek\ (v\csname chemgreek@version\endcsname)\\[2ex] + {\Large documentation for the \Chemformula\ package}}, + modules = true, + code-box = {skipabove=1ex,skipbelow=1ex}, + label = {}, + name = chemformula, + url = https://bitbucket.org/cgnieder/chemmacros/ +} + +\usepackage{chemfig,booktabs,cancel} +\usepackage[version=3]{mhchem} +\usepackage{fontspec} +\usepackage[oldstyle,proportional]{libertine} +\usepackage[libertine]{newtxmath} +\usepackage{libertinehologopatch} +\setmonofont[Scale=MatchLowercase]{Bitstream Vera Sans Mono} + +\cnpkgusecolorscheme{friendly} +\renewcommand*\othersectionlevelsformat[3]{% + \textcolor{main}{#3\autodot}\enskip} +\renewcommand*\partformat{% + \textcolor{main}{\partname~\thepart\autodot}} + +\usepackage{fnpct} +\usepackage[biblatex]{embrac} +\ChangeEmph{[}[,.02em]{]}[.055em,-.08em] +\ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em] + +\pagestyle{headings} + +\usepackage[accsupp]{acro} +\acsetup{ + long-format=\scshape, + short-format=\scshape +} +\DeclareAcronym{ghs}{ + short = ghs , + long = Globally Harmonized System of Classification and Labelling of + Chemicals , + pdfstring = GHS , + accsupp = GHS +} +\DeclareAcronym{eu}{ + short = EU , + long = European Union , + pdfstring = EU , + accsupp = EU +} +\DeclareAcronym{iupac}{ + short = iupac , + long = International Union of Pure and Applied Chemistry , + pdfstring = IUPAC , + accsupp = IUPAC +} +\DeclareAcronym{UN}{ + short = un , + long = United Nations , + pdfstring = UN , + accsupp = UN +} +\DeclareAcronym{dvi}{ + short = dvi , + long = device independent file format , + pdfstring = DVI , + accsupp = DVO +} +\DeclareAcronym{pdf}{ + short = pdf , + long = portable document file , + pdfstring = PDF , + accsupp = PDF +} + +\chemsetup{ + option/synchronize , + chemformula/font-spec={[Numbers=Lining]Linux Libertine O} +} +\colorlet{chemformula}{darkgray} + +\sisetup{ + detect-mode=false, + mode=text, + text-rm=\addfontfeatures{Numbers={Proportional,Lining}} +} + +\usepackage{filecontents} + +\begin{filecontents*}{\jobname.ist} + preamble "\\begin{theindex}\n Section titles are indicated \\textbf{bold}, + packages \\textsf{sans serif}, commands \\code{\\textbackslash\\textcolor{code}{brown}}, + options \\textcolor{key}{\\code{yellow}} and modules (only \\chemmacros) + \\textcolor{module}{\\code{blue}}.\\newline\n\n" + heading_prefix "{\\bfseries " + heading_suffix "\\hfil}\\nopagebreak\n" + headings_flag 1 + delim_0 "\\dotfill\\hyperpage{" + delim_1 "\\dotfill\\hyperpage{" + delim_2 "\\dotfill\\hyperpage{" + delim_r "}\\textendash\\hyperpage{" + delim_t "}" + suffix_2p "\\nohyperpage{\\,f.}" + suffix_3p "\\nohyperpage{\\,ff.}" +\end{filecontents*} + +\usepackage[backend=biber,style=alphabetic,maxbibnames=20]{biblatex} +\addbibresource{\jobname.bib} +\begin{filecontents*}{\jobname.bib} +@book{iupac:greenbook, + author = {E. Richard Cohan and Tomislav Cvita\v{s} and Jeremy G. Frey and + Bertil Holmström and Kozo Kuchitsu and Roberto Marquardt and Ian Mills and + Franco Pavese and Martin Quack and Jürgen Stohner and Herbert L. Strauss and + Michio Takami and Anders J Thor}, + title = {“Quantities, Symbols and Units in Physical Chemistry”, \acs{iupac} + Green Book}, + edition = {3rd Edition. 2nd Printing}, + year = {2008}, + publisher = {\acs{iupac} \&\ RSC Publishing, Cambridge} +} +@book{iupac:redbook, + author = {Neil G. Connelly and Ture Damhus and Richard M. Hartshorn and + Alan T. Hutton}, + title = {“Nomenclature of Inorganic Chemistry”, \acs{iupac} Red Book}, + year = {2005}, + publisher = { \acs{iupac} \&\ RSC Publishing, Cambridge}, + isbn = {0-85404-438-8} +} +@misc{eu:ghsystem_regulation, + author = {{The European Parliament and The Council of the European Union}}, + title = {Regulation (EC) No 1272/2008 of the European Parliament and of the Council}, + subtitle = {on classification, labelling and packaging of substances and mixtures, + amending and repealing Directives 67/548/EEC and 1999/45/EC, and amending + Regulation (EC) No 1907/2006}, + journal = {Official Journal of the European Union}, + date = {2008-12-16} +} +@online{unece:ghsystem_implementation, + author = {United Nations Economic Commission for Europe}, + title = {GHS Implementation}, + url = {http://www.unece.org/trans/danger/publi/ghs/implementation_e.html}, + urldate = {2012-03-20}, + date = {2012-03-20} +} +\end{filecontents*} + +\DeclareInstance{xfrac}{chemformula-text-frac}{text} + { + scale-factor = 1 , + denominator-bot-sep = -.2ex , + denominator-format = \scriptsize #1 , + numerator-top-sep = -.2ex , + numerator-format = \scriptsize #1 , + slash-right-kern = .05em , + slash-left-kern = .05em + } + +\usetikzlibrary{calc,positioning,decorations.pathmorphing,patterns} + +\pgfdeclaredecoration{penciline}{initial}{ + \state{initial}[ + width=+\pgfdecoratedinputsegmentremainingdistance, + auto corner on length=1mm + ]{ + \pgfpathcurveto% + {% From + \pgfqpoint + {\pgfdecoratedinputsegmentremainingdistance} + {\pgfdecorationsegmentamplitude} + } + {% Control 1 + \pgfmathrand + \pgfpointadd + {\pgfqpoint{\pgfdecoratedinputsegmentremainingdistance}{0pt}} + {% + \pgfqpoint + {-\pgfdecorationsegmentaspect\pgfdecoratedinputsegmentremainingdistance}% + {\pgfmathresult\pgfdecorationsegmentamplitude} + } + } + {%TO + \pgfpointadd + {\pgfpointdecoratedinputsegmentlast} + {\pgfpoint{1pt}{1pt}} + } + } + \state{final}{} +} +\tikzset{pencil/.style={decorate,decoration=penciline}} + +\TitlePicture{% + \ch[font-spec={Augie}]{ + 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)[red,pencil,-cf]{\small\ch[font-spec={[Color=red]Augie},math-space=.3em]{$-$ 2 e-}} + \redox(r1,r2)[blue,pencil,-cf][-1]{\small\ch[font-spec={[Color=blue]Augie},math-space=.3em]{$+$ 2 e-}}} + +\addcmds{ + a, abinitio, AddRxnDesc, anti, aq, aqi, + b, ba, bond, bottomrule, bridge, + cancel, cd, cdot, ce, cee, celsius, centering, chemabove, Chemalpha, + Chembeta, Chemgamma, Chemdelta, ChemDelta, chemfig, chemname, Chemomega, + chemsetup, cip, cis, ch, clap, cnsetup, CNMR, color, cstack, cstsetup, + d, D, data, DeclareChemArrow, DeclareChemBond, DeclareChemBondAlias, + DeclareChemIUPAC, DeclareChemLatin, DeclareChemNMR, DeclareChemParticle, + DeclareChemPhase, DeclareChemReaction, DeclareChemState, DeclareInstance, + DeclareSIUnit, definecolor, delm, delp, Delta, Dfi, draw, + E, el, electronvolt, ElPot, endo, Enthalpy, enthalpy, Entropy, + footnotesize, fmch, fpch, fscrm, fscrp, + g, gas, ghs, ghslistall, ghspic, Gibbs, glqq, gram, grqq, + H, hapto, HNMR, Helmholtz, hertz, hspace, + includegraphics, insitu, intertext, invacuo, iupac, IUPAC, + J, joule, + Ka, Kb, kilo, Kw, + L, latin, lewis, Lewis, Lfi, listofreactions, lqd, ltn, + mch, mega, meta, metre, mhName, midrule, milli, mmHg, mole, + N, nano, nicefrac, newman, NMR, Nu, Nuc, num, numrange, + O, ominus, orbital, ortho, oplus, ox, OX, + p, P, para, pch, per, percent, pgfarrowsdeclarealias, pgfarrowsrenewalias, + pH, phase, photon, pKa, pKb, pOH, pos, positron, Pot, prt, + R, Rad, redox, RenewChemArrow, RenewChemBond, RenewChemIUPAC, + RenewChemLatin, RenewChemNMR, RenewChemParticle, RenewChemPhase, + RenewChemState, renewtagform, rightarrow, + S, Sf, sample, scriptscriptstyle, scrm, scrp, second, setatomsep, + setbondoffset, setchemformula, sfrac, shorthandoff, ShowChemArrow, + ShowChemBond, si, SI, sisetup, sld, Sod, square, State, subsection, + textcolor, textendash, textsuperscript, tiny, toprule, trans, + upbeta, upeta, upgamma, + val, volt, vphantom, vspave, + w, xspace, Z +} + +\usepackage{imakeidx} +\indexsetup{othercode=\footnotesize} +\makeindex[columns=3,intoc,options={-sl \jobname.ist}] + +\newcommand*\Chemmacros{% + {% + \fontspec[Color=main,Scale=1.2] + {Linux Biolinum Shadow O}% + chemmacros% + }% +} +\providecommand*\chemmacros{{\scshape\textcolor{main}{chemmacros}}\xspace} + +\newcommand*\Chemformula{% + {% + \fontspec[Color=main,Scale=1.2] + {Linux Biolinum Shadow O}% + chemformula% + }% +} +\providecommand*\chemformula{{\scshape\textcolor{main}{chemformula}}\xspace} + +\newcommand*\Ghsystem{% + {% + \fontspec[Color=main,Scale=1.2] + {Linux Biolinum Shadow O}% + ghsystem% + }% +} +\providecommand*\ghsystem{{\scshape\textcolor{main}{ghsystem}}\xspace} + +\newcommand*\Chemgreek{% + {% + \fontspec[Color=main,Scale=1.2] + {Linux Biolinum Shadow O}% + chemgreek% + }% +} +\providecommand*\chemgreek{{\scshape\textcolor{main}{chemgreek}}\xspace} + +\renewcommand*\AmS{\hologo{AmS}} + +\newcommand*\Default[1]{% + \hfill\llap{% + \ifblank{#1} + {(initially~empty)} + {Default:~\code{#1}}% + }\newline +} + +\usepackage{marginnote,ragged2e} +\makeatletter +\providecommand*\sinceversion[1]{% + \@bsphack + \marginnote{% + \footnotesize\sffamily\RaggedRight + \textcolor{black!75}{Introduced in version~#1}}% + \@esphack} +\providecommand*\changedversion[1]{% + \@bsphack + \marginnote{% + \footnotesize\sffamily\RaggedRight + \textcolor{black!75}{Changed in version~#1}}% + \@esphack} + +\RenewDocumentCommand\CTANurl{O{macros/latex/contrib}m} + {% + on CTAN: % + \hyper@linkurl{#2}{http://mirrors.ctan.org/#1/#2/}% + } +\ExplSyntaxOn +\RenewDocumentCommand \paket { sO{macros/latex/contrib}m } + { + \paketfont { #3 } + \index { #3 @ \paketfont { #3 } } + \prop_if_in:NnF \g_cnpkgdoc_pakete_prop { #3 } + { + \prop_gput:Nnn \g_cnpkgdoc_pakete_prop { #3 } {} + \IfBooleanF { #1 } + { \footnote { \CTANurl[]{#3} } } + } + } +\ExplSyntaxOff +\makeatother + +\begin{document} + +\section{Introduction} +Probably every chemist using \LaTeXe\ is aware of the great \paket{mhchem} +package by Martin Hensel. There have always been some difficulties +intertwining it with \chemmacros, though. Also, some other minor points in +\paket{mhchem} always bothered me, but they hardly seemed enough for a new +package. They weren't even enough for a feature request to the \paket{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\ works very similar to \paket{mhchem} but is more strict as to how +compounds, stoichiometric factors and arrows are input. In the same time +\chemformula\ offers \emph{many} possibilities to customize the output. + +\sinceversion{4.0}Since version 4.0, the \chemformula\ package can be used +independently from \chemmacros. This means that if you say +\begin{beispiel}[code only] + \usepackage{chemformula} +\end{beispiel} +then \chemmacros\ will not be loaded. The \chemmacros\ package, however, +\emph{will} load \chemformula. + +\section{Licence and Requirements} +Permission is granted to copy, distribute and/or modify this software under +the terms of the \LaTeX\ project public license (lppl) version 1.3 or later +(\url{http://www.latex-project.org/lppl.txt}). The package has the status +``maintained.'' + +The \chemformula\ package needs and thus loads the packages \paket*{expl3} +(from the \paket*{l3kernel}\footnote{\CTANurl{l3kernel}}), \paket*{xparse}, +\paket*{l3keys2e} and \paket*{xfrac} (from the +\paket*{l3packages}\footnote{\CTANurl{l3packages}}), +\paket*{tikz}\footnote{\CTANurl[graphics]{pgf}}, \paket{amsmath}, +\paket*{nicefrac} and \paket*{scrlfile} (from the +\KOMAScript\footnote{\CTANurl{koma-script}} bundle). + +\section{Setup} +All of \chemformula's options belong to \chemmacros' module +\textcolor{module}{\code{chemformula}}. This means they can be setup with +\begin{beispiel}[code only] + \chemsetup[chemformula]{<options>} or + \chemsetup{chemformula/<option1>,chemformula/<option2>} +\end{beispiel} +However, if you're using \chemformula\ as a standalone package the command +\cmd{chemsetup} is not available. This is why \chemformula\ also has its own +setup command: +\begin{beispiel}[code only] + \setchemformula{<options>} +\end{beispiel} + +\section{The Basic Principle} +\chemformula\ offers one main command. +\begin{beschreibung} + \Befehl{ch}[<options>]{<input>} +\end{beschreibung} +The usage will seem very familiar to you if you're familiar with \paket{mhchem}: +\begin{beispiel} + \ch{H2O} \\ + \ch{Sb2O3} \\ + \ch{H+} \\ + \ch{CrO4^2-} \\ + \ch{AgCl2-} \\ + \ch{[AgCl2]-} \\ + \ch{Y^{99}+} \\ + \ch{Y^{99+}} \\ + \ch{H2_{(aq)}} \\ + \ch{NO3-} \\ + \ch{(NH4)2S} \\ + \ch{^{227}_{90}Th+} \\ + $V_{\ch{H2O}}$ \\ + \ch{Ce^{IV}} \\ + \ch{KCr(SO4)2 * 12 H2O} +\end{beispiel} + +However, there are differences. The most notable one: \chemformula\ +distinguishes between different types of input. These different parts +\emph{have} to be separated with blanks: +\begin{beschreibung} + \Befehl{ch}{part1 part2 part3 part4} +\end{beschreibung} +A blank in the input \emph{never} is a blank in the output. This role of the +blank strictly holds and disregarding it can have unexpected results and even +lead to errors. + +Another notable difference: \chemformula\ tries to avoid math mode whenever +possible: +\begin{beispiel} + \ch{A + B ->[a] C} \\ + \ce{A + B ->[a] C} +\end{beispiel} + +This means that \cmd{ch}{2H2O} is recognized as a \emph{single} part, which in +this case is recognized as a compound. +\begin{beispiel} + \ch{2H2O} \\ + \ch{2 H2O} +\end{beispiel} +This also means, that a part cannot contain a blank since this will +automatically divide it into two parts. If you need an extra blank in the +output you need to use \lstinline+~+. However, since commands in most cases +gobble a space after them a input like \cmd{ch}{\textbackslash command ABC} +will be treated as a single part. If you want or need to divide them you need +to add an empty group: \cmd{ch}{\textbackslash command\{\} ABC}. The +different input types are described in the following sections. + +% TODO: Module überdenken, Beschreibung anpassen +There are some options to customize the output of the \cmd{ch} command. They +can either be applied locally using the optional argument or can be set +globally using the setup command. All options of \chemformula\ belong to the +module \textcolor{module}{\code{chemformula}} and can be set in different +ways: +\begin{beschreibung} + \Befehl{chemsetup}[chemformula]{<options>} (when loaded via \chemmacros) + \Befehl{chemsetup}{chemformula/<options>} (when loaded via \chemmacros) + \Befehl{setchemformula}{<options>} (independent from \chemmacros) +\end{beschreibung} + +\section{Stoichiometric Factors}\secidx{Stoichiometric Factors} +A stoichiometric factor may only contain of numbers and the signs +\lstinline+.,_/()+ +\begin{beispiel} + \ch{2} \\ + \ch{12} + + % decimals: + \ch{.5} \\ + \ch{5,75} + + % fractions: + \ch{3/2} \\ + \ch{1_1/2} + + % ``iupac'': + \ch{(1/2)} +\end{beispiel} + +As you can see if you input decimal numbers a missing leading zero is added. + +You have to be a little bit careful with the right syntax but I believe it is +rather intuitive. +\begin{beispiel}[code only] + this won't work but will result in an error: \ch{1/1_1} +\end{beispiel} + +If stoichiometric factors are enclosed with parentheses the fractions are not +recognized and missing leading zeros are not added. What's inside the +parentheses is typeset as is. +\begin{beispiel} + \ch{(1/2) H2O} \ch{1/2 H2O} \ch{0.5 H2O} +\end{beispiel} +You can find many examples like the following for stoichiometric factors in +parentheses in the \acs{iupac} Green Book~\cite{iupac:greenbook}: +\begin{reaction*} + (1/5) K "\ox*{7,Mn}" O4 + (8/5) HCl == (1/5) "\ox*{2,Mn}" Cl2 + (1/2) Cl2 + (1/5) KCl + (4/5) H2O +\end{reaction*} + +There are a few possibilities to customize the output. +\begin{beschreibung} + \Option{decimal-marker}{<marker>}\Default{.} + The symbol to indicate the decimal. + \Option{frac-style}{math|xfrac|nicefrac}\Default{math} + Determines how fractions are displayed. + \Option{stoich-space}{<skip>}\Default{.1667em plus .0333em minus .0117em} + The space that is placed after the stoichiometric factor. A rubber + length. + \Option{stoich-paren-parse}{\default{true}|false}\Default{false} + If set to true stoichiometric factors enclosed by parentheses also are + parsed. +\end{beschreibung} +\begin{beispiel} + \ch[decimal-marker={,}]{3.5} \ch[decimal-marker={$\cdot$}]{3,5} +\end{beispiel} + +The option \key{frac-style}{xfrac} uses the \lstinline+\sfrac+ command of the +\paket{xfrac} package. The output strongly depends on the font you +use.\secidx[xfrac]{Stoichiometric Factors} +\begin{beispiel} + \ch[frac-style=xfrac]{3/2} \ch[frac-style=xfrac]{1_1/2} +\end{beispiel} +\chemformula\ defines the instance \lstinline=formula-text-frac= which you can +redefine to your needs. See the \paket{xfrac} documentation for further +information. The default definition is this: +\begin{beispiel}[code only] + \DeclareInstance{xfrac}{chemformula-text-frac}{text} + { + slash-left-kern = -.15em , + slash-right-kern = -.15em + } +\end{beispiel} +This document uses the font Linux Libertine~O and the following definition: +\begin{beispiel}[code only] + \DeclareInstance{xfrac}{chemformula-text-frac}{text} + { + scale-factor = 1 , + denominator-bot-sep = -.2ex , + denominator-format = \scriptsize #1 , + numerator-top-sep = -.2ex , + numerator-format = \scriptsize #1 , + slash-right-kern = .05em , + slash-left-kern = .05em + } +\end{beispiel} + +The option \key{frac-style}{nicefrac} uses the \lstinline+\nicefrac+ command +of the \paket{nicefrac} package.\secidx[nicefrac]{Stoichiometric Factors} +\begin{beispiel} + \ch[frac-style=nicefrac]{3/2} \ch[frac-style=nicefrac]{1_1/2} +\end{beispiel} + +The option \key{stoich-space} allows you to customize the space between +stoichiometric factor and the group following after +it.\secidx[space]{Stoichiometric Factors} +\begin{beispiel} + \ch{2 H2O} \\ + \ch[stoich-space=.3em]{2 H2O} +\end{beispiel} +\secidx*{Stoichiometric Factors} + +\section{Compounds}\label{ssec:compounds}\secidx{Compounds} +\chemformula\ determines compounds as the type that ``doesn't fit in anywhere +else.'' This point will become more clear when you know what the other types +are. +\begin{beispiel} + \ch{H2SO4} \\ + \ch{[Cu(NH3)4]^2+} +\end{beispiel} + +\subsection{Adducts}\secidx[adducts]{Compounds} +\chemformula\ has two identifiers which will create adducts. +\begin{beschreibung} + \Befehl{ch}{A.B}\newline \ch{A.B} + \Befehl{ch}{A*B}\newline \ch{A*B} +\end{beschreibung} +\begin{beispiel} + \ch{CaSO4.H2O} \\ + \ch{CaSO4*H2O} +\end{beispiel} +Since numbers in a compound always are treated as subscripts (see +section~\ref{ssec:subscripts}) you sometimes need to introduce stoichiometric +factors for the right output: +\begin{beispiel} + \ch{Na3PO4*12H2O} \\ + \ch{Na3PO4* 12 H2O} \\ + \ch{Na3PO4 * 12 H2O} +\end{beispiel} + +\subsection{Subscripts}\label{ssec:subscripts}\secidx[subscripts]{Compounds} +\emph{All} numbers in a compound are treated as subscripts. +\begin{beispiel} + \ch{H2SO4} +\end{beispiel} +If you want a letter to be a subscript you can use the math syntax: +\begin{beispiel} + \ch{A_nB_m} +\end{beispiel} +The subscript recognizes groups. You can also use math inside it. +\begin{beispiel} + \ch{A_{$n$}B_{$m$}} \\ + \ch{NaCl_{(aq)}} +\end{beispiel} + +\subsection{Commands}\secidx[commands]{Compounds} +Commands are allowed in a compound: +\begin{beispiel} + \ch{\textbf{A2}B3} \ch{A2\color{red}B3} +\end{beispiel} + +However, if the commands demand numbers as argument, \eg, space commands or +\chemmacros' \lstinline+\ox+ command the direct use will fail. This is +because the numbers are treated as subscripts \emph{before} the command +expands. +\begin{beispiel}[code only] + \ch{A\hspace{2mm}B} will raise an error because \hspace sees something like + this: \hspace{$_2$mm}. Actually not at all like it but equally bad\ldots +\end{beispiel} +See section~\ref{ssec:text} for a way around this. + +\subsection{Charges and Other Superscripts}\secidx[charges]{Compounds}\secidx[superscripts]{Compounds} +\paragraph{Basics} +If a compound \emph{ends} with a plus or minus sign it will be treated as +charge sign and typeset as superscript. In other places a plus is treated as +a triple bond and a dash will be used as a single bond, see +section~\ref{ssec:bonds}. +\begin{beispiel} + \ch{A+B} \ch{AB+} \\ + \ch{A-B} \ch{AB-} +\end{beispiel} + +For longer charge groups or other superscripts you can use the math syntax. +It recognizes groups and you can use math inside them. Inside these groups +neither \code{+} nor \code{-} are treated as bonds. If a dot \code{.} is +inside a superscript it is treated as indicator for a radical. A \code{*} +gives the excited state. +\begin{beispiel} + \ch{A^{x-}} \\ + \ch{A^x-} \\ + \ch{A^{x}-} \\ + \ch{A^{$x-$}} \\ + \ch{RNO2^{-.}} \\ + \ch{^31H} \\ + \ch{^{14}6C} \\ + \ch{^{58}_{26}Fe} \\ + \ch{NO^*} +\end{beispiel} + +Ions and ion composites with more than one charge can be typeset quite as +easy: +\begin{beispiel} + \ch{SO4^2-} \ch{Ca^2+ SO4^2-} +\end{beispiel} + +\paragraph{Charge Commands}\secidx[superscripts!charge commands]{Compounds} +You don't need to use \cmd{mch} and related commands inside \cmd{ch}. Indeed, +you \emph{shouldn't} use them as they might mess with the subscript and +superscript alignment. The \chemmacros\ option \code{circled} is obeyed by +\cmd{ch}. +\begin{beispiel} + \chemsetup[option]{circled=all} + \ch{H+ + OH- <=> H2O} +\end{beispiel} + +\paragraph{Behaviour}\secidx[superscripts!behaviour]{Compounds} +The supercripts behave differently depending on their position in a compound, +if there are super- and subscripts following each other directly. +\begin{beispiel} + \ch{^33B} \ch{{}^33B} \ch{3^3B} \ch{B^3} \ch{B3^3} \\ + \ch{^{23}_{123}B} \ch{{}^{23}_{123}B} \ch{_{123}^{23}B} \ch{B^{23}} \ch{B_{123}^{23}} \\ + \ch{^{123}_{23}B} \ch{{}^{123}_{23}B} \ch{_{23}^{123}B} \ch{B^{123}} \ch{B23^{123}} +\end{beispiel} +\begin{itemize} +\item If a compound \emph{starts} with a sub- or superscript both sub- and + superscript are aligned to the \emph{right} else to the \emph{left}. +\item If a compound \emph{does not start} with a sub- or superscript and there + is both a sub- and a superscript, the superscript is shifted additionally by + a length determined from the option \key{charge-hshift}{<dim>}, also see + page~\pageref{desc:charge-hshift}f. +\end{itemize} +The second point follows \ac{iupac}'s recommendations: +\begin{zitat}[{\acs{iupac} Green Book {\cite[][p.\,51]{iupac:greenbook}}}] + In writing the formula for a complex ion, spacing for charge number can be + added (staggered arrangement), as well as parentheses: + \ch[charge-hshift=full]{SO4^2-}, \ch{(SO4)^2-} The staggered arrangement is + now recommended. +\end{zitat} + +\subsection{Bonds}\label{ssec:bonds}\secidx[bonds]{Compounds} +\subsubsection{Native Bonds} +There are three kinds of what I will call ``native bonds'': +\begin{beispiel} + single: \ch{CH3-CH3} \\ + double: \ch{CH2=CH2} \\ + triple: \ch{CH+CH} +\end{beispiel} + +\subsubsection{Flexible Bonds} +\paragraph{Predefined Bonds} +In addition to the three native bonds there are a few more which can be called +by +\begin{beschreibung} + \Befehl{bond}{<bond name>} +\end{beschreibung} +The predefined bond types are shown in table~\ref{tab:bond_types}. + +\begin{table} + \centering + \caption{Bonds available with \protect\cmd{bond}.} + \label{tab:bond_types} + \begin{tabular}{lcl} + \toprule + \bfseries name & \bfseries appearance & \bfseries aliases \\ + \midrule + \code{single} & \bond{single} & \code{normal}, \code{sb} \\ + \code{double} & \bond{double} & \code{db} \\ + \code{triple} & \bond{triple} & \code{tp} \\ + \code{dotted} & \bond{dotted} & \code{semisingle} \\ + \code{deloc} & \bond{deloc} & \code{semidouble} \\ + \code{tdeloc} & \bond{tdeloc} & \code{semitriple} \\ + \code{co>} & \bond{co>} & \code{coordright} \\ + \code{<co} & \bond{<co} & \code{coordleft} \\ + \bottomrule + \end{tabular} +\end{table} + +\begin{beispiel} + \ch{C\bond{sb}C\bond{db}C\bond{tp}C\bond{deloc}C\bond{tdeloc}C\bond{co>}C\bond{<co}C} +\end{beispiel} + +\paragraph{Own Bonds} +\chemformula\ offers commands to define own bond types: +\begin{beschreibung} + \Befehl{DeclareChemBond}{<name>}\ma{<code>} + \Befehl{RenewChemBond}{<name>}\ma{<code>} + \Befehl{DeclareChemBondAlias}{<new name>}\ma{<old name>} + \Befehl{ShowChemBond}{<name>} +\end{beschreibung} +The usage is best described with an example. So let's see how the +\code{single} bond and the \code{co>} bond are defined: +\begin{beispiel}[code only] + \DeclareChemBond{single} + { \draw[chembond] (chemformula-bond-start) -- (chemformula-bond-end) ; } + \DeclareChemBond{coordright} + { \draw[chembond,butt cap->] (chemformula-bond-start) -- (chemformula-bond-end) ; } + \DeclareChemBondAlias{co>}{coordright} +\end{beispiel} +Two points are important: the names of the starting and the ending +coordinates, \code{chemformula-bond-start} and \code{chemformula-bond-end}, +and the \TikZ style of the bonds \code{chembond}. + +So, let's say you want to define a special kind of dashed bond. You could do +this: +\begin{beispiel} + \usetikzlibrary{decorations.pathreplacing} + \makeatletter + \DeclareChemBond{dashed} + { + \draw[ + chembond, + decorate, + decoration={ticks,segment length=\chemformula@bondlength/10,amplitude=1.5pt}] + (chemformula-bond-start) -- (chemformula-bond-end) ; + } + \makeatother + \chemsetup[chemformula]{bond-length=2ex} + \ch{C\bond{dashed}C} +\end{beispiel} + +The last example showed you another macro: +\makeatletter\cmd{chemformula@bondlength}\makeatother. It only exists so you +can use it to access the bond length as set with \key{bond-length} +directly. + +\subsection{Customization}\secidx[customization]{Compounds}\label{ssec:compounds:customization} +These options allow you to customize the ouptut of the compounds: +\begin{beschreibung} + \Option{subscript-vshift}{<dim>}\Default{0pt} + Extra vertical shift of the subscripts. + \Option{subscript-style}{text|math}\Default{text} + Style that is used to typeset the subscripts. + \Option{charge-hshift}{<dim>}\Default{.25em} + Shift of superscripts when following a subscript.\label{desc:charge-hshift} + \Option{charge-vshift}{<dim>}\Default{0pt} + Extra vertical shift of the superscripts. + \Option{charge-style}{text|math}\Default{text} + Style that is used to typeset the superscripts. + \Option{adduct-space}{<dim>}\Default{.1333em} + Space to the left and the right of the adduct point. + \Option{bond-length}{<dim>}\Default{.5833em} + The length of the bonds. + \Option{bond-offset}{<dim>}\Default{.07em} + Space between bond and atoms. + \Option{bond-style}{<tikz>}\Default{} + \TikZ\ options for the bonds. + \Option{radical-style}{<tikz>}\Default{} + \TikZ\ options for the radical point. + \Option{radical-radius}{<dim>}\Default{.2ex} + The radius of the radical point. + \Option{radical-hshift}{<dim>}\Default{.15em} + Horizontal shift before the radical point is drawn. + \Option{radical-vshift}{<dim>}\Default{.5ex} + Vertical shift relative to the current baseline. + \Option{radical-space}{<dim>}\Default{.15em} + Horizontal shift after the radical point is drawn. +\end{beschreibung} + +Maybe you have noticed that charges of certain ions are shifted to the +right.\secidx[charges!shift]{Compounds} +\begin{beispiel} + \ch{SO4^2-} \ch{NH4+} \ch{Na+} +\end{beispiel} +They are shifted if they \emph{follow} a subscript which follows \ac{iupac} +recommendations~\cite[][p.\,51]{iupac:greenbook}. The amount of the shift can +be set with the option \key{charge-hshift}. +\begin{beispiel} + \ch{SO4^2-} \ch{NH4+} \ch{Na+} \\ + \chemsetup[chemformula]{charge-hshift=.5ex} + \ch{SO4^2-} \ch{NH4+} \ch{Na+} \\ + \chemsetup[chemformula]{charge-hshift=.5pt} + \ch{SO4^2-} \ch{NH4+} \ch{Na+} +\end{beispiel} + +Despite \ac{iupac}'s recommendation \chemformula\ does not make fully staggered +arrangements in the default setting as I find it hard to read in some cases +and ugly in others. Since this is a subjective decision \chemformula\ not only +let's you define the absolute amount of the shift but also provides a +possibility for full staggered arrangements. For this you have to use +\key{charge-hshift}{full}. +\begin{beispiel} + \ch[charge-hshift=0pt]{C5H11+} \ch[charge-hshift=0pt]{SO4^2-} \\ + \ch{C5H11+} \ch{SO4^2-} \\ + \ch[charge-hshift=1ex]{C5H11+} \ch[charge-hshift=1ex]{SO4^2-} \\ + \ch[charge-hshift=full]{C5H11+} \ch[charge-hshift=full]{SO4^2-} +\end{beispiel} + +If you don't want the charges to be typeset in text mode you can switch to +math mode: +\begin{beispiel} + \ch{M^x+} \ch{SO4^2-} \\ + \chemsetup[chemformula]{charge-style = math} + \ch{M^x+} \ch{SO4^2-} +\end{beispiel} + +The option \key{subscript-vshift} can be used to adjust the vertical shift of +the subscripts:\secidx[subscripts!shift]{Compounds} +\begin{beispiel} + \ch{H2SO4} \ch{Na3PO4} \\ + \chemsetup[chemformula]{subscript-vshift=.5ex} + \ch{H2SO4} \ch{Na3PO4} \\ + \chemsetup[chemformula]{subscript-vshift=-.2ex} + \ch{H2SO4} \ch{Na3PO4} +\end{beispiel} + +You can choose the mode subscripts are typeset in the same way as it is +possible for the charges: +\begin{beispiel} + \ch{A_nB_m} \ch{H2SO4} \\ + \chemsetup[chemformula]{subscript-style = math} + \ch{A_nB_m} \ch{H2SO4} +\end{beispiel} + +The option \key{adduct-space} sets the space left and right to the adduct +symbol $\cdot$. +\begin{beispiel} + \ch{Na3PO3*H2O} \\ + \chemsetup[chemformula]{adduct-space=.2em} + \ch{Na3PO3*H2O} +\end{beispiel} + +Changing the length of the bonds:\secidx[bonds!length]{Compounds} +\begin{beispiel} + \chemsetup[chemformula]{bond-length=4mm}% + single: \ch{CH3-CH3} \\ + double: \ch{CH2=CH2} \\ + triple: \ch{CH+CH} +\end{beispiel} + +You can change the distance between bond and atom, too: +\begin{beispiel} + \ch{H-H + N+N + O=O} \\ + \ch[bond-offset=1pt]{H-H + N+N + O=O} +\end{beispiel} + +\subsection{Standalone Formulae}\secidx[standalone]{Compounds} +\noindent\sinceversion{4.0}\chemformula\ offers a command that \emph{only + accepts} the \enquote{compound} input type: +\begin{beschreibung} + \Befehl{chcpd}[<options>]{<compound>} +\end{beschreibung} +\secidx*{Compounds} + +\section{Special Input Types}\secidx{Special Types} +There are some \enquote{special type} input groups. + +\subsection{Single Token Groups}\secidx[single token groups]{Special Types} +The first kind are groups which consist of only one token, namely of the +following ones: +\begin{beschreibung} + \Befehl{ch}{ + } \ch{ + }\newline + Creates the plus sign between compounds with space around it:\\ + \cmd{ch}{2 Na + Cl2} \ch{2 Na + Cl2} + \Befehl{ch}{ v } \ch{ v }\newline + Sign for precipitate: \cmd{ch}{BaSO4 v} \ch{BaSO4 v} + \Befehl{ch}{ \lstinline+^+ } \ch{ ^ }\newline + Sign for escaping gas\footnotemark: \cmd{ch}{\lstinline=H2 ^=} + \ch{H2 ^} +\end{beschreibung} +\footnotetext{Is this the correct English term? Please correct me if it isn't.} + +The space left and right of the plus sign can be set with this option: +\begin{beschreibung} + \Option{plus-space}{<skip>}\Default{.3em plus .1em minus .1em} + A rubber length. +\end{beschreibung} +\begin{beispiel} + \ch{A + B}\\ + \ch[plus-space=4pt]{A + B} +\end{beispiel} + +\subsection{Option Input}\secidx[option input]{Special Types} +Sometimes you might want to apply an option only to a part of a, say, +reaction. Of course you have the possibility to use \cmd{ch} several times. +\begin{beispiel} + \ch{H2O +}\textcolor{red}{\ch{H2SO4}}\ch{-> H3O+ + HSO4-} \\ + \ch{H2O +}\ch[subscript-vshift=2pt]{H2SO4}\ch{-> H3O+ + HSO4-} +\end{beispiel} +This, however, interrupts the input in your source and \emph{may} mess with +the spacing. That's why there is an alternative: +\begin{beschreibung}\makeatletter + \Befehl{ch}{ @\{<options>\} }\newline + The options specified this way will be valid \emph{only} until the next + compound is set. +\end{beschreibung} +\begin{beispiel} + \ch{H2O +}\textcolor{red}{\ch{H2SO4}}\ch{-> H3O+ + HSO4-} \\ + \ch{H2O + @{format=\color{red}} H2SO4 -> H3O+ + HSO4-} \\ + or of course:\\ + \ch{H2O + \textcolor{red}{H2SO4} -> H3O+ + HSO4-}\\[1em] + \ch{H2O +}\ch[subscript-vshift=2pt]{H2SO4}\ch{-> H3O+ + HSO4-} \\ + \ch{H2O + @{subscript-vshift=2pt} H2SO4 -> H3O+ + HSO4-} +\end{beispiel} +\secidx*{Special Types} + +\section{Escaped Input}\secidx{Escaped Input} +In some cases it may be desirable to prevent \chemformula\ from parsing the +input. This can be done in two ways. + +\subsection{Text}\label{ssec:text}\secidx[text]{Escaped Input} +If you put something between \lstinline+" "+ or \lstinline+' '+ then the input +will be treated as normal text, except that spaces are not allowed and have to +be input with \lstinline+~+. +\begin{beschreibung} + \Befehl{ch}{ "<escaped text>" } + \Befehl{ch}{ '<escaped text>' } +\end{beschreibung} +\begin{beispiel} + \ch{"\ox{2,Ca}" O} \\ + \ch{"\ldots\," Na + "\ldots\," Cl2 -> "\ldots\," NaCl} \\ + \ch{'A~->~B'} +\end{beispiel} +In many cases you won't need to escape the input. But when you get into +trouble when using a command inside \cmd{ch} try hiding it. + +\subsection{Math}\secidx[math]{Escaped Input} +If you especially want to input math you just enclose it with \lstinline+$ $+. +This output is different from the escaped text as it is followed by a space. +The reasoning behind this is that I assume math will mostly be used to replace +stoichiometric factors. +\begin{beschreibung} + \Befehl{ch}{ \string$<escaped math>\string$ } + \Befehl{ch}{ \string\(<escaped math>\string\) } +\end{beschreibung} +\begin{beispiel} + escaped text: \ch{"$x$" H2O} \\ + escaped math: \ch{$x$ H2O} \\ + also escaped math: \ch{\(x\) H2O} \\ + \ch{$2n$ Na + $n$ Cl2 -> $2n$ NaCl} +\end{beispiel} + +The space that is inserted after a math group can be edited: +\begin{beschreibung} + \Option{math-space}{<skip>}\Default{.1667em plus .0333em minus .0117em} + A rubber length. +\end{beschreibung} +\begin{beispiel} + \ch{$2n$ Na + $n$ Cl2 -> $2n$ NaCl} \\ + \chemsetup[chemformula]{math-space=.25em} + \ch{$2n$ Na + $n$ Cl2 -> $2n$ NaCl} \\ + \ch{$A->B$} +\end{beispiel} +\secidx*{Escaped Input} + +\section{Arrows}\label{sec:arrows}\secidx{Arrows} +\subsection{Arrow types}\secidx[types]{Arrows} +Arrows are input in the same intuitive way they are with \paket{mhchem}. +There are various different types: +\begin{beschreibung} + \Befehl{ch}{ -> } \ch{->}\newline + standard right arrow + \Befehl{ch}{ <- } \ch{<-}\newline + standard left arrow + \Befehl{ch}{ -/> } \ch{-/>}\newline + does not react (right) + \Befehl{ch}{ </- } \ch{}</-\newline + does not react (left) + \Befehl{ch}{ <-> } \ch{<->}\newline + resonance arrow + \Befehl{ch}{ <> } \ch{<>}\newline + reaction in both directions + \Befehl{ch}{ == } \ch{==}\newline + stoichiometric equation + \Befehl{ch}{ <=> } \ch{<=>}\newline + equilibrium arrow + \Befehl{ch}{ \lstinline+<=>>+ } \ch{<=>>}\newline + unbalanced equilibrium arrow to the right + \Befehl{ch}{ \lstinline+<<=>+ } \ch{<<=>}\newline + unbalanced equilibrium arrow to the left + \Befehl{ch}{ <o> } \ch{<o>}\newline + isolobal arrow +\end{beschreibung} +All these arrows are drawn with \TikZ. +\begin{beispiel} + \ch{H2 + Cl2 -> 2 HCl} \\ + \ch{H2O + CO3^2- <=> OH- + HCO3-} \\ + \ch{A <- B} \\ + \ch{\{[CH2=CH-CH2]- <-> [CH2-CH=CH2]- \}} \\ + \ch{A <> B} \\ + \ch{H+ + OH- <=>> H2O} \\ + \ch{2 NO2 <<=> N2O4} +\end{beispiel} + +% TODO: add description for \charrow + +\subsection{Labels}\secidx[labels]{Arrows} +The arrows take two optional arguments to label them. +\begin{beschreibung} + \Befehl{ch}{ ->[<above>][<below>] } +\end{beschreibung} +\begin{beispiel} + \ch{A ->[a] B} \\ + \ch{A ->[a][b] B} \\ + \ch{A ->[\SI{100}{\celsius}] B} +\end{beispiel} +The label text can be parsed seperately from the arrow. The recipe is easy: +leave blanks. +\begin{beispiel} + \ch{A ->[H2O] B} \\ + \ch{A ->[ H2O ] B} \\ + \ch{A ->[ "\ox{2,Ca}" F2 ] B} \\ + \ch{A ->[$\Delta$,~ \[H+ \]] B} +\end{beispiel} +% TODO: correct info about [] + +If you leave the blanks \chemformula\ treats the groups inside the square +brackets as seperated input types. The arrow reads its arguments +\emph{afterwards}. As you can see the arrows \enquote{grow} with the length +of the labels. What stays constant is the part that protrudes the labels. As +you also can see in the last example square brackets inside the arrow +arguments should be produced using \cmd{[} and \cmd{]}. They keep their usual +meaning outside \cmd{ch}. These commands are necessary since the usual +grouping (\ie hiding the brackets inside curly brackets) doesn't work due to +the way \cmd{ch} reads its argument. +\begin{beispiel} + \ch{A ->[a] B} \\ + \ch{A ->[ab] B} \\ + \ch{A ->[abc] B} \\ + \ch{A ->[abc~abc] B} \\ + % needs the `chemfig' package: + \setatomsep{15pt} + \ch{A ->[ "\chemfig{-[:30]-[:-30]OH}" ] B} \\ + \ch{A ->[[]] B} vs. \ch{A ->[\[\]] B} +\end{beispiel} + +\subsection{Customization}\secidx[customization]{Arrows} +These are the options which enable you to customize the arrows: +\begin{beschreibung} + \Option{arrow-offset}{<dim>}\Default{.75em} + This is the length that an arrow protrudes a label on both sides. This + means an empty arrow's length is two times \code{arrow-offset}. + \Option{arrow-min-length}{<dim>}\Default{0pt} + The minimal length an error must have unless two times \key{arrow-offset} + plus the width of the label is larger. + \Option{arrow-yshift}{<dim>}\Default{0pt} + Shifts an arrow up (positive value) or down (negative value). + \Option{arrow-ratio}{<factor>}\Default{.6} + The ratio of the arrow lengths of the unbalanced equilibrium. \code{.4} + would mean that the length of the shorter arrow is $0.4\times$ the length + of the longer arrow. + \Option{compound-sep}{<dim>}\Default{.5em} + The space between compounds and the arrows. + \Option{label-offset}{<dim>}\Default{2pt} + The space between the labels and the arrows. + \Option{label-style}{<font command>}\Default{\cmd*{footnotesize}} + The relative font size of the labels. +\end{beschreibung} + +The following code shows the effect of the different options on the \lstinline+<=>>+ +arrow: +\begin{beispiel} + standard: \ch{A <=>>[x][y] B} \\ + longer: \ch[arrow-offset=12pt]{A <=>>[x][y] B} \\ + higher: \ch[arrow-yshift=2pt]{A <=>>[x][y] B} \\ + more balanced: \ch[arrow-ratio=.8]{A <=>>[x][y] B} \\ + labels further away: \ch[label-offset=4pt]{A <=>>[x][y] B} \\ + larger distance to compounds: \ch[compound-sep=2ex]{A <=>>[x][y] B} \\ + smaller labels: \ch[label-style=\tiny]{A <=>[x][y] B} +\end{beispiel} + +\subsection{Modify Arrow Types}\label{sec:arrows_modify}\secidx[types!modify]{Arrows} +The arrows are defined with the command +\begin{beschreibung} + \Befehl{DeclareChemArrow}{<tokens>}\ma{<tikz>} +\end{beschreibung} +\ma{<tokens>} is the sequence of tokens that is replaced with the actual arrow +code. For example the basic arrow is defined via +\begin{beispiel}[code only] + \DeclareChemArrow{->}{\draw[-cf] (cf_arrow_start) -- (cf_arrow_end) ;} +\end{beispiel} +In order to define arrows yourself you need to know the basics of +\TikZ\footnote{Please see the \textsf{pgfmanual} for details.}. There are +some predefined coordinates you can and should use: +\begin{description} + \item[\code{(cf\_arrow\_start)}] The beginning of the arrow. + \item[\code{(cf\_arrow\_end)}] The end of the arrow. + \item[\code{(cf\_arrow\_mid)}] The mid of the arrow. + \item[\code{(cf\_arrow\_mid\_start)}] The beginning of the shorter arrow in + types like \lstinline+<=>>+. + \item[\code{(cf\_arrow\_mid\_end)}] The end of the shorter arrow in types like + \lstinline+<=>>+. + \item[\code{cf}, \code{left cf}, \code{right cf}] \chemformula's own arrow + heads. +\end{description} +\begin{beispiel} + \DeclareChemArrow{.>}{\draw[-cf,dotted,red] (cf_arrow_start) -- (cf_arrow_end);} + \DeclareChemArrow{n>}{\draw[-cf] (cf_arrow_start) .. controls ([yshift=3ex]cf_arrow_mid) .. (cf_arrow_end);} + \ch{A .> B} \ch{A .>[a][b] B} \ch{A n> B} +\end{beispiel} +If you want to redefine an existing arrow there are two commands you can use: +\begin{beschreibung} + \Befehl{RenewChemArrow}{<tokens>}\ma{<tikz>} + \Befehl{ShowChemArrow}{<tokens>} +\end{beschreibung} +The second one gives the current definition, the first one redefines an existing +arrow. +\begin{beispiel} + \texttt{\ShowChemArrow{->}} \\ + \RenewChemArrow{->}{\draw[->,red] (cf_arrow_start) -- (cf_arrow_end) ;} + \texttt{\ShowChemArrow{->}} \\ + \ch{A -> B} +\end{beispiel} + +\subsection{Standalone Arrows}\secidx[standalone]{Arrows} +\noindent\sinceversion{4.0}\chemformula\ offers a command that \emph{only + accepts} the \enquote{arrow} input type: +\begin{beschreibung} + \Befehl{charrow}{<arrow>}\oa{<above>}\oa{<below>} +\end{beschreibung} +\secidx*{Arrows} + +\section{Names}\secidx{Names} +\subsection{Syntax}\secidx[syntax]{Names} +\chemformula\ has a built-in syntax to write text under a compound. In a way +it works very similar to the arrows. +\begin{beschreibung} + \Befehl{ch}{ !(<name>)( <formula> ) } +\end{beschreibung} +If an exclamation mark is followed by a pair of parentheses \chemformula\ will +parse it this way: +\begin{beispiel} + \ch{!(ethanol)( CH2CH2OH )} +\end{beispiel} +The same what's true for the arrows arguments holds for these arguments: if +you leave blanks the different parts will be treated according to their input +type before the text is set below the formula. +\begin{beispiel} + \ch{!(water)(H2O)} \quad + \ch{!( "\textcolor{blue}{water}" )( H2O )} \quad + \ch{!( $2n-1$ )( H2O )} \quad + \ch{!( H2O )( H2O )} \quad + \ch{!(oxonium)( H3O+ )} +\end{beispiel} +If for some reason you want to insert an exclamation mark \emph{without} it +creating a name you only have to make sure it isn't followed by parentheses. +\begin{beispiel} + \ch{H2O~(!)} \\ + \ch{A!{}()} +\end{beispiel} + +% TODO add description of \chname command + +\subsection{Customization}\secidx[customization]{Names} +\chemformula\ provides two options to customize the output of the names: +\begin{beschreibung} + \Option{name-format}{<commands>}\Default{\cmd*{scriptsize}\cmd*{centering}} + The format of the name. This can be arbitrary input. + \Option{name-width}{<dim>|auto}\Default{auto} + The width of the box where the label is put into. \code{auto} will detect + the width of the name and set the box to this width. +\end{beschreibung} +\begin{beispiel} + \ch{!(acid)( H2SO4 ) -> B} \\ + \ch[name-format=\sffamily\small]{!(acid)( H2SO4 ) -> B} \\ + \ch[name-format=\scriptsize N:~]{!(acid)( H2SO4 ) -> B} \\ + \ch[name-width=3em,name-format=\scriptsize\raggedright]{!(acid)( H2SO4 ) -> B} +\end{beispiel} + +\subsection{Standalone Names}\secidx[standalone]{Names} +\noindent\sinceversion{4.0}\chemformula\ offers a command that allows the +usage of the \enquote{name} syntax in normal text. This is the command that +a bang is replaced with in \chemformula's formulas, actually. Both arguments +are mandatory. +\begin{beschreibung} + \Befehl{chname}\da{<under>}\da{<text>} +\end{beschreibung} +\secidx*{Names} + +\section{Format and Font}\secidx{Format and Font}\label{sec:format} +In the standard setting \chemformula\ doesn't make any default changes to the +font of the formula output. Let's take a look at a nonsense input which shows +all features: +\begin{beispiel} + \newcommand*\sample{% + \ch{H2C-C+C-CH=CH+ + CrO4^2- + <=>[x][y] + 2.5 Cl^{-.} + 3_1/2 Na*OH_{(aq)} + !(name)( A^n ) "\LaTeXe"} + } + \sample +\end{beispiel} +\newcommand*\sample{% + \ch{H2C-C+C-CH=CH+ + CrO4^2- + <=>[x][y] + 2.5 Cl^{-.} + 3_1/2 Na*OH_{(aq)} + !(name)( A^n ) "\LaTeXe"} +} + +Now we're going to change different aspects of the font a look what happens: +\begin{beispiel}[below] + \sffamily Hallo \sample \\ + \ttfamily Hallo \sample \normalfont \\ + \bfseries Hallo \sample \normalfont \\ + \itshape Hallo \sample +\end{beispiel} +As you can see most features adapt to the surrounding font. + +If you want to change the default format you need to use this option: +\begin{beschreibung} + \Option{format}{<anything>}\Default{} + Adds arbitrary code before the output of \cmd{ch}. +\end{beschreibung} +\begin{beispiel} + \definecolor{newblue}{rgb}{.1,.1,.5} + \chemsetup[chemformula]{format=\color{newblue}\sffamily} + \sffamily Hallo \sample \\ + \ttfamily Hallo \sample \normalfont \\ + \bfseries Hallo \sample \normalfont \\ + \itshape Hallo \sample +\end{beispiel} + +You can also specifically change the fontfamily, fontseries and fontshape of +the output. +\begin{beschreibung} + \Option{font-family}{<family>}\Default{} + Changes the fontfamily of the output with + \lstinline+\fontfamily{<family>}\selectfont+. + \Option{font-series}{<series>}\Default{} + Changes the fontseries of the output with + \lstinline+\fontseries{<series>}\selectfont+. + \Option{font-shape}{<shape>}\Default{} + Changes the fontshape of the output with + \lstinline+\fontshape{<shape>}\selectfont+. +\end{beschreibung} +\begin{beispiel} + \chemsetup[chemformula]{font-series=bx} + Hallo \sample \\ + \sffamily Hallo \sample \normalfont \\ + \chemsetup[chemformula]{font-family=lmr,font-series=m} Hallo \sample \normalfont \\ + \itshape Hallo \sample +\end{beispiel} + +If you're using \XeLaTeX\ or \LuaLaTeX\ and have loaded \paket{fontspec} you +have the possibilty to set the font with it: +\begin{beschreibung} + \Option{font-spec}{\{<font>\}}\Default{} + or with options + \Option{font-spec}{\{[<options>]<font>\}} +\end{beschreibung} +\begin{beispiel} + \chemsetup[chemformula]{font-spec={Linux Biolinum O}} \sample \\ + \chemsetup[chemformula]{font-spec={Augie}} \sample \\ + \chemsetup[chemformula]{font-spec={Latin Modern Sans}} \sample \\ + \bfseries \sample \normalfont +\end{beispiel} +\secidx*{Format and Font} + +\section{Usage In Math Equations}\secidx{Math Environments} +The \cmd{ch} command can be used inside math equations. It recognizes +\lstinline+\\+ and \lstinline+&+ and passes them on. However, you can't use +the optional arguments of \lstinline+\\+ inside \cmd{ch}. +\begin{beispiel} + \begin{align} + \ch{ + H2O & ->[a] H2SO4 \\ + Cl2 & ->[x][y] CH4 + } + \end{align} + \begin{align*} + \ch{ + RNO2 &<=>[ + e- ] RNO2^{-.} \\ + RNO2^{-.} &<=>[ + e- ] RNO2^2- + } + \end{align*} +\end{beispiel} +\secidx*{Math Environments} + +\section{Further Examples} +This section presents some examples of a possible usage. + +\begin{beispiel} + \begin{reaction}[Synthese von Alkanen] + !(Synthesegas)( $n$ CO + $(2n+1)$ H2 ) + ->[\SI{200}{\celsius}][\[CoNi\]] + C_{$n$}H_{$2n+2$} + $n$ H2O + \end{reaction} +\end{beispiel} + +\begin{beispiel} + \begin{reactions*} + "a)" && CH4 + Cl2 &-> CH3Cl + HCl && "{\small Chlormethan/Methylchlorid}" \\ + "b)" && CH3Cl + Cl2 &-> CH2Cl2 + HCl && "{\small Dichlormethan/Methylenchlorid}" \\ + "c)" && CH2Cl2 + Cl2 &-> CHCl3 + HCl && "{\small Trichlormethan/Chloroform}" \\ + "d)" && CHCl3 + Cl2 &-> CCl4 + HCl && "{\small Tetrachlormethan/Tetrachlorkohlenstoff}" + \end{reactions*} +\end{beispiel} + +\begin{beispiel} + \chemsetup[ox]{parse=false} + \ch{"\ox{\delm,C}" -{} "\ox{\delp,M}" \qquad ( <-> "\ox{\delp,C}" -{} "\ox{\delm,Br}" )} \\ + \ch[adduct-space=0pt]{X. + .Y <=> X-Y + Bindungsenergie} \\ + \ch[name-format=\normalsize]{ + !(\State{H}{f}\qquad)() !(\textcolor{red}{??})( CH4\gas{} ) + + !(\num{0})( 2 O2\gas{} ) + -> + !(\num{-94.3})( CO2\gas{} ) + + !(\num{-57.9})( H2O\lqd{} ) + + !(\num{-192.1})( "\State{H}" ) + } +\end{beispiel} + +\begin{beispiel} + \newcommand\cstack[1]{% + \clap{% + \begin{tabular}{c} + #1 + \end{tabular} + }% + } + \begin{reactions*} + CH3MgBr + "\ox*{1,Cu}" X &-> "\glqq" CH3 "\ox*{1,Cu}\grqq" + MgBrX "\qquad X~$=$~Br,I,CN" \\ + 2 MeLi + CuI &-> !(\cstack{Dimethylcuprat\\(Gilmann-Cuprat)})( Me2CuLi ) + Li + \end{reactions*} +\end{beispiel} + +\begin{beispiel} + % needs `chemfig' + \begin{reactions*} + H3C-CH3 + Cl2 &->[$\Delta$][$h\nu$] H3CCH2Cl + HCl & &"\Enthalpy{-27.1}" \\ + H3C-CH3 + "\Lewis{0.,Cl}" &-> H3CCH2 "\Lewis{0.,\vphantom{H}}" + HCl & &"\Enthalpy{-5.0}" \\ + H3C-CH2 "\Lewis{0.,\vphantom{H}}" + Cl2 &-> H3CCH2Cl + "\Lewis{0.,Cl}" & &"\Enthalpy{-23.0}" + \end{reactions*} +\end{beispiel} + +The following example shows how the cancelling of compounds could be done% +\footnote{Inspired by a question on TeX.SE: \url{http://tex.stackexchange.com/q/30118/5049}}. +\begin{beispiel} + % needs `cancel' + \begin{align*} + \ch{\cancel{HCOOH\aq} + H2O\lqd{} &<=> H3O^+\aq{} + \cancel{HCOO^-\aq}} \\ + \ch{\cancel{HCOO^-\aq} + H2O\lqd{} &<=> \cancel{HCOOH\aq} + OH^-\aq}\\[-1ex] + \cline{1-2} + \ch{H2O\lqd{} + H2O\lqd{} &<=> H3O^+\aq{} + OH^-\aq} + \end{align*} +\end{beispiel} + +\printbibliography + +{\catcode`\^=11 \catcode`\#=11 +\printindex} + +\end{document} |