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 | 2177 |
1 files changed, 1143 insertions, 1034 deletions
diff --git a/Master/texmf-dist/doc/latex/chemmacros/chemformula_en.tex b/Master/texmf-dist/doc/latex/chemmacros/chemformula_en.tex index 2d7864629a1..81fc8b7229c 100644 --- a/Master/texmf-dist/doc/latex/chemmacros/chemformula_en.tex +++ b/Master/texmf-dist/doc/latex/chemmacros/chemformula_en.tex @@ -1,56 +1,133 @@ -% arara: xelatex +% arara: pdflatex % !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/ +% !arara: pdflatex +% arara: pdflatex +% -------------------------------------------------------------------------- +% the CHEMMACROS bundle +% chemformula_en.tex +% macros and commands for chemists +% -------------------------------------------------------------------------- +% Clemens Niederberger +% -------------------------------------------------------------------------- +% https://bitbucket.org/cgnieder/chemmacros/ +% contact@mychemistry.eu +% -------------------------------------------------------------------------- +% If you have any ideas, questions, suggestions or bugs to report, please +% feel free to contact me. +% -------------------------------------------------------------------------- +% Copyright 2011-2013 Clemens Niederberger +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Clemens Niederberger. +% -------------------------------------------------------------------------- +\documentclass[load-preamble+]{cnltx-doc} +\usepackage[greek=newtx]{chemmacros} +\setcnltx{ + package = {chemformula}, + title = \huge the \chemmacros\ bundle, + url = https://bitbucket.org/cgnieder/chemmacros/ , + authors = Clemens Niederberger , + email = contact@mychemistry.eu , + info = { + 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}} , + abstract = {% + \centering + \includegraphics{chemmacros-logo.pdf} + \par + } , + add-cmds = { + abinitio, AddRxnDesc, anti, aq, aqi, + ba, bond, bridge, + cd, ch, charrow, chcpd, chemabove, Chemalpha, Chembeta, Chemgamma, + Chemdelta, ChemDelta, chemformula@bondlength, Chemomega, chemsetup, + chlewis, chname , cip, cis, ch, CNMR, + data, DeclareChemArrow, DeclareChemBond, DeclareChemBondAlias, + 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, + hapto, HNMR, Helmholtz, + insitu, invacuo, iupac, + Ka, Kb, Kw, + Lfi, listofreactions, lqd, ltn, + mch, mega, meta, mhName, + newman, NMR, Nu, Nuc, + orbital, ortho, ox, OX, + para, pch, per, pH, phase, photon, pKa, pKb, pOH, pos, positron, + Pot, prt, + Rad, redox, RenewChemArrow, RenewChemBond, RenewChemIUPAC, + RenewChemLatin, RenewChemNMR, RenewChemParticle, RenewChemPhase, + RenewChemState, + Sf, scrm, scrp, second, setchemformula, ShowChemArrow, ShowChemBond, + sld, Sod, State, + trans, + val + } , + add-silent-cmds = { + addplot, + bottomrule, + cancel, cdot, ce, cee, celsius, centering, chemfig, chemname, clap, + cnsetup, color, cstack, cstsetup, + DeclareInstance, DeclareSIUnit, definecolor, draw, + electronvolt, + footnotesize, + glqq, grqq, + hertz, hspace, + includegraphics, intertext, IUPAC, + joule, + kilo, + latin, lewis, Lewis, + 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, + upbeta, upeta, upgamma, usetikzlibrary, + volt, vphantom, vspave, + xspace + } } -\usepackage{chemfig,booktabs,cancel} +\usepackage{chemfig,booktabs,cancel,varioref} \usepackage[version=3]{mhchem} -\usepackage{fontspec} -\usepackage[oldstyle,proportional]{libertine} +% \usepackage{fontspec} +% \usepackage[oldstyle,proportional]{libertine} \expandafter\def\csname libertine@figurestyle\endcsname{LF} \usepackage[libertine]{newtxmath} \expandafter\def\csname libertine@figurestyle\endcsname{OsF} -\usepackage{libertinehologopatch} -\setmonofont[Scale=MatchLowercase]{Bitstream Vera Sans Mono} +% \usepackage{libertinehologopatch} +% \setmonofont[Scale=MatchLowercase]{Bitstream Vera Sans Mono} % \usepackage{selnolig} -\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 + long-format = \scshape , + short-format = \scshape } \DeclareAcronym{ghs}{ short = ghs , @@ -92,71 +169,59 @@ \chemsetup{ option/synchronize , - chemformula/font-spec={[Numbers=Lining]Linux Libertine O} + chemformula/format = \libertineLF } -\colorlet{chemformula}{darkgray} +% \colorlet{chemformula}{black!90} \sisetup{ detect-mode=false, mode=text, - text-rm=\addfontfeatures{Numbers={Proportional,Lining}} + text-rm=\libertineLF } \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}, + Bertil Holmstr\"om and Kozo Kuchitsu and Roberto Marquardt and Ian Mills and + Franco Pavese and Martin Quack and J\"urgen Stohner and Herbert L. Strauss and + Michio Takami and Anders J Thor} , + title = {``Quantities, Symbols and Units in Physical Chemistry'', \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} , + 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}, + Alan T. Hutton} , + title = {``Nomenclature of Inorganic Chemistry'', \acs{iupac} Red Book} , + sorttitle = {Nomenclature of Inorganic Chemistry} , + indexsorttitle = {Nomenclature of Inorganic Chemistry} , + 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}, + 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}, + 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*} @@ -174,276 +239,192 @@ \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, addplot, 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} +\newpackagename\chemmacros{chemmacros} +% \newpackagename\chemformula{chemformula} +\newpackagename\ghsystem{ghsystem} +\newpackagename\chemgreek{chemgreek} -\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} +\newidxcmd\manual{\textsf{#1}}[\ (manual)] -\newcommand*\Chemgreek{% +\newenvironment{codedesc} {% - \fontspec[Color=main,Scale=1.2] - {Linux Biolinum Shadow O}% - chemgreek% - }% -} -\providecommand*\chemgreek{{\scshape\textcolor{main}{chemgreek}}\xspace} + \def\Code##1{\item\code{##1}\hfill\newline}% + \cnltxlist + } + {\endcnltxlist} \renewcommand*\AmS{\hologo{AmS}} +\newcommand*\TikZ{Ti\textit{k}Z} +\newname\hensel{Martin}{Hensel} \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 +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\ works very similar to \pkg{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 +\section{News} +\subsection{Version 4.0} +Since version 4.0\sinceversion{4.0}, the \chemformula\ package can be used independently from \chemmacros. This means that if you say -\begin{beispiel}[code only] +\begin{sourcecode} \usepackage{chemformula} -\end{beispiel} +\end{sourcecode} then \chemmacros\ will not be loaded. The \chemmacros\ package, however, \emph{will} load \chemformula. +\subsection{Version 4.2} +\begin{itemize} + \item New option \option{arrow-style}. + \item New command \cs{chlewis} that allows to add Lewis electrons to an + atom, see section~\ref{sec:lewis-formulae}. +\end{itemize} + \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). +\license + +The \chemformula\ package needs and thus loads the packages +\bnd{l3kernel}~\cite{bnd:l3kernel}, \pkg{xparse}, \pkg{l3keys2e} and +\pkg{xfrac} (all three are part of the \bnd{l3packages} +bundle~\cite{bnd:l3packages}), +\pkg{tikz}\footnote{\CTANurl[graphics]{pgf}}~\cite{pkg:pgf}, +\pkg{amsmath}~\cite{pkg:amsmath}, \pkg{nicefrac}~\cite{pkg:nicefrac} and +\pkg{scrlfile} (from the \KOMAScript\footnote{\CTANurl{koma-script}} +bundle~\cite{bnd:koma-script}). \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} +\module{chemformula}. This means they can be setup with +\begin{commands} + \command{chemsetup}[\Oarg{chemformula}\marg{options}] + Set up options for \chemformula\ exclusively, or + \command{chemsetup}[\Marg{chemformula/\meta{option1},chemformula/\meta{option2}}] + Set up options for \chemformula\ together with others of \chemmacros' + options. +\end{commands} 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 +\cs{chemsetup} is not available. This is why \chemformula\ also has its own setup command: -\begin{beispiel}[code only] - \setchemformula{<options>} -\end{beispiel} +\begin{commands} + \command{setchemformula}[\marg{options}] + Set up \chemformula\ when using it independently from \chemmacros. +\end{commands} \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} +\begin{commands} + \command{ch}[\oarg{options}\marg{input}] + \chemformula's main command. +\end{commands} +The usage will seem very familiar to you if you're familiar with \pkg{mhchem}: +\begin{example}[side-by-side] + \ch{H2O} \par + \ch{Sb2O3} \par + \ch{H+} \par + \ch{CrO4^2-} \par + \ch{AgCl2-} \par + \ch{[AgCl2]-} \par + \ch{Y^{99}+} \par + \ch{Y^{99+}} \par + \ch{H2_{(aq)}} \par + \ch{NO3-} \par + \ch{(NH4)2S} \par + \ch{^{227}_{90}Th+} \par + $V_{\ch{H2O}}$ \par + \ch{Ce^{IV}} \par + \ch{KCr(SO4)2 * 12 H2O} +\end{example} 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} +\begin{commands} + \command{ch}[\Marg{part1 part2 part3 part4}] +\end{commands} 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} +\begin{example}[side-by-side] + \ch{A + B ->[a] C} \par + \ce{A + B ->[a] C} +\end{example} + +This means that \cs{ch}\Marg{2H2O} is recognized as a \emph{single} part, +which in this case is recognized as a compound. +\begin{example}[side-by-side] + \ch{2H2O} \par + \ch{2 H2O} +\end{example} 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. +output you need to use \verbcode+~+. However, since commands in most cases +gobble a space after them a input like \cs{ch}\Marg{\cs*{command} ABC} will be +treated as a single part. If you want or need to divide them you need to add +an empty group: \cs{ch}\Marg{\cs*{command}\marg{} 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 +There are some options to customize the output of the \cs{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} +module \module{chemformula} and can be set in different ways: +\begin{commands} + \command{chemsetup}[\Oarg{chemformula}\marg{options}] + when loaded via \chemmacros + \command{chemsetup}[\Marg{chemformula/\meta{options}}] + when loaded via \chemmacros + \command{setchemformula}[\marg{options}] + independent from \chemmacros +\end{commands} + +\section{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} +\verbcode+.,_/()+ +\begin{example}[side-by-side] + \ch{2} \par + \ch{12} + + % decimals: + \ch{.5} \par + \ch{5,75} + + % fractions: + \ch{3/2} \par + \ch{1_1/2} - % ``iupac'': - \ch{(1/2)} -\end{beispiel} + % ``iupac'': + \ch{(1/2)} +\end{example} 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} +\begin{sourcecode} + this won't work but will result in an error: \ch{1/1_1} +\end{sourcecode} 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} +\begin{example} + \ch{(1/2) H2O} \ch{1/2 H2O} \ch{0.5 H2O} +\end{example} You can find many examples like the following for stoichiometric factors in parentheses in the \acs{iupac} Green Book~\cite{iupac:greenbook}: \begin{reaction*} @@ -451,568 +432,581 @@ parentheses in the \acs{iupac} Green Book~\cite{iupac:greenbook}: \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{frac-math-cmd}{<command sequence>}\Default{\cmd*{frac}} - \sinceversion{4.1}Allows you to choose which command is used with - \key{frac-style}{math}. This needs to be a command sequence that takes two - arguments that are set in math mode. - \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 +\begin{options} + \keyval{decimal-marker}{marker}\Default{.} + The symbol to indicate the decimal. + \keychoice{frac-style}{math,xfrac,nicefrac}\Default{math} + Determines how fractions are displayed. + \keyval{frac-math-cmd}{command sequence}\Default{\cs*{frac}} + \sinceversion{4.1}Allows you to choose which command is used with + \keyis{frac-style}{math}. This needs to be a command sequence that takes + two arguments that are set in math mode. + \keyval{stoich-space}{skip}\Default{.1667em plus .0333em minus .0117em} + The space that is placed after the stoichiometric factor. A rubber + length. + \keybool{stoich-paren-parse}\Default{false} + If set to true stoichiometric factors enclosed by parentheses also are + parsed. +\end{options} + +\begin{example} + \ch[decimal-marker={,}]{3.5} \ch[decimal-marker={$\cdot$}]{3,5} +\end{example} + +The option \keyis{frac-style}{xfrac} uses the \verbcode+\sfrac+ command of the +\pkg{xfrac} package. The output strongly depends on the font you use. +\begin{example} + \ch[frac-style=xfrac]{3/2} \ch[frac-style=xfrac]{1_1/2} +\end{example} +\chemformula\ defines the instance \verbcode=formula-text-frac= which you can +redefine to your needs. See the \pkg{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} +\begin{sourcecode} + \DeclareInstance{xfrac}{chemformula-text-frac}{text} + { + slash-left-kern = -.15em , + slash-right-kern = -.15em + } +\end{sourcecode} 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} +\begin{sourcecode} + \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{sourcecode} + +The option \keyis{frac-style}{nicefrac} uses the \verbcode+\nicefrac+ command +of the \pkg{nicefrac} package. +\begin{example} + \ch[frac-style=nicefrac]{3/2} \ch[frac-style=nicefrac]{1_1/2} +\end{example} + +The option \option{stoich-space} allows you to customize the space between +stoichiometric factor and the group following after it. +\begin{example}[side-by-side] + \ch{2 H2O} \par + \ch[stoich-space=.3em]{2 H2O} +\end{example} + +\section{Compounds}\label{ssec: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} +\begin{example}[side-by-side] + \ch{H2SO4} \par + \ch{[Cu(NH3)4]^2+} +\end{example} -\subsection{Adducts}\secidx[adducts]{Compounds} +\subsection{Adducts} \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} +\begin{commands} + \command{ch}[\Marg{A.B}] \ch{A.B} + \command{ch}[\Marg{A*B}] \ch{A*B} +\end{commands} +\begin{example}[side-by-side] + \ch{CaSO4.H2O} \par + \ch{CaSO4*H2O} +\end{example} 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} +\begin{example}[side-by-side] + \ch{Na3PO4*12H2O} \par + \ch{Na3PO4* 12 H2O} \par + \ch{Na3PO4 * 12 H2O} +\end{example} -\subsection{Subscripts}\label{ssec:subscripts}\secidx[subscripts]{Compounds} +\subsection{Subscripts}\label{ssec:subscripts} \emph{All} numbers in a compound are treated as subscripts. -\begin{beispiel} - \ch{H2SO4} -\end{beispiel} +\begin{example}[side-by-side] + \ch{H2SO4} +\end{example} If you want a letter to be a subscript you can use the math syntax: -\begin{beispiel} - \ch{A_nB_m} -\end{beispiel} +\begin{example}[side-by-side] + \ch{A_nB_m} +\end{example} The subscript recognizes groups. You can also use math inside it. -\begin{beispiel} - \ch{A_{$n$}B_{$m$}} \\ - \ch{NaCl_{(aq)}} -\end{beispiel} +\begin{example}[side-by-side] + \ch{A_{$n$}B_{$m$}} \par + \ch{NaCl_{(aq)}} +\end{example} -\subsection{Commands}\secidx[commands]{Compounds} +\subsection{Commands} Commands are allowed in a compound: -\begin{beispiel} - \ch{\textbf{A2}B3} \ch{A2\color{red}B3} -\end{beispiel} +\begin{example}[side-by-side] + \ch{\textbf{A2}B3} \ch{A2\color{red}B3} +\end{example} However, if the commands demand numbers as argument, \eg, space commands or -\chemmacros' \lstinline+\ox+ command the direct use will fail. This is +\chemmacros' \verbcode+\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] +\begin{sourcecode} \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} +\end{sourcecode} See section~\ref{ssec:text} for a way around this. -\subsection{Charges and Other Superscripts}\secidx[charges]{Compounds}\secidx[superscripts]{Compounds} +\subsection{Charges and Other Superscripts} \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} +\begin{example}[side-by-side] + \ch{A+B} \ch{AB+} \par + \ch{A-B} \ch{AB-} +\end{example} 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} +\begin{example}[side-by-side] + \ch{A^{x-}} \par + \ch{A^x-} \par + \ch{A^{x}-} \par + \ch{A^{$x-$}} \par + \ch{RNO2^{-.}} \par + \ch{^31H} \par + \ch{^{14}6C} \par + \ch{^{58}_{26}Fe} \par + \ch{NO^*} +\end{example} 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} +\begin{example}[side-by-side] + \ch{SO4^2-} \ch{Ca^2+ SO4^2-} +\end{example} -\paragraph{Charge Commands}\secidx[superscripts!charge commands]{Compounds} -You don't need to use \cmd{mch} and related commands inside \cmd{ch}. Indeed, +\paragraph{Charge Commands} +You don't need to use \cs{mch} and related commands inside \cs{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} +\cs{ch}. +\begin{example} + \chemsetup[option]{circled=all} + \ch{H+ + OH- <=> H2O} +\end{example} -\paragraph{Behaviour}\secidx[superscripts!behaviour]{Compounds} +\paragraph{Behaviour} 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{example} + \ch{^33B} \ch{{}^33B} \ch{3^3B} \ch{B^3} \ch{B3^3} \par + \ch{^{23}_{123}B} \ch{{}^{23}_{123}B} \ch{_{123}^{23}B} + \ch{B^{23}} \ch{B_{123}^{23}} \par + \ch{^{123}_{23}B} \ch{{}^{123}_{23}B} \ch{_{23}^{123}B} + \ch{B^{123}} \ch{B23^{123}} +\end{example} \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. + \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}}}] +\begin{cnltxquote}[{\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} + \ch[charge-hshift=full]{SO4^2-}, \ch{(SO4)^2-}. The staggered arrangement + is now recommended. +\end{cnltxquote} -\subsection{Bonds}\label{ssec:bonds}\secidx[bonds]{Compounds} +\subsection{Bonds}\label{ssec:bonds} \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} +\begin{example}[side-by-side] + single: \ch{CH3-CH3} \par + double: \ch{CH2=CH2} \par + triple: \ch{CH+CH} +\end{example} \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{commands} + \command{bond}[\marg{bond name}] + Prints the bond type specified by \meta{bond name}. +\end{commands} +The predefined bond types are shown in table~\vref{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} + \centering + \caption{Bonds available with \cs*{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} +\begin{example} + \ch{C\bond{sb}C\bond{db}C\bond{tp}C\bond{deloc}C\bond{tdeloc}C\bond{co>}C\bond{<co}C} +\end{example} \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} +\begin{commands} + \command{DeclareChemBond}[\marg{name}\marg{code}] + Define the new bond type \meta{name}. + \command{RenewChemBond}[\marg{name}\marg{code}] + Redefine the existing bond type \meta{name}. + \command{DeclareChemBondAlias}[\marg{new name}\marg{old name}] + Declare the bond type \meta{new name} to be an alias of \meta{old name}. + \command{ShowChemBond}[\marg{name}] + Print the definition of bond type \meta{name}. +\end{commands} 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} +\begin{sourcecode} + \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{sourcecode} 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}. +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} +\begin{example} + \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{example} + +The last example showed you another macro: \verbcode+\chemformula@bondlength+. +It only exists so you can use it to access the bond length as set with +\option{bond-length} directly. + +\subsection{Customization}\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{bond-penalty}{<num>}\Default{10000} - \sinceversion{4.0a}The penalty that is inserted after a bond for - (dis-)allowing line breaks. - \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} +\begin{options} + \keyval{subscript-vshift}{dim}\Default{0pt} + Extra vertical shift of the subscripts. + \keychoice{subscript-style}{text,math}\Default{text} + Style that is used to typeset the subscripts. + \keyval{charge-hshift}{dim}\Default{.25em} + Shift of superscripts when following a subscript.\label{desc:charge-hshift} + \keyval{charge-vshift}{dim}\Default{0pt} + Extra vertical shift of the superscripts. + \keychoice{charge-style}{text,math}\Default{text} + Style that is used to typeset the superscripts. + \keyval{adduct-space}{dim}\Default{.1333em} + Space to the left and the right of the adduct point. + \keyval{bond-length}{dim}\Default{.5833em} + The length of the bonds. + \keyval{bond-offset}{dim}\Default{.07em} + Space between bond and atoms. + \keyval{bond-style}{\TikZ}\Default + \TikZ\ options for the bonds. + \keyval{bond-penalty}{num}\Default{10000} + \sinceversion{4.0a}The penalty that is inserted after a bond for + (dis-)allowing line breaks. + \keyval{radical-style}{\TikZ}\Default + \TikZ\ options for the radical point. + \keyval{radical-radius}{dim}\Default{.2ex} + The radius of the radical point. + \keyval{radical-hshift}{dim}\Default{.15em} + Horizontal shift before the radical point is drawn. + \keyval{radical-vshift}{dim}\Default{.5ex} + Vertical shift relative to the current baseline. + \keyval{radical-space}{dim}\Default{.15em} + Horizontal shift after the radical point is drawn. +\end{options} 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} +right. +\begin{example}[side-by-side] + \ch{SO4^2-} \ch{NH4+} \ch{Na+} +\end{example} 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} +\begin{example} + \ch{SO4^2-} \ch{NH4+} \ch{Na+} \par + \chemsetup[chemformula]{charge-hshift=.5ex} + \ch{SO4^2-} \ch{NH4+} \ch{Na+} \par + \chemsetup[chemformula]{charge-hshift=.5pt} + \ch{SO4^2-} \ch{NH4+} \ch{Na+} +\end{example} 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} +\keyis{charge-hshift}{full}. +\begin{example} + \ch[charge-hshift=0pt]{C5H11+} \ch[charge-hshift=0pt]{SO4^2-} \par + \ch{C5H11+} \ch{SO4^2-} \par + \ch[charge-hshift=1ex]{C5H11+} \ch[charge-hshift=1ex]{SO4^2-} \par + \ch[charge-hshift=full]{C5H11+} \ch[charge-hshift=full]{SO4^2-} +\end{example} 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} +\begin{example} + \ch{M^x+} \ch{SO4^2-} \par + \chemsetup[chemformula]{charge-style = math} + \ch{M^x+} \ch{SO4^2-} +\end{example} + +The option \option{subscript-vshift} can be used to adjust the vertical shift +of the subscripts: +\begin{example} + \ch{H2SO4} \ch{Na3PO4} \par + \chemsetup[chemformula]{subscript-vshift=.5ex} + \ch{H2SO4} \ch{Na3PO4} \par + \chemsetup[chemformula]{subscript-vshift=-.2ex} + \ch{H2SO4} \ch{Na3PO4} +\end{example} 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} +\begin{example} + \ch{A_nB_m} \ch{H2SO4} \par + \chemsetup[chemformula]{subscript-style = math} + \ch{A_nB_m} \ch{H2SO4} +\end{example} -The option \key{adduct-space} sets the space left and right to the adduct +The option \option{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} +\begin{example} + \ch{Na3PO3*H2O} \par + \chemsetup[chemformula]{adduct-space=.2em} + \ch{Na3PO3*H2O} +\end{example} + +Changing the length of the bonds: +\begin{example} + \chemsetup[chemformula]{bond-length=4mm}% + single: \ch{CH3-CH3} \par + double: \ch{CH2=CH2} \par + triple: \ch{CH+CH} +\end{example} 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} +\begin{example} + \ch{H-H + N+N + O=O} \par + \ch[bond-offset=1pt]{H-H + N+N + O=O} +\end{example} + +\subsection{Standalone Formulae} +\chemformula\sinceversion{4.0} offers a command that \emph{only accepts} the +\enquote{compound} input type: +\begin{commands} + \command{chcpd}[\oarg{options}\marg{compound}] + Typeset single compounds. +\end{commands} + +\section{Special Input Types} There are some \enquote{special type} input groups. -\subsection{Single Token Groups}\secidx[single token groups]{Special Types} +\subsection{Single Token Groups} 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} +\begin{commands} + \command{ch}[\marg{ + } \ch{ + }] + Creates the plus sign between compounds with space around it:\\ + \cs{ch}\Marg{2 Na + Cl2} \ch{2 Na + Cl2} + \command{ch}[\Marg{ v } \ch{ v }] + Sign for precipitate: \cs{ch}\Marg{BaSO4 v} \ch{BaSO4 v} + \command{ch}[\Marg{ \textasciicircum\ } \ch{ ^ }] + Sign for escaping gas\footnotemark: \cs{ch}\Marg{H2 \textasciicircum} + \ch{H2 ^} +\end{commands} \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. - \Option{plus-penalty}{<num>}\Default{700} - \sinceversion{4.0a}The penalty that is inserted after the plus sign for - (dis-)allowing line breaks. -\end{beschreibung} -\begin{beispiel} - \ch{A + B}\\ - \ch[plus-space=4pt]{A + B} -\end{beispiel} - -\subsection{Option Input}\secidx[option input]{Special Types} +\begin{options} + \keyval{plus-space}{skip}\Default{.3em plus .1em minus .1em} + A rubber length. + \keyval{plus-penalty}{num}\Default{700} + \sinceversion{4.0a}The penalty that is inserted after the plus sign for + (dis-)allowing line breaks. +\end{options} +\begin{example}[side-by-side] + \ch{A + B}\par + \ch[plus-space=4pt]{A + B} +\end{example} + +\subsection{Option Input} 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} +reaction. Of course you have the possibility to use \cs{ch} several times. +\begin{example} + \ch{H2O +}\textcolor{red}{\ch{H2SO4}}\ch{-> H3O+ + HSO4-} \par + \ch{H2O +}\ch[subscript-vshift=2pt]{H2SO4}\ch{-> H3O+ + HSO4-} +\end{example} 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} +\begin{commands} + \command{ch}[\Marg{ @\marg{options} }] + The options specified this way will be valid \emph{only} until the next + compound is set. +\end{commands} +\begin{example} + \ch{H2O +}\textcolor{red}{\ch{H2SO4}}\ch{-> H3O+ + HSO4-} \par + \ch{H2O + @{format=\color{red}} H2SO4 -> H3O+ + HSO4-} \par + or of course:\par + \ch{H2O + \textcolor{red}{H2SO4} -> H3O+ + HSO4-}\par\bigskip + \ch{H2O +}\ch[subscript-vshift=2pt]{H2SO4}\ch{-> H3O+ + HSO4-} \par + \ch{H2O + @{subscript-vshift=2pt} H2SO4 -> H3O+ + HSO4-} +\end{example} + +\section{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 +\subsection{Text}\label{ssec:text} +If you put something between \verbcode+" "+ or \verbcode+' '+ 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} +be input with \verbcode+~+. +\begin{commands} + \command{ch}[\Marg{ "\meta{escaped text}" }] + One of two possibilities to \emph{escape} \chemformula's parsing. + \command{ch}[\Marg{ '\meta{escaped text}' }] + The second of two possibilities to \emph{escape} \chemformula's parsing. +\end{commands} +\begin{example} + \ch{"\ox{2,Ca}" O} \par + \ch{"\ldots\," Na + "\ldots\," Cl2 -> "\ldots\," NaCl} \par + \ch{'A~->~B'} +\end{example} 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. +trouble when using a command inside \cs{ch} try hiding it. -\subsection{Math}\secidx[math]{Escaped Input} -If you especially want to input math you just enclose it with \lstinline+$ $+. +\subsection{Math} +If you especially want to input math you just enclose it with \verbcode+$ $+. 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} +\begin{commands} + \command{ch}[\Marg{ \string$\meta{escaped math}\string$ }] + One of two possibilities to \emph{escape} \chemformula's parsing into math + mode. + \command{ch}[\Marg{ \string\(\meta{escaped math}\string\) }] + The second of two possibilities to \emph{escape} \chemformula's parsing + into math mode. +\end{commands} +\begin{example}[side-by-side] + escaped text: \ch{"$x$" H2O} \par + escaped math: \ch{$x$ H2O} \par + also escaped math: \ch{\(x\) H2O} \par + \ch{$2n$ Na + $n$ Cl2 -> $2n$ NaCl} +\end{example} The space that is inserted after a math group can be edited: -\begin{beschreibung} - \Option{math-space}{<skip>}\Default{.1667em plus .0333em minus .0117em} +\begin{options} + \keyval{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}. +\end{options} +\begin{example} + \ch{$2n$ Na + $n$ Cl2 -> $2n$ NaCl} \par + \chemsetup[chemformula]{math-space=.25em} + \ch{$2n$ Na + $n$ Cl2 -> $2n$ NaCl} \par + \ch{$A->B$} +\end{example} + +\section{Arrows}\label{sec:arrows} +\subsection{Arrow types} +Arrows are input in the same intuitive way they are with \pkg{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} +\begin{commands} + \command{ch}[\Marg{ -> } \ch{->}] + standard right arrow + \command{ch}[\Marg{ <- } \ch{<-}] + standard left arrow + \command{ch}[\Marg{ -/> } \ch{-/>}] + does not react (right) + \command{ch}[\Marg{ </- } \ch{</-}] + does not react (left) + \command{ch}[\Marg{ <-> } \ch{<->}] + resonance arrow + \command{ch}[\Marg{ <> } \ch{<>}] + reaction in both directions + \command{ch}[\Marg{ == } \ch{==}] + stoichiometric equation + \command{ch}[\Marg{ <=> } \ch{<=>}] + equilibrium arrow + \command{ch}[\Marg{ <=>> } \ch{<=>>}] + unbalanced equilibrium arrow to the right + \command{ch}[\Marg{ <<=> } \ch{<<=>}] + unbalanced equilibrium arrow to the left + \command{ch}[\Marg{ <o> } \ch{<o>}] + isolobal arrow +\end{commands} 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} +\begin{example} + \ch{H2 + Cl2 -> 2 HCl} \par + \ch{H2O + CO3^2- <=> OH- + HCO3-} \par + \ch{A <- B} \par + \ch{\{[CH2=CH-CH2]- <-> {}[CH2-CH=CH2]- \}} \par + \ch{A <> B} \par + \ch{H+ + OH- <=>> H2O} \par + \ch{2 NO2 <<=> N2O4} +\end{example} + +\subsection{Labels} 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} +\begin{commands} + \command{ch}[\Marg{ ->[\meta{above}][\meta{below}] }] + Add text above or under an arrow. +\end{commands} +\begin{example}[side-by-side] + \ch{A ->[a] B} \par + \ch{A ->[a][b] B} \par + \ch{A ->[\SI{100}{\celsius}] B} +\end{example} 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} +\begin{example}[side-by-side] + \ch{A ->[H2O] B} \par + \ch{A ->[ H2O ] B} \par + \ch{A ->[ "\ox{2,Ca}" F2 ] B} \par + \ch{A ->[$\Delta$,~ \[H+ \]] B} +\end{example} % TODO: correct info about [] If you leave the blanks \chemformula\ treats the groups inside the square @@ -1020,180 +1014,210 @@ 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} +arguments should be produced using \cs*{[} and \cs*{]}. They keep their usual +meaning outside \cs{ch}. These commands are necessary since the usual +grouping (\ie, hiding the brackets inside curly brackets) doesn't work due to +the way \cs{ch} reads its argument. +\begin{example} + \ch{A ->[a] B} \par + \ch{A ->[ab] B} \par + \ch{A ->[abc] B} \par + \ch{A ->[abc~abc] B} \par + % needs the `chemfig' package: + \setatomsep{15pt} + \ch{A ->[ "\chemfig{-[:30]-[:-30]OH}" ] B} \par + \ch{A ->[[]] B} vs. \ch{A ->[\[\]] B} +\end{example} + +\subsection{Customization} 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} - \sinceversion{3.6b}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. - \Option{arrow-penalty}{<num>}\Default{0} - \sinceversion{4.0a}The penalty that is inserted after an arrow for - (dis-)allowing line breaks. -\end{beschreibung} - -The following code shows the effect of the different options on the \lstinline+<=>>+ +\begin{options} + \keyval{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}. + \keyval{arrow-min-length}{dim}\Default{0pt} + \sinceversion{3.6b}The minimal length an error must have unless two times + \key{arrow-offset} plus the width of the label is larger. + \keyval{arrow-yshift}{dim}\Default{0pt} + Shifts an arrow up (positive value) or down (negative value). + \keyval{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. + \keyval{compound-sep}{dim}\Default{.5em} + The space between compounds and the arrows. + \keyval{label-offset}{dim}\Default{2pt} + The space between the labels and the arrows. + \keyval{label-style}{font command}\Default{\cs*{footnotesize}} + The relative font size of the labels. + \keyval{arrow-penalty}{num}\Default{0} + \sinceversion{4.0a}The penalty that is inserted after an arrow for + (dis-)allowing line breaks. + \keyval{arrow-style}{\TikZ}\Default + \sinceversion{4.1a}Additonal \TikZ\ keys for formatting the arrows. +\end{options} + +The following code shows the effect of the different options on the \verbcode+<=>>+ 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} +\begin{example} + standard: \ch{A <=>>[x][y] B} \par + longer: \ch[arrow-offset=12pt]{A <=>>[x][y] B} \par + higher: \ch[arrow-yshift=2pt]{A <=>>[x][y] B} \par + more balanced: \ch[arrow-ratio=.8]{A <=>>[x][y] B} \par + labels further away: \ch[label-offset=4pt]{A <=>>[x][y] B} \par + larger distance to compounds: \ch[compound-sep=2ex]{A <=>>[x][y] B} \par + smaller labels: \ch[label-style=\tiny]{A <=>[x][y] B} +\end{example} + +\subsection{Modify Arrow Types}\label{sec:arrows_modify} 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 +\begin{commands} + \command{DeclareChemArrow}[\marg{type}\marg{\TikZ}] + Define a new arrow type \meta{type}. +\end{commands} +\meta{type} 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} +\begin{sourcecode} + \DeclareChemArrow{->}{ + \draw[chemarrow,-cf] (cf_arrow_start) -- (cf_arrow_end) ; + } +\end{sourcecode} 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} +\TikZ\footnote{Please see the \manual{pgfmanual} for details.}. The +predefined arrows use the arrow tips \code{cf}, \code{left cf} and \code{right + cf}. They also all except the net reaction arrow \code{==} use the +\TikZ-style \code{chemarrow} that you should use, too, if you want the option +\option{arrow-style} to have an effect. + +There are some predefined coordinates you can and should use. For +completeness' sake the arrow tips and the \TikZ-style are also listed: +\begin{codedesc} + \Code{(cf\_arrow\_start)} + The beginning of the arrow. + \Code{(cf\_arrow\_end)} + The end of the arrow. + \Code{(cf\_arrow\_mid)} + The mid of the arrow. + \Code{(cf\_arrow\_mid\_start)} + The beginning of the shorter arrow in types like \verbcode+<=>>+. + \Code{(cf\_arrow\_mid\_end)} + The end of the shorter arrow in types like \verbcode+<=>>+. + \Code{cf} + A double-sided arrow tip. + \Code{left cf} + A left-sided arrow tip. + \Code{right cf} + A right-sided arrow tip. + \Code{chemarrow} + \chemformula's \TikZ-style that is applied to the arrows and set with + \option{arrow-style} +\end{codedesc} +\begin{example} + \DeclareChemArrow{.>}{ + \draw[chemarrow,-cf,dotted,red] (cf_arrow_start) -- (cf_arrow_end); + } + \DeclareChemArrow{n>}{ + \draw[chemarrow,-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{example} 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} +\begin{commands} + \command{RenewChemArrow}[\marg{type}\marg{\TikZ}] + Redefine the arrow type \meta{type}. + \command{ShowChemArrow}[\marg{type}] + Print out the current definition of the arrow type \meta{type}. +\end{commands} 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} +\begin{example} + \texttt{\ShowChemArrow{->}} \par + \RenewChemArrow{->}{\draw[chemarrow,->,red] (cf_arrow_start) -- (cf_arrow_end) ;} + \texttt{\ShowChemArrow{->}} \par + \ch{A -> B} +\end{example} + +\subsection{Standalone Arrows} +\chemformula\ offers\sinceversion{4.0} a command that \emph{only accepts} the +\enquote{arrow} input type: +\begin{commands} + \command{charrow}[\marg{type}\oarg{above}\oarg{below}] + Print the arrow type \meta{type}. +\end{commands} +This command is internally used for the arrows, too, when \cs{ch} is parsed. + +\section{Names} +\subsection{Syntax} \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} +\begin{commands} + \command{ch}[\Marg{ !(\meta{text})( \meta{formula} ) }] + Writes \meta{text} below \meta{formula}. +\end{commands} If an exclamation mark is followed by a pair of parentheses \chemformula\ will parse it this way: -\begin{beispiel} - \ch{!(ethanol)( CH2CH2OH )} -\end{beispiel} +\begin{example} + \ch{!(ethanol)( CH2CH2OH )} +\end{example} 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} +\begin{example} + \ch{!(water)(H2O)} \quad + \ch{!( "\textcolor{blue}{water}" )( H2O )} \quad + \ch{!( $2n-1$ )( H2O )} \quad + \ch{!( H2O )( H2O )} \quad + \ch{!(oxonium)( H3O+ )} +\end{example} 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 +\begin{example}[side-by-side] + \ch{H2O~(!)} \par + \ch{A!{}()} +\end{example} -\subsection{Customization}\secidx[customization]{Names} +\subsection{Customization} \chemformula\ provides two options to customize the output of the names: -\begin{beschreibung} - \Option{name-format}{<commands>}\Default{\cmd*{scriptsize}\cmd*{centering}} +\begin{options} + \keyval{name-format}{commands}\Default{\cs*{scriptsize}\cs*{centering}} The format of the name. This can be arbitrary input. - \Option{name-width}{<dim>|auto}\Default{auto} + \keychoice{name-width}{\meta{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} +\end{options} +\begin{example} + \ch{!(acid)( H2SO4 ) -> B} \par + \ch[name-format=\sffamily\small]{!(acid)( H2SO4 ) -> B} \par + \ch[name-format=\scriptsize N:~]{!(acid)( H2SO4 ) -> B} \par + \ch[name-width=3em,name-format=\scriptsize\raggedright]{!(acid)( H2SO4 ) -> B} +\end{example} + +\subsection{Standalone Names} +\chemformula\ offers a command\sinceversion{4.0} 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{commands} + \command{chname}[\darg{text~1}\darg{text~2}] + The command that is useed internally for placing \meta{text~1} below of + \meta{text~2}. +\end{commands} + +\section{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} +\begin{example}[pre-output={\biolinumLF\libertineLF\chemsetup{chemformula/format=}}] + \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{example} \newcommand*\sample{% \ch{H2C-C+C-CH=CH+ + CrO4^2- <=>[x][y] @@ -1201,184 +1225,269 @@ all features: } 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} +\begin{example}[pre-output={\biolinumLF\libertineLF\chemsetup{chemformula/format=}}] + \sffamily Hallo \sample \\ + \ttfamily Hallo \sample \normalfont \\ + \bfseries Hallo \sample \normalfont \\ + \itshape Hallo \sample +\end{example} 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} +\begin{options} + \keyval{format}{anything}\Default + Adds arbitrary code before the output of \cs{ch}. +\end{options} +\begin{example}[pre-output={\biolinumLF\libertineLF\chemsetup{chemformula/format=}}] + \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{example} 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 +\begin{options} + \keyval{font-family}{family}\Default + Changes the fontfamily of the output with \cs*{fontfamily}\marg{family}. + \keyval{font-series}{series}\Default + Changes the fontseries of the output with \cs*{fontseries}\marg{series}. + \keyval{font-shape}{shape}\Default + Changes the fontshape of the output with \cs*{fontshape}\marg{shape}. +\end{options} +\begin{example}[pre-output={\biolinumLF\libertineLF\chemsetup{chemformula/format=}}] + \chemsetup[chemformula]{font-series=bx} + Hallo \sample \par + \sffamily Hallo \sample \normalfont \par + \chemsetup[chemformula]{font-family=lmss,font-series=m} Hallo \sample + \normalfont \par + \itshape Hallo \sample +\end{example} + +If you're using \XeLaTeX\ or \LuaLaTeX\ and have loaded \pkg{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} +\begin{options} + \keyval{font-spec}{font}\Default + Use font \meta{font} for \chemformula's formulas. +\end{options} +or with options +\begin{options} + \keychoice{font-spec}{\Marg{[\meta{options}]\meta{font}}} + Use font \meta{font} with options \meta{options} for \chemformula's + formulas. +\end{options} +Since this document is typeset with \pdfLaTeX\ the option cannot be +demonstrated here. + +\section{Usage In Math Equations} +The \cs{ch} command can be used inside math equations. It recognizes +\verbcode+\\+ and \verbcode+&+ and passes them on. However, you can't use the +optional arguments of \verbcode+\\+ inside \cs{ch}. +\begin{example} + \begin{align} + \ch{ + H2O & ->[a] H2SO4 \\ + Cl2 & ->[x][y] CH4 + } + \end{align} + \begin{align*} \ch{ - H2O & ->[a] H2SO4 \\ - Cl2 & ->[x][y] CH4 + RNO2 &<=>[ + e- ] RNO2^{-.} \\ + RNO2^{-.} &<=>[ + e- ] RNO2^2- } - \end{align} - \begin{align*} - \ch{ - RNO2 &<=>[ + e- ] RNO2^{-.} \\ - RNO2^{-.} &<=>[ + e- ] RNO2^2- - } - \end{align*} -\end{beispiel} -\secidx*{Math Environments} - -\section{Usage with \TikZ{} or \paket*{pgfplots} and externalization} -\sinceversion{4.1} -\noindent -Since \chemformula{} uses \TikZ{} to draw reaction arrows and bonds they would -be externalized, too, if you use that facility with \TikZ{} or -\paket{pgfplots}\footnote{\CTANurl{pgfplots}}. This may not be desirable -since they are very small pictures maybe containing of a single line. This is -why \chemformula's default behaviour is to disable externalization for it's -bonds and arrows. This can be turned on and off through the following option: -\begin{beschreibung} - \Option{tikz-external-disable}{\default{true}|false}\Default{true} + \end{align*} +\end{example} + +\section{Usage with \TikZ{} or \pkg*{pgfplots} and externalization} +Since \chemformula{} uses\sinceversion{4.1} \TikZ{} to draw reaction arrows +and bonds they would be externalized, too, if you use that facility with +\TikZ{} or \needpackage{pgfplots}~\cite{pkg:pgfplots}. This may not be +desirable since they are very small pictures maybe containing of a single +line. This is why \chemformula's default behaviour is to disable +externalization for it's bonds and arrows. This can be turned on and off +through the following option: +\begin{options} + \keybool{tikz-external-disable}\Default{true} dis- or enable \TikZ' externalization mechanism for \chemformula's arrows and bonds. -\end{beschreibung} +\end{options} If you should be using a formula that contains bonds or arrows inside of a \code{tikzpicture} that is externalized you should locally enable it for \chemformula, too: -\begin{beispiel}[code only] +\begin{sourcecode} \begin{tikzpicture} \setchemformula{tikz-external-disable=false} \begin{axis}[xlabel={\ch{2 H+ + 2 e- -> H2}}] \addplot ... ; \end{axis} \end{tikzpicture} -\end{beispiel} +\end{sourcecode} + +\section{Lewis Formulae}\label{sec:lewis-formulae} +\chemformula\ offers\sinceversion{4.2} a command to typeset Lewis formulae. +This does not mean Lewis structures! Those can be achieved using the +\pkg{chemfig} package~\cite{pkg:chemfig}. \chemformula\ provides the +possibility to draw electrons as dots and pairs of dots or a line around an +atom. + +\begin{commands} + \command{chlewis}[\oarg{options}\marg{electron spec}\marg{atom}] + Draws electrons around the \meta{atom} according to \meta{electron spec}. +\end{commands} + +Electrons are specified by the angle to the horizontal in the couter-clockwise +direction. The default appearance is a pair of electrons drawn as a pair of +dots. Other specifications can be chosen. The specification follows the +pattern \meta{angle}\meta{separator}. \meta{angle} is a positiv or negativ +integer denoting the angle counter clockwise to the horizontal where the +electrons should be drawn. \meta{separator} is either a dot (\code{.}, single +electron), a colon (\code{:}, electron pair), a vertical line (\code{|}, +electron pair), an o (\code{o}, empty pair), or a comma (\code{,} default +spec). + +\begin{commands} + \command{chlewis}[\Marg{\meta{angle1}\meta{type1}\meta{angle2}\meta{type2}}% + \marg{atom}] + For example: \cs{chlewis}\Marg{0,180}\Marg{O} gives \chlewis{0,180}{O} and + \cs{chlewis}\Marg{0.90.180.270.}\Marg{C} gives + \chlewis{0.90.180.270.}{C}. +\end{commands} + +The appearance can be influenced by a number of options: +\begin{options} + \keychoice{lewis-default}{.,:,|,o,single,pair,pair (dotted),pair + (line),empty}\Default{pair} + Sets the default type that is used when no type is given in \meta{electron + spec}. + \keyval{lewis-distance}{dim}\Default{1ex} + The distance of two electrons in a pair. + \keyval{lewis-line-length}{dim}\Default{1.5ex} + The length of the line representing an electron pair. + \keyval{lewis-line-width}{dim}\Default{1pt} + The thickness of a line representing an electron pair. + \keyval{lewis-offset}{dim}\Default{.5ex} + The distance of the symbols from the atom. +\end{options} +The dots are drawn according to the \option{radical-radius} option mentioned +in section~\ref{ssec:compounds:customization}. + +The basic usage should be more or less self-explaining: +\begin{example}[side-by-side] + \chlewis{0:90|180.270}{O} + \quad + \chlewis{45,135}{O} + \quad + \chlewis{0o}{Na} +\end{example} + +The next example shows the effect of some of the options: +\begin{example} + \chlewis[lewis-default=.]{23,68,113,158,203,248,293,338}{X} + \quad + \chlewis{0,90,180,270}{X} + \quad + \chlewis[lewis-distance=1.25ex]{0,90,180,270}{X} + \quad + \chlewis[lewis-distance=.75ex,radical-radius=.5pt]{0,90,180,270}{X} + \quad + \chlewis[ + radical-radius=.5pt, + lewis-default=. + ]{23,68,113,158,203,248,293,338}{X} +\end{example} + +\begin{example} + \ch{ + !($1s^22s^1$)( "\chlewis{180.}{Li}" ) + + !($1s^22s^22p^5$)( "\chlewis{0.90,180,270}{F}" ) + -> + !($1s^2$)( Li+ ) + !($1s^22s^22p^6$)( "\chlewis{0,90,180,270}{F}" {}- ) + } +\end{example} \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} +\begin{example} + \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{example} + +\begin{example} + \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{example} + +\begin{example} + \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{example} + +\begin{example} + \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{example} + +\begin{example} + % 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{example} + +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{example} + % 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{example} \end{document} |