summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/carbohydrates/carbohydrates_en.tex
blob: 4da1156d2a909372d819c160a16c94a582bd8e1d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
% arara: pdflatex
% arara: biber
% arara: pdflatex
% arara: pdflatex
\documentclass[load-preamble+]{cnltx-doc}
\usepackage[utf8]{inputenc}
\usepackage{carbohydrates}

\setcnltx{
  package  = {carbohydrates} ,
  authors  = Clemens Niederberger ,
  email    = contact@mychemistry.eu ,
  info     = {carbohydrate molecules with \pkg*{chemfig}} ,
  url      = https://github.com/cgnieder/carbohydrates/ ,
  abstract = {%
    \carbohydrates\ offers macros for making exercise sheets when teaching
    carbohydrate chemistry a lot less tedious.  It uses \pkg{chemfig} for
    drawing the formulas.
  } ,
  add-cmds = {
    allose , altrose , arabinose ,
    carbohydrate ,
    desoxyribose ,
    erythrose ,
    galactose , glucose , glycerinaldehyde , gulose ,
    idose ,
    lyxose ,
    mannose ,
    newaldose ,
    ribose ,
    setcarbohydrates , setcarbohydratedefaults ,
    talose , threose ,
    xylose
  } ,
  add-silent-cmds = {
    arrow ,
    bondboldwidth , bondhashlength , bondwidth ,
    D ,
    chemfig , chemname , chemnameinit ,
    definesubmol ,
    iupac ,
    printatom ,
    schemestart , schemestop , setatomsep , setbondoffset , setbondstyle ,
      setcrambond , setdoublesep
  } ,
  index-setup = { othercode = \footnotesize , level = \addsec } ,
  makeindex-setup = { columns = 3 , columnsep = 1em }
}

