summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/chemfig/chemfig_doc_en.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/chemfig/chemfig_doc_en.tex')
-rw-r--r--Master/texmf-dist/doc/generic/chemfig/chemfig_doc_en.tex184
1 files changed, 19 insertions, 165 deletions
diff --git a/Master/texmf-dist/doc/generic/chemfig/chemfig_doc_en.tex b/Master/texmf-dist/doc/generic/chemfig/chemfig_doc_en.tex
index b878c81c67d..1d8af66fb9f 100644
--- a/Master/texmf-dist/doc/generic/chemfig/chemfig_doc_en.tex
+++ b/Master/texmf-dist/doc/generic/chemfig/chemfig_doc_en.tex
@@ -1,9 +1,9 @@
% __________________________________________________________________
% | |
% | |
-% | ChemFig Documentation |
+% | Chemfig manual |
% | |
-% | February 24, 2012 |
+% | November 16, 2012 |
% | |
% |__________________________________________________________________|
%
@@ -327,26 +327,24 @@ The command \verb|\chemfig| draws a molecule using the commands provided by the
\end{itemize}
\newpage
-\part{\protect\CF for the impatient}
-This part is a non-exhaustive overview of the features of \CF. The goal is to introduce the basic ideas, allowing the user to get started drawing molecules as quickly as possible. This part does not go into detail; advanced use and a more formal approach to \CF commands will be discussed in the following parts.
+\part{Operation of \protect\CF}
+This part is devoted to describing the most common features of \CF. The user will find here explanations sufficient to draw most molecules. The presentation of features is done from a theoretical angle, and the goal of this part is not to draw real molecules but to give the user a formal description of the functionality of \CF. The ``Advanced usage'', page~\pageref{utilisation.avancee}, will be more practical and will illustrate advanced features for the most demanding uses. It will also highlight methods of building real molecules, page~\pageref{exemples.commentes}. Finally, the last part will give examples of molecules and the code used to draw them.
-\section{Syntax}
-The command \verb|\chemfig|\idx*{\chemfig} is used in the following way:
-\centerverb/\chemfig{<atom1><bond type>[<angle>,<coeff>,<n1>,<n2>,<tikz code>]<atom2>}/
+\section{Groups of atoms}
+Drawing a molecule consists inherently of connecting groups of atoms with lines. Thus, in the molecule \chemfig{O=O}, there are two groups of atoms, each consisting of a single atom ``O''.
-\begin{itemize}
-\item \verb-<angle>- is the bond angle\idx*{bond!angle} between the two atoms;
-\item \verb-<coeff>- is a coefficient multiplying the default bond length\idx*{bond!length};
-\item \verb-<n1>- and \verb-<n2>- are the numbers of the departure and arrival atoms of the bond\idx*{bond!departure and arrival atoms};
-\item \verb-<tikz code>- is additional options concerning the colour or style of a bond\idx*{bond!customization}.
-\end{itemize}
-\medskip
-Each bond takes optional arguments\idx*{bond!optional argument} which are placed in square brackets. These arguments can adjust everything one needs for the bond. Each argument has a default value, so one can simply write:
-\exemple{The water molecule}|\chemfig{H-O-H}|
+{\fboxsep1pt
+However, in this molecule
+\molht{H_3C-C(-[:-30]OH)=[:30]O}
+there are four groups of atoms: ``$\mathrm{H_3C}$'', ``C'', ``O'' and ``OH''. For reasons which we shall see later, \CF splits each group into single atoms. Each atom extends up to the next capital letter or one of these special characters: {\ttfamily \boxedfalseverb{-} \boxedfalseverb{=} \boxedfalseverb{~} \boxedfalseverb{(} \boxedfalseverb{!} \boxedfalseverb{*} \boxedfalseverb{<} \boxedfalseverb{>} \boxedfalseverb{@}}. \CF ignores all characters inside braces when splitting groups into atoms\idx*{separating atom mechanism}.
-In all the examples, the grey line represents the \idx{baseline}.
+Therefore the first group of atoms ``$\mathrm{H_3C}$'' is split into two atoms: $\boxednode{H_3}{}$ and $\boxednode C{}$. In terms of chemistry, of course, these are not real atoms; $\mathrm{H_3}$, for example, consists of three hydrogen atoms. In what follows the word atom refers to \CF's definition. Thus \CF sees the preceding molecule as follows:
+\renewcommand*\printatom[1]{\fbox{\ensuremath{\mathrm{#1}}}}
+\molht{H_3C-[,1.75]C(=[:30,1.5]O)(-[:-30,1.5]OH)}}
+
+A space is ignored when at the begining of a group of atoms.
-\section{The different types of bonds}
+\section{Different types of bonds}
\idx*{bond!types}For \CF, bonds between two atoms are one of nine types, represented by the characters \boxedfalseverb-, \boxedfalseverb=, \boxedfalseverb~, \boxedfalseverb>, \boxedfalseverb<, \boxedfalseverb{>:}, \boxedfalseverb{<:}, \boxedfalseverb{>|} and \boxedfalseverb{<|} :\label{types.liaisons}
\begin{center}
\begin{tabular}{>{\centering\arraybackslash}m{1.7cm}>{\centering\arraybackslash}m{3cm}>{\centering\arraybackslash}m{2cm}m{4cm}}
@@ -365,152 +363,6 @@ Bond \#&Code &Result &Bond type\\\hline
\end{center}
\label{setdoublesep}The command \verb-\setdoublesep{<dim>}-\idx*{\setdoublesep} adjusts the spacing between the lines in double or triple bonds. This spacing is 2pt by default.
-\section{Different types of diagrams}
-\subsection{Complete structural diagram}
-\exemple{Ethane}|\chemfig{C(-[2]H)(-[4]H)(-[6]H)-C(-[2]H)(-[6]H)-H}|
-
-Each bond takes several optional arguments\idx*{bond!optional argument}. The first optional argument defines the \verb-<angle>- of the bond\idx*{bond!angle}. Angles increase counterclockwise. If no angle is give then its default value is 0\degres.
-
-Note: the parentheses allow multiple bonds from the same atom; see ``Branched molecules''\idx*{branched molecule}, page~\pageref{molecules.ramifiees}.
-
-There are many ways of specifying the angle of a bond.
-\begin{description}
-\item[Predefined angles] \idx*{bond!angle!predefined}When the optional argument contains a whole number, this represents the angle that the bond makes with the horizontal, in multiples of 45\degres.
-
-\exemple{Predefined angles}|\chemfig{(-[1]1)(-[2]2)(-[3]3)(-[4]4)(-[5]5)(-[6]6)(-[7]7)-0}|
-
-\item[Absolute angle] \idx*{bond!angle!absolute}To give an angle in degrees relative to the horizontal, the optional argument must take this form: \verb-[:<absolute angle>]-. The \verb-<absolute angle>- may be positive or negative, and may have decimal places. It is reduced to the interval $[0,360)$.
-\item[Relative angle] \idx*{bond!angle!relative}It is often useful to give the bond angle relative to the preceding bond. In this case, the following syntax must be used:\verb-[::<relative angle>]-. The \verb-<relative angle>- may be positive or negative, and may have decimal places.
-\end{description}
-
-\subsection{Condensed structural diagram}
-\exemple{Hex-1-ene}|\chemfig{H_3C-{{(CH_2)}_3}-CH=CH_2}|
-
-It is sometimes useful to change the length of a bond\idx*{bond!length}. In the preceding example, the first two bonds need to be lengthened; they are too short compared to the double bond. To do this, the \verb|<coeff>| is needed in the optional arguments\idx*{bond!optional argument}.
-
-\exemple{Hex-1-ene}|\chemfig{H_3C-[,1.5]{{(CH_2)}_3}-[,1.5]CH=CH_2}|
-
-Notes:
-\begin{itemize}
- \item in the notation \verb|[,1.5]|, the comma indicates that the value placed in brackets corresponds to the second argument (\verb|coeff|). To give a value for the fourth argument one would write \verb|[,,,2]|;
- \item characters between braces are not interpreted by \CF, which allows (for example) groupings of atoms to be written inside parentheses without having them treated as part of a branched molecule (see page~\pageref{molecules.ramifiees}).
-\end{itemize}
-
-\subsection{Cram representation}
-\idx*{Cram representation}Another way of showing the bond angle between two atoms.
-\exemple{Methane}|\chemfig{C(-[5]H)(-[2]H)(<[:-70]H)(<:[:-20]H)}|
-
-\subsection{Skeleton diagram}
-\idx*{skeleton diagram}The simplest input, only covalent bonds are listed with their possible settings.
-\exemple{But-2-ene}|\chemfig{-[:30]=[:-30,,,,red]-[:30]}|
-
-The double bond lines are drawn on either side of where the single bond line would be. To keep graphical consistency between skeleton diagrams of various compounds it is useful to shift the second double bond line above or below the single bond line\idx*{bond!shifted}. Just follow the \verb-=- symbol with \verb-^- or \verb-_-, as shown below:
-\exemple{Comparison between double bonds and shifted double bonds}/\chemfig{-[:-30]=[:30]-[:-30]} \chemfig{-[:-30]=^[:30]-[:-30]}\par
-\chemfig{=[:-30]-[:30]=[:-30]} \chemfig{=_[:-30]-[:30]=^[:-30]}/
-
-\subsection{Lewis diagrams}
-\idx*{Lewis diagram}The syntax is as follows:
-\centerverb/\lewis{<position index><electron state>,<atom>}/
-\smallskip
-
-The electron states can be a lone pair, an empty electron slot, or a single electron. By default the electron state is a lone pair. A single electron is represented by the character \boxedfalseverb. and an empty slot by \boxedfalseverb|.
-
-\exemple{Chloromethane and water}|\chemfig{C(-[2]H)(-[4]H)(-[6]H)-\lewis{260,Cl}}\hspace{1cm}
-\chemfig{[:40]H-\lewis{13,O}-[::-80]H}|
-
-Note: the positions take whole number values between 0 and 7.
-\exemple{Positions}/\lewis{0.2.4.6.,C}\hspace{1cm}
-\lewis{0|2.46.,C}\hspace{1cm}
-\lewis{1357,Ar}/
-
-\section{Branched molecules}\label{molecules.ramifiees}
-\idx*{branched molecule}To indicate a branch, simply follow the atom holding the branch with a \verb-<code>- in parentheses. This \verb-<code>- is the code of the submolecule which will be attached to the atom. Multiple branches can be attached to the same atom, and these can be nested.
-
-\exemple{Alkanes}|\chemfig{H_3C-CH(-[2]CH_3)-CH_3}
-\hspace{.5cm}\chemfig{-(-[2])(-[6])-}|
-
-In this type of representation it is sometimes necessary to connect to distant atoms\idx*{bond!distant atoms}. To do this, the character \verb|?| is used, which creates a hook between two atoms. The function
-\centerverb/?[<name>,<bond>,<tikz>]/
-takes three arguments: the name of the hook, the bond type, and tikz code. The following example shows how to make two different hooks.
-
-\exemple*{Cocaine}|\chemfig{H_2C(-C?[a]H-[:-30]CH_2-[:30]C?[b]H-O-CO-C_6H_5)
--[2]CH_2-[,1.7]CH(-[3]N?[a]-[3]H_3C)(-[,1.35]C?[b]H-CO-OCH_3)}|
-
-\section{Rings}
-\idx*{ring}\CF can easily draw regular polygons. The syntax is the following:
-\centerverb/\chemfig{*n(<code for the molecule>)}/
-\smallskip
-
-\exemple{Some rings}|
-\chemfig{*3(---)}\hspace{.5cm}
-\chemfig{*5(-=-=-)}\hspace{.5cm}
-\chemfig{*6(-=-=-=)}|
-
-\idx*{ring!branch}Branches are used in the same way as before.
-
-\exemple{Rings and branches}|\chemfig{*4(-(--[1]*4(----))---)}|
-
-Note: a ring does not start or finish with the atom or group of atoms with which one wants to close the ring. The chemical entity on which the ring is based must be outside the ring definition.
-
-\exemple{Proper coding}|\chemfig{A*4(-B-C-D-)}|
-
-\exemple{Bad coding}|\chemfig{*4(A-B-C-D-)}\hspace{1cm}
- \chemfig{*4(-B-C-D-A)}|
-
-\section{Ions}
-The \verb|chemfig| commands enters the \idx{math mode}\footnote{There is a problem with the placement of groups of atoms containing exponents or subscripts. See page~\pageref{alignement.vertical}.} of \TeX, so it is very simple to write an ion. A negative charge ($-$) must always be enclosed in braces to avoid \CF confusing it with the symbol for a single bond.
-
-\exemple{Acetate ion}|\chemfig{-(-[1]O^{-})=[7]O}|
-
-For purists it is possible to circle the charge of an ion by using the commands \verb|\ominus| and \verb|\oplus|\idx*{charge!\protect\texttt{\protect\string\protect\oplus}}\idx*{charge!\protect\texttt{\protect\string\protect\ominus}}.
-
-To meet all requirements, there are two other commands \idx{\chemabove} and \idx{\chembelow} which allow placement of charges above or below the current atom\idx*\lewis.
-
-\exemple{Some ions}|\chemfig{-(-[1]O^{\ominus})=[7]O}
-\hspace{1cm}
-\chemfig{\lewis{35,O}=\lewis{26,Cl}-\chemabove
-{\lewis{026,O}}{\ominus}}
-\vskip5pt
-\chemfig{-\chemabove{N}{\scriptstyle\oplus}(=[1]O)-[7]O^{\ominus}}|
-
-For those who are extremely picky, the commands \idx{\chemabove} and \idx{\chembelow} accept an optional argument which sets the distance between the charge and the atom\idx*\lewis.
-\exemple{Charge position}|\chemfig{\lewis{35,O}=C-\chemabove
-[3pt]{\lewis{246,O}}{\hspace{.5cm}\ominus}}|
-
-\section{Chemical equations}
-Here is an example of a \idx{chemical reaction}:
-\exemple*{Chemical reaction}/\chemfig{**6(------)} \hspace{.5cm} + \hspace{.5cm} \chemfig{H_3C-Cl}
-\hspace{.5cm} $\xrightarrow{catalyst}$ \hspace{.5cm}
-\chemfig{**6(---(-)---)} \hspace{.5cm} + \hspace{.5cm} \chemfig{H-Cl}/
-
-\CF adds two new commands \idx{\chemsign} and \idx{\chemrel} which slightly simplify the preceding syntax.
-
-\exemple*{Using the \CF commands}|\setchemrel{0pt}{1.2em}{6em}
-\chemfig{**6(------)}\chemsign[0.5cm]+\chemfig{H_3C-Cl}
-\chemrel[\itshape\tiny Catalyst]{->}
-\chemfig{**6(---(-)---)}\chemsign[0.5cm]+\chemfig{H-Cl}|
-\newpage
-
-\part{Operation of \protect\CF}
-This part is devoted to describing the most common features of \CF. The outline of this description far exceeds that of ``\CF for the impatient``, but the user will find here explanations sufficient to draw most molecules. The presentation of features is done from a theoretical angle, and the goal of this part is not to draw real molecules but to give the user a formal description of the functionality of \CF. The ``Advanced usage'', page~\pageref{utilisation.avancee}, will be more practical and will illustrate advanced features for the most demanding uses. It will also highlight methods of building real molecules, page~\pageref{exemples.commentes}. Finally, the last part will give examples of molecules and the code used to draw them.
-
-\section{Groups of atoms}
-Drawing a molecule consists inherently of connecting groups of atoms with lines. Thus, in the molecule \chemfig{O=O}, there are two groups of atoms, each consisting of a single atom ``O''.
-
-{\fboxsep1pt
-However, in this molecule
-\molht{H_3C-C(-[:-30]OH)=[:30]O}
-there are four groups of atoms: ``$\mathrm{H_3C}$'', ``C'', ``O'' and ``OH''. For reasons which we shall see later, \CF splits each group into single atoms. Each atom extends up to the next capital letter or one of these special characters: {\ttfamily \boxedfalseverb{-} \boxedfalseverb{=} \boxedfalseverb{~} \boxedfalseverb{(} \boxedfalseverb{!} \boxedfalseverb{*} \boxedfalseverb{<} \boxedfalseverb{>} \boxedfalseverb{@}}. \CF ignores all characters inside braces when splitting groups into atoms\idx*{separating atom mechanism}.
-
-Therefore the first group of atoms ``$\mathrm{H_3C}$'' is split into two atoms: $\boxednode{H_3}{}$ and $\boxednode C{}$. In terms of chemistry, of course, these are not real atoms; $\mathrm{H_3}$, for example, consists of three hydrogen atoms. In what follows the word atom refers to \CF's definition. Thus \CF sees the preceding molecule as follows:
-\renewcommand*\printatom[1]{\fbox{\ensuremath{\mathrm{#1}}}}
-\molht{H_3C-[,1.75]C(=[:30,1.5]O)(-[:-30,1.5]OH)}}
-
-A space is ignored when at the begining of a group of atoms.
-
-\section{Different types of bonds}
-\idx*{bond!types}As we have already seen (see page~\pageref{types.liaisons}), bonds can be one of nine types, each corresponding to the characters \boxedfalseverb-, \boxedfalseverb=, \boxedfalseverb~, \boxedfalseverb>, \boxedfalseverb<, \boxedfalseverb{>:}, \boxedfalseverb{<:}, \boxedfalseverb{>|} and \boxedfalseverb{<|}.
-
\label{longueur.liaison}\idx*{bond!length}We must understand that when a bond is made between two atoms, these atoms are contained within invisible rectangular boxes. The centres of these two rectangles are separated by an adjustable distance $\Delta$ called the ``interatomic distance''. Furthermore, bonds do not connect to the exact edges of the rectangles: a length $\delta$, also adjustable, separates the edges of the rectangles and the beginning and end of the bond line. The rectangular boxes are made visible in the diagram below to help understanding.
\begin{center}
\begin{tikzpicture}[every node/.style={anchor=base,inner sep=1.5pt,outer sep=0pt,minimum size=0pt},baseline]
@@ -1287,7 +1139,9 @@ and\idx*{\chembelow}
\centerverb|\chembelow[<dim>]{<code>}{<stuff>}|
\smallskip
-place the \verb-<stuff>- above and below the \verb-<code>- respectively at a vertical distance \verb-<dim>-, without changing the \idx{bounding box} of \verb-<code>-. The length \verb-<dim>- is 1.5pt by default.
+place the \verb-<stuff>- above and below the \verb-<code>- respectively at a vertical distance \verb-<dim>-, without changing the \idx{bounding box} of \verb-<code>-. The optional argument allows, if written, to specify this dimension at each call. If the optional argument is not used, a default size will be taken: its value is 1.5pt but it can be modified with the macro \idx*{\setstacksep}
+
+\centerverb|\setstacksep{<dimension>}|
These commands are independent of the macro \verb-\chemfig- and can be used either inside or outside its argument.