Documentation for build semantics, CGNR and linear least squares dumping to disk
diff --git a/docs/api.tex b/docs/api.tex
index a9f4aef..c8feeeb 100644
--- a/docs/api.tex
+++ b/docs/api.tex
@@ -541,13 +541,35 @@
  List of iterations at which the optimizer should dump the
      linear least squares problem to disk. Useful for testing and
      benchmarking. If empty (default), no problems are dumped.
-Note that this requires a version of Ceres built with protocol buffers.
 
-\item{\texttt{lsqp\_dump\_format}}(\texttt{"lm\_iteration\_\%03d.lsqp"})
- Format string for the file name used for dumping the least
-     squares problem to disk. If the format is \texttt{ascii}, then the
-     problem is logged to the screen; don't try this with large
-     problems or expect a frozen terminal.
+\item{\texttt{lsqp\_dump\_directory}} (\texttt{/tmp})
+ If \texttt{lsqp\_iterations\_to\_dump} is non-empty, then this setting determines the directory to which the files containing the linear least squares problems are written to.
+
+
+\item{\texttt{lsqp\_dump\_format}}{\texttt{TEXTFILE}} The format in which linear least squares problems should be logged
+when \texttt{lsqp\_iterations\_to\_dump} is non-empty.  There are three options
+\begin{itemize}
+\item{\texttt{CONSOLE}} prints the linear least squares problem in a human readable format
+  to \texttt{stderr}. The Jacobian is printed as a dense matrix. The vectors
+   $D$, $x$ and $f$ are printed as dense vectors. This should only be used
+   for small problems.
+\item{\texttt{PROTOBUF}}  
+   Write out the linear least squares problem to the directory
+   pointed to by \texttt{lsqp\_dump\_directory} as a protocol
+   buffer. \texttt{linear\_least\_squares\_problems.h/cc} contains routines for
+   loading these problems. For details on the on disk format used,
+   see \texttt{matrix.proto}. The files are named \texttt{lm\_iteration\_???.lsqp}. This requires that \texttt{protobuf} be linked into Ceres Solver.
+\item{\texttt{TEXTFILE}}
+   Write out the linear least squares problem to the directory
+   pointed to by \texttt{lsqp\_dump\_directory} as text files
+   which can be read into \texttt{MATLAB/Octave}. The Jacobian is dumped as a
+   text file containing $(i,j,s)$ triplets, the vectors $D$, $x$ and $f$ are
+   dumped as text files containing a list of their values.
+  
+   A \texttt{MATLAB/Octave} script called \texttt{lm\_iteration\_???.m} is also output,
+   which can be used to parse and load the problem into memory.
+\end{itemize}
+
 
 \item{\texttt{crash\_and\_dump\_lsqp\_on\_failure}}(\texttt{false})
  Dump the linear least squares problem to disk if the minimizer
diff --git a/docs/build.tex b/docs/build.tex
index a501c39..44ef9dd 100644
--- a/docs/build.tex
+++ b/docs/build.tex
@@ -17,7 +17,7 @@
  Note: Ceres requires \texttt{glog}\ version 0.3.1 or later. Version 0.3 (which ships with Fedora 16) has a namespace bug which prevents Ceres from building.
 
 \item{\gflags~\footnote{\url{http://code.google.com/p/gflags}}} is used by the code in
-  \texttt{examples}. It is also used by some of the tests. While technically it is not required to build the core library, we do not recommend building Ceres without it.
+  \texttt{examples}. It is also used by some of the tests. Strictly speaking it is not required to build the core library, we do not recommend building Ceres without it.
 \item{\suitesparse~\footnote{\url{http://www.cise.ufl.edu/research/sparse/suitesparse/}}} is used for sparse matrix analysis,
   ordering and factorization. In particular Ceres uses the
   \amd, \colamd\ and \cholmod\ libraries. This is an optional
@@ -88,8 +88,7 @@
 tar zxf ceres-solver-1.0.tar.gz
 mkdir ceres-bin
 cd ceres-bin
-cmake ../ceres-solver-1.0              \
- -DEIGEN_INCLUDE=/usr/include/eigen3   \
+cmake ../ceres-solver-1.0     
 make -j3
 make test
 \end{minted}
@@ -199,19 +198,17 @@
 
 \item{\suitesparse}
 
-
-It is possible to compile Ceres in without \suitesparse, which
-saves on binary size, but the resulting version of Ceres is not suited
-to large scale problems due to the lack of a sparse Cholesky solver.  This will reduce Ceres' dependencies down to
-\eigen, \gflags\ and \glog. To build Ceres without \suitesparse\ use
+By default, Ceres will only link to SuiteSparse if all its dependencies are present. 
+To build Ceres without \suitesparse\ use
 \begin{minted}{bash}
 -DSUITESPARSE=OFF.
 \end{minted}
- This will also disable dependency checking for \lapack\ and \blas.
+ This will also disable dependency checking for \lapack\ and \blas. This saves on binary size, but the resulting version of Ceres is not suited
+to large scale problems due to the lack of a sparse Cholesky solver.  This will reduce Ceres' dependencies down to
+\eigen, \gflags\ and \glog.
 
 \item{\gflags}
 
-
 To build Ceres without \gflags, use
 \begin{minted}{bash}
 -DGFLAGS=OFF.
diff --git a/docs/theory.tex b/docs/theory.tex
index 92a7aa6..35a1bbf 100644
--- a/docs/theory.tex
+++ b/docs/theory.tex
@@ -167,6 +167,14 @@
 
 For bundle adjustment problems, particularly those arising in reconstruction from community photo collections, more effective preconditioners can be constructed by analyzing and exploiting the camera-point visibility structure of the scene~\cite{kushal2012}. Ceres implements the two visibility based preconditioners described by Kushal \& Agarwal as \texttt{CLUSTER\_JACOBI} and \texttt{CLUSTER\_TRIDIAGONAL}. These are fairly new preconditioners and Ceres' implementation of them is in its early stages and is not as mature as the other preconditioners described above.
 
+
+\section{\texttt{CGNR}}
+For general sparse problems, if the problem is too large for \texttt{CHOLMOD} or \texttt{SuiteSparse} is not linked into Ceres, another option is the \texttt{CGNR} solver. This solver uses the Conjugate Gradients solver on the {\em normal equations}, but without forming the normal equations explicitly. It exploits the relation
+\begin{align}
+	H x = J^\top J x = J^\top(J x)
+\end{align}
+Currently only the \texttt{JACOBI} preconditioner is available for use with this solver. It uses the block diagonal of $H$ as a preconditioner. 
+
 \section{Ordering}
 All three of the Schur based solvers depend on the user indicating to the solver, which of the parameter blocks correspond to the points and which correspond to the cameras. Ceres refers to them as \texttt{e\_block}s and \texttt{f\_blocks}. The only constraint on \texttt{e\_block}s is that there should be no term in the objective function with two or more \texttt{e\_block}s.