\documentclass{book}
\usepackage{a4}
\usepackage{palatino}
%\usepackage{times}
%\usepackage{utopia}
%\usepackage{euler}
\usepackage{fancyhdr}
\usepackage{epsf}

\newcommand {\atilde} {$_{\char '176}$} % tilde(~) character

\title{The Coot Reference Manual}
\author{Paul Emsley \\\textsf{\small emsley@ysbl.york.ac.uk}}
%\makeindex  % Not at the moment.  There are no index markups (yet).

\begin{document}
\maketitle
\tableofcontents

\chapter{Acknowledgments}
Paul Emsley is extremely grateful to use the library code of the
following people, without whom Coot could not have been realised:

\begin{trivlist}
\item Kevin Cowtan
\item Eugene Krissinel
\item Stuart McNicholas
\item Raghavendra Chandrashekara
\item Paul Bourke \& Cory Gene Bloyd
\end{trivlist}

Roland Dunbrack \& co-workers for rotamer library data.

Also (for generally useful software used in Coot):

\begin{trivlist}
\item Matteo Frigo \& Steven G. Johnson
\item Gary Houston \& other Guile developers
\item Python developers
\item Gtk+ and GNOME-Canvas developers
\item GNU Scientific Library developers
\item OpenGL developers
\item Janne L\"of
\end{trivlist}

Also those with whom Paul has corresponded about or provided
features and bug fixes and built the software:

\begin{tabular}{ll}
 William G. Scott & Bernhard Lohkamp \\
 Joel Bard  & Ezra Peisach           \\
 Alex Schuettelkopf & Charlie Bond 
\end{tabular}

Not forgetting the testers\footnote{in no particular order}

%\begin{trivlist}
%\item Eleanor J. Dodson
%\item Jan Dohnalek
%\item Karen McLuskey
%\item Bernhard Lohkamp
%\item Aleks Roszak
%\item Florence Vincent
%\item Roberto Steiner
%\item Alex Schuettelkopf
%\item Charlie Bond
%\item Constantina Fotinou
%\item William G. Scott
%\item Adrian Lapthorn
%\end{trivlist}

\begin{tabular}{ll}
Eleanor J. Dodson & Jan Dohnalek \\
Constantina Fotinou & Alex Roszak  \\
Florence Vincent  & Roberto Steiner \\
Karen McLuskey & Adrian Lapthorn   
\end{tabular}

\vspace{5mm}

Those with experience of Quanta, XFit and O will notice similarities
between Coot and those programs, it's fair to say that they have had
considerable influence in the look of Coot, so Paul respectively
thanks for inspiration: Tom Oldfield, Alwyn Jones and Duncan McRee
(and their co-workers).

\chapter{Design Overview}
\section{Why?}
``Why does Coot exist?'' you might ask.  ``Given that other molecular
graphics\footnote{molecular graphics with protein modeling and
  density fitting functions, that is.} programs exist, why write
another?''

Because I like having the source code to programs I use and think that
others feel the same.  Because the other programs don't quite work how
I wanted them to\footnote{and of course, there was no way to fix
  that.}. Because there was the possibility to integrate molecular
graphics into the CCP4 Suite.  

As to why write Coot when CCP4MG was available: that is not how it
happened. Coot\footnote{it was called ``MapView'' at the time.} was
released over a year before CCP4MG was available.  I followed my own
design, toolkit and aesthetic decisions - for good or bad\footnote{for
  example, I was (and remain) less concerned about porting to various
  shades of Microsoft Windows operating systems than the CCP4MG
  developers.}.

\section{Hacker's Guide}

The are several core libraries that are fundamental to Coot:

\begin{itemize}
\item Clipper: Kevin Cowtan's General crystallographic object library
\item mmdb: CCP4's Coordinate Library
\item GTk+: GNU's GUI toolkit.
\end{itemize}

\subsection{GUI}
The GUI is almost entirely built using glade.  Glade writes out its
code in pure C.  This causes a problem.  \texttt{src/interface.h} and
\texttt{src/support.h} both get regenerated in ``C mode'' every time
glade is run.  So, after every time we change the GUI with glade, we
need to run \texttt{post-glade} to introduce the C/C++ linking type
declaration wrapper into these files.

Not all of the GUI is build with glade - there are dynamic elements,
for example the ``Map and Molecule (Display) Control'' window the
frame of which are generated in glade, but the hboxs are filled using
hand-made code (see \texttt{gtk-manual.c}).

\subsection{GUI/State Variables}
The graphics\_info\_t class contains a host of static state variables,
mostly manipulated by GUI element (\emph{e.g} button)
callbacks\footnote{mostly button clicked signals and menu item
  activative signals}. For historical reasons they are initially set
in \texttt{globjects.cc}.  Because the callbacks are written in C by
glade\footnote{the GUI builder}, these variables need a functional
interface to set the variables, and that interface is used by both the
GUI button\footnote{and other GUI elements} callbacks and is exported
to the scripting level.  These function declarations are in
\texttt{c-interface.h}.  All manipulations of graphics\_info\_t's
state variables go via \texttt{c-interface.h}.

Notice that MMDB functions are not allowed in
this interface\footnote{because SWIG chokes on them}. 

\subsection{Scripting}
So, SWIG uses \texttt{c-interface.h} to generate the python/scheme
scripting interface. The scripting language is chosen at
configure-time using either \texttt{--with-guile} or
\texttt{--with-python}.

\section{Validation}
As I write this, a few of us are cobbling together a XML-based system
for validation.  We think that validation data should be presented as
XML data that can be passed between packages and programs.  Either the
program itself will output the data, or we will write a wrapper to
turn the output into the appropriate XML format.  

These XML data will be then available for use in the molecular
graphics and will provide information for a ``Next Unusual Feature''
button.  The library to provide the XML cabability for this is expat,
the same library used in Perl's XML::Parser, Python's XML parser
Pyexpat and Mozilla's XML parser.

\subsection{Example: Temperature Factor Analysis}
Recall that the kurtosis of a distribution, $k$ is given by:

\begin{equation}
  \label{eq:kurtosis}
  k = \frac{\Sigma(X_i - \mu)^4} {N \sigma^4} - 3 
\end{equation}

We calculate the kurtosis for the isotropic temperature factors for
each residue in the molecule and residues with the most leptokurtic
distributions are written out to a file.  The format of the file is
XML.

This is an example of how we expect validation data to be presented to
molecular graphics programs.



\chapter{Refinement and Regularization}
\input{../../coot/doc/derivatives-part}

\chapter{Exported Functions}
\input{functions}

%\input{reference.ind} % no indexes yet
\end{document}