summaryrefslogtreecommitdiff
path: root/graphics/mol2chemfig/docs/chapters
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/mol2chemfig/docs/chapters')
-rw-r--r--graphics/mol2chemfig/docs/chapters/abstract.tex11
-rw-r--r--graphics/mol2chemfig/docs/chapters/arrows.tex2
-rw-r--r--graphics/mol2chemfig/docs/chapters/atom-numbers.tex19
-rw-r--r--graphics/mol2chemfig/docs/chapters/bond-lengths.tex23
-rw-r--r--graphics/mol2chemfig/docs/chapters/compatibility.tex5
-rw-r--r--graphics/mol2chemfig/docs/chapters/composite.tex52
-rw-r--r--graphics/mol2chemfig/docs/chapters/conclusion.tex37
-rw-r--r--graphics/mol2chemfig/docs/chapters/context.tex5
-rw-r--r--graphics/mol2chemfig/docs/chapters/crossing-bonds.tex23
-rw-r--r--graphics/mol2chemfig/docs/chapters/flip-rotate.tex16
-rw-r--r--graphics/mol2chemfig/docs/chapters/help.tex7
-rw-r--r--graphics/mol2chemfig/docs/chapters/hydrogens.tex30
-rw-r--r--graphics/mol2chemfig/docs/chapters/input-modes.tex25
-rw-r--r--graphics/mol2chemfig/docs/chapters/installation.tex39
-rw-r--r--graphics/mol2chemfig/docs/chapters/introduction.tex43
-rw-r--r--graphics/mol2chemfig/docs/chapters/output.tex53
-rw-r--r--graphics/mol2chemfig/docs/chapters/polishing.tex39
-rw-r--r--graphics/mol2chemfig/docs/chapters/recalculating.tex10
-rw-r--r--graphics/mol2chemfig/docs/chapters/submolecules.tex46
-rw-r--r--graphics/mol2chemfig/docs/chapters/tpic1.tex18
-rw-r--r--graphics/mol2chemfig/docs/chapters/tpic2.tex21
-rw-r--r--graphics/mol2chemfig/docs/chapters/tpic3.tex16
-rw-r--r--graphics/mol2chemfig/docs/chapters/tutorial.tex4
23 files changed, 544 insertions, 0 deletions
diff --git a/graphics/mol2chemfig/docs/chapters/abstract.tex b/graphics/mol2chemfig/docs/chapters/abstract.tex
new file mode 100644
index 0000000000..9b07a8d001
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/abstract.tex
@@ -0,0 +1,11 @@
+\begin{abstract}
+\noindent \mcf is a Python program that generates \TeX\ graphics of chemical structures provided in \mf or \smiles format. Its output is written in the syntax of the \chf package, which in turn is based on \tkz. Thus, both these packages are required in order to compile \mcf's output.
+%
+The program is available
+%
+a) through a web interface,
+b) for local installation, and
+c) as a command line-driven thin client.
+%
+The thin client is a Lua script that is designed to work with the Lua interpreted embedded in LuaTeX, which is part of all recent TeXLive versions.
+\end{abstract}
diff --git a/graphics/mol2chemfig/docs/chapters/arrows.tex b/graphics/mol2chemfig/docs/chapters/arrows.tex
new file mode 100644
index 0000000000..c41097ac0e
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/arrows.tex
@@ -0,0 +1,2 @@
+\subsection{Attaching electron flow arrows}
+
diff --git a/graphics/mol2chemfig/docs/chapters/atom-numbers.tex b/graphics/mol2chemfig/docs/chapters/atom-numbers.tex
new file mode 100644
index 0000000000..e80db27d5b
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/atom-numbers.tex
@@ -0,0 +1,19 @@
+\subsection{Displaying atom numbers}
+
+% well this is a steaming pile. What do I do with this? A better use of displaying atom numbers is in connection with cross bonds. Let's go for those, then.
+
+
+If we look closely at the second doxorubicin graphic above, we notice that some bonds aren't quite straight but are veering slightly off course. In order to fix that up manually, we would need to correlate the atoms in the generated \texttt{.tex} file with the graphic. To do so, we display their numbers with the \lstinline!--atom-numbers! or \lstinline!-n! option:
+
+\lstinputlisting{doxo-numbered.sh}
+
+which gives
+
+\cfpic{doxo-numbered.tex}
+
+Let's say we want to straighten out the double bonds that point to atom no.\ 9 and no.\ 10. We delve into the previously generated, unnumbered version of the file and locate the atoms (only a fragment of the file is shown):
+
+\lstinputlisting[firstline=37,lastline=48]{doxo-stripped.tex}
+
+We see that the bond angles slightly deviate from multiples of 90 degrees in both cases. Indeed, slightly inaccurate angles are seen all over the file; fixing them all would be tedious. Instead, we can simply ask \mcf to recalculate the coordinates for us.
+
diff --git a/graphics/mol2chemfig/docs/chapters/bond-lengths.tex b/graphics/mol2chemfig/docs/chapters/bond-lengths.tex
new file mode 100644
index 0000000000..edf4f00f19
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/bond-lengths.tex
@@ -0,0 +1,23 @@
+\subsection{Bond lengths}
+
+You will have noticed that, in the above doxorubicin example, the removal of the hydrogens was accompanied by a reduction in length of the remaining bonds. This happened because, by default, \mcf scales all bond lengths such that the \emph{most frequently occurring} bond length is set equal to 1. In the unstripped version, the most frequent bonds were those to the explicit hydrogens. These were very short, which caused all other bonds to be unduly extended. Stripping the hydrogens restored a more proportioned appearance.
+
+There are two mechanisms with which we can explicitly change the bond lengths:
+
+\begin{enumerate}
+\item Within \mcf, you can use the \lstinline!--bond-scale! or \lstinline!-s! option, usually in combination with the \lstinline!--bond-stretch! or \lstinline!-t! option.
+
+\item Within \chf, you can set the unit bond length with e.g.\ \lstinline!\setchemfig{atom sep=16pt}!. This sets the length of a bond whose length is equals 1 (the default) inside the \lstinline!\chemfig! macro.
+\end{enumerate}
+
+The \lstinline!\setchemfig! approach is straightforward; in this document, \lstinline!\setchemfig{atom sep=16pt}! has been used throughout. The two \mcf options need a bit more explaining. The \lstinline!--bond-scale! or \lstinline!-s! option defines \mcf's overall behavior:
+
+\begin{itemize}
+\item With a setting of \lstinline!--bond-scale=keep!, \mcf will leave the bond lengths entirely alone; the \lstinline!--bond-stretch! option will have no effect in this case.
+
+\item With \lstinline!--bond-scale=normalize!, which is the default, all bonds will be scaled such that the most frequently occurring bond length is set to the value of the \lstinline!--bond-stretch! option, which defaults to 1.
+
+\item With \lstinline!--bond-scale=scale!, the value of \lstinline!--bond-stretch! will be used as a multiplier to the native length of each bond, as contained in the input file; no normalization will occur in this case.
+\end{itemize}
+
+Thus, the meaning of the \lstinline!--bond-stretch! option depends on the setting of the \lstinline!--bond-scale! option.
diff --git a/graphics/mol2chemfig/docs/chapters/compatibility.tex b/graphics/mol2chemfig/docs/chapters/compatibility.tex
new file mode 100644
index 0000000000..c3d4bb39b1
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/compatibility.tex
@@ -0,0 +1,5 @@
+\section{\chf version compatibility}
+
+Earlier versions of \chf used a series of named macros to adjust various parameters, for example \lstinline!\setatomsep{...}! to set the regular distance between two atoms in a rendered molecule. In recent versions of the package, these macros have been replaced with a unified key-value interface that employs a single macro, e.g.: \lstinline!\setchemfig{atom sep=...}!. There is at least one transitional \chf version (1.34, which I happen to have installed as of this writing) that understands both.
+
+The \texttt{mol2chemfig.sty} version that accompanies this documentation works only with \chf versions which use the \lstinline!\setchemfig{...}! interface. If your chemfig version is old and does not have this macro, then you can download a matching, older version from the \mcf \href{http://chimpsky.uwaterloo.ca/mol2chemfig/download}{home page}. If you have installed the \mcf program or the Lua client locally, you don't need to downgrade those; the required change only affects the \mcf LaTeX package. \ No newline at end of file
diff --git a/graphics/mol2chemfig/docs/chapters/composite.tex b/graphics/mol2chemfig/docs/chapters/composite.tex
new file mode 100644
index 0000000000..db2ffc84ce
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/composite.tex
@@ -0,0 +1,52 @@
+\subsection{Using generated code in composite figures}
+
+The \texttt{mol2chemfig} package loads \texttt{chemfig}, which in turn loads the general purpose graphics package \texttt{TikZ}. Through the latter package, we have access to the \texttt{tikzpicture} environment. Here is a \texttt{tikzpicture} that depicts two resonance structures of alanine bound to pyridoxal phosphate:
+
+\input{chapters/tpic1}
+
+The code for this graphic is
+
+\lstinputlisting{chapters/tpic1}
+
+The two structures were placed on the canvas using \tkz nodes. The \tkz nodes cannot contain \lstinline!\input! macros. Therefore, as a workaround, we first render the structures as submol definitions with
+
+\lstinputlisting{plp.sh}
+
+and then reference those definitions from within the \lstinline!\chemfig! macros inside the nodes.
+
+Reactions such as the mesomeric transitions within pyridoxal phosphate should also show some electron pushing. The \chf package offers a mechanism for naming atoms and bonds in molecules; these names can then be used to attach push arrows. We can ask \mcf to generate atom and bond names for us, using the \lstinline!--markers! or \lstinline!-g! option:
+
+\lstinputlisting{mp.sh}
+
+This option adds a unique identifier to each atom and to each bond. The option value (\texttt{mp} in our example) is used as a prefix; this allows to unambiguously reference atoms in multiple molecules in the same drawing. In our example, atom 3 will be given the marker \lstinline!@{mp3}! for atom 3. The bond between atoms 3 and 4 will be labeled with \lstinline!@{mp3-4}!; in bond markers, the smaller atom number always comes first. The generated code now starts to get a wee bit tough on the eyeballs:
+
+\lstinputlisting[firstline=1,lastline=5]{mp.tex}
+
+\ldots
+
+In order to attach drawing elements to the nodes defined in the \mcf-rendered structures, we need to use a separate \lstinline!tikzpicture! environment, with the optional arguments \lstinline![remember picture, overlay]!. Inside this environment, we can use arbitrary \tkz commands to decorate our rendered structures. Here is an example:
+
+\lstinputlisting{chapters/tpic2.tex}
+
+which gives
+
+\input{chapters/tpic2}
+
+One important thing to note is that, when the overlay mechanism is used, the document has to be processed \emph{twice} by pdftex---otherwise, the overlaid elements tend to get misaligned.
+
+The \lstinline!\draw! commands used in the example for the electron push arrows employed the \lstinline!mcfpusharrow! \tkz style that is defined by the \mcf package. You can adjust this style to your own tastes with the \lstinline!\tikzset! macro; see the \tkz documentation for details.
+
+If the push-arrows are the \emph{only} drawing element you need, you can avoid the need for explicitly creating an overlaid second \lstinline!tikzpicture! environment by using macros predefined by either \chf and \mcf. The next example illustrates the use of the \lstinline!\mcfpush! macro defined by \mcf.
+
+\lstinputlisting{chapters/tpic3.tex}
+
+which gives
+
+\input{chapters/tpic3}
+
+The arguments of the \lstinline!\mcfpush! macro are, in order, the named anchor of the origin, the parameters of the first control point (departure angle:distance), and the second anchor and second control point (arrival angle:distance). Two optional arguments set the \lstinline!shorten <=! and \lstinline!shorten >=! lengths for the arrow in question, which override the global values that can be adjusted using the \lstinline!\tikzset! mechanism.
+
+The \lstinline!\mcfpush! macro uses the \lstinline!mcfpusharrow! \tkz style (see above). This style references two color definitions, which were redefined using \lstinline!colorlet! (supplied by package \lstinline!xcolor!) in this example. The background color (\lstinline!mcfbgcolor!) defaults to white; you will only want to change it when drawing on a non-white canvas. This color definition is also used when drawing crossing bonds in the foreground (see section \ref{sec:tweaking}).
+
+Note that, even though the the overlaid \lstinline!tikzpicture! environment is no longer explicitly declared, the overlay mechanism is still used internally, so the need for processing the file with \TeX\ twice remains.
+
diff --git a/graphics/mol2chemfig/docs/chapters/conclusion.tex b/graphics/mol2chemfig/docs/chapters/conclusion.tex
new file mode 100644
index 0000000000..ef88bf7f10
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/conclusion.tex
@@ -0,0 +1,37 @@
+\section{Invoking \texttt{mol2chemfig} from within \LaTeX}
+
+Using the \lstinline!--shell-escape! option on Linux or its equivalents on other systems, \LaTeX\ can execute shell commands, capture the output and insert it directly into the document. We can use this with \mcf. If you have \mcf working and \LaTeX\ properly configured, the following command will insert the structure of FMNH directly into your document, without creating a separate file:
+
+\begin{verbatim}
+\mcfinput{-fw examples/fmnh.mol}
+\end{verbatim}
+
+\begin{center}
+\mcfinput{-fw examples/fmnh.mol}
+\end{center}
+
+\noindent Note, however, that with large documents and numerous chemical structures the overhead of running \texttt{mol2chemfig} on each formula during every compilation will add up.
+
+\section{\texttt{chemfig} settings used in this document}
+\label{sec:ChemfigSettings}
+
+Several settings are offered by \chf to control the appearance of structures in your documents. Below are the settings that were used in this document.
+
+\lstinputlisting{hand-coded-tex/chemfig-settings}
+
+\section{Conclusion}
+
+This tutorial has covered most capabilities of \mcf. There are a few more options that influence the appearance of the output; these should be pretty much self-explanatory.
+
+I hope \mcf will be useful to you. If you come across any bugs or issues, please send email to mpalmer\lstinline!@!uwaterloo.ca.
+
+\section{Acknowledgments}
+
+Christian Tellechea wrote the excellent \chf package, upon which \mcf is based. He also gave valuable help concerning \mcf itself; he solved several problems for me that had me stumped. He is the author of a French book on TeX; if you read French, you should probably get a copy.
+
+To the extent that \mcf understands chemistry, it owes this to the creators of \texttt{indigo}. An earlier version of \mcf used \texttt{rdkit}; however, after some experimentation, I found that \texttt{indigo} was better suited to my purpose. Nevertheless, I thank \texttt{rdkit}'s creator, Greg Landrum, for promptly and thoroughly answering all my questions.
+
+My (now former) student Eric Brefo-Mensah tested the code extensively and uncovered numerous bugs (or rather, a whole plague of locusts). Further bugs were reported by Benjamin Abel, Philipp Bisson, and Vincent Liegeois.
+%
+% A big thank you to everyone.
+
diff --git a/graphics/mol2chemfig/docs/chapters/context.tex b/graphics/mol2chemfig/docs/chapters/context.tex
new file mode 100644
index 0000000000..95ed624913
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/context.tex
@@ -0,0 +1,5 @@
+\subsection{ConTeXt compatibility}
+
+Currently not available. Volunteers for porting welcome.
+
+%\tkz and \chf are both compatible with ConTeXt. I don't know the first thing about ConTeXt myself, but thankfully Christian Tellechea, the author of \chf, has provided a plain-\TeX\ file with macros that should allow \mcf to work with ConTeXt. This file, \mcfplain, is also included with the archive and should be installed alongside \chf.
diff --git a/graphics/mol2chemfig/docs/chapters/crossing-bonds.tex b/graphics/mol2chemfig/docs/chapters/crossing-bonds.tex
new file mode 100644
index 0000000000..a6066ad023
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/crossing-bonds.tex
@@ -0,0 +1,23 @@
+\subsection{Crossing bonds}
+
+The cubane molecule contains several bonds that cross each other:
+
+\lstinputlisting{cubane-n.sh}
+
+\cfpic{cubane-n.tex}
+
+Use the \lstinline!--cross-bond! or \lstinline!-k! option to specify which bonds should go into the foreground:
+
+\lstinputlisting{cubane-cross-n.sh}
+
+\cfpic{eschers-cubane.tex}
+
+The implementation of this feature is a bit of a hack, I'm afraid; the following code listing (with hand-written comments) illustrates the contortions it adds to the generated code.
+
+\lstinputlisting{hand-coded-tex/twisted-commented.tex}
+
+The styling of the bond in the foreground can be adjusted by tweaking the \lstinline!mcfcrossbond! \tkz key in the \lstinline!mol2chemfig.sty! package. Alternatively, as of version 1.2b, \lstinline!mol2chemfig.sty! patches \chf's \lstinline!\setbondstyle! macro, such that the background for crossing bonds can be passed as an optional argument:
+
+\lstinputlisting{setbondstyle.tex}\input{setbondstyle.tex}
+
+\cfpic{eschers-cubane.tex}
diff --git a/graphics/mol2chemfig/docs/chapters/flip-rotate.tex b/graphics/mol2chemfig/docs/chapters/flip-rotate.tex
new file mode 100644
index 0000000000..8857af4857
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/flip-rotate.tex
@@ -0,0 +1,16 @@
+\subsection{Flipping and rotating structures}
+
+The vertical flipping can be reverted by passing the option \lstinline!--flop! or \lstinline!-q!:
+
+\lstinputlisting{doxo-recalculated-flopped.sh}
+
+\cfpic{doxo-recalculated-flopped.tex}
+
+Horizontal flipping is done with option \lstinline!--flip! or \lstinline!-p!.
+
+Rotation is performed by passing the \lstinline!--angle! or \lstinline!-a! option; rotation is counter-clockwise:
+
+\lstinputlisting{doxo-recalculated-rotated.sh}
+
+\cfpic{doxo-recalculated-rotated.tex}
+
diff --git a/graphics/mol2chemfig/docs/chapters/help.tex b/graphics/mol2chemfig/docs/chapters/help.tex
new file mode 100644
index 0000000000..b38ca5df9c
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/help.tex
@@ -0,0 +1,7 @@
+\section{Getting help}
+
+When you type \lstinline!mol2chemfig -h! or just \lstinline!mol2chemfig!, you will see a brief description of the program, as well as a list of all available options:%
+%
+\bigskip
+
+\lstinputlisting{optionlist}
diff --git a/graphics/mol2chemfig/docs/chapters/hydrogens.tex b/graphics/mol2chemfig/docs/chapters/hydrogens.tex
new file mode 100644
index 0000000000..4bf7f16592
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/hydrogens.tex
@@ -0,0 +1,30 @@
+\subsection{Adding and deleting hydrogens}
+
+The next example renders an SDF file for doxorubicin, downloaded from PubChem%
+%
+\footnote{We could also just have used the \texttt{-i pubchem} option, but since we are going to reuse the file, a local copy is handy.}
+
+\lstinputlisting{doxo-from-sdf.sh}
+
+This gives us
+
+\cfpic{doxo-raw.tex}
+
+Yikes. Let's remove the explicit hydrogens with option \lstinline!--hydrogens=delete! or \lstinline!-y delete!:
+
+\lstinputlisting{doxo-strip-h.sh}
+
+This gives
+
+\cfpic{doxo-stripped.tex}
+
+It is also possible to \emph{add} hydrogens to a structure that does not supply them; for example:
+
+\lstinputlisting{phenol-add-h.sh}
+
+produces
+
+\cfpic{phenol-with-hydrogens.tex}
+
+By default, \mcf neither removes nor adds hydrogens. Note also that adding hydrogens will trigger coordinate recalculation (see section \ref{sec:recalc}).
+
diff --git a/graphics/mol2chemfig/docs/chapters/input-modes.tex b/graphics/mol2chemfig/docs/chapters/input-modes.tex
new file mode 100644
index 0000000000..75e60f79cd
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/input-modes.tex
@@ -0,0 +1,25 @@
+\subsection{Input modes}
+
+By default, if you type \lstinline!mol2chemfig myinput!, \mcf expects \texttt{myinput} to be the name of a file that contains a molecule's description in either \mf or \smiles format. These are widely used file formats that can be exported from any chemical drawing program that I am aware of.
+%
+If you want \texttt{myinput} to be treated verbatim, rather than as a file name, you say:
+
+\begin{lstlisting}
+mol2chemfig --input=direct 'C1=CC=C(C=C1)O'
+\end{lstlisting}
+
+or, shorter:
+
+\begin{lstlisting}
+mol2chemfig -i direct 'C1=CC=C(C=C1)O'
+\end{lstlisting}
+
+When passing a smiles string as in this example, don't forget to put quotes around it; without them, the shell will try to expand it and likely cause an error.
+
+There is also the input format 'pubchem', which makes \mcf expect a numerical identifier for the pubchem database:
+
+\begin{lstlisting}
+mol2chemfig -i pubchem 996
+\end{lstlisting}
+
+This retrieves the \texttt{SDF} file for compound no.\ 996 (which happens to be phenol) from the PubChem database and uses it as input. The \texttt{SDF} format is a superset of the \texttt{molfile} format and is understood by the program as well. Obviously, you have to be online for this input mode to work.
diff --git a/graphics/mol2chemfig/docs/chapters/installation.tex b/graphics/mol2chemfig/docs/chapters/installation.tex
new file mode 100644
index 0000000000..0671439af9
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/installation.tex
@@ -0,0 +1,39 @@
+\section{Installation}
+
+There are three ways to run \mcf:
+%
+\begin{enumerate}
+\item You can use the web interface at \url{http://chimpsky.uwaterloo.ca/mol2chemfig/}
+\item You can install the entire program locally and run it from the command line. This requires that you also install Python and the indigo cheminformatics library.
+\item You can install a web client version of \mcf that is operated from the command line. This is a little program written entirely in Lua, which can be run by the \texttt{texlua} executable that is part of TeXLive.
+\end{enumerate}
+
+\subsection{\LaTeX\ requirements}
+
+In order to use the code generated by \mcf in your documents, you need
+
+\begin{enumerate}
+\item \tkz, a large and powerful general graphics package.
+
+\item \chf, which defines the code format used by \mcf and uses \tkz to render it to molecule graphics.
+
+\item The \texttt{mol2chemfig.sty} package. This is a fairly small package that defines some auxiliary macros for \mcf.
+
+Version 1.3 of \chf changed its interface for setting options; e.g.\ \verb|\setatomsep{16pt}| has been replaced by \verb|\setchemfig{atom sep=16pt}|. The current version of the \mcf package has been brought up to date with this change. I will leave an old version of the \mcf package up on my website (see web interface, above), which you can use in case you have to or want to use an older version of \chf.
+
+\end{enumerate}
+
+\tkz and \chf are available through TeXLive. Note that the \mcf package will load the \chf package for you, which in turn loads \tkz. Therefore, in your documents, it is sufficient to include the clause \lstinline!\usepackage{mol2chemfig}! in order to load all three of them.
+
+\subsection{Local installation}
+
+For the full local install of \mcf, you need a Python base installation, and additionally the \texttt{indigo} cheminformatics tool kit. On at least some Linux distributions, \texttt{indigo} is available through the package manager. On other systems, manual download (\url{http://lifescience.opensource.epam.com/indigo/index.html}) and installation may be required.
+
+Once you have the prerequisites installed and working, download the \mcf Python code from CTAN or from \url{http://chimpsky.uwaterloo.ca/mol2chemfig}, unzip in a convenient location and follow the included instructions.
+
+\subsection{Installing the Lua web client}
+
+% no need to repeat this here.
+This is a Lua script that lets you use the \mcf from the command line, but without having to install any additional libraries. For instructions, please see the instructions in the included README file that is within the \texttt{lua} subdirectory contained within the \mcf download.
+
+
diff --git a/graphics/mol2chemfig/docs/chapters/introduction.tex b/graphics/mol2chemfig/docs/chapters/introduction.tex
new file mode 100644
index 0000000000..ad260ca6dd
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/introduction.tex
@@ -0,0 +1,43 @@
+
+\section{A few examples}
+\label{sec:example}
+
+The following is a \smiles representation of caffeine, contained in the file \texttt{caffeine.smi}:
+
+\lstinputlisting{caffeine.smi}
+
+We can turn this into \chf code with the following command:%
+%
+\footnote{The examples in this document assume that you have installed the local version of \mcf. If you installed the web client version, you must use \lstinline!mol2chemfig.lua! wherever the listed example commands use \lstinline!mol2chemfig!.}
+
+\lstinputlisting{caffeine-from-smiles.sh}
+
+This writes the following \chf code to the target file:
+
+\lstinputlisting{caffeine-smi.tex}
+
+If we load this file with \lstinline!\input{caffeine-smi.tex}!, we get the following result%
+%
+\footnote{The appearance of the chemical formulas in this document has been tweaked using some settings that are provided by the \texttt{chemfig} package. The settings used here are listed in Section \ref{sec:ChemfigSettings}.}
+
+\cfpic{caffeine-smi.tex}
+
+which is almost what we want. We adjust the rotation of the molecule and also tweak its appearance a little:
+
+\lstinputlisting{caffeine-from-smiles-rotated.sh}
+
+With these modifications, the structure looks as follows:
+
+\cfpic{caffeine-smi2.tex}
+
+Small molecules like caffeine are fairly easy to create with \chf alone. Hand-written \chf code will look cleaner and more concise than the code generated by \mcf. For example, here is the hand-coded \chf version for caffeine that will produce the exact same graphic as the last \mcf command:
+
+\lstinputlisting{hand-coded-tex/caffeine}
+%
+In particular, the syntax for specifying rings and ring substituents in \chf is remarkably powerful and elegant. With a little practice, molecules such as this one can be hand-written with little effort, and I sincerely recommend that you learn this skill. However, if you need to depict many small molecules, or fairly large ones, a tool like \mcf will come in handy. Take, for example, the lipopeptide antibiotic daptomycin, which we in this case load from a molfile:
+
+\lstinputlisting{daptomycin1.sh}
+
+\cfpic{daptomycin}
+
+This molecule might take a little longer to code by hand \ldots
diff --git a/graphics/mol2chemfig/docs/chapters/output.tex b/graphics/mol2chemfig/docs/chapters/output.tex
new file mode 100644
index 0000000000..9db9450716
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/output.tex
@@ -0,0 +1,53 @@
+\subsection{Output destination and formats}
+
+By default, \mcf simply writes to the terminal (stdout). Use output redirection to send the output to a file instead:
+
+\lstinputlisting{phenol-from-smiles.sh}
+
+This writes the following \chf code to the file:
+
+\lstinputlisting{phenol-smi.tex}
+
+If we input this code directly, we will not produce a graphic; instead, we will just see the code itself, only without the line breaks. To produce a graphic, the code must be enclosed in a \lstinline!\chemfig{...}! macro. This could be done manually by copying and pasting. It is usually more convenient to use the \lstinline!-w! or \lstinline!--wrap-chemfig! option:
+
+\lstinputlisting{phenol-from-smiles-w.sh}
+
+which will produce
+
+\lstinputlisting{phenol-smi-wrapped.tex}
+
+This file can then be used with \lstinline!\input{phenol-smi-wrapped}! directly:
+
+\cfpic{phenol-smi-wrapped}
+
+Note that the following will \emph{not} work:
+
+\begin{lstlisting}
+\chemfig{\input{phenol-smi.tex}}
+\end{lstlisting}
+
+This is because the \lstinline!\chemfig{...}! command puts \TeX\ into an altogether different frame of mind, in which many other commands, including \lstinline!\input!, no longer work as usual.
+
+In addition to the option \lstinline!--wrap-chemfig! or \lstinline!-w!, there is also the option \lstinline!--submol-name! or \lstinline!-l!, which will wrap the generated code into a \lstinline!\definesubmol! macro:
+
+\lstinputlisting{phenol-as-submol.sh}
+
+%\clearpage
+
+This produces
+
+\lstinputlisting{phenol-as-submol.tex}
+
+The \lstinline!\definesubmol! macro is implemented by \chf and defines a named shortcut for a molecule or fragment. This is useful if you want to integrate the generated code into larger, manually assembled structures or drawings. We will revisit this topic below.
+
+In the file listings above, each atom appears on a separate line and is annotated by a comment with its number. The \texttt{\% ->} in the last line indicates that this bond does not create a new atom but instead connects back to atom number 4 to close a ring.
+
+The formatting and annotation in the code example above is useful if you want to manually edit the generated code. If this is not required, you can create more compact output with option \lstinline!--terse! or \lstinline!-z!:
+
+\lstinputlisting{phenol-from-smiles-wz.sh}
+
+The generated code is equivalent, but with comments and whitespace stripped out:
+
+\lstinputlisting{phenol-smi-terse}
+
+%\cfpic{phenol-smi-terse} % just checkin ... chicken?
diff --git a/graphics/mol2chemfig/docs/chapters/polishing.tex b/graphics/mol2chemfig/docs/chapters/polishing.tex
new file mode 100644
index 0000000000..7b00af9641
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/polishing.tex
@@ -0,0 +1,39 @@
+\subsection{Tweaking the appearance of bonds}
+\label{sec:tweaking}
+
+The plain command
+
+\lstinputlisting{morphine.sh}
+
+produces
+
+\cfpic{morphine.tex}
+
+which can be improved. First, we may want to give the double (and, if present, triple) bonds a more well-proportioned look. To do so, use option \lstinline!--fancy-bonds! or \lstinline!-f!:
+
+\lstinputlisting{morphine-f.sh}
+
+which gives
+
+\cfpic{morphine-f.tex}
+
+Note that the look of the double bonds involves some \tkz trickery; in the generated code, the double bonds are no longer represented by \lstinline!=! symbols but instead by something like \lstinline!-[:120,,,,drh]!.
+
+Next, the molecule contains two bonds that cross each other, and we would like to draw the vertical one in the foreground. To specify this bond, we need the numbers of the adjoining atoms. We first can let \mcf print the atom numbers:
+
+\lstinputlisting{morphine-n.sh}
+
+which gives
+
+\cfpic{morphine-n.tex}
+
+The bond that we are looking at connects atoms 19 and 20. We now can use the \lstinline!-k! or \lstinline!--crossbond! option to put it in the foreground:
+
+\lstinputlisting{morphine-k.sh}
+
+which gives us
+
+\cfpic{morphine-k.tex}
+
+To draw crossing bonds, atom numbers and proportioned double or triple bonds, \mcf relies on several custom macros and \tkz styles defined in the \texttt{mol2chemfig.sty} package. Accordingly, the generated code becomes a bit more verbose and less \chf-like.
+
diff --git a/graphics/mol2chemfig/docs/chapters/recalculating.tex b/graphics/mol2chemfig/docs/chapters/recalculating.tex
new file mode 100644
index 0000000000..04a6bf428c
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/recalculating.tex
@@ -0,0 +1,10 @@
+\subsection{Recalculating coordinates}
+\label{sec:recalc}
+
+Molecules specified in \texttt{SMILES} format don't have any coordinates attached to them, so \mcf needs to calculate them; this is performed automatically. Input in \texttt{molfile} format comes with coordinates attached, and \mcf uses these by default. However, we can explicitly request \mcf to discard these coordinates and calculate new ones with the \lstinline!--recalculate-coordinates! or \lstinline!-u! option. When applied to the daptomycin example from section \ref{sec:example},
+\lstinputlisting{daptomycin-u.sh}
+
+this gives us
+
+\cfpic{daptomycin-u.tex}
+
diff --git a/graphics/mol2chemfig/docs/chapters/submolecules.tex b/graphics/mol2chemfig/docs/chapters/submolecules.tex
new file mode 100644
index 0000000000..2509962799
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/submolecules.tex
@@ -0,0 +1,46 @@
+\subsection{Working with sub-molecules}
+
+The \chf package supplies a nifty mechanism to assemble larger molecules from predefined fragments, or sub-molecules. The following (hand-coded) example builds aspirin from two sub-molecules:
+
+\lstinputlisting{hand-coded-tex/aspirin.tex}
+
+\cfpic{hand-coded-tex/aspirin}
+
+As a more advanced example, let us piece together the structure of Sodium Green, a fluorescent sodium indicator dye (the figure below was ripped from an information sheet by the supplier, Molecular Probes).
+
+\begin{center}
+\includegraphics[width=0.75\textwidth]{examples/hand-coded-tex/sodium-green.png}
+\end{center}
+
+The molecule contains two moieties of dichlorofluorescein, attached to a crown ether via a linker. We start with dichlorofluorescein as one submol and the crown ether-cum-linkers as the other.
+
+\lstinputlisting{dichlorofluorescein1.sh}
+
+Now, we put the two pieces together, starting with the bridging carbonyl group:
+
+\lstinputlisting{hand-coded-tex/sodium-green1}
+
+which gives us the following fabulous result:
+
+\cfpic{hand-coded-tex/sodium-green1}
+
+What went wrong here? Submol expansion is essentially string substitution. When the submol is filled in, the connection to the preceding part of the molecule is made by whichever atom happens to have been rendered first, and the last rendered atom of the submol connects to the subsequent parts of the structure. Thus, we need to tell \mcf the order in which to render the atoms. To identify the atoms that we want to join, we display all atom numbers in the structure.
+
+\lstinputlisting[firstline=2]{dichlorofluorescein2.sh}
+
+\cfpic{hand-coded-tex/sodium-green2}
+
+For dichlorofluorescein, we need to connect to atom 22. For the crown ether, we want to enter at atom 12 coming from the left, and leave at atom 32 on the right. To render the sub-molecules accordingly, we use the \lstinline!--entry-atom! or \lstinline!-e! as well as the \lstinline!--exit-atom! or \lstinline!-x! options:
+
+\lstinputlisting[firstline=2]{dichlorofluorescein3.sh}
+
+We put the whole molecule together:
+
+\lstinputlisting{hand-coded-tex/sodium-green3.tex}
+
+This produces
+
+\cfpic{hand-coded-tex/sodium-green3}
+
+which is what we want \ldots\ well, almost; the entry and exit amine groups of the crown ether submol now each have one surplus hydrogen. This problem cannot be fixed using \mcf but requires editing of the generated code by hand.
+
diff --git a/graphics/mol2chemfig/docs/chapters/tpic1.tex b/graphics/mol2chemfig/docs/chapters/tpic1.tex
new file mode 100644
index 0000000000..b6cbf60595
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/tpic1.tex
@@ -0,0 +1,18 @@
+\input{plp}
+\input{plp2}
+
+\begin{center}
+\begin{tikzpicture}%
+[>=stealth, help lines/.style={very thin,draw=black!25}, x=1cm, y=1cm]
+
+% draw grid of help lines
+\draw[help lines] (0,0) grid (12,4);
+
+% place both structures
+\node[anchor=south west, inner sep=10pt] at (0,0) (plp) {\chemfig{!{plp}}};
+\node[anchor=south west, inner sep=10pt] at (7,0) (plp2) {\chemfig{!{plp2}}};
+
+\draw[<->] (plp) -- (plp2);
+
+\end{tikzpicture}
+\end{center} \ No newline at end of file
diff --git a/graphics/mol2chemfig/docs/chapters/tpic2.tex b/graphics/mol2chemfig/docs/chapters/tpic2.tex
new file mode 100644
index 0000000000..901594b2b3
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/tpic2.tex
@@ -0,0 +1,21 @@
+\input{mp}
+
+\begin{center}
+\begin{tikzpicture}% first picture contains mol2chemfig structure
+[>=stealth, help lines/.style={very thin,draw=black!25}, x=1cm, y=1cm]
+
+\draw[help lines] (0,0) grid (6,3);
+\node[anchor=south west, inner sep=10pt] at (1,0) {\chemfig{!{mp}}};
+\end{tikzpicture}
+
+\begin{tikzpicture}[remember picture,overlay] % overlaid picture
+% places draws relative to nodes defined in the mol2chemfig structure
+
+% The mcfpusharrow tikz style is defined in the mol2chemfig package.
+\draw[mcfpusharrow](mp12-13) to [out=60,in=60,looseness=4] (mp11-12);
+\draw[mcfpusharrow](mp2-3) to [out=105,in=105,looseness=5] (mp3);
+
+% attach some arbitrary shapes to the molecule
+\draw[semithick,blue,fill=red](mp17) -- ++(0.5,0.5) node[circle,fill=yellow,inner sep=1pt,draw=blue]{\scriptsize\textsf{blob}};
+\end{tikzpicture}
+\end{center}
diff --git a/graphics/mol2chemfig/docs/chapters/tpic3.tex b/graphics/mol2chemfig/docs/chapters/tpic3.tex
new file mode 100644
index 0000000000..82567ec23c
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/tpic3.tex
@@ -0,0 +1,16 @@
+\input{mp}
+
+\colorlet{mcfpusharrowcolor}{red}
+\colorlet{mcfbgcolor}{yellow}
+\begin{center}
+\begin{tikzpicture}[help lines, x=1cm, y=1cm]
+
+\draw[help lines] (0,0) grid (6,3);
+\node[anchor=south west, inner sep=10pt] at (1,0) {\chemfig{!{mp}}};
+
+\mcfpush{mp12-13}{60:1.5em}{mp11-12}{60:1.5em}
+\mcfpush[-4pt][4pt]{mp2-3}{105:1.5em}{mp3}{105:1.5em}
+
+\end{tikzpicture}
+\end{center}
+
diff --git a/graphics/mol2chemfig/docs/chapters/tutorial.tex b/graphics/mol2chemfig/docs/chapters/tutorial.tex
new file mode 100644
index 0000000000..ddf8c9ef82
--- /dev/null
+++ b/graphics/mol2chemfig/docs/chapters/tutorial.tex
@@ -0,0 +1,4 @@
+\section{Tutorial}
+
+In the following, we will work through a series of examples to illustrate the use of some of \mcf's options. With all but the most basic examples, it will be assumed that you are familiar with \chf and its syntax. If you aren't, you can still use \mcf, but you will not be able to manually enhance the \chf output that it generates---your loss.
+