summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/chemmacros/chemmacros-manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/chemmacros/chemmacros-manual.tex')
-rw-r--r--macros/latex/contrib/chemmacros/chemmacros-manual.tex327
1 files changed, 182 insertions, 145 deletions
diff --git a/macros/latex/contrib/chemmacros/chemmacros-manual.tex b/macros/latex/contrib/chemmacros/chemmacros-manual.tex
index 3504f8cfa8..c099679864 100644
--- a/macros/latex/contrib/chemmacros/chemmacros-manual.tex
+++ b/macros/latex/contrib/chemmacros/chemmacros-manual.tex
@@ -1,35 +1,34 @@
-% arara: pdflatex: { interaction: nonstopmode }
-% arara: biber
-% arara: pdflatex: { interaction: nonstopmode }
-% arara: pdflatex: { interaction: nonstopmode }
% --------------------------------------------------------------------------
-% the CHEMMACROS package
+% the CHEMMACROS package v6.1 2022/02/13
%
% comprehensive support for typesetting chemistry documents
%
% --------------------------------------------------------------------------
-% Clemens Niederberger
-% --------------------------------------------------------------------------
-% https://github.com/cgnieder/chemmacros/
-% contact@mychemistry.eu
+% Web: https://github.org/cgnieder/chemmacros/
+% E-Mail: chemmacros@cnltx.de
% --------------------------------------------------------------------------
% If you have any ideas, questions, suggestions or bugs to report, please
-% feel free to contact me.
+% feel free to contact us.
% --------------------------------------------------------------------------
-% Copyright 2011--2022 Clemens Niederberger
+% Copyright 2011--2021 Clemens Niederberger
+% 2022-- Clemens Niederberger & Sonja K.
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% 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
+% and version 1.3c or later is part of all distributions of LaTeX
% version 2008/05/04 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
-% The Current Maintainer of this work is Clemens Niederberger.
+% The Current Maintainers of this work are Clemens Niederberger and Sonja K.
% --------------------------------------------------------------------------
+% arara: pdflatex: { interaction: nonstopmode }
+% arara: biber
+% arara: pdflatex: { interaction: nonstopmode }
+% arara: pdflatex: { interaction: nonstopmode }
\documentclass{chemmacros-manual}
\usepackage[T1]{fontenc}
@@ -95,24 +94,24 @@
urldate = {2012-03-20} ,
date = {2012-03-20}
}
-@online{mychemistry:chemmacros-dev,
+@online{cnltx:chemmacros-dev,
author = {Clemens Niederberger} ,
title = {chemmacros development} ,
- url = {http://www.mychemistry.eu/2015/06/chemmacros-development/} ,
+ url = {http://www.cnltx.de/2015/06/chemmacros-development/} ,
urldate = {2015-07-16} ,
date = {2015-06-14}
}
-@online{mychemistry:modular-chemmacros,
+@online{cnltx:modular-chemmacros,
author = {Clemens Niederberger} ,
title = {modular chemmacros} ,
- url = {http://www.mychemistry.eu/2015/06/modular-chemmacros/} ,
+ url = {http://www.cnltx.de/2015/06/modular-chemmacros/} ,
urldate = {2015-07-16} ,
date = {2015-06-08}
}
-@online{mychemistry:chemmacros-update-how,
+@online{cnltx:chemmacros-update-how,
author = {Clemens Niederberger} ,
title = {a new chemmacros -- but how?} ,
- url = {http://www.mychemistry.eu/2015/07/a-new-chemmacros-but-how/} ,
+ url = {http://www.cnltx.de/2015/07/a-new-chemmacros-but-how/} ,
urldate = {2015-07-16} ,
date = {2015-07-15}
}
@@ -196,18 +195,21 @@ Since version~6.0 the different modules of \chemmacros\ are divided into three
groups:
\begin{enumerate}
\item Core modules which provide underlying functionality or basic
- functionality which is not of direct interest from a user perspective but
- might be if you plan to write a module yourself (see
- section~\ref{sec:own-modules} for details).
+ functionality and which are not of direct interest from a user perspective
+ but might be if you plan to write a module yourself (see
+ section~\ref{sec:own-modules} for details). These modules are described in
+ part~\ref{part:core-modules} of this manual.
\item Main modules which provide all the stuff for typesetting and which are
- always loaded.
+ always loaded. These modules are described in
+ part~\ref{part:main-modules} of this manual.
\item Additional modules which are also loaded in the default setup. They
are not loaded if \chemmacros\ is loaded with the minimal setup:
- \cs*{usepackage}\Oarg{minimal}\Marg{chemmacros}.
+ \cs*{usepackage}\Oarg{minimal}\Marg{chemmacros}. These modules are described in
+ part~\ref{part:additional-modules} of this manual.
\end{enumerate}
\subsection{\chemmacros' Options}\label{sec:using-chemm-opti}
-Prior to v5.0 \chemmacros\ had quite a number of package options.
+Prior to v5.0 \chemmacros\ had quite a number of load-time options.
\chemmacros\ v6.0 has only two:
\begin{options}
\keybool{minimal}\Default{false}
@@ -216,7 +218,7 @@ Prior to v5.0 \chemmacros\ had quite a number of package options.
When \option{minimal} is used this option allows to load additional
modules.
\end{options}
-These are load-time option that only can be used in the optional argument of
+These options only can be used in the optional argument of
\cs*{usepackage}. \emph{All} other of \chemmacros' options are set using the
command
\begin{commands}
@@ -275,7 +277,7 @@ descriptions and are also set without specifying a module:
Some internal modules may also define core options, \eg, the \chemmodule{lang}
module, see section~\vref{sec:lang-module}.
-\subsection{Support Package \chemformula}
+\subsection{Support Package \chemformula}\label{sec:supp-pack-chemf}
\chemformula\ provides means of typesetting chemical formulas and reactions.
You will see its macros \cs{ch} and \cs{chcpd} every now and then in this
manual. When using \chemmacros\ you can consider the \chemformula\
@@ -283,8 +285,7 @@ package~\cite{pkg:chemformula} to be loaded as \chemmacros\ makes use of it in
various places. \chemmacros\ and \chemformula\ are tightly intertwined.
Nevertheless you should be able to use the \pkg{mhchem}~\cite{pkg:mhchem}
package with \chemmacros\ without problems. Please see
-section~\vref{sec:using-mhchem} for details and \latin{caveat}s. \emph{The
- recommendation is to use \chemformula.}
+section~\vref{sec:using-mhchem} for details and \latin{caveat}s.
A historical note: \chemformula\ started as a part of \chemmacros\ in
January~2012. Since July~2013 it is a completely independent package -- from
@@ -398,7 +399,7 @@ This is how \cs{Ka} is defined:
\section{The \chemmodule*{charges} Module}\label{sec:charges-module}
-The \chemmodule{charges} module loads the module \chemmodule{chemformula}.
+The \chemmodule{charges} module loads the module \chemmodule{formula}.
\subsection{Charge Symbols}
\begin{commands}
@@ -934,7 +935,7 @@ You can change the appearance with this option:
\section{The \chemmodule*{particles} Module}\label{sec:particles-module}
The \chemmodule{particles} module loads the modules \chemmodule{charges} and
-\chemmodule{chemformula}.
+\chemmodule{formula}.
\subsection{Provided Particle Macros}
The \chemmodule{particles} defines a number of macros which can be used for
@@ -975,22 +976,22 @@ nucleophiles.
\command{NewChemParticle}[\marg{cs}\marg{formula}]
Defines a new macro \meta{cs}. \meta{formula} is any valid \chemformula\
input (this depends on the setting of the \option{formula} option,
- see~\vref{sec:chemformula-module}). Raises an error if \meta{cs} already
+ see~\vref{sec:formula-module}). Raises an error if \meta{cs} already
exists.
\command{RenewChemParticle}[\marg{cs}\marg{formula}]
Redefines a new macro \meta{cs}. \meta{formula} is any valid \chemformula\
input (this depends on the setting of the \option{formula} option,
- see~\vref{sec:chemformula-module}). Raises an error if \meta{cs} doesn't
+ see~\vref{sec:formula-module}). Raises an error if \meta{cs} doesn't
exist.
\command{DeclareChemParticle}[\marg{cs}\marg{formula}]
Defines a macro \meta{cs}. \meta{formula} is any valid \chemformula\
input (this depends on the setting of the \option{formula} option,
- see~\vref{sec:chemformula-module}). Silently overwrites \meta{cs} if it
+ see~\vref{sec:formula-module}). Silently overwrites \meta{cs} if it
exists.
\command{ProvideChemParticle}[\marg{cs}\marg{formula}]
Defines a new macro \meta{cs}. \meta{formula} is any valid \chemformula\
input (this depends on the setting of the \option{formula} option,
- see~\vref{sec:chemformula-module}). Does nothing if \meta{cs} already
+ see~\vref{sec:formula-module}). Does nothing if \meta{cs} already
exists.
\end{commands}
An example of usage is the definition of the existing particle macros:
@@ -1005,22 +1006,22 @@ The following set defines macros like \cs{Nuc}
\command{NewChemNucleophile}[\marg{cs}\marg{formula}]
Defines a new macro \meta{cs}. \meta{formula} is any valid \chemformula\
input (this depends on the setting of the \option{formula} option,
- see~\vref{sec:chemformula-module}). Note that \meta{formula} will get a
+ see~\vref{sec:formula-module}). Note that \meta{formula} will get a
trailing negative charge! Raises an error if \meta{cs} already exists.
\command{RenewChemNucleophile}[\marg{cs}\marg{formula}]
Redefines a new macro \meta{cs}. \meta{formula} is any valid \chemformula\
(this depends on the setting of the \option{formula} option,
- see~\vref{sec:chemformula-module}). Note that \meta{formula} will get a
+ see~\vref{sec:formula-module}). Note that \meta{formula} will get a
trailing negative charge! Raises an error if \meta{cs} doesn't exist.
\command{DeclareChemNucleophile}[\marg{cs}\marg{formula}]
Defines a macro \meta{cs}. \meta{formula} is any valid \chemformula\
(this depends on the setting of the \option{formula} option,
- see~\vref{sec:chemformula-module}). Note that \meta{formula} will get a
+ see~\vref{sec:formula-module}). Note that \meta{formula} will get a
trailing negative charge! Silently overwrites \meta{cs} if it exists.
\command{ProvideChemNucleophile}[\marg{cs}\marg{formula}]
Defines a new macro \meta{cs}. \meta{formula} is any valid \chemformula\
(this depends on the setting of the \option{formula} option,
- see~\vref{sec:chemformula-module}). Note that \meta{formula} will get a
+ see~\vref{sec:formula-module}). Note that \meta{formula} will get a
trailing negative charge! Does nothing if \meta{cs} already exists.
\end{commands}
An example of usage is the definition of the existing nucleophile macros:
@@ -1033,7 +1034,7 @@ A macro defined this way will have an optional argument for the
\section{The \chemmodule*{phases} Module}\label{sec:phases-module}
-The \chemmodule{phases} module loads the \chemmodule{chemformula} modul.
+The \chemmodule{phases} module loads the \chemmodule{formula} modul.
\subsection{Basics}
@@ -1145,20 +1146,21 @@ then. It loads the package \pkg{amstext}~\cite{pkg:amstext}.
\command{standardstate}
Again self-explaining: \standardstate
\command{changestate}
- The uppercase delta used in \state[superscript=]{H} for example.
+ The uppercase delta used in \state^{}{H} for example.
\end{commands}
-\section{The \chemmodule*{chemformula} Module}\label{sec:chemformula-module}
+\section{The \chemmodule*{formula} Module}\label{sec:formula-module}
-The \chemmodule{chemformula} module loads the \pkg{amstext}
+The \chemmodule{formula} module loads the \pkg{amstext}
package~\cite{pkg:amstext} and the \chemmodule{charges} module.
\subsection{For Users}
There are different packages which provide means for typesetting chemical
formulas:
\begin{itemize}
- \item \pkg{chemformula}~\cite{pkg:chemformula}. This is probably well known
- to users of \chemmacros.
+ \item \pkg{chemformula}~\cite{pkg:chemformula}. This package started as a
+ part of \chemmacros\ and thus goes naturally together with \chemmacros,
+ see also \vref{sec:supp-pack-chemf}.
\item \pkg{mhchem}~\cite{pkg:mhchem}. This is the \enquote{older brother} of
\chemformula.
\item \pkg{chemfig}~\cite{pkg:chemfig}. The easiest and most complete of the
@@ -1197,9 +1199,9 @@ you'll have to choose manually. \emph{All automatic choices only happen at the
end of the preamble}.
\subsection{Using the \pkg*{chemformula} Package}
-If you set \keyis{formula}{chemformula} the \chemmodule{chemformula} module
+If you set \keyis{formula}{chemformula} the \chemmodule{formula} module
makes it possible that you can set all \chemformula\ options via the
-\cs{chemsetup} command using the module \module{chemformula}, for example:
+\cs{chemsetup} command using the module \module{formula}, for example:
\begin{sourcecode}
\chemsetup[chemformula]{format=\sffamily}
\end{sourcecode}
@@ -1211,7 +1213,7 @@ provided by the \chemmodule{reactions} module.
\emph{This method is the recommended choice!}
\subsection{Using the \pkg*{mhchem} Package}\sinceversion{5.1}\label{sec:using-mhchem}
-If you set \keyis{formula}{mhchem} the \chemmodule{chemformula} module makes
+If you set \keyis{formula}{mhchem} the \chemmodule{formula} module makes
it possible that you can set all of \pkg{mhchem}'s options via the
\cs{chemsetup} command using the module \module{mhchem}, for example:
\begin{sourcecode}
@@ -1632,7 +1634,7 @@ implements the following macro based on the same idea:
\end{example}
\section{The \chemmodule*{reactions} Module}\label{sec:reactions-module}
-The \chemmodule{reactions} module loads the \chemmodule{chemformula} module
+The \chemmodule{reactions} module loads the \chemmodule{formula} module
and the \pkg{mathtools} package~\cite{pkg:mathtools}.
\subsection{Predefined Environments}
@@ -1644,12 +1646,12 @@ You can use these environments for numbered\ldots
environment body. A wrapper around the \env*{equation} environment. The
environment body is parsed with \cs{ch} or \cs{ce} depending on the value
of the \option{formula} option, see
- section~\vref{sec:chemformula-module}.
+ section~\vref{sec:formula-module}.
\environment{reactions}
Several aligned reactions. A wrapper around \pkg{amsmath}'s \env*{align}
environment. The environment body is parsed with \cs{ch} or \cs{ce}
depending on the value of the \option{formula} option, see
- section~\vref{sec:chemformula-module}.
+ section~\vref{sec:formula-module}.
\end{environments}
\ldots and their starred versions for unnumbered reactions.
@@ -1657,12 +1659,12 @@ You can use these environments for numbered\ldots
\environment{reaction*}
A wrapper around the \env*{equation*} environment. The environment body
is parsed with \cs{ch} or \cs{ce} depending on the value of the
- \option{formula} option, see section~\vref{sec:chemformula-module}.
+ \option{formula} option, see section~\vref{sec:formula-module}.
\environment{reactions*}
A wrapper around \pkg{amsmath}'s \env*{align*} environment. The
environment body is parsed with \cs{ch} or \cs{ce} depending on the value
of the \option{formula} option, see
- section~\vref{sec:chemformula-module}.
+ section~\vref{sec:formula-module}.
\end{environments}
With those environments you can create (un)numbered reaction equations similar
@@ -1729,6 +1731,14 @@ or use the following options:
\end{reaction}
\end{example}
+You\sinceversion{6.1} can also make reactions share a counter with math
+equations (by using the \code{equation} counter).
+\begin{options}
+ \keybool{own-counter}\Module{reactions}\Default{true}
+ If set to false the reaction environments will use the \code{equation}
+ counter instead of the \code{reaction} counter.
+\end{options}
+
The use of \AmS math's \cs{intertext} is possible:
\begin{example}
\begin{reactions}
@@ -1739,9 +1749,22 @@ The use of \AmS math's \cs{intertext} is possible:
See reaction~\ref{rxn:test}.
\end{example}
-If\sinceversion{5.6} you are using either \pkg{cleveref} or \pkg{fancyref} the
-\env{reaction} counter is supported already. For \pkg{fancyref} use the
-prefix \code{rct}.
+\subsection{Cross-Referencing}
+If\sinceversion{5.6} you are using either \pkg{cleveref}~\cite{pkg:cleveref}
+or \pkg{fancyref}~\cite{pkg:fancyref} and have set \keyis{own-counter}{true}
+the \env{reaction} counter is supported by both packages and already set up by
+\chemmacros.
+
+For \pkg{fancyref} use the prefix \code{rct} by defining the following:
+\begin{sourcecode}
+ \newcommand*\fancyrefrctlabelprefix{rct}
+\end{sourcecode}
+
+Also \pkg{hyperref}'s \cs*{autoref} is supported.
+\begin{options}
+ \keyval{autoref-name}{name}\Module{reactions}\Default{\cs*{ChemTranslate}\Marg{reaction}}
+ \sinceversion{6.1}Change the name used by \pkg{hyperref}'s \cs*{autoref}.
+\end{options}
\subsection{Own Reactions}
You can create new types of reactions with the command:
@@ -1816,14 +1839,10 @@ The output of this list can be modified by two options:
The\sinceversion{5.2} macro that is called at the beginning of the list.
Inside of \meta{code} \code{\#1} refers to the actual heading of the list.
The default setting is not entirely true: if a macro \cs*{chapter} is
- defined \code{\cs*{chapter}\sarg\Marg{\#1}} is used.
- \keybool{tocbasic}\Module{reactions}\Default{false}
- \sinceversion{5.6}If you use a \KOMAScript\ class \emph{or} if you load
- the \pkg{tocbasic} package \emph{or} if you set this option to \code{true}
- the list of reactions will be set up using the \pkg{tocbasic} package.
- This \emph{disables} the \option{list-heading-cmd} option. For a
- \KOMAScript\ class this means that the list of reactions obeys
- \KOMAScript's \option*{listof} option.
+ defined \code{\cs*{chapter}\sarg\Marg{\#1}} is used. \par
+ This command has no effect if a \KOMAScript\ class or the package
+ \pkg{tocbasic} is used. The list of reactions then obeys \KOMAScript's
+ \option*{listof} option.
\end{options}
Instead of using the option \option{list-name} you also could redefine
\cs{reactionlistname}.
@@ -1865,13 +1884,14 @@ names are declared in the preamble removing the need to repeat the same
module options the output style (order of name number and data) can be altered
globally (or locally) to suit your needs, while the data itself is input using
an easy to use key-value approach and processed by the \pkg{siunitx}
-package. The \module{reactants} module responds to the language declared with
-the \pkg{babel} package and also offers methods to integrate the acronyms of
-used reactants or solvents into the list of acronyms.
+package~\cite{pkg:siunitx}. The \module{reactants} module responds to the
+language declared with the \pkg{babel} package and also offers methods to
+integrate the acronyms of used reactants or solvents into the list of
+acronyms.
The module requires and loads the packages \pkg{chemnum}~\cite{pkg:chemnum}
-and \pkg{siunitx}~\cite{pkg:siunitx}. Depending on the selected options the
-packages \pkg{acro}~\cite{pkg:acro},
+and \pkg{siunitx}. Depending on the selected options the packages
+\pkg{acro}~\cite{pkg:acro},
\pkg{glossaries-extra}~\cite{pkg:glossaries-extra},
\pkg{hyperref}~\cite{pkg:hyperref}, \pkg{longtable}~\cite{pkg:longtable}
and/or \pkg{xltabular}~\cite{pkg:xltabular} might be needed for this module
@@ -1928,8 +1948,8 @@ Common declarations will look like this:
\cs{Reactant} can be used in order to start a sentence with an upper case
version of a compound's name. The corresponding text must be defined
through \cs{DeclareChemReactant}'s \option{upper-name} option. Further
- variants of \cs{reactant} with different suffixes, such as \code{*},
- \code{+}, \code{l}, \code{s} or \code{plain} will be described later.
+ variants of \cs{reactant} with different suffixes, such as \sarg,
+ \parg, \code{l}, \code{s} or \code{plain} will be described later.
\command{solvent}[\oarg{data and units}\marg{ID}]
Analogous to \cs{reactants}. Can be used to insert solvent names and
corresponding data in the text. Format and order depend on the on the
@@ -1979,9 +1999,9 @@ Typical uses will look like this:
which they were declared in the preamble or in an external document.
\keybool{switch}\Module{reactants}\Default{false}
While \cs{reactants} will output name and number of a reactant, its
- starred variant \cs{reactant*}, will by default result in the name without
- the corresponding number. Setting \keyis{switch}{true}, globally or
- locally, reverses this behavior and outputs a reactant's number without
+ starred variant \cs{reactant}\sarg, will by default result in the name
+ without the corresponding number. Setting \keyis{switch}{true}, globally
+ or locally, reverses this behavior and outputs a reactant's number without
its name.
\end{options}
Other options are described at later places when the corresponding behavior is
@@ -1997,7 +2017,9 @@ argument that can be used to easily input this data:
\begin{commands}
\command{reactant}[\oarg{data and units}\marg{ID}]
+ \phantom{X}\vspace*{-\baselineskip}
\command{solvent}[\oarg{data and units}\marg{ID}]
+ \phantom{X}\vspace*{-\baselineskip}
\end{commands}
\begin{table}[bp]
@@ -2011,16 +2033,16 @@ argument that can be used to easily input this data:
\toprule
\tablehead{Key} & \tablehead{default unit} & \tablehead{option} \\
\midrule
- mass & \unit{\gram} & mass-unit \\
- volume & \unit{\milli\liter} & volume-unit \\
- fraction & w/w\% & fraction-unit \\
- amount & \unit{\milli\mole} & amount-unit \\
- equiv & eq & equiv-unit \\
- purity & \% & purity-unit \\
- concentration & \unit{\Molar} & concentration-unit \\
- solvent & n.a. & \\
+ mass & \unit{\gram} & mass-unit \\
+ volume & \unit{\milli\liter} & volume-unit \\
+ fraction & w/w\% & fraction-unit \\
+ amount & \unit{\milli\mole} & amount-unit \\
+ equiv & eq & equiv-unit \\
+ purity & \% & purity-unit \\
+ concentration & \unit{\Molar} & concentration-unit \\
+ solvent & n.a. & \\
\midrule
- solution-name & solution in & solution \\
+ solution-name & solution in & solution \\
\bottomrule
\end{tabular}
\end{table}
@@ -2044,7 +2066,7 @@ solvent. This text automatically adapts to the document language set via
the German translation are included in the package. If you write in a
different language (or just don't like the predefined text), you can use the
command \cs{DeclareChemTranslation}\marg{key}\marg{language}\marg{translation}
-(with \keyis{\meta{key}}{solution}) as described in
+(with \keyis*{\meta{key}}{solution}) as described in
section~\vref{sec:lang-module} in order to supply your own translation.
\begin{example}
@@ -2159,11 +2181,11 @@ contents of the categories are typeset.
Using the \cs{reactants} command inside of section headings or captions can
mess up the order in which the molecules are numbered, especially when also
using a table of contents and/or a list of figures/tables. To prevent this,
-the \module{reactants} module offers the \code{+} suffixed variant of
-\cs{reactants}, comparable to \pkg{chemnum}'s \cs{cmpd+} command.
+the \module{reactants} module offers the \parg\ suffixed variant of
+\cs{reactants}, comparable to \pkg{chemnum}'s \cs{cmpd}\parg\ command.
\begin{commands}
- \command{reactant+}[\oarg{data and units}\marg{ID}]
+ \command{reactant}[\parg\oarg{data and units}\marg{ID}]
This command is used to insert name, number, and, if present, data of a
predefined reactant with the \meta{ID} in a section heading or caption.
\end{commands}
@@ -2241,7 +2263,7 @@ uses either \pkg{longtable} or \pkg{xltabular} to typeset this list:
are responsible for formatting the list of reactants. Be aware that with
\code{longtable}, the column widths are hard coded, thus you could
experience overfull box warnings if you use exceptionally long \meta{ID}s
- in combination with the starred variant \cs{printreactants*}, which is
+ in combination with the starred variant \cs{printreactants}\sarg, which is
responsible for adding the \meta{ID} in resulting list, as well.
\end{options}
@@ -2269,7 +2291,7 @@ The following command is provided to set oxidation numbers:
Places \meta{number} as right superscript to \meta{atom}; \meta{number}
has to be a (rational) number! \meta{atom} is treated as a \chemformula\
formula, like it would be in \cs{chcpd} (this depends on the setting of
- the \option{formula} option, see~\vref{sec:chemformula-module}).
+ the \option{formula} option, see~\vref{sec:formula-module}).
\end{commands}
\begin{example}
@@ -2476,7 +2498,7 @@ The \chemmodule{scheme} module loads the \pkg{chemnum}
package~\cite{pkg:chemnum} and defines a floating environment
\showenv{scheme}. That is, it \emph{only} defines this float if no
environment \env{scheme} exists at the end of the preamble. The module checks
-for different available float defining methods, in \emph{this} order:
+for different available float defining methods:
\begin{itemize}
\item If the current class is a \KOMAScript\ class \cs*{DeclareNewTOC} will
be used.
@@ -2491,9 +2513,19 @@ for different available float defining methods, in \emph{this} order:
\item If neither of the above the \enquote{manual} method is used. This
means the environment is defined the same way like \env*{figure} is
defined in the \cls*{article} class or the \cls*{book} class, depending if
- \cs*{chapter} is defined or not.
+ \cs*{chapter} is defined or not (the \enquote{traditional} way).
+ \item \sinceversion{6.1}If no unique choice is possible the \emph{last} of
+ the detected methods will be used. For example, if you use the
+ \cls{memoir} class \emph{and} load the \pkg{float} then the method of
+ \pkg{float} will be used.
\end{itemize}
+\begin{options}
+ \keychoice{float-method}{KOMA,memoir,tocbasic,newfloat,floatrow,float,traditional}\Module{scheme}
+ \sinceversion{6.1}You can also decide for yourself which method you want
+ \chemmacros\ to use by setting this option accordingly.
+\end{options}
+
The list name and the caption name both are translated to the language
specified according to the \option{lang} option and the provided translations,
see section~\vref{sec:lang-module} for details. If you want to manually change
@@ -2509,13 +2541,18 @@ The list of schemes is printed as expected with
\command{listofschemes}
\end{commands}
-If\sinceversion{5.6} you are using either \pkg{cleveref} or \pkg{fancyref} the
-\env{scheme} environment (or rather its captions) are supported already. For
-\pkg{fancyref} use the prefix \code{sch}.
+If\sinceversion{5.6} you are using either \pkg{cleveref}~\cite{pkg:cleveref}
+or \pkg{fancyref}~\cite{pkg:fancyref} the \env{scheme} counter is supported by
+both packages and already set up by \chemmacros.
+
+For \pkg{fancyref} use the prefix \code{sch} by defining the following:
+\begin{sourcecode}
+ \newcommand*\fancyrefschlabelprefix{sch}
+\end{sourcecode}
\section{The \chemmodule*{spectroscopy} Module}\label{sec:spectroscopy-module}
-The \chemmodule{spectroscopy} module loads the \chemmodule{chemformula} module
+The \chemmodule{spectroscopy} module loads the \chemmodule{formula} module
and the \pkg{siunitx} package~\cite{pkg:siunitx}.
\subsection{The \cs*{NMR} Command}
@@ -2535,7 +2572,7 @@ input.
\pkg{siunitx} number input, \meta{unit} is a valid \pkg{siunitx} unit
input. \meta{solvent} is any valid \chemformula\ input as in \cs{chcpd}
(this depends on the setting of the \option{formula} option,
- see~\vref{sec:chemformula-module}).
+ see~\vref{sec:formula-module}).
\end{commands}
\emph{All} Argument are optional! Without arguments we get:
@@ -2682,7 +2719,7 @@ number of options.
(printed by \cs{\#}).
\keybool{parse}\Module{spectroscopy}\Default{true}
Treat the solvent as \chemformula\ formula (this depends on the setting of
- the \option{formula} option, see~\vref{sec:chemformula-module}) or not.
+ the \option{formula} option, see~\vref{sec:formula-module}) or not.
\keyval{delta}{tokens}\Module{spectroscopy}\Default
The \meta{tokens} are added after $\delta$.
\keybool{list}\Module{spectroscopy}\Default{false}
@@ -2932,9 +2969,9 @@ package~\cite{pkg:siunitx}.
This macro can be used to write the thermodynamic state variables.
\begin{example}
- \state{A}, \state[subscript-left=f]{G} ,
- \state[subscript-right=\ch{Na}]{E},
- \state[superscript-right=\qty{1000}{\celsius}]{H}
+ \state{A}, \state_f{G} ,
+ \state{E}_{\ch{Na}},
+ \state{H}^{\qty{1000}{\celsius}}
\end{example}
These options are available:
@@ -2957,6 +2994,13 @@ These options are available:
An alias of \option{subscript-left}.
\end{options}
+Since version~6.1\sinceversion{6.1} you can input the sub- and superscripts in
+a more intuitive way instead of using the options -- the latter are still
+available, though:
+\begin{example}
+ \state_a^b{X}_c^d
+\end{example}
+
\subsection{Thermodynamic Variables}
The \chemmodule{thermodynamics} module provides a few commands for specific
@@ -3123,11 +3167,11 @@ units. Like all \pkg{siunitx} units they're only valid inside
\command{Molar} \unit{\Molar}
\command{MolMass} \unit{\MolMass}
\command{normal} \unit{\normal}
- \command{torr} \unit{\torr}
- \par
-\sinceversion{6.0} Since some units still frequently used in chemistry were removed from version 3 of \pkg{siunitx},
- \chemmacros\ also defines these in the same way, older versions of \pkg{siunitx} used to do.
- These units are:
+ \command{torr} \unit{\torr}\par
+ %%%
+ \sinceversion{6.0}Since some units still frequently used in chemistry were
+ removed from version 3 of \pkg{siunitx} \chemmacros\ also defines these in
+ the same way, older versions of \pkg{siunitx} used to do. These units are:
\command{angstrom} \unit{\angstrom}
\command{atomicmassunit} \unit{\atomicmassunit}
\command{bar} \unit{\bar}
@@ -3136,8 +3180,7 @@ units. Like all \pkg{siunitx} units they're only valid inside
\end{commands}
-\part{Core Modules}
-
+\part{Core Modules}\label{part:core-modules}
The modules described in this part are always loaded and mainly concern module
writers.
@@ -3175,7 +3218,7 @@ modules. In the macro descriptions below \TF\ denotes that a \code{T}, an
\explcommand{chemmacros_allow_break:}
Inserts a penalty of \num{0}.
\explcommand{chemmacros_skip_nobreak:N}[ \meta{skip/length variable}]
- Insert a horizontal skip where a linebreak is disallowed.
+ Inserts a horizontal skip where a linebreak is disallowed.
\expandable\explcommand{chemmacros_if_is_int:n}[\TF\ \marg{input} \marg{true}
\marg{false}]
Checks if \meta{input} is an integer or something else.
@@ -3183,7 +3226,7 @@ modules. In the macro descriptions below \TF\ denotes that a \code{T}, an
Checks if the current font weight is one of \chemboldchecks{or}.
\explcommand{chemmacros_bold:n}[ \marg{text}]
Checks if the current font weight is bold and if yes places \meta{text} in
- \cs*{textbf} if in text mode or in \cs*{bm} if in math mode. If no
+ \cs*{textbf} if in text mode or in \cs*{bm} if in math mode. If no,
\meta{text} simply is placed in the input stream as is.
\explcommand{chemmacros_text:n}[ \marg{text}]
Ensures that \meta{text} is placed in text mode.
@@ -3240,24 +3283,22 @@ This is how the macros \cs{NewChemParticle}, \cs{RenewChemParticle},
The following macros strictly speaking are not provided by the
\chemmodule{base} module but this place fits best for their description.
\begin{commands}
- \expandable\explcommand{chemmacros_if_module_exist:n}[\TF\ \marg{module}
+ \expandable\explcommand{chemmacros_module_if_exist:n}[\TF\ \marg{module}
\marg{true} \marg{false}]
Checks if a file with the correct name for a module \meta{module} can be
found.
- \expandable\explcommand{chemmacros_if_module_loaded:n}[\TF\ \marg{module}
+ \expandable\explcommand{chemmacros_module_if_loaded:n}[\TF\ \marg{module}
\marg{true} \marg{false}]
Checks if the module \meta{module} has already been loaded or not.
- \explcommand{chemmacros_load_module:n}[ \marg{module}]
- Loads module \meta{module} if it hasn't been loaded, yet.
- \explcommand{chemmacros_load_modules:n}[ \marg{csv list of modules}]
- Loads every module in \meta{csv list of modules} if they haven't been
- loaded, yet. This is the code level variant of \cs{usechemmodule}.
- \explcommand{chemmacros_before_module:nn}[ \marg{module} \marg{code}]
+ \explcommand{chemmacros_module_load:n}[ \marg{module}]
+ Loads module \meta{module} if it hasn't been loaded, yet. The module must
+ exist as a separate file as described in section~\ref{sec:own-modules}.
+ \explcommand{chemmacros_module_before:nn}[ \marg{module} \marg{code}]
Saves\sinceversion{5.1} \meta{code} and inserts it right before
\meta{module} is loaded. If \meta{module} is never loaded then
\meta{code} is never inserted. If \meta{module} already is loaded when
the command is used then \meta{code} also is never inserted.
- \explcommand{chemmacros_after_module:nn}[ \marg{module} \marg{code}]
+ \explcommand{chemmacros_module_after:nn}[ \marg{module} \marg{code}]
Saves\sinceversion{5.1} \meta{code} and inserts it right after
\meta{module} is loaded. If \meta{module} is never loaded then
\meta{code} is never inserted. If \meta{module} already is loaded when
@@ -3371,13 +3412,13 @@ following macros are available:
A token list variable that holds the language which is used by
\explcs{chemmacros_translate:n} for translation, \emph{after begin
document}.
- \command{ChemTranslate}[\marg{translation key}]
+ \expandable\command{ChemTranslate}[\marg{translation key}]
A version of \explcs{chemmacros_translate:n} for those who prefer
traditional \LaTeXe\ programming over expl3.
- \explcommand{chemmacros_declare_translation:nnn}[\marg{language}\marg{key}%
+ \explcommand{chemmacros_declare_translation:nnn}[ \marg{language} \marg{key}
\marg{translation}]
The expl3 version of \cs{DeclareChemTranslation}.
- \explcommand{chemmacros_declare_translations:nn}[\marg{key}\Marg{\meta{language}
+ \explcommand{chemmacros_declare_translations:nn}[ \marg{key} \Marg{\meta{language}
= \meta{translation}}]
The expl3 version of \cs{DeclareChemTranslations}.
\end{commands}
@@ -3507,47 +3548,42 @@ me (see section~\vref{sec:submitting-module}) so they can be added to the
\appendix
\part{Appendix}
-\section{Own Modules}\label{sec:own-modules}
+\section{Own Modules Called Styles}\label{sec:own-modules}
\subsection{How To}
If you have additional functionality which you think might be useful as a
\chemmacros\ module then you can easily write one yourself. The module must
be a file in a path where \TeX\ can find it following a certain naming
scheme. The file for a module \chemmodule*{foo} \emph{must be named}
-\code{chemmacros.module.foo.code.tex}.
+\code{chemmacros.style.foo.code.tex}.
\begin{commands}
- \command{ChemModule}[\sarg\marg{name}\marg{description}\oarg{minimal
- compatibility version}]
- Register module \meta{name}. The optional argument \meta{minimal
- compatibility version} ensures that this module is only loaded if the
- option \option{compatibility} has a high enough version number. If it is
- omitted the module can be loaded in each version~5.0 or higher.
+ \command{ChemStyle}[\sarg\marg{name}\oarg{version description}]
+ Register module \meta{name} where the optional argument is passed to the
+ optional argument of \cs*{ProvidesFile}.
\end{commands}
The first line in the file then should look similar to this:
\begin{sourcecode}
- \ChemModule{foo}{2015/07/14 description of foo}
+ \ChemStyle{foo}[2022-02-07 description of foo]
\end{sourcecode}
-This registers module \chemmodule*{foo} which means \chemmacros\ will accept
-this file as a valid module.
+This registers the style \chemmodule*{foo} which means \chemmacros\ will
+accept this file as a valid style.
+
+Such a style can then be loaded to your document via
+\begin{commands}
+ \command{usechemstyle}[\marg{csv list of style names}]
+ which should be used in the preamble of your document.
+\end{commands}
Since \chemmacros\ is written using expl3 \cs{ChemModule} starts an expl3
programming environment. If you don't want that but rather want to write your
module using traditional \LaTeXe\ methods then use the starred variant:
\begin{sourcecode}
- \ChemModule*{foo}{2015/07/14 description of foo}
+ \ChemStyle*{foo}[2022-02-07 description of foo]
\end{sourcecode}
In both variants \code{@} has category code~11 (letter).
-Since new modules very likely might rely on code provided first in a certain
-version of \chemmacros\ you might want to make sure that your module only is
-loaded when the compatibility mode is high enough to provide the features you
-want:
-\begin{sourcecode}
- \ChemModule{foo}{2015/10/14 description of foo}[5.2]
-\end{sourcecode}
-
If you decide to write your module \chemmodule*{foo} using expl3 and add
options you want to be able to set using
\cs{chemsetup}\Oarg{foo}\marg{options} please make sure you define (and set)
@@ -3608,8 +3644,9 @@ the usual support forums
\end{itemize}
You can also open an issue on
\url{https://github.com/cgnieder/chemmacros/issues/} possibly adding the label
-\emph{support}.
-
+\emph{support} or write an email to
+\href{mailto:chemmacros@cnltx.de}{chemmacros@cnltx.de}.
+
\subsection{Suggestions}
If you have any suggestions on how \chemmacros\ could be improved then please
go to \url{https://github.com/cgnieder/chemmacros/issues/} and open a new
@@ -3619,8 +3656,8 @@ issue possibly adding the label \emph{suggestion}.
If you find any bugs, \ie, errors (something not working as described,
conflicts with other packages, \ldots) then please go to
\url{https://github.com/cgnieder/chemmacros/issues/} and open a new issue
-describing the error including a minimal working example and possibly adding
-the label \emph{bug}.
+describing the error including a \emph{minimal working example} and possibly
+adding the label \emph{bug}.
\printbibliography