\defbibheading{bibliography}[References]{\addsec{#1}}
\addbibresource{\jobname.bib}

\usepackage{filecontents}
\begin{filecontents*}{\jobname.bib}
@online{texdev,
  url = {http://www.texdev.net/} ,
  urldate = {2014-04-25} ,
  author = {Joseph Wright}
}
\end{filecontents*}

\usepackage{varioref}

\usepackage{chemmacros}
\chemsetup{greek=newtx}
\newcommand*{\bondwidth}{0.06642 em}
\newcommand*{\bondboldwidth}{0.22832 em}
\newcommand*{\bondhashlength}{0.25737 em}
\setdoublesep{0.35700 em}
\setatomsep{1.78500 em}
\setbondoffset{0.18265 em}
\setbondstyle{line width = \bondwidth}
\setcrambond
  {\dimexpr\bondwidth*2 + \bondboldwidth\relax}
  {\bondwidth}
  {\bondhashlength}
\renewcommand*\printatom[1]{{\small\ensuremath{\mathsf{#1}}}}

\usepackage{rotating,array,tabu,booktabs}

\defabbr\vs{\cnltxlatin{vs}}

\begin{document}

\section{Licence and Requirements}
\license

\carbohydrates\ loads the packages \pkg{chemfig}~\cite{pkg:chemfig},
\pkg{etoolbox}~\cite{pkg:etoolbox} and \pkg{xcolor}~\cite{pkg:xcolor}.

\section{The Idea}
When teaching chemistry -- and in the case of this package: carbohydrate
chemistry -- you have to show many examples of the basic aldoses and you have
to explain the Fischer and the Haworth representation as well. This means you
may have nearly the same \pkg{chemfig}~\cite{pkg:chemfig} formulas over and
over in your documents.  \carbohydrates\ aims to ease this task.

The following example will give a short impression of what the package does:
\begin{example}
  \glucose
  \glucose[model={fischer=skeleton}]
  \setatomsep{2.5em}
  \glucose[model=haworth,ring]
  \glucose[model=haworth,ring=furanose]
\end{example}

\section{Usage}
\subsection{The Base Macro}
\begin{commands}
  \command{carbohydrate}[\oarg{options}\marg{spec}]
    A generic macro for typesetting carbohydrates.
\end{commands}
We will talk about the options in a bit. First lets see what \meta{spec}
means.  This argument is a series of the tokens \code{r}, \code{l} and
\code{0} denoting an hydroxy group placed to the right or the left in the
Fischer projection of the carbohydrate.  A \code{0} means that the hydroxy
group is to be left out.  The series of tokens is meant to describe the
hydroxy groups at the chiral centers. The aldehyde group\footnote{Also the
  keto group once ketoses will be implemented.} and the hydroxy group at the
end of the chain will be set automatically.  Unless specified otherwise the
command expects a hexose which means a series of \emph{four} tokens.

\begin{example}
  \chemname{\carbohydrate{llrr}}{\iupac{\D-Mannose}}
  \chemname{\carbohydrate[model={fischer=skeleton}]{llrr}}{\iupac{\D-Mannose}}
  \setatomsep{2.5em}\chemnameinit{}
  \chemname{\carbohydrate[model=chair]{llrr}}{\iupac{\D-Mannose}}
  \chemname{\carbohydrate[model=haworth]{llrr}}{\iupac{\D-Mannose}}
\end{example}

Adding the option \option{pentose} means that now only \emph{three} tokens
need to be specified.

\begin{example}
  \chemname{\carbohydrate[pentose]{rlr}}{\iupac{\D-Xylose}}
  \chemname{\carbohydrate[pentose,model={fischer=skeleton}]{rlr}}{\iupac{\D-Xylose}}
  \setatomsep{2.5em}\chemnameinit{}
  \chemname{\carbohydrate[pentose,model=haworth,ring]{rlr}}{\iupac{\D-Xylose}}
  \chemname{\carbohydrate[pentose,model=haworth,ring=pyranose]{rlr}}{\iupac{\D-Xylose}}
\end{example}

\subsection{Available Options}
As you have already seen in the pevious examples \cs{carbohydrate} has an
optional argument that takes different options.  Here is a complete list:
\begin{options}
  % model/fischer/skeleton/.code = \def\cbhdr@model{fischer@skeleton} ,
  % model/fischer/full/.code     = \def\cbhdr@model{fischer} ,
  \keychoice{model}{fischer,haworth,chair}\Default{fischer}
    The model to be used to draw the molecule.  The choice \option{fischer}
    is itself an option with two choices: \keyis{fischer}{skeleton} and
    \keyis{fischer}{full}.  Leaving the choice out will use \code{full} as
    default choice.
  \opt{chain}
    Draw the open chain isomer.
  \keychoice{ring}{\default{true},pyranose,furanose}
    Draw a ring isomer.  If you don't specify what ring type should be drawn
    (\ie, if you choose \code{true}) the default depends on the length of the
    carbohydrate.  For example for hexoses the default ring type is
    \code{pyranose}.
  \keychoice{anomer}{alpha,beta,undetermined}\Default{alpha}
    The ring anomer.
  \keychoice{length}{6,5,4,3}\Default{6}
    The length of the carbohydrate.  \keyis{length}{6} draws a hexose,
    \keyis{length}{3} draws a triose.
  \opt{hexose}
    An alias for \keyis{length}{6}.
  \opt{pentose}
    An alias for \keyis{length}{5}.
  \opt{tetrose}
   An alias for \keyis{length}{4}.
  \opt{triose}
    An alias for \keyis{length}{3}.
  \keybool{3d}\Default{false}
    Draw some of the bonds of the rings in the \code{haworth} and \code{chair}
    models in a way that indicates the three dimensional structure of the
    molecules.
  \keylit-{color}{\marg{name}\marg{color}}
    This option takes two arguments: \meta{name} specifies which part of the
    molecule is to be colored, \meta{color} specifies the color to be used,
    also see table~\vref{tab:color} and section~\ref{sec:colors}.
\end{options}

\begin{table}[htb]
  \centering
  \caption{Available names for the \option*{color} option.}\label{tab:color}
  \begin{tabular}{>{\ttfamily}ll}
    \toprule
      \rmfamily\bfseries Name & \bfseries Function \\
    \midrule
      C1 & carbon 1 \\
      C2 & carbon 2 \\
      O-C2 & oxygen of the hydroxy group at carbon 2 \\
      H-C2 & hydrogen of the hydroxy group at carbon 2 \\
      C3 & carbon 3 \\
      O-C3 & oxygen of the hydroxy group at carbon 3 \\
      H-C3 & hydrogen of the hydroxy group at carbon 3 \\
      C4 & carbon 4 \\
      O-C4 & oxygen of the hydroxy group at carbon 4 \\
      H-C4 & hydrogen of the hydroxy group at carbon 4 \\
      C5 & carbon 5 \\
      O-C5 & oxygen of the hydroxy group at carbon 5 \\
      H-C5 & hydrogen of the hydroxy group at carbon 5 \\
      C6 & carbon 6 \\
      O-C6 & oxygen of the hydroxy group at carbon 6 \\
      H-C6 & hydrogen of the hydroxy group at carbon 6 \\
      anomerO & oxygen of the anomeric hydroxy group\slash aldehyde oxygen \\
      anomerH & hydrogen of the anomeric hydroxy group \\
      ringO & oxygen in the ring \\
    \bottomrule
  \end{tabular}
\end{table}

\subsection{Defining Shortcuts}\label{sec:defining-shortcuts}

\carbohydrates\ allows to define shortcuts for aldoses:

\begin{commands}
  \command{newaldose}[\marg{cs}\oarg{options}\marg{spec}]
    This defines the macro \meta{cs} with preset options \meta{options}.
    \meta{spec} has the same meaning as for \cs{carbohydrate}.
  \command{renewaldose}[\marg{cs}\oarg{options}\marg{spec}]
    The same command but redefines an existing macro.
\end{commands}

In fact, \carbohydrates\ already defines macros for the common aldoses.  They
are listed in table~\ref{tab:predefined-aldoses} on
page~\pageref{tab:predefined-aldoses}.  They don't have any predefined options
(except for \option{hexose}, \option{pentose} \etc).

\begin{sidewaystable}
  \setcarbohydrates{model={fischer=skeleton}}
  \caption{Overview over the predefined aldoses.}
  \label{tab:predefined-aldoses}
  \begin{tabu}{*{8}{X[c]<{\strut}}}
    \toprule
      \allose & \altrose & \glucose   & \mannose &
      \gulose & \idose   & \galactose & \talose \\
      \cs{allose} & \cs{altrose} & \cs{glucose}   & \cs{mannose} &
      \cs{gulose} & \cs{idose}   & \cs{galactose} & \cs{talose} \\
      \iupac{\D-Allose}    & \iupac{\D-Altrose} &
      \iupac{\D-Glucose}   & \iupac{\D-Mannose} &
      \iupac{\D-Gulose}    & \iupac{\D-Idose} &
      \iupac{\D-Galactose} & \iupac{\D-Talose} \\
    \midrule
      \ribose & \arabinose & \xylose & \lyxose & \desoxyribose \\
      \cs{ribose} & \cs{arabinose} & \cs{xylose} & \cs{lyxose} &
      \multicolumn{2}{l}{\cs{desoxyribose}} \\
      \iupac{\D-Ribose} & \iupac{\D-Arabinose} &
      \iupac{\D-Xylose} & \iupac{\D-Lyxose} &
      \iupac{\D-Desoxy|ribose} \\
    \midrule
      \erythrose & \threose & \glycerinaldehyde \\
      \cs{erythrose} & \cs{threose} & \multicolumn{2}{l}{\cs{glycerinaldehyde}} \\
      \iupac{\D-Erythrose} & \iupac{\D-Threose} &
      \iupac{\D-Glycerin|aldehyde} \\
    \bottomrule
  \end{tabu}
\end{sidewaystable}

\subsection{Available Models}\label{sec:available-models}

\carbohydrates\ implements different models for drawing carbohydrates:
\begin{itemize}
  \item Fischer -- skeleton: the Fischer representation with only a skeleton
    formula.
  \item Fischer -- full: the Fischer representation including all C and H
    atoms.
  \item Haworth: the Haworth representation.
  \item Chair: the chair conformation.
\end{itemize}

While the Fischer model is implemented for all carbohydrates both Haworth and
chair are not.  The chair model is only implemented for aldohexoses, Haworth
is implemented for aldotetroses, -pentoses and -hexoses.

\begin{example}
  \glucose[model={fischer=skeleton}]
  \glucose[model={fischer=full}]
  \setatomsep{2.5em}
  \glucose[model=haworth]
  \glucose[model=chair]
\end{example}

\subsection{Chain \vs\ Ring Forms}

While the chain forms are available in all models the ring forms obviously
aren't.  There are two ring forms for hexoses and pentoses: pyranoses and
furanoses.  For tetroses only the furanose rings are available as there don't
exist pyranose ring forms (for obvious reasons).  It is also clear that
neither pyranose nor furanose forms of trioses exist.

\begin{example}
  \setatomsep{2.5em}
  \glucose[model=haworth,ring]
  \ribose[model=haworth,ring]
  \threose[model=haworth,ring]
\end{example}

\textbf{Actually the above is not true: the chain forms are not available in all
models for all aldoses.  As said in section~\ref{sec:available-models} the
chair model is only implemented for aldohexoses.  Also chains are not
implemented for tetroses and trioses in the Haworth model.}

\subsection{Default Settings}
\begin{commands}
  \command{setcarbohydrate}[\marg{options}]
    Set package options for all carbohydrates within the current scope.
  \command{setcarbohydratedefaults}[\marg{csname}\marg{options}]
    Set options for a predefined carbohydrate within the current scope. The
    first argument \meta{csname} is the macro name of the shortcut (see
    section~\ref{sec:defining-shortcuts}).
\end{commands}

\begin{example}
  \setatomsep{2.5em}
  \setcarbohydratedefaults\glucose{ring,model=haworth,anomer=undetermined}
  \glucose\
  \mannose
\end{example}

\subsection{Colors}\label{sec:colors}
For educating purposes it may be useful to be able to color certain atoms. The
\option{color} option allows this.
\begin{example}
  \setcarbohydrates{model=chair}
  \setatomsep{2.5em}
  \schemestart
    \glucose[color={anomerO}{red},color={O-C5}{green},color={H-C5}{blue}]
    \arrow{<=>}
    \glucose[ring,color={anomerO}{red},color={ringO}{green},color={anomerH}{blue}]
  \schemestop
\end{example}

\section{\texorpdfstring{\textsc{todo}}{TODO}s}
There are still quite a number of missing features that I'd like to implement
some day such as
\begin{itemize}
  \item ring forms for \laevus-carbohydrates,
  \item support for both chair conformations and the boat conformation,
  \item support for ketoses,
  \item support for oxidized and reduzed forms, and
  \item disaccharides.
\end{itemize}
There is \emph{no} time table, though -- wether these features will be implemented
any time soon or at all is undecided.

\section{About the Examples in this Manual}
All macros used in the examples either belong to \carbohydrates\ and are
described in this manual or they belong to either
\pkg{chemfig}~\cite{pkg:chemfig}, \pkg{chemmacros}~\cite{pkg:chemmacros},
\pkg{chemformula}~\cite{pkg:chemformula}, or are standard \LaTeX\ macros.  I
encourage you to take a look at the packages for typesetting chemistry
documents.

The \pkg{chemfig} settings have been adjusted for the examples in this
manual.  Specifically the preamble of this document makes these settings:

\begin{sourcecode}
  \newcommand*{\bondwidth}{0.06642 em}
  \newcommand*{\bondboldwidth}{0.22832 em}
  \newcommand*{\bondhashlength}{0.25737 em}
  \setdoublesep{0.35700 em}
  \setatomsep{1.78500 em}
  \setbondoffset{0.18265 em}
  \setbondstyle{line width = \bondwidth}
  \setcrambond
    {\dimexpr\bondwidth*2 + \bondboldwidth\relax}
    {\bondwidth}
    {\bondhashlength}
  \renewcommand*\printatom[1]{{\small\ensuremath{\mathsf{#1}}}}
\end{sourcecode}
These settings are taken from~\cite{texdev}.  Search the page for
\code{chemfig} and you should be able to find them there.

\end{document